fix(lore): accept -q/--query alias on lore appraise (#28) (#81)

SAY-5 · web-flow · commit ada875d69a32 · 2026-05-11T10:18:33.000-07:00
Signed-off-by: SAY-5 &lt;SAY-5@users.noreply.github.com&gt;
Co-authored-by: SAY-5 &lt;SAY-5@users.noreply.github.com&gt;
diff --git a/internal/command/cobra.go b/internal/command/cobra.go
@@ -146,11 +146,16 @@ func countPositional(args []ArgSpec) int {
 
 // cobraPositionalValidator returns the cobra args validator for the
 // spec's positional args. If any positional is Variadic, the count is
-// a minimum (cobra.MinimumNArgs). Otherwise exactly-N applies.
+// a minimum (cobra.MinimumNArgs); a Variadic positional with
+// Required=false drops the floor to 0 so a sibling flag may supply
+// the value instead. Otherwise exactly-N applies.
 func cobraPositionalValidator(args []ArgSpec) cobra.PositionalArgs {
 	n := countPositional(args)
 	for _, a := range args {
 		if a.Kind == ArgPositional && a.Variadic && !a.MCPOnly {
+			if !a.Required {
+				return cobra.MinimumNArgs(0)
+			}
 			return cobra.MinimumNArgs(n)
 		}
 	}
diff --git a/internal/command/cobra_validator_test.go b/internal/command/cobra_validator_test.go
@@ -0,0 +1,36 @@
+package command
+
+import "testing"
+
+// TestCobraPositionalValidator_VariadicRequired keeps the
+// historical behavior: a Required variadic positional demands at
+// least one positional CLI arg.
+func TestCobraPositionalValidator_VariadicRequired(t *testing.T) {
+	args := []ArgSpec{
+		{Name: "query", Kind: ArgPositional, Type: ArgString, Required: true, Variadic: true, Help: "q"},
+	}
+	v := cobraPositionalValidator(args)
+	if err := v(nil, []string{}); err == nil {
+		t.Fatal("expected error for missing required positional, got nil")
+	}
+	if err := v(nil, []string{"foo"}); err != nil {
+		t.Fatalf("unexpected error with one positional: %v", err)
+	}
+}
+
+// TestCobraPositionalValidator_VariadicOptional asserts the new
+// affordance: a non-Required variadic positional accepts zero
+// positional args so a sibling flag can supply the value.
+func TestCobraPositionalValidator_VariadicOptional(t *testing.T) {
+	args := []ArgSpec{
+		{Name: "query", Kind: ArgPositional, Type: ArgString, Variadic: true, Help: "q"},
+		{Name: "query_flag", CLIFlagName: "query", Short: "q", Kind: ArgFlag, Type: ArgString, CLIOnly: true, Help: "q via flag"},
+	}
+	v := cobraPositionalValidator(args)
+	if err := v(nil, []string{}); err != nil {
+		t.Fatalf("expected zero positionals to be allowed when Required=false: %v", err)
+	}
+	if err := v(nil, []string{"foo", "bar"}); err != nil {
+		t.Fatalf("unexpected error with two positionals: %v", err)
+	}
+}
diff --git a/internal/lore/appraise_cmd.go b/internal/lore/appraise_cmd.go
@@ -12,6 +12,7 @@ import (
 
 type AppraiseInput struct {
 	Query       string `json:"query" jsonschema:"search query; BM25+recency+title-boost ranked"`
+	QueryFlag   string `json:"query_flag,omitempty" jsonschema:"-"`
 	AllProjects bool   `json:"all_projects,omitempty" jsonschema:"search every project (recommended for research)"`
 	Limit       int    `json:"limit,omitempty" jsonschema:"max results (default 10)"`
 	Since       string `json:"since,omitempty" jsonschema:"entries within window: 7d|2w|1m"`
@@ -31,7 +32,8 @@ var AppraiseCommand = &command.Command[AppraiseInput, AppraiseCmdOutput]{
 	Short:      "search lore before researching or inscribing",
 	Long:       "Search lore before storing new knowledge or spawning research subagents. Returns ranked entries with project, kind, age, and summary — if current results exist, use them instead of re-deriving.",
 	Args: []command.ArgSpec{
-		{Name: "query", Kind: command.ArgPositional, Type: command.ArgString, Required: true, Variadic: true, Help: "search query (remaining positional args joined on CLI)"},
+		{Name: "query", Kind: command.ArgPositional, Type: command.ArgString, Variadic: true, Help: "search query (remaining positional args joined on CLI)"},
+		{Name: "query_flag", CLIFlagName: "query", Short: "q", Kind: command.ArgFlag, Type: command.ArgString, CLIOnly: true, Help: "search query (alternative to positional form)"},
 		{Name: "all_projects", Kind: command.ArgFlag, Type: command.ArgBool, Help: "search every project"},
 		{Name: "limit", Kind: command.ArgFlag, Type: command.ArgInt, Help: "max results (default 10)"},
 		{Name: "since", Kind: command.ArgFlag, Type: command.ArgString, Help: "entries within window (7d|2w|1m)"},
@@ -40,7 +42,10 @@ var AppraiseCommand = &command.Command[AppraiseInput, AppraiseCmdOutput]{
 	Handler: func(ctx context.Context, d command.Deps, in AppraiseInput) (AppraiseCmdOutput, error) {
 		query := strings.TrimSpace(in.Query)
 		if query == "" {
-			return AppraiseCmdOutput{}, errors.New("query required")
+			query = strings.TrimSpace(in.QueryFlag)
+		}
+		if query == "" {
+			return AppraiseCmdOutput{}, errors.New("query required: pass as positional arg or via -q/--query")
 		}
 		db, err := d.OpenDB(ctx)
 		if err != nil {
