@gkoreli/ghx 0.2.0 → 0.2.1

package/README.md

@@ -42,6 +42,7 @@ If you have `gh` CLI working, ghx works too — same prerequisites.
 ```bash
 # Search repos — name, stars, language, README preview in 1 call
 ghx repos "react state management"
+ghx repos "playwright mcp" --limit 5
 
 # Explore a repo — branch, file tree, and README in 1 API call
 ghx explore plausible/analytics
@@ -60,7 +61,7 @@ ghx read plausible/analytics --lines 42-80 lib/plausible/stats/query.ex
 
 # Search code (AND matching, shows matching lines, token-protected)
 ghx search "useState repo:facebook/react"
-ghx search "path:llms.txt extension:txt"
+ghx search "path:llms.txt extension:txt" --limit 10
 
 # Full recursive tree
 ghx tree plausible/analytics assets/js
@@ -68,7 +69,7 @@ ghx tree plausible/analytics assets/js
 
 ## Why
 
-AI agents exploring GitHub face a reliability gap: *"Did I find nothing because nothing exists, or because I used the tool wrong?"* ghx eliminates this with smart defaults — AND matching instead of exact phrase, README previews instead of bare names, matching context instead of bare paths. The right behavior is the default behavior.
+AI agents exploring GitHub face a reliability gap: *"Did I find nothing because nothing exists, or because I used the tool wrong?"* ghx eliminates this with smart defaults — AND matching instead of exact phrase, README previews instead of bare names, matching context instead of bare paths. Unknown flags are rejected loudly (not silently absorbed into queries). The right behavior is the default behavior, and the wrong behavior is impossible.
 
 | Tool | Files per call | Matching context | Smart defaults | Dependencies |
 |------|---------------|-----------------|---------------|-------------|

package/SKILL.md

@@ -22,12 +22,17 @@ ghx read <owner/repo> <f1> [f2] [f3]       # Read 1-10 files in 1 API call (Grap
 ghx read <owner/repo> --map <f1> [f2]       # Structural map: signatures, imports, types (~92% token reduction)
 ghx read <owner/repo> --grep "pat" <f>      # Read file, show only matching lines (2 lines context)
 ghx read <owner/repo> --lines 42-80 <f>     # Read specific line range
-ghx repos "<query>"                         # Search repos with README preview in 1 GraphQL call
-ghx search "<query>"                        # Code search (REST API, AND matching, shows matching lines)
+ghx repos "<query>"                         # Search repos with README preview (default: 10 results)
+ghx repos "<query>" --limit 5               # Limit repo results (max: 20)
+ghx search "<query>"                        # Code search (AND matching, default: 30 results)
+ghx search "<query>" --limit 10             # Limit code search results (max: 100)
 ghx search --full "<query>"                 # Code search without line truncation (for minified files)
 ghx tree <owner/repo> [path]                # Full recursive tree listing
 ```
 
+**Exit codes:** 0 = results returned, 1 = no results (query valid), 2 = usage error (bad flags/args).
+**Flag safety:** Unknown flags always error (exit 2). Never silently absorbed into queries.
+
 ## Chain of Thought: Progressive Disclosure
 
 **Always start surgical, escalate only when needed.** This mirrors how developers work: scan structure → identify interesting files → read specific sections.
@@ -157,6 +162,8 @@ AND matching is almost always what agents want. `gh search code "useState fetchD
 
 10. **`gh search repos` and `gh search code` use different rate limit pools.** Repo search: 30/min (generous). Code search: 10/min (restrictive). Don't assume one rate limit applies to both.
 
+11. **Unknown flags are rejected, not silently absorbed.** `ghx search "query" --json` exits 2 with a clear error. This is intentional — silent flag absorption was the #1 cause of agent failures (flags like `--limit` would get concatenated into the query string, corrupting it). If you get exit 2, check your flags.
+
 ## Anti-Patterns
 
 - ❌ `web_fetch`/`web_search` on github.com — returns HTML noise, wastes thousands of tokens for zero useful information
@@ -176,6 +183,8 @@ AND matching is almost always what agents want. `gh search code "useState fetchD
 - **Batch file reads.** `ghx read owner/repo f1 f2 f3` = 1 API call. Three separate reads = 3 calls.
 - **Map before reading.** `ghx read --map` first to understand structure, then `--grep` or `--lines` for specifics.
 - **Refine search, don't paginate.** If `ghx search` shows "201472 results (showing 30)", add qualifiers (`repo:`, `language:`, `path:`) — don't try to page through. 9 req/min rate limit makes pagination expensive.
