@rodat.dev/wit 0.1.11
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.
- package/README.md +260 -0
- package/bin/wit.js +64 -0
- package/package.json +31 -0
package/README.md
ADDED
|
@@ -0,0 +1,260 @@
|
|
|
1
|
+
# wit
|
|
2
|
+
|
|
3
|
+
GitHub for AI Agents -- explore GitHub repositories without cloning. Repos are cached as shallow bare clones under your system temp directory by default (override with `WIT_CACHE_DIR`).
|
|
4
|
+
|
|
5
|
+
## Status
|
|
6
|
+
|
|
7
|
+
**v0.1.0** - Early development
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
10
|
+
|
|
11
|
+
### Install from npm
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm install -g @thehumanworks/wit
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Run without global install:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npx @thehumanworks/wit --help
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
`@thehumanworks/wit` currently publishes native npm binaries for:
|
|
24
|
+
- `darwin-x64`
|
|
25
|
+
- `darwin-arm64`
|
|
26
|
+
- `linux-x64`
|
|
27
|
+
- `linux-arm64`
|
|
28
|
+
- `win32-x64`
|
|
29
|
+
|
|
30
|
+
`win32-arm64` remains available via GitHub release archives and `install.sh`.
|
|
31
|
+
|
|
32
|
+
### Install from binary release (`.sh` installer)
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
curl -fsSL https://raw.githubusercontent.com/thehumanworks/wit/main/install.sh | sh
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Install a specific version:
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
curl -fsSL https://raw.githubusercontent.com/thehumanworks/wit/main/install.sh | sh -s -- --version v0.1.0
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Install to a specific bin directory:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
curl -fsSL https://raw.githubusercontent.com/thehumanworks/wit/main/install.sh | sh -s -- --bin-dir ~/.local/bin
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The installer auto-detects platform and fetches these release artifacts:
|
|
51
|
+
- `wit-linux-x86_64.tar.gz`
|
|
52
|
+
- `wit-linux-aarch64.tar.gz`
|
|
53
|
+
- `wit-macos-x86_64.tar.gz`
|
|
54
|
+
- `wit-macos-aarch64.tar.gz`
|
|
55
|
+
- `wit-windows-x86_64.zip`
|
|
56
|
+
- `wit-windows-aarch64.zip` (best effort; falls back to x64 in shell environments if unavailable)
|
|
57
|
+
|
|
58
|
+
### Install from source
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
cargo install --path .
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Quick Start
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
wit search -p 'ratatui' -l 'Rust' # Find repos
|
|
68
|
+
wit tree ratatui/ratatui # See structure
|
|
69
|
+
wit ls -l ratatui/ratatui src # Browse with sizes
|
|
70
|
+
wit rg -l 'impl Widget' ratatui/ratatui # Find files
|
|
71
|
+
wit cat -n ratatui/ratatui src/lib.rs # Read a file
|
|
72
|
+
wit head -n 30 ratatui/ratatui Cargo.toml # Preview a file
|
|
73
|
+
wit sed -n '100,150p' ratatui/ratatui src/lib.rs # Extract range
|
|
74
|
+
wit rg 'TODO' ratatui/ratatui --ignore '.git' --ignore '*.png' # Exclude paths
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Global Options
|
|
78
|
+
|
|
79
|
+
| Flag | Description |
|
|
80
|
+
|------|-------------|
|
|
81
|
+
| `--ignore <PATH\|GLOB>` | Exclude files/directories/globs from file operations. Repeat the flag to provide multiple patterns. |
|
|
82
|
+
|
|
83
|
+
Ignore examples:
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
wit tree ratatui/ratatui --ignore '.github' --ignore 'assets/**'
|
|
87
|
+
wit ls ratatui/ratatui src --ignore 'generated'
|
|
88
|
+
wit rg 'fn main' ratatui/ratatui --ignore '.git' --ignore '*.lock'
|
|
89
|
+
wit cat ratatui/ratatui src/main.rs --ignore 'src/main.rs' # blocked (explicitly ignored)
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
`search` accepts `--ignore`, but applies it only when `--with-snippets` is enabled.
|
|
93
|
+
|
|
94
|
+
## Commands
|
|
95
|
+
|
|
96
|
+
### search (alias: s)
|
|
97
|
+
|
|
98
|
+
Find GitHub repositories by name and search their code via grep.app.
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
wit search -p 'ratatui' -l 'Rust' # Find Rust repos named 'ratatui'
|
|
102
|
+
wit search -p 'auth' -q 'JWT' -l 'Go' -w # Find Go auth repos using JWT, show code
|
|
103
|
+
wit search -p 'ratatui' -q 'impl Widget' -w -c # Matching lines only, no context
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
| Flag | Long | Description |
|
|
107
|
+
|------|------|-------------|
|
|
108
|
+
| `-p` | `--pattern` | Regex pattern to match repository names (required) |
|
|
109
|
+
| `-l` | `--lang` | Filter results by language |
|
|
110
|
+
| `-q` | `--query` | Code pattern to search within repos (default: `.*`) |
|
|
111
|
+
| `-r` | `--regex` | Enable regex search (default: true) |
|
|
112
|
+
| `-w` | `--with-snippets` | Show code snippets with context |
|
|
113
|
+
| `-c` | `--compact` | Show only matching lines (requires `-w`) |
|
|
114
|
+
|
|
115
|
+
### cache (alias: c)
|
|
116
|
+
|
|
117
|
+
Clone a repository into the local cache (or refresh an existing one). Repos are auto-cached on first use by other commands.
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
wit cache ratatui/ratatui # Force re-clone of ratatui
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### tree (alias: t)
|
|
124
|
+
|
|
125
|
+
Show the file tree of a repository (or subtree). Use `-l` for line counts and token estimates.
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
wit tree ratatui/ratatui # Full repo tree
|
|
129
|
+
wit tree ratatui/ratatui src/widgets # Only the widgets subtree
|
|
130
|
+
wit tree -l ratatui/ratatui src # With line counts and token estimates
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### ls
|
|
134
|
+
|
|
135
|
+
List directory contents (non-recursive). Unlike `tree`, shows only immediate children. Use `-l` for file sizes.
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
wit ls ratatui/ratatui # List repo root
|
|
139
|
+
wit ls ratatui/ratatui src/widgets # List a subdirectory
|
|
140
|
+
wit ls -l ratatui/ratatui src # With line counts and token estimates
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### cat
|
|
144
|
+
|
|
145
|
+
Print a file's contents. For large files, prefer `head`/`tail`/`sed` to read specific ranges, or `rg` to search.
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
wit cat ratatui/ratatui Cargo.toml # Print file
|
|
149
|
+
wit cat -n ratatui/ratatui src/lib.rs # With line numbers
|
|
150
|
+
wit cat -b ratatui/ratatui README.md # Number non-blank lines only
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
| Flag | Long | Description |
|
|
154
|
+
|------|------|-------------|
|
|
155
|
+
| `-n` | `--number` | Number all output lines |
|
|
156
|
+
| `-b` | `--number-nonblank` | Number non-blank lines only (overrides -n) |
|
|
157
|
+
| `-s` | `--squeeze-blank` | Suppress repeated empty lines |
|
|
158
|
+
| `-E` | `--show-ends` | Show `$` at end of each line |
|
|
159
|
+
| `-T` | `--show-tabs` | Show TAB as `^I` |
|
|
160
|
+
| `-A` | `--show-all` | Equivalent to `-ET` |
|
|
161
|
+
|
|
162
|
+
### rg
|
|
163
|
+
|
|
164
|
+
Search file contents (ripgrep-style). Use `-l` to find files, `-g` to filter by type.
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
wit rg 'impl Widget' ratatui/ratatui # Find implementations
|
|
168
|
+
wit rg -l 'struct.*Frame' ratatui/ratatui # List files containing pattern
|
|
169
|
+
wit rg -g '*.rs' -i 'todo' ratatui/ratatui # Case-insensitive in .rs files
|
|
170
|
+
wit rg -C 3 'fn render' ratatui/ratatui # 3 lines of context
|
|
171
|
+
wit rg -l --long 'Widget' ratatui/ratatui # File list with line counts
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
| Flag | Long | Description |
|
|
175
|
+
|------|------|-------------|
|
|
176
|
+
| `-i` | `--ignore-case` | Case insensitive search |
|
|
177
|
+
| `-S` | `--smart-case` | Case-insensitive if pattern is all lowercase |
|
|
178
|
+
| `-w` | `--word-regexp` | Match whole words only |
|
|
179
|
+
| `-v` | `--invert-match` | Show non-matching lines |
|
|
180
|
+
| `-m` | `--max-count` | Maximum matches to show (0 = unlimited) |
|
|
181
|
+
| `-C` | `--context` | Lines of context before and after matches |
|
|
182
|
+
| `-B` | `--before-context` | Lines of context before matches |
|
|
183
|
+
| `-A` | `--after-context` | Lines of context after matches |
|
|
184
|
+
| `-g` | `--glob` | Glob pattern to filter files (e.g., `*.rs`) |
|
|
185
|
+
| `-l` | `--files-with-matches` | Only show file names with matches |
|
|
186
|
+
| `-c` | `--count` | Only show count of matches per file |
|
|
187
|
+
| | `--long` | Show file sizes alongside names (useful with `-l`) |
|
|
188
|
+
|
|
189
|
+
### sed
|
|
190
|
+
|
|
191
|
+
Extract or transform file content using sed scripts (POSIX-style, Rust regex).
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
wit sed -n '320,460p' modal-labs/modal-client modal/image.py # Print line range
|
|
195
|
+
wit sed -n '/TODO/p' ratatui/ratatui src/lib.rs # Lines matching pattern
|
|
196
|
+
wit sed 's/Widget/Component/g' ratatui/ratatui src/lib.rs # Substitute text
|
|
197
|
+
wit sed -n '/^pub fn/p' ratatui/ratatui src/lib.rs # Extract function signatures
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
**Notes:**
|
|
201
|
+
- Regex uses Rust syntax (not POSIX BRE).
|
|
202
|
+
- `sed` operates on a single repo file (no stdin or in-place edits).
|
|
203
|
+
- Supports addresses, substitution, hold space, branching, and most POSIX commands.
|
|
204
|
+
|
|
205
|
+
### head
|
|
206
|
+
|
|
207
|
+
Print the first N lines of a file (default: 10). Use to preview a file before deciding whether to read it fully.
|
|
208
|
+
|
|
209
|
+
```bash
|
|
210
|
+
wit head ratatui/ratatui src/lib.rs # First 10 lines
|
|
211
|
+
wit head -n 50 ratatui/ratatui Cargo.toml # First 50 lines
|
|
212
|
+
wit head -N ratatui/ratatui README.md # With line numbers
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
### tail
|
|
216
|
+
|
|
217
|
+
Print the last N lines of a file, or from line N onward. Use `-p` to read from a specific line to end-of-file.
|
|
218
|
+
|
|
219
|
+
```bash
|
|
220
|
+
wit tail ratatui/ratatui src/lib.rs # Last 10 lines
|
|
221
|
+
wit tail -n 20 ratatui/ratatui Cargo.toml # Last 20 lines
|
|
222
|
+
wit tail -p 100 ratatui/ratatui src/lib.rs # From line 100 to end
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
## Packaging & Release
|
|
226
|
+
|
|
227
|
+
- Every push to `main` triggers `.github/workflows/auto-tag.yml`, which increments the patch version in `Cargo.toml`, creates a new `vX.Y.Z` tag, and pushes it.
|
|
228
|
+
- Push a semver tag (for example `v0.2.0`) to trigger `.github/workflows/release.yml`.
|
|
229
|
+
- `.github/workflows/release.yml` can also be triggered manually with `workflow_dispatch` (select a `vX.Y.Z` tag ref).
|
|
230
|
+
- The workflow builds and uploads `wit-<platform>-<arch>` archives plus `wit-checksums.txt` to the GitHub release.
|
|
231
|
+
- The same tag flow publishes npm platform packages first and then publishes `@thehumanworks/wit`.
|
|
232
|
+
- `install.sh` downloads the matching archive and verifies it against the checksum manifest when available.
|
|
233
|
+
|
|
234
|
+
## Architecture
|
|
235
|
+
|
|
236
|
+
```
|
|
237
|
+
src/
|
|
238
|
+
├── cli.rs # CLI entry point and display logic
|
|
239
|
+
├── lib.rs # Library exports
|
|
240
|
+
├── sed.rs # POSIX-style sed engine
|
|
241
|
+
├── gitops/
|
|
242
|
+
│ ├── mod.rs
|
|
243
|
+
│ └── ops.rs # Bare-repo caching, file access, tree, ls, head/tail, ripgrep
|
|
244
|
+
└── grep/
|
|
245
|
+
├── mod.rs
|
|
246
|
+
├── client.rs # grep.app API client
|
|
247
|
+
└── types.rs # Response types and data structures
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
## Dependencies
|
|
251
|
+
|
|
252
|
+
- `clap` - CLI argument parsing
|
|
253
|
+
- `gix` (gitoxide) - Bare clone + tree traversal + blob reading
|
|
254
|
+
- `reqwest` - HTTP client for grep.app
|
|
255
|
+
- `scraper` - HTML parsing for code snippets
|
|
256
|
+
- `grep-regex` / `grep-searcher` / `grep-matcher` - Ripgrep-style search on blobs
|
|
257
|
+
- `ptree` - Tree display
|
|
258
|
+
- `colored` - Terminal output formatting
|
|
259
|
+
- `tokio` - Async runtime
|
|
260
|
+
- `serde` - JSON serialization
|
package/bin/wit.js
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
"use strict";
|
|
3
|
+
|
|
4
|
+
const { spawnSync } = require("node:child_process");
|
|
5
|
+
|
|
6
|
+
const TARGETS = {
|
|
7
|
+
"darwin-x64": {
|
|
8
|
+
"packageName": "@rodat.dev/wit-darwin-x64",
|
|
9
|
+
"binaryFile": "wit"
|
|
10
|
+
},
|
|
11
|
+
"darwin-arm64": {
|
|
12
|
+
"packageName": "@rodat.dev/wit-darwin-arm64",
|
|
13
|
+
"binaryFile": "wit"
|
|
14
|
+
},
|
|
15
|
+
"linux-x64": {
|
|
16
|
+
"packageName": "@rodat.dev/wit-linux-x64",
|
|
17
|
+
"binaryFile": "wit"
|
|
18
|
+
},
|
|
19
|
+
"linux-arm64": {
|
|
20
|
+
"packageName": "@rodat.dev/wit-linux-arm64",
|
|
21
|
+
"binaryFile": "wit"
|
|
22
|
+
},
|
|
23
|
+
"win32-x64": {
|
|
24
|
+
"packageName": "@rodat.dev/wit-win32-x64",
|
|
25
|
+
"binaryFile": "wit.exe"
|
|
26
|
+
}
|
|
27
|
+
};
|
|
28
|
+
|
|
29
|
+
function fail(message) {
|
|
30
|
+
console.error(message);
|
|
31
|
+
process.exit(1);
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
function resolveBinary() {
|
|
35
|
+
const key = `${process.platform}-${process.arch}`;
|
|
36
|
+
const target = TARGETS[key];
|
|
37
|
+
if (!target) {
|
|
38
|
+
fail(
|
|
39
|
+
`Unsupported platform/arch: ${process.platform}/${process.arch}. Install from GitHub releases: https://github.com/thehumanworks/wit/releases`,
|
|
40
|
+
);
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
try {
|
|
44
|
+
return require.resolve(`${target.packageName}/bin/${target.binaryFile}`);
|
|
45
|
+
} catch (error) {
|
|
46
|
+
fail(
|
|
47
|
+
`Unable to resolve native binary package ${target.packageName}. Try reinstalling @rodat.dev/wit.`,
|
|
48
|
+
);
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
const binaryPath = resolveBinary();
|
|
53
|
+
const result = spawnSync(binaryPath, process.argv.slice(2), { stdio: "inherit" });
|
|
54
|
+
|
|
55
|
+
if (result.error) {
|
|
56
|
+
console.error(result.error.message);
|
|
57
|
+
process.exit(1);
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
if (result.signal) {
|
|
61
|
+
process.kill(process.pid, result.signal);
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
process.exit(result.status ?? 1);
|
package/package.json
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@rodat.dev/wit",
|
|
3
|
+
"version": "0.1.11",
|
|
4
|
+
"description": "GitHub exploration CLI for AI agents",
|
|
5
|
+
"license": "UNLICENSED",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "https://github.com/thehumanworks/wit.git"
|
|
9
|
+
},
|
|
10
|
+
"homepage": "https://github.com/thehumanworks/wit#readme",
|
|
11
|
+
"bugs": {
|
|
12
|
+
"url": "https://github.com/thehumanworks/wit/issues"
|
|
13
|
+
},
|
|
14
|
+
"bin": {
|
|
15
|
+
"wit": "bin/wit.js"
|
|
16
|
+
},
|
|
17
|
+
"engines": {
|
|
18
|
+
"node": ">=18"
|
|
19
|
+
},
|
|
20
|
+
"files": [
|
|
21
|
+
"bin/wit.js",
|
|
22
|
+
"README.md"
|
|
23
|
+
],
|
|
24
|
+
"optionalDependencies": {
|
|
25
|
+
"@rodat.dev/wit-darwin-x64": "0.1.11",
|
|
26
|
+
"@rodat.dev/wit-darwin-arm64": "0.1.11",
|
|
27
|
+
"@rodat.dev/wit-linux-x64": "0.1.11",
|
|
28
|
+
"@rodat.dev/wit-linux-arm64": "0.1.11",
|
|
29
|
+
"@rodat.dev/wit-win32-x64": "0.1.11"
|
|
30
|
+
}
|
|
31
|
+
}
|