@nothumanwork/wit 0.1.15

package/README.md

@@ -0,0 +1,259 @@
+# wit
+
+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`).
+
+## Status
+
+**v0.1.0** - Early development
+
+## Installation
+
+### Install from npm
+
+```bash
+npm install -g @nothumanwork/wit
+```
+
+Run without global install:
+
+```bash
+npx @nothumanwork/wit --help
+```
+
+`@nothumanwork/wit` is a single npm package. During `npm install`, its `postinstall` script detects the host platform, selects the matching bundled release archive, and extracts it into npm's bin-managed install location, so one package covers:
+- `darwin-x64`
+- `darwin-arm64`
+- `linux-x64`
+- `linux-arm64`
+- `win32-x64`
+- `win32-arm64`
+
+### Install from binary release (`.sh` installer)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/thehumanworks/wit/main/install.sh | sh
+```
+
+Install a specific version:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/thehumanworks/wit/main/install.sh | sh -s -- --version v0.1.0
+```
+
+Install to a specific bin directory:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/thehumanworks/wit/main/install.sh | sh -s -- --bin-dir ~/.local/bin
+```
+
+The installer auto-detects platform and fetches these release artifacts:
+- `wit-linux-x86_64.tar.gz`
+- `wit-linux-aarch64.tar.gz`
+- `wit-macos-x86_64.tar.gz`
+- `wit-macos-aarch64.tar.gz`
+- `wit-windows-x86_64.zip`
+- `wit-windows-aarch64.zip` (best effort; falls back to x64 in shell environments if unavailable)
+
+### Install from source
+
+```bash
+cargo install --path .
+```
+
+## Quick Start
+
+```bash
+wit search -p 'ratatui' -l 'Rust'                        # Find repos
+wit tree ratatui/ratatui                                   # See structure
+wit ls -l ratatui/ratatui src                              # Browse with sizes
+wit rg -l 'impl Widget' ratatui/ratatui                    # Find files
+wit cat -n ratatui/ratatui src/lib.rs                      # Read a file
+wit head -n 30 ratatui/ratatui Cargo.toml                  # Preview a file
+wit sed -n '100,150p' ratatui/ratatui src/lib.rs           # Extract range
+wit rg 'TODO' ratatui/ratatui --ignore '.git' --ignore '*.png'  # Exclude paths
+```
+
+## Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--ignore <PATH\|GLOB>` | Exclude files/directories/globs from file operations. Repeat the flag to provide multiple patterns. |
+
+Ignore examples:
+
+```bash
+wit tree ratatui/ratatui --ignore '.github' --ignore 'assets/**'
+wit ls ratatui/ratatui src --ignore 'generated'
+wit rg 'fn main' ratatui/ratatui --ignore '.git' --ignore '*.lock'
+wit cat ratatui/ratatui src/main.rs --ignore 'src/main.rs'   # blocked (explicitly ignored)
+```
+
+`search` accepts `--ignore`, but applies it only when `--with-snippets` is enabled.
+
+## Commands
+
+### search (alias: s)
+
+Find GitHub repositories by name and search their code via grep.app.
+
+```bash
+wit search -p 'ratatui' -l 'Rust'                  # Find Rust repos named 'ratatui'
+wit search -p 'auth' -q 'JWT' -l 'Go' -w           # Find Go auth repos using JWT, show code
+wit search -p 'ratatui' -q 'impl Widget' -w -c      # Matching lines only, no context
+```
+
+| Flag | Long | Description |
+|------|------|-------------|
+| `-p` | `--pattern` | Regex pattern to match repository names (required) |
+| `-l` | `--lang` | Filter results by language |
+| `-q` | `--query` | Code pattern to search within repos (default: `.*`) |
+| `-r` | `--regex` | Enable regex search (default: true) |
+| `-w` | `--with-snippets` | Show code snippets with context |
+| `-c` | `--compact` | Show only matching lines (requires `-w`) |
+
+### cache (alias: c)
+
+Clone a repository into the local cache (or refresh an existing one). Repos are auto-cached on first use by other commands.
+
+```bash
+wit cache ratatui/ratatui          # Force re-clone of ratatui
+```
+
+### tree (alias: t)
+
+Show the file tree of a repository (or subtree). Use `-l` for line counts and token estimates.
+
+```bash
+wit tree ratatui/ratatui                # Full repo tree
+wit tree ratatui/ratatui src/widgets    # Only the widgets subtree
+wit tree -l ratatui/ratatui src         # With line counts and token estimates
+```
+
+### ls
+
+List directory contents (non-recursive). Unlike `tree`, shows only immediate children. Use `-l` for file sizes.
+
+```bash
+wit ls ratatui/ratatui                    # List repo root
+wit ls ratatui/ratatui src/widgets        # List a subdirectory
+wit ls -l ratatui/ratatui src             # With line counts and token estimates
+```
+
+### cat
+
+Print a file's contents. For large files, prefer `head`/`tail`/`sed` to read specific ranges, or `rg` to search.
+
+```bash
+wit cat ratatui/ratatui Cargo.toml             # Print file
+wit cat -n ratatui/ratatui src/lib.rs           # With line numbers
+wit cat -b ratatui/ratatui README.md            # Number non-blank lines only
+```
+
+| Flag | Long | Description |
+|------|------|-------------|
+| `-n` | `--number` | Number all output lines |
+| `-b` | `--number-nonblank` | Number non-blank lines only (overrides -n) |
+| `-s` | `--squeeze-blank` | Suppress repeated empty lines |
+| `-E` | `--show-ends` | Show `$` at end of each line |
+| `-T` | `--show-tabs` | Show TAB as `^I` |
+| `-A` | `--show-all` | Equivalent to `-ET` |
+
+### rg
+
+Search file contents (ripgrep-style). Use `-l` to find files, `-g` to filter by type.
+
+```bash
+wit rg 'impl Widget' ratatui/ratatui              # Find implementations
+wit rg -l 'struct.*Frame' ratatui/ratatui          # List files containing pattern
+wit rg -g '*.rs' -i 'todo' ratatui/ratatui         # Case-insensitive in .rs files
+wit rg -C 3 'fn render' ratatui/ratatui             # 3 lines of context
+wit rg -l --long 'Widget' ratatui/ratatui           # File list with line counts
+```
+
+| Flag | Long | Description |
+|------|------|-------------|
+| `-i` | `--ignore-case` | Case insensitive search |
+| `-S` | `--smart-case` | Case-insensitive if pattern is all lowercase |
+| `-w` | `--word-regexp` | Match whole words only |
+| `-v` | `--invert-match` | Show non-matching lines |
+| `-m` | `--max-count` | Maximum matches to show (0 = unlimited) |
+| `-C` | `--context` | Lines of context before and after matches |
+| `-B` | `--before-context` | Lines of context before matches |
+| `-A` | `--after-context` | Lines of context after matches |
+| `-g` | `--glob` | Glob pattern to filter files (e.g., `*.rs`) |
+| `-l` | `--files-with-matches` | Only show file names with matches |
+| `-c` | `--count` | Only show count of matches per file |
+|      | `--long` | Show file sizes alongside names (useful with `-l`) |
+
+### sed
+
+Extract or transform file content using sed scripts (POSIX-style, Rust regex).
+
+```bash
+wit sed -n '320,460p' modal-labs/modal-client modal/image.py    # Print line range
+wit sed -n '/TODO/p' ratatui/ratatui src/lib.rs                 # Lines matching pattern
+wit sed 's/Widget/Component/g' ratatui/ratatui src/lib.rs       # Substitute text
+wit sed -n '/^pub fn/p' ratatui/ratatui src/lib.rs              # Extract function signatures
+```
+
+**Notes:**
+- Regex uses Rust syntax (not POSIX BRE).
+- `sed` operates on a single repo file (no stdin or in-place edits).
+- Supports addresses, substitution, hold space, branching, and most POSIX commands.
+
+### head
+
+Print the first N lines of a file (default: 10). Use to preview a file before deciding whether to read it fully.
+
+```bash
+wit head ratatui/ratatui src/lib.rs            # First 10 lines
+wit head -n 50 ratatui/ratatui Cargo.toml      # First 50 lines
+wit head -N ratatui/ratatui README.md           # With line numbers
+```
+
+### tail
+
+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.
+
+```bash
+wit tail ratatui/ratatui src/lib.rs              # Last 10 lines
+wit tail -n 20 ratatui/ratatui Cargo.toml        # Last 20 lines
+wit tail -p 100 ratatui/ratatui src/lib.rs       # From line 100 to end
+```
+
+## Packaging & Release
+
+- 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.
+- Push a semver tag (for example `v0.2.0`) to trigger `.github/workflows/release.yml`.
+- `.github/workflows/release.yml` can also be triggered manually with `workflow_dispatch` (select a `vX.Y.Z` tag ref).
+- The workflow builds and uploads `wit-<platform>-<arch>` archives plus `wit-checksums.txt` to the GitHub release.
+- `.github/workflows/publish-npm.yml` publishes `@nothumanwork/wit` from the GitHub release assets and can be re-run manually for an existing release tag without rebuilding Rust binaries.
+- `install.sh` downloads the matching archive and verifies it against the checksum manifest when available.
+
+## Architecture
+
+```
+src/
+├── cli.rs          # CLI entry point and display logic
+├── lib.rs          # Library exports
+├── sed.rs          # POSIX-style sed engine
+├── gitops/
+│   ├── mod.rs
+│   └── ops.rs      # Bare-repo caching, file access, tree, ls, head/tail, ripgrep
+└── grep/
+    ├── mod.rs
+    ├── client.rs   # grep.app API client
+    └── types.rs    # Response types and data structures
+```
+
+## Dependencies
+
+- `clap` - CLI argument parsing
+- `gix` (gitoxide) - Bare clone + tree traversal + blob reading
+- `reqwest` - HTTP client for grep.app
+- `scraper` - HTML parsing for code snippets
+- `grep-regex` / `grep-searcher` / `grep-matcher` - Ripgrep-style search on blobs
+- `ptree` - Tree display
+- `colored` - Terminal output formatting
+- `tokio` - Async runtime
+- `serde` - JSON serialization