+- **Use `--limit` to control token budget.** `ghx repos "query" --limit 5` for quick checks, `--limit 15` for thorough discovery. `ghx search "query" --limit 10` when you only need top results.
+- **Check exit codes.** 0 = got results, 1 = no results (query was valid, broaden it), 2 = usage error (fix your command).
 - **Use `gh api --cache 1h`** for repeated lookups when using raw `gh` commands.
 - **Use `--json fields --jq 'expr'`** on `gh` commands to get structured output and reduce noise.
 - **Piped output is machine-formatted.** Tab-delimited, no truncation, no color codes — agents always get clean output.

package/ghx

@@ -5,6 +5,8 @@
 
 set -euo pipefail
 
+VERSION="0.2.1"
+
 cmd="${1:-help}"
 shift || true
 
@@ -73,13 +75,14 @@ read)
       --grep) grep_pattern="$2"; shift 2 ;;
       --lines) line_range="$2"; shift 2 ;;
       --map) map_mode=1; shift ;;
+      --*) echo "ghx read: unknown flag '$1'" >&2; exit 2 ;;
       *) files+=("$1"); shift ;;
     esac
   done
 
   if [[ ${#files[@]} -eq 0 ]]; then
     echo "Usage: ghx read <owner/repo> <path1> [path2] [--grep pattern] [--lines N-M]" >&2
-    exit 1
+    exit 2
   fi
 
   # Get default branch
@@ -136,28 +139,37 @@ read)
 search)
   # Parse flags
   full_mode=""
+  limit=""
   args=()
-  for arg in "$@"; do
-    case "$arg" in
-      --full) full_mode=1 ;;
-      *) args+=("$arg") ;;
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --full) full_mode=1; shift ;;
+      --limit) [[ $# -lt 2 ]] && { echo "ghx search: --limit requires a value" >&2; exit 2; }
+        limit="$2"; shift 2 ;;
+      --*) echo "ghx search: unknown flag '$1'" >&2; exit 2 ;;
+      *) args+=("$1"); shift ;;
     esac
   done
   query="${args[*]}"
   if [[ -z "$query" ]]; then
-    echo "Usage: ghx search <query> [--full]" >&2
+    echo "Usage: ghx search <query> [--full] [--limit N]" >&2
     echo "Examples: 'useState repo:owner/repo' | 'path:src/ extension:tsx language:typescript'" >&2
-    exit 1
+    exit 2
+  fi
+  # Validate and clamp limit (API max: 100)
+  if [[ -n "$limit" ]]; then
+    [[ "$limit" =~ ^[0-9]+$ ]] || { echo "ghx search: --limit must be a number, got '$limit'" >&2; exit 2; }
+    (( limit > 100 )) && { echo "⚠ --limit clamped to 100 (API max)" >&2; limit=100; }
   fi
 
   # Prerequisite checks
   if ! command -v gh &>/dev/null; then
     echo "ghx requires the GitHub CLI (gh). Install: https://cli.github.com" >&2
-    exit 1
+    exit 2
   fi
   if ! gh auth status &>/dev/null; then
     echo "GitHub code search requires authentication. Run: gh auth login" >&2
-    exit 1
+    exit 2
   fi
 
   # Warn on web-only qualifiers (they silently become literal text in REST API)
@@ -168,9 +180,10 @@ search)
   done
 
   # Search with text_matches for matching context
+  per_page="${limit:-30}"
   response=$(gh api /search/code --method GET \
     -H "Accept: application/vnd.github.text-match+json" \
-    -f q="$query" 2>&1) || {
+    -f q="$query" -f per_page="$per_page" 2>&1) || {
     echo "$response" >&2
     exit 1
   }
