@gkoreli/ghx 2.1.12 → 2.1.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +29 -8
  2. package/package.json +7 -7
package/README.md CHANGED
@@ -4,9 +4,23 @@ One command does what takes 3-5 API calls. Batch file reads, code maps, search
4
4
 
5
5
  ## Why
6
6
 
7
- AI agents exploring GitHub face a reliability gap: *"Did I find nothing because nothing exists, or because I used the tool wrong?"* Raw `gh` commands have silent failure modes — `gh search code` wraps in quotes without telling you, `gh api contents/` returns base64, README requires a separate call. The agent can't distinguish "no results" from "wrong flags."
7
+ An agent wants to understand `packages/shadcn/src/utils/` in [shadcn-ui/ui](https://github.com/shadcn-ui/ui):
8
8
 
9
- ghx eliminates this by encoding the right defaults into every command. One call returns enough context to decide the next action.
9
+ **With `gh` CLI** — 4 turns, 4 API calls, reads 3 full files (3,761 tokens), sees 3 of 34 files:
10
+ ```
11
+ gh api /repos/shadcn-ui/ui/contents/packages/shadcn/src/utils → JSON with shas, urls, links (480 tokens for a file list)
12
+ gh api /repos/.../get-config.ts --jq '.content' | base64 -d → full file (1,981 tokens — agent only needed exports)
13
+ gh api /repos/.../registries.ts --jq '.content' | base64 -d → full file (676 tokens)
14
+ gh api /repos/.../frameworks.ts --jq '.content' | base64 -d → full file (624 tokens)
15
+ ```
16
+
17
+ **With ghx** — 2 turns, 2 API calls, maps 10 files (3,058 tokens), sees signatures of all 10:
18
+ ```
19
+ ghx read shadcn-ui/ui packages/shadcn/src/utils → directory listing (199 tokens)
20
+ ghx read shadcn-ui/ui "packages/shadcn/src/utils/*.ts" --map → signatures of 10 files (2,859 tokens)
21
+ ```
22
+
23
+ Same token budget. The `gh` agent read 3 full files. The ghx agent saw the structure of 10 — imports, exports, function signatures — and knows which ones to drill into. Pass a file, get content. Pass a directory, get a listing. Pass a glob, get matching files. Same command, always useful output.
10
24
 
11
25
  | Tool | Files per call | Matching context | Programmable | Dependencies |
12
26
  |------|---------------|-----------------|-------------|-------------|
@@ -56,8 +70,12 @@ No install step — npx downloads and caches the binary on first run.
56
70
  ghx explore <owner/repo> # Branch + tree + README in 1 API call
57
71
  ghx explore <owner/repo> <path> # Subdirectory listing
58
72
  ghx read <owner/repo> <f1> [f2] [f3] # Read 1-10 files (GraphQL batching)
73
+ ghx read <owner/repo> <dir> # Directory path → returns file listing
59
74
  ghx read <owner/repo> "src/**/*.ts" --map # Glob patterns with structural map
60
- ghx read <owner/repo> --map <f1> [f2] # Signatures, imports, types (~92% token reduction)
75
+ ghx read <owner/repo> --map <f1> [f2] # Parser-backed structural map (~92% token reduction)
76
+ ghx read <owner/repo> --map --kind func <f> # Map only functions/methods
77
+ ghx read <owner/repo> --map --kind type <f> # Map only types/structs/interfaces
78
+ ghx read <owner/repo> --map --level minimal <f> # Symbol names only (e.g. UserService.GetUser)
61
79
  ghx read <owner/repo> --grep "pat" <f> # Matching lines only (ERE regex, 2 lines context)
62
80
  ghx read <owner/repo> --lines 42-80 <f> # Specific line range
63
81
  ghx search "<query>" # Code search with matching lines
@@ -114,11 +132,13 @@ Designed for eager context injection via spawn hooks — the agent always has th
114
132
 
115
133
  ## How It Was Built
116
134
 
117
- 23 agent sessions, 2,500+ conversation turns, 3 rewrites, 10 ADRs. The full story: **[Build the GitHub Exploration Tool, No Mistakes](https://gkoreli.com/how-ghx-was-born)**
135
+ 23 agent sessions, 2,500+ conversation turns, 3 rewrites, 12 ADRs. The full story: **[Build the GitHub Exploration Tool, No Mistakes](https://gkoreli.com/how-ghx-was-born)**
118
136
 
119
137
  ## How It Works
120
138
 
121
- Wraps `gh` CLI with GraphQL batching. `repos` and `explore` batch search + metadata + README into 1 call. `read` uses GraphQL aliases to fetch up to 10 files in 1 call. Glob patterns (`src/**/*.ts`) auto-expand via tree fetch + [doublestar](https://github.com/bmatcuk/doublestar) matching in 2 API calls. `--grep` uses ERE regex with BRE normalization (agents trained on `grep` write `\|` for alternation — both styles work). `search` hits REST `/search/code` with `text_matches` for matching context and 200-char token protection.
139
+ Wraps `gh` CLI with GraphQL batching. `repos` and `explore` batch search + metadata + README into 1 call. `read` uses GraphQL aliases to fetch up to 10 files in 1 call — and if a path is a directory, returns its file listing instead of "not found" (via `... on Tree` inline fragments in the same query, zero extra API calls). Glob patterns (`src/**/*.ts`) auto-expand via tree fetch + [doublestar](https://github.com/bmatcuk/doublestar) matching in 2 API calls. `--grep` uses ERE regex with BRE normalization (agents trained on `grep` write `\|` for alternation — both styles work). `search` hits REST `/search/code` with `text_matches` for matching context and 200-char token protection.
140
+
141
+ `--map` runs a dedicated parser engine on the fetched content — no extra API calls. Engine selection is automatic: **Go** uses `go/ast` (top-level declarations only, full multi-line signatures, generics preserved), **TypeScript, JavaScript, Python, Rust** use [gotreesitter](https://github.com/odvcencio/gotreesitter) (captures class/impl methods that regex cannot reach), everything else falls back to regex. Methods carry a parent reference (`UserService.GetUser`) visible at `--level minimal`. `--map-engine regex` forces the fallback for any file.
122
142
 
123
143
  Codemode runs JS in a [goja](https://github.com/nicholasgasior/goja) sandbox with esbuild TypeScript transpilation. Tools are injected as synchronous functions on a `codemode` global object. Max 20 tool calls per execution, 64KB code size limit.
124
144
 
@@ -126,9 +146,10 @@ Codemode runs JS in a [goja](https://github.com/nicholasgasior/goja) sandbox wit
126
146
 
127
147
  ```
128
148
  v2/
129
- ├── pkg/ghx/ — core library (Explore, Read, Search, Repos, Tree, Glob)
130
- ├── pkg/codemode/ — JS executor (goja sandbox, TS transpilation, type generation)
131
- └── cmd/ — CLI frontend (cobra) + MCP server (mcp-go)
149
+ ├── internal/mapengine/ — parser-backed map engine (GoAST, TreeSitter, Regex, engine routing)
150
+ ├── pkg/ghx/ — core library (Explore, Read, Search, Repos, Tree, Glob)
151
+ ├── pkg/codemode/ — JS executor (goja sandbox, TS transpilation, type generation)
152
+ └── cmd/ — CLI frontend (cobra) + MCP server (mcp-go)
132
153
  ```
133
154
 
134
155
  See [docs/adr/](docs/adr/) for architectural decisions.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gkoreli/ghx",
3
- "version": "2.1.12",
3
+ "version": "2.1.16",
4
4
  "description": "Agent-first GitHub code exploration. GraphQL batching, code maps, codemode TypeScript sandbox, MCP server.",
5
5
  "bin": {
6
6
  "ghx": "npm/bin/ghx"
@@ -27,11 +27,11 @@
27
27
  "node": ">=16"
28
28
  },
29
29
  "optionalDependencies": {
30
- "@gkoreli/ghx-darwin-arm64": "2.1.12",
31
- "@gkoreli/ghx-darwin-x64": "2.1.12",
32
- "@gkoreli/ghx-linux-arm64": "2.1.12",
33
- "@gkoreli/ghx-linux-x64": "2.1.12",
34
- "@gkoreli/ghx-win32-arm64": "2.1.12",
35
- "@gkoreli/ghx-win32-x64": "2.1.12"
30
+ "@gkoreli/ghx-darwin-arm64": "2.1.16",
31
+ "@gkoreli/ghx-darwin-x64": "2.1.16",
32
+ "@gkoreli/ghx-linux-arm64": "2.1.16",
33
+ "@gkoreli/ghx-linux-x64": "2.1.16",
34
+ "@gkoreli/ghx-win32-arm64": "2.1.16",
35
+ "@gkoreli/ghx-win32-x64": "2.1.16"
36
36
  }
37
37
  }