package/bin/wit.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+"use strict";
+
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const TARGETS = {
+  "darwin-x64": {
+    "binaryFile": "wit"
+  },
+  "darwin-arm64": {
+    "binaryFile": "wit"
+  },
+  "linux-x64": {
+    "binaryFile": "wit"
+  },
+  "linux-arm64": {
+    "binaryFile": "wit"
+  },
+  "win32-x64": {
+    "binaryFile": "wit.exe"
+  },
+  "win32-arm64": {
+    "binaryFile": "wit.exe"
+  }
+};
+const PACKAGE_NAME = "@nothumanwork/wit";
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function resolveBinaryPath() {
+  const key = `${process.platform}-${process.arch}`;
+  const target = TARGETS[key];
+  if (!target) {
+    fail(`Unsupported platform/arch: ${process.platform}/${process.arch}`);
+  }
+
+  const binaryPath = path.join(__dirname, target.binaryFile);
+  try {
+    require("node:fs").accessSync(binaryPath);
+    return binaryPath;
+  } catch {
+    fail(
+      `Binary not installed for ${process.platform}/${process.arch}. Reinstall ${PACKAGE_NAME} without --ignore-scripts.`,
+    );
+  }
+}
+
+const binaryPath = resolveBinaryPath();
+const result = spawnSync(binaryPath, process.argv.slice(2), { stdio: "inherit" });
+
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+}
+
+process.exit(result.status ?? 1);

