address review: bare 'query' shows help, 'add' subcommand, list previews, SQL hints

- lrc query with no args now prints help (not the stats alias)
- promote add to a subcommand: lrc query add <name> "<sql>" (consistent with list/view/delete); removed --add/--name options
- lrc query list now shows a truncated SQL preview per alias
- on a failed query, append correct-usage examples (alias + raw SQL)
- query --help documents the ~/.lrc/queries.toml structure
- remove installer queries.toml writing: default aliases are built into the binary, so the installer change was unnecessary

LiveReview Pre-Commit Check: skipped (iter:1, coverage:0%)

Author: iconicvenom

cmd/app.go

@@ -62,6 +62,7 @@ type Handlers struct {
 	RunConfigCheck                  cli.ActionFunc
 	RunConfigPreview                cli.ActionFunc
 	RunQuery                        cli.ActionFunc
+	RunQueryAdd                     cli.ActionFunc
 	RunQueryList                    cli.ActionFunc
 	RunQueryView                    cli.ActionFunc
 	RunQueryDelete                  cli.ActionFunc
@@ -370,41 +371,46 @@ TABLE: review_log (one row per commit)
    iterations   INTEGER  review iterations (0 if none)
    coverage     INTEGER  review coverage percent 0-100 (0 if none)
 
-ALIASES: built-ins (stats, by-author, recent) plus your own, saved in
-~/.lrc/queries.toml. 'lrc query' with no args runs the 'stats' alias.
+ALIASES: built-in (stats, by-author, recent) plus your own. Manage them with
+'lrc query add|list|view|delete'. User aliases are saved in ~/.lrc/queries.toml:
+
+   [queries]
+   skipped = "SELECT date, subject FROM review_log WHERE action='skipped'"
+   my-cov  = "SELECT ROUND(AVG(coverage),1) FROM review_log WHERE action='reviewed'"
 
 EXAMPLES
-   lrc query                              # default summary (the 'stats' alias)
+   lrc query stats                        # run a built-in alias
    lrc query stats --json                 # same data, as JSON
-   lrc query list                         # show all aliases
-   lrc query view stats                   # show an alias's SQL
+   lrc query list                         # show all aliases + a preview
+   lrc query view stats                   # show an alias's full SQL
 
    # Was a specific commit reviewed? (incident forensics)
    lrc query "SELECT short_hash, action, iterations, coverage FROM review_log WHERE hash LIKE 'a1b2c3%'"
 
    # Per-author review effort
    lrc query "SELECT author, COUNT(*) AS commits, SUM(action='reviewed') AS reviewed FROM review_log GROUP BY author ORDER BY commits DESC"
 
-   # Coverage only on reviewed commits
-   lrc query "SELECT ROUND(AVG(coverage),1) AS avg_cov FROM review_log WHERE action='reviewed'"
-
    # Save and reuse your own query
-   lrc query --add "SELECT date, subject FROM review_log WHERE action='skipped'" --name skipped
+   lrc query add skipped "SELECT date, subject FROM review_log WHERE action='skipped'"
    lrc query skipped --json
 
    # Bound the scan on huge repos (Linux kernel = ~1.5M commits)
    lrc query stats --from "2024-01-01" --to "2024-12-31"
    lrc query stats --range main...feature   # just this PR's commits`,
 				Flags: []cli.Flag{
 					&cli.BoolFlag{Name: "json", Usage: "output machine-readable JSON"},
-					&cli.StringFlag{Name: "add", Usage: "save the given SQL as an alias (requires --name)"},
-					&cli.StringFlag{Name: "name", Usage: "alias name to save with --add"},
 					&cli.StringFlag{Name: "from", Usage: "only scan commits since this git date (e.g. 2024-01-01, '2 weeks ago') — bounds large repos"},
 					&cli.StringFlag{Name: "to", Usage: "only scan commits until this git date"},
 					&cli.StringFlag{Name: "range", Usage: "only scan a ref range, e.g. main...feature (per-PR stats)"},
 				},
 				Action: h.RunQuery,
 				Subcommands: []*cli.Command{
+					{
+						Name:      "add",
+						Usage:     "Save a query alias: lrc query add <name> \"<sql>\"",
+						ArgsUsage: "<name> \"<sql>\"",
+						Action:    h.RunQueryAdd,
+					},
 					{
 						Name:   "list",
 						Usage:  "List saved and built-in query aliases",

internal/reviewquery/command.go

@@ -7,25 +7,10 @@ import (
 	"github.com/urfave/cli/v2"
 )
 
-// RunQuery is the default action for `lrc query`. It either saves an alias
-// (--add/--name) or runs a saved alias / raw SQL and prints a table or JSON.
+// RunQuery is the default action for `lrc query`: runs a saved alias or raw SQL
+// and prints a table or JSON. With no argument it shows help (so users discover
+// the schema and examples rather than silently running a default query).
 func RunQuery(c *cli.Context) error {
-	if c.IsSet("add") {
-		add := strings.TrimSpace(c.String("add"))
-		name := strings.TrimSpace(c.String("name"))
-		if !c.IsSet("name") || name == "" {
-			return fmt.Errorf("--add requires --name")
-		}
-		if add == "" {
-			return fmt.Errorf("--add requires non-empty SQL")
-		}
-		if err := AddAlias(name, add); err != nil {
-			return err
-		}
-		fmt.Printf("Saved alias %q.\n", name)
-		return nil
-	}
-
 	// Seed from flags placed BEFORE the positional arg (cli parses those).
 	jsonOut := c.Bool("json")
 	filter := Filter{From: c.String("from"), To: c.String("to"), Range: c.String("range")}
@@ -37,11 +22,12 @@ func RunQuery(c *cli.Context) error {
 		return err
 	}
 
-	arg := "stats" // default alias
-	if len(positionals) > 0 && strings.TrimSpace(positionals[0]) != "" {
-		arg = strings.TrimSpace(positionals[0])
+	// No alias/SQL given -> show help instead of defaulting to a query.
+	if len(positionals) == 0 || strings.TrimSpace(positionals[0]) == "" {
+		return cli.ShowSubcommandHelp(c)
 	}
 
+	arg := strings.TrimSpace(positionals[0])
 	sqlText, found, err := ResolveAlias(arg)
 	if err != nil {
 		return err
@@ -53,7 +39,7 @@ func RunQuery(c *cli.Context) error {
 
 	res, err := Run(filter, sqlText)
 	if err != nil {
-		return err
+		return fmt.Errorf("%w\n\nRun a saved alias or valid SQL, e.g.:\n  lrc query stats\n  lrc query \"SELECT * FROM review_log LIMIT 5\"\nSee 'lrc query --help' for the table schema and 'lrc query list' for aliases", err)
 	}
 
 	if jsonOut {
@@ -68,6 +54,29 @@ func RunQuery(c *cli.Context) error {
 	return nil
 }
 
+// RunQueryAdd saves a user alias: `lrc query add <name> "<sql>"`.
+func RunQueryAdd(c *cli.Context) error {
+	name := strings.TrimSpace(c.Args().Get(0))
+	sqlText := strings.TrimSpace(c.Args().Get(1))
+	if name == "" || sqlText == "" {
+		return fmt.Errorf("usage: lrc query add <name> \"<sql>\"")
+	}
+	if err := AddAlias(name, sqlText); err != nil {
+		return err
+	}
+	fmt.Printf("Saved alias %q.\n", name)
+	return nil
+}
+
+// truncateSQL shortens a query for compact listing.
+func truncateSQL(s string, max int) string {
+	s = strings.Join(strings.Fields(s), " ") // collapse whitespace/newlines
+	if len(s) > max {
+		return s[:max-1] + "…"
+	}
+	return s
+}
+
 // parseTrailingFlags pulls flags out of args that cli left unparsed (anything
 // after the first positional). Supports `--flag value` and `--flag=value`.
 // Returns the remaining positional args; sets jsonOut/filter via pointers.
@@ -128,7 +137,7 @@ func RunQueryList(c *cli.Context) error {
 		return nil
 	}
 	for _, a := range aliases {
-		fmt.Printf("%-18s [%s]\n", a.Name, a.Source)
+		fmt.Printf("%-16s %-10s %s\n", a.Name, "["+a.Source+"]", truncateSQL(a.SQL, 60))
 	}
 	return nil
 }

main.go

@@ -86,6 +86,7 @@ func main() {
 		RunConfigCheck:                  appcore.RunConfigCheck,
 		RunConfigPreview:                appcore.RunConfigPreview,
 		RunQuery:                        reviewquery.RunQuery,
+		RunQueryAdd:                     reviewquery.RunQueryAdd,
 		RunQueryList:                    reviewquery.RunQueryList,
 		RunQueryView:                    reviewquery.RunQueryView,
 		RunQueryDelete:                  reviewquery.RunQueryDelete,

scripts/lrc-install.ps1

@@ -646,23 +646,6 @@ if (-not $env:HOME -and $env:USERPROFILE) {
     $env:HOME = $env:USERPROFILE
 }
 
-# Ship default review-history query aliases (idempotent — never clobbers edits)
-$LRC_DATA_DIR = Join-Path $env:USERPROFILE ".lrc"
-$LRC_QUERIES_FILE = Join-Path $LRC_DATA_DIR "queries.toml"
-if (-not (Test-Path $LRC_QUERIES_FILE)) {
-    New-Item -ItemType Directory -Path $LRC_DATA_DIR -Force | Out-Null
-    @'
-# git-lrc saved queries. Run with:  lrc query <name>
-# Add your own with:                lrc query --add "<sql>" --name "<name>"
-# Table columns: hash, short_hash, author, email, date, branch, subject, action, iterations, coverage
-[queries]
-stats = "SELECT action AS Action, COUNT(*) AS Commits, ROUND(AVG(iterations),1) AS AvgIter, ROUND(AVG(coverage),1) AS AvgCoveragePct FROM review_log GROUP BY action ORDER BY Commits DESC"
-by-author = "SELECT author AS Author, COUNT(*) AS Commits, SUM(action = 'reviewed') AS Reviewed FROM review_log GROUP BY author ORDER BY Commits DESC"
-recent = "SELECT short_hash AS Hash, date AS Date, action AS Action, subject AS Subject FROM review_log ORDER BY date DESC LIMIT 20"
-'@ | Set-Content -Path $LRC_QUERIES_FILE -Encoding UTF8
-    Write-Host "  OK Wrote default query aliases to $LRC_QUERIES_FILE" -ForegroundColor Green
-}
-
 # Install global hooks via lrc unless explicitly suppressed by the caller.
 if ($LRC_INSTALL_SKIP_HOOKS -eq "1") {
     Write-Host "Skipping automatic hook installation because LRC_INSTALL_SKIP_HOOKS=1" -ForegroundColor Yellow

scripts/lrc-install.sh

@@ -529,21 +529,6 @@ esac
 ENVEOF
 chmod +x "$LRC_ENV_FILE"
 
-# Ship default review-history query aliases (idempotent — never clobbers edits)
-LRC_QUERIES_FILE="$LRC_ENV_DIR/queries.toml"
-if [ ! -f "$LRC_QUERIES_FILE" ]; then
-    cat > "$LRC_QUERIES_FILE" << 'QUERIESEOF'
-# git-lrc saved queries. Run with:  lrc query <name>
-# Add your own with:                lrc query --add "<sql>" --name "<name>"
-# Table columns: hash, short_hash, author, email, date, branch, subject, action, iterations, coverage
-[queries]
-stats = "SELECT action AS Action, COUNT(*) AS Commits, ROUND(AVG(iterations),1) AS AvgIter, ROUND(AVG(coverage),1) AS AvgCoveragePct FROM review_log GROUP BY action ORDER BY Commits DESC"
-by-author = "SELECT author AS Author, COUNT(*) AS Commits, SUM(action = 'reviewed') AS Reviewed FROM review_log GROUP BY author ORDER BY Commits DESC"
-recent = "SELECT short_hash AS Hash, date AS Date, action AS Action, subject AS Subject FROM review_log ORDER BY date DESC LIMIT 20"
-QUERIESEOF
-    echo -e "  ${GREEN}OK${NC} Wrote default query aliases to $LRC_QUERIES_FILE"
-fi
-
 # Helper: append source line to a shell rc file if not already present
 add_source_line() {
     local rcfile="$1"