@@ -182,6 +195,7 @@ search)
   echo "$total results (showing $count)" >&2
   [[ "$incomplete" == "true" ]] && echo "⚠ Results may be incomplete (query timed out)" >&2
   [[ "$total" -gt 1000 ]] 2>/dev/null && echo "⚠ Query too broad — add repo:, language:, or path: to narrow" >&2
+  [[ "$count" -eq 0 ]] && exit 1
 
   # Output: repo path: matching context from fragment
   # Default: 200 char window centered on the match (prevents minified JS token explosion)
@@ -233,15 +247,29 @@ search)
 
 # ─── repos: search repos with README preview in 1 GraphQL call ───
 repos)
-  query="$*"
+  limit=""
+  args=()
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --limit) [[ $# -lt 2 ]] && { echo "ghx repos: --limit requires a value" >&2; exit 2; }
+        limit="$2"; shift 2 ;;
+      --*) echo "ghx repos: unknown flag '$1'" >&2; exit 2 ;;
+      *) args+=("$1"); shift ;;
+    esac
+  done
+  query="${args[*]}"
   if [[ -z "$query" ]]; then
-    echo "Usage: ghx repos <query>" >&2
-    exit 1
+    echo "Usage: ghx repos <query> [--limit N]" >&2
+    exit 2
   fi
+  # Validate and clamp limit (GraphQL max: 100, but README fetching makes >20 expensive)
+  first="${limit:-10}"
+  [[ "$first" =~ ^[0-9]+$ ]] || { echo "ghx repos: --limit must be a number, got '$first'" >&2; exit 2; }
+  (( first > 20 )) && { echo "⚠ --limit clamped to 20 (README fetching makes larger values slow)" >&2; first=20; }
 
   response=$(gh api graphql -f query='
   {
-    search(query: "'"$query"'", type: REPOSITORY, first: 5) {
+    search(query: "'"$query"'", type: REPOSITORY, first: '"$first"') {
       repositoryCount
       nodes {
         ... on Repository {
@@ -258,6 +286,8 @@ repos)
   }')
 
   echo "$response" | jq -r '.data.search.repositoryCount | "\(.) repos found"' >&2
+  count=$(echo "$response" | jq '.data.search.nodes | length')
+  [[ "$count" -eq 0 ]] && exit 1
   echo "$response" | jq -r '
     .data.search.nodes[] |
     .nameWithOwner as $name |
@@ -313,6 +343,10 @@ tree)
   ;;
 
 # ─── help ───
+version|-v|--version)
+  echo "ghx $VERSION"
+  ;;
+
 help|*)
   cat <<'EOF'
 ghx — GitHub code exploration for agents and humans
@@ -320,8 +354,8 @@ ghx — GitHub code exploration for agents and humans
 Commands:
   ghx explore <owner/repo> [path]     Branch + tree + README in 1 API call
   ghx read <owner/repo> <f1> [f2..]   Read 1-10 files in 1 API call
-  ghx repos <query>                    Search repos with README preview in 1 GraphQL call
-  ghx search "<query>"                 Code search (AND matching, qualifiers: repo: path: language: extension: filename:)
+  ghx repos <query> [--limit N]        Search repos with README preview (default: 10)
+  ghx search "<query>" [--limit N]     Code search (AND matching, default: 30)
   ghx search --full "<query>"          Code search without line truncation
   ghx skill                            Output SKILL.md (for agent context injection)
   ghx tree <owner/repo> [path]         Full recursive tree listing
@@ -329,6 +363,12 @@ Commands:
 Read flags:
   --grep <pattern>    Filter output to matching lines (case-insensitive, 2 lines context)
   --lines <N-M>       Extract specific line range
+  --map               Structural signatures only (~92% token reduction)
+
+Exit codes:
+  0  Success with results
+  1  No results (query valid, nothing matched)
+  2  Usage error (bad flags, missing args)
 
 Examples:
   ghx explore plausible/analytics

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gkoreli/ghx",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "GitHub code exploration for agents and humans. Batch file reads, code maps, search — all via gh CLI.",
   "bin": {
     "ghx": "./ghx"