package/dists/wit-checksums.txt

@@ -0,0 +1,6 @@
+cb0f5ca02cad7aa6ca9ab72f06c28274bc1d03cd0634878ec0c7860858a324e7  wit-linux-aarch64.tar.gz
+06fcc3ba0d0827aa0cb77b2c1c26ea98526f9e2d74aaa446629b889f23271a2c  wit-linux-x86_64.tar.gz
+43322f2cd008f69e6d648c12ab2d120dc23b631fd0429424ce93eeebfd78fe2b  wit-macos-aarch64.tar.gz
+d92b487faa3e30290e69f853b2d1df067f8174d3104eacc5395ecd8b1cf2c2cc  wit-macos-x86_64.tar.gz
+339ed6145aae0a6a25d22ba3b6572b550eac278462bd463e327ddfa2c99e38b4  wit-windows-aarch64.zip
+69e55278c53bee00c7a850c58c0ca1f2fa05cc7f5709173a488aab450006401e  wit-windows-x86_64.zip

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@nothumanwork/wit",
+  "version": "0.1.15",
+  "description": "GitHub exploration CLI for AI agents",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thehumanworks/wit.git"
+  },
+  "homepage": "https://github.com/thehumanworks/wit#readme",
+  "bugs": {
+    "url": "https://github.com/thehumanworks/wit/issues"
+  },
+  "bin": {
+    "wit": "bin/wit.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/wit.js",
+    "scripts/postinstall.js",
+    "README.md",
+    "dists/*"
+  ]
+}

package/scripts/postinstall.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const fsp = require("node:fs/promises");
+const os = require("node:os");
+const path = require("node:path");
+const { createHash } = require("node:crypto");
+const { spawnSync } = require("node:child_process");
+const packageJson = require("../package.json");
+
+const TARGETS = {
+  "darwin-x64": {
+    "artifact": "wit-macos-x86_64.tar.gz",
+    "binaryFile": "wit"
+  },
+  "darwin-arm64": {
+    "artifact": "wit-macos-aarch64.tar.gz",
+    "binaryFile": "wit"
+  },
+  "linux-x64": {
+    "artifact": "wit-linux-x86_64.tar.gz",
+    "binaryFile": "wit"
+  },
+  "linux-arm64": {
+    "artifact": "wit-linux-aarch64.tar.gz",
+    "binaryFile": "wit"
+  },
+  "win32-x64": {
+    "artifact": "wit-windows-x86_64.zip",
+    "binaryFile": "wit.exe"
+  },
+  "win32-arm64": {
+    "artifact": "wit-windows-aarch64.zip",
+    "binaryFile": "wit.exe"
+  }
+};
+const BINARY_NAME = "wit";
+const PACKAGE_NAME = "@nothumanwork/wit";
+const REPOSITORY_URL = "https://github.com/thehumanworks/wit";
+const CHECKSUM_FILE = "wit-checksums.txt";
+
+function log(message) {
+  console.log(`${PACKAGE_NAME}: ${message}`);
+}
+
+function warn(message) {
+  console.warn(`${PACKAGE_NAME}: ${message}`);
+}
+
+function fail(message) {
+  console.error(`${PACKAGE_NAME}: ${message}`);
+  process.exit(1);
+}
+
+function resolveTarget() {
+  const key = `${process.platform}-${process.arch}`;
+  const target = TARGETS[key];
+  if (!target) {
+    fail(
+      `unsupported platform/arch: ${process.platform}/${process.arch}. Install from ${REPOSITORY_URL}/releases instead.`,
+    );
+  }
+  return target;
+}
+
+async function sha256(filePath) {
+  return new Promise((resolve, reject) => {
+    const hash = createHash("sha256");
+    const stream = fs.createReadStream(filePath);
+
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("end", () => resolve(hash.digest("hex")));
+    stream.on("error", reject);
+  });
+}
+
+function parseChecksums(rawManifest) {
+  const manifest = new Map();
+  for (const line of rawManifest.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+
+    const match = trimmed.match(/^([a-f0-9]{64})\s+\*?(.+)$/i);
+    if (!match) {
+      throw new Error(`invalid checksum entry: ${trimmed}`);
+    }
+    manifest.set(match[2], match[1]);
+  }
+  return manifest;
+}
+
+function runCommand(command, args) {
+  const result = spawnSync(command, args, { stdio: "inherit" });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new Error(`command failed (${result.status}): ${command} ${args.join(" ")}`);
+  }
+}
+
+function extractArchive(archivePath, destination) {
+  if (archivePath.endsWith(".tar.gz")) {
+    runCommand("tar", ["-xzf", archivePath, "-C", destination]);
+    return;
+  }
+
+  if (archivePath.endsWith(".zip")) {
+    runCommand(
+      "powershell.exe",
+      [
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        "Expand-Archive -LiteralPath $args[0] -DestinationPath $args[1] -Force",
+        archivePath,
+        destination,
+      ],
+    );
+    return;
+  }
+
+  throw new Error(`unsupported archive format: ${archivePath}`);
+}
+
+async function findFile(rootDir, fileName) {
+  const entries = await fsp.readdir(rootDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(rootDir, entry.name);
+    if (entry.isFile() && entry.name === fileName) {
+      return fullPath;
+    }
+    if (entry.isDirectory()) {
+      const nested = await findFile(fullPath, fileName);
+      if (nested) {
+        return nested;
+      }
+    }
+  }
+  return null;
+}
+
+async function installBinary({ target }) {
+  const packageRoot = path.resolve(__dirname, "..");
+  const binDir = path.join(packageRoot, "bin");
+  const distsDir = path.join(packageRoot, "dists");
+  const binaryPath = path.join(binDir, target.binaryFile);
+  const tempDir = await fsp.mkdtemp(path.join(os.tmpdir(), "wit-npm-"));
+  const archivePath = path.join(distsDir, target.artifact);
+  const checksumsPath = path.join(distsDir, CHECKSUM_FILE);
+  const extractDir = path.join(tempDir, "extract");
+
+  try {
+    log(`installing ${target.artifact} for ${process.platform}/${process.arch}`);
+    await fsp.access(archivePath);
+
+    const checksums = parseChecksums(await fsp.readFile(checksumsPath, "utf8"));
+    const expectedChecksum = checksums.get(target.artifact);
+    if (!expectedChecksum) {
+      throw new Error(`checksum entry missing for ${target.artifact}`);
+    }
+
+    const actualChecksum = await sha256(archivePath);
+    if (actualChecksum !== expectedChecksum) {
+      throw new Error(`checksum mismatch for ${target.artifact}`);
+    }
+
+    await fsp.mkdir(extractDir, { recursive: true });
+    extractArchive(archivePath, extractDir);
+
+    const sourceBinary =
+      (await findFile(extractDir, target.binaryFile)) || path.join(extractDir, target.binaryFile);
+    await fsp.access(sourceBinary);
+
+    await fsp.mkdir(binDir, { recursive: true });
+    await fsp.rm(binaryPath, { force: true });
+    await fsp.copyFile(sourceBinary, binaryPath);
+    if (!binaryPath.endsWith(".exe")) {
+      await fsp.chmod(binaryPath, 0o755);
+    }
+
+    log(`installed ${BINARY_NAME} ${packageJson.version}`);
+  } finally {
+    await fsp.rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+async function main() {
+  const target = resolveTarget();
+  await installBinary({ target });
+}
+
+main().catch((error) => {
+  fail(error instanceof Error ? error.message : String(error));
+});