aiseerr 1.0.0

package/AGENTS.md

@@ -0,0 +1,14 @@
+# AI Agent Rules
+
+<!-- ai-xray:start -->
+## Project Context Protocol (powered by ai-xray)
+
+Before modifying this project, gather context by running:
+  npx ai-xray scout --budget=2000
+
+When debugging a failing test:
+  npx ai-xray read <file> --lines=<error-range>
+
+Before committing changes:
+  npx ai-xray diff --full
+<!-- ai-xray:end -->

package/CODE-REVIEW.md

@@ -0,0 +1,333 @@
+# Code Review: ai-xray v1.0.0
+
+> **Reviewer:** Claude Opus 4 (via Ana)
+> **Date:** 2026-03-06
+> **Scope:** Full source review — all 8 source files, 2 test files, build config, dependencies
+> **Verdict:** Solid v1 — ships clean, zero runtime deps, 10.6KB bundle. A handful of real bugs and several "Gemini-isms" to trim. No blockers.
+
+---
+
+## Summary
+
+ai-xray is a well-scoped, well-executed CLI tool that does exactly what it promises: structured JSON context gathering for AI agents. The zero-dependency design is genuine (not just marketing), the codebase is small (~630 LOC across 8 files), and the build output is a single 10.6KB file. The code is straightforward and readable. However, there are **2 security issues** (command injection in `diff.ts`/`env.ts`), **1 correctness bug** (budget system doesn't actually truncate), and several patterns where Gemini over-designed flexibility that will never be used. Test coverage is minimal (2 files, 5 tests) and misses the most important commands entirely.
+
+---
+
+## 🔴 Critical Issues (Security / Bugs)
+
+### C1. Command Injection via `--file` in `diff.ts` (SECURITY)
+
+**File:** `src/commands/diff.ts:113-114`
+
+```typescript
+const diffCmd = targetFile ? `git diff ${targetFile}` : `git diff`;
+const diffCmdStaged = targetFile ? `git diff --cached ${targetFile}` : `git diff --cached`;
+```
+
+`targetFile` comes directly from user input (`--file=<value>`) and is interpolated into a shell command passed to `execSync()`. An attacker (or a confused AI agent) could pass:
+
+```bash
+ai-xray diff --file="; rm -rf /"
+```
+
+This would execute arbitrary shell commands. Since this tool is specifically designed to be called by AI agents (which can be manipulated via prompt injection in code comments), this is a real attack surface.
+
+**Fix:** Use `execSync`'s array form or `execFileSync`, or at minimum sanitize `targetFile` to reject characters outside `[a-zA-Z0-9._/\\-]`.
+
+### C2. Command Injection via `execSafe` pattern (SECURITY)
+
+**Files:** `src/commands/env.ts:9-15`, `src/commands/diff.ts:5-11`
+
+Both files define identical `execSafe()` functions that pass strings to `execSync()` with shell interpretation. While the currently hardcoded commands are safe, this pattern is fragile — any future extension that interpolates user input into these calls inherits the injection risk. The `targetFile` issue above (C1) is a concrete example.
+
+**Fix:** Switch to `execFileSync('git', ['diff', targetFile])` pattern. This avoids shell interpretation entirely.
+
+### C3. Budget System Doesn't Actually Truncate — It Just Labels (BUG)
+
+**File:** `src/utils/output.ts:12-53`
+
+The `applyBudget()` function checks if the serialized JSON exceeds the token budget, but when it does, it only attaches a `_meta.truncated: true` flag and a "hint" string. **It does not actually remove or reduce any data.** In fact, attaching the `_meta` object makes the output *larger*.
+
+```typescript
+if (estimated > budget) {
+    // ... only attaches _meta, doesn't prune anything
+    return {
+        ...data,        // ← entire original data preserved
+        _meta: { ... }  // ← adds MORE data
+    };
+}
+```
+
+The `read.ts` command does its own character-level truncation (correctly), but `tree.ts` and `scout.ts` rely on the global budget system which is effectively a no-op. An AI agent trusting `--budget=500` could still receive 5000+ tokens of tree output.
+
+**Fix:** `applyBudget()` needs to actually prune the JSON — e.g., recursively truncate string values, remove deep keys, or serialize-then-slice with a closing marker.
+
+---
+
+## 🟡 Major Issues (Design / Performance / Correctness)
+
+### M1. Duplicate `execSafe` Function (DRY Violation)
+
+**Files:** `src/commands/env.ts:9-15` and `src/commands/diff.ts:5-11`
+
+Identical function defined in two files. Should be in `src/utils/exec.ts`.
+
+### M2. `tree.ts` Calls `statSync` Twice Per Entry
+
+**File:** `src/commands/tree.ts:73-82`
+
+```typescript
+if (isIgnored(entryPath) || entry.startsWith('.DS_Store')) {
+    const stat = statSync(entryPath, { throwIfNoEntry: false }); // stat #1
+    if (stat?.isDirectory()) {
+        stats.ignoredDirs.add(entry);
+    }
+    continue;
+}
+
+const stat = statSync(entryPath, { throwIfNoEntry: false }); // stat #2
+```
+
+For non-ignored entries this is fine (only the second stat runs), but for ignored entries we stat just to record them in `ignoredDirs` — this is wasteful for large directories with many ignored files. More importantly, for very large repos (monorepos with thousands of files), the synchronous recursive traversal could block the event loop for seconds.
+
+**Fix:** Either check name-only patterns without statting, or use a single stat per entry.
+
+### M3. `.gitignore` Parsing Is Extremely Naive
+
+**File:** `src/commands/tree.ts:4-28`
+
+The `buildIgnoreMatcher()` only handles:
+- Exact name matches (after stripping trailing `/`)
+- Leading `*` glob (e.g., `*.log`)
+
+It does **not** handle:
+- Negation patterns (`!important.log`)
+- Directory-only patterns (`build/`)
+- Nested path patterns (`src/**/test`)
+- Mid-string globs (`foo*.js`)
+- Comments with inline content
+
+For a v1 labeled "sufficient for 95% of use cases" this is acceptable, but the comment should be more honest — it's closer to 70% coverage. Real-world `.gitignore` files routinely use `**` and negation.
+
+### M4. `env.ts` Only Supports Node.js Projects
+
+**File:** `src/commands/env.ts:21-23`
+
+```typescript
+if (!existsSync(pkgPath)) {
+    throw new Error('Not a Node.js project: package.json not found');
+}
+```
+
+The README doesn't scope this to Node.js only, and AI agents calling `ai-xray env` on a Python or Rust project will get an unhelpful error. The `tree`, `read`, and `diff` commands work for any project, but `env` and `scout` (which calls `env`) will crash.
+
+**Fix:** Return a degraded result `{ packageManager: null, note: "No package.json found" }` instead of throwing. Let `scout` handle the null gracefully.
+
+### M5. No Timeout on `execSync` Calls
+
+**Files:** `src/commands/env.ts`, `src/commands/diff.ts`
+
+`execSync` calls to `git` and package managers have no timeout. In edge cases (large repos, slow git operations, hanging git hooks), these will block indefinitely.
+
+**Fix:** Add `{ timeout: 10000 }` to `execSync` options.
+
+### M6. Test Coverage Is Minimal
+
+**Files:** `tests/env.test.ts` (1 test), `tests/output.test.ts` (4 tests)
+
+Only 2 of 8 source files have tests. The most complex commands (`tree`, `read`, `diff`, `scout`, `init`) have **zero tests**. The `read.ts` budget truncation logic (which actually works correctly) is untested. The `tree.ts` recursive traversal with its compaction logic is untested.
+
+---
+
+## 🟢 Minor Issues (Style / Naming / Polish)
+
+### m1. Pervasive `any` Types
+
+Every command handler returns `any` and most internal variables are typed as `any`. Example:
+
+```typescript
+export function handleScoutCommand(budget?: number): any {
+    const result: any = {};
+```
+
+For a TypeScript project with `"strict": true`, this defeats much of the type system's value. At minimum, define return interfaces for each command.
+
+### m2. `--pretty` Detection Via Global `process.argv` Inspection
+
+**File:** `src/utils/output.ts:57`
+
+```typescript
+process.argv.includes('--pretty')
+```
+
+This reaches into global state instead of receiving `pretty` as a parameter. It works, but it's a hidden coupling. The `cli.ts` even has a comment acknowledging this: `// handled globally in output.ts by inspecting process.argv`.
+
+### m3. `.DS_Store` Hardcoded Check in `tree.ts`
+
+**File:** `src/commands/tree.ts:73`
+
+```typescript
+if (isIgnored(entryPath) || entry.startsWith('.DS_Store')) {
+```
+
+`.DS_Store` doesn't "start with" `.DS_Store` — it **equals** `.DS_Store`. The `startsWith` call is technically correct but misleading; it would also match a hypothetical `.DS_Store_backup`. Use `===` for exact match. Also, this should be in the default ignore list, not a special case.
+
+### m4. Inconsistent Error Handling in `scout.ts`
+
+**File:** `src/commands/scout.ts:12-16`
+
+```typescript
+try {
+    result.env = handleEnvCommand();
+} catch (e: any) {
+    result.env = { error: e.message };
+}
+```
+
+Scout wraps each sub-command in try/catch, which is good. But `handleEnvCommand()` throws on non-Node.js projects (M4 above), meaning `scout` will produce `{ env: { error: "Not a Node.js project..." } }` — a degraded but functional result. This is actually decent error handling, but it papers over the underlying issue.
+
+### m5. `process.exit(0)` in `outputSuccess`
+
+**File:** `src/utils/output.ts:58`
+
+Calling `process.exit(0)` after writing to stdout means the process terminates before the write buffer is guaranteed to flush. On most systems this works because stdout is synchronous for TTY, but when piped (which is the primary use case — AI agents piping JSON), the buffer may not flush.
+
+**Fix:** Use `process.stdout.write(data, () => process.exit(0))` or just let the process exit naturally after `main()` completes (remove the `process.exit(0)` call).
+
+### m6. `help` is Both a Positional Command and a Flag
+
+**File:** `src/cli.ts:27`
+
+```typescript
+if (args.length === 0 || args.includes('--help') || args.includes('-h') || args.includes('help')) {
+```
+
+`args.includes('help')` will match `help` anywhere in the argument list, including `ai-xray read help.md`. This would show help instead of reading the file `help.md`.
+
+---
+
+## 🎭 Gemini-isms (Over-Engineering Patterns)
+
+### G1. The Budget System Architecture Is Over-Designed for What It Does
+
+The codebase has a two-layer budget architecture:
+1. Per-command truncation (only `read.ts` implements this)
+2. Global `applyBudget()` wrapper (does nothing except add metadata)
+
+This is classic Gemini: build the *framework* for a feature (metadata, hints, token estimation) without implementing the *substance* (actual truncation). The comments in `output.ts` even acknowledge this:
+
+> "Specific commands should ideally handle pruning *before* this step... but this serves as a final check or metadata attach point."
+
+Translation: "I built the scaffold but didn't finish the building."
+
+### G2. Unnecessarily Verbose JSON Output Structure
+
+The help command output includes deeply nested objects with `usage` and `desc` for each command. This is well-structured, but consider that AI agents already know how to read a flat string. A simpler format would save tokens:
+
+```json
+{"commands": ["scout [--budget=N]", "env", "tree [dir] [--depth=N]", ...]}
+```
+
+The current verbose format costs ~3x more tokens than necessary for the same information.
+
+### G3. `testFramework.parseHint` and `lintFramework.parseHint`
+
+**File:** `src/commands/env.ts:67-77`
+
+```typescript
+testFramework = {
+    name: 'vitest',
+    runCommand: `npx vitest run --reporter=json`,
+    parseHint: `Look for 'testResults[].assertionResults[].failureMessages'`
+};
+```
+
+Including natural-language "hints" for AI agents on how to parse JSON output is a charming but unnecessary abstraction. Any competent LLM can figure out vitest's JSON output format. This is Gemini being helpful to a fault — spending tokens to save hypothetical future LLM confusion.
+
+### G4. `_moreReplacedFiles` Key in Tree Output
+
+**File:** `src/commands/tree.ts:114`
+
+```typescript
+result['_moreReplacedFiles'] = hiddenCount;
+```
+
+This key name is confusing — "replaced" implies substitution, but it means "additional files not shown." The `_files` array uses `_more` for the same concept. Inconsistent naming within the same function.
+
+### G5. Workspaces Duplication in Scout
+
+**File:** `src/commands/scout.ts:85-90`
+
+```typescript
+if (result.env && result.env.workspaces) {
+    result.workspaces = result.env.workspaces;
+} else {
+    result.workspaces = null;
+}
+```
+
+This copies `env.workspaces` to a top-level `workspaces` key for "convenience." Now the same data exists in two places in the JSON output, wasting tokens — the exact thing the tool is designed to minimize.
+
+---
+
+## ✅ Positive Aspects
+
+1. **Zero runtime dependencies is genuine.** `package.json` has only devDependencies. The 10.6KB bundled output is impressively small. This is a real competitive advantage.
+
+2. **Machine-first protocol is well-executed.** Structured JSON on stdout, structured errors on stderr, no ANSI codes, no interactivity. The uncaughtException/unhandledRejection handlers guarantee JSON output even on crashes. This shows real product thinking.
+
+3. **The `read` command is well-designed.** Multi-file support, line ranges, JSON key extraction, per-file budget tracking with character-level truncation — this is the most polished command and clearly saw the most iteration.
+
+4. **Smart array compaction in `tree`**. The `_files` array for leaf directories is a genuinely clever optimization that saves significant tokens vs. the naive `{ "file.ts": {} }` per-file format.
+
+5. **`init` has idempotent injection.** Checks for `<!-- ai-xray:start -->` before re-injecting. Simple and correct.
+
+6. **The overall architecture is clean.** One file per command, a shared output utility, a simple router in `cli.ts`. No framework, no DI container, no abstract base classes. For once, Gemini showed restraint.
+
+7. **Build config is minimal and correct.** `tsup` with `noExternal: [/(.*)/]` to bundle everything. `target: node18`. Clean.
+
+---
+
+## Recommendations
+
+### Priority 1 (Fix Before Publishing)
+1. **Fix command injection** in `diff.ts` — use `execFileSync` or sanitize `targetFile`
+2. **Fix `applyBudget()` to actually truncate** — currently it's a no-op that misleads consumers
+3. **Fix `help` command collision** — `ai-xray read help.md` should read the file, not show help
+4. **Fix `process.exit(0)` in stdout pipe scenarios** — use callback or natural exit
+
+### Priority 2 (Before v1.1)
+5. **Add tests for `tree`, `read`, `diff`, `scout`, `init`** — current coverage is ~25%
+6. **Add `execSync` timeout** (10s) to all git/pm calls
+7. **Degrade gracefully on non-Node.js projects** instead of throwing in `env`
+8. **Extract shared `execSafe`** to `utils/exec.ts`
+9. **Define TypeScript return types** for all command handlers
+
+### Priority 3 (Nice to Have)
+10. **Improve `.gitignore` parsing** or document its limitations explicitly
+11. **Remove workspace duplication** in scout output
+12. **Rename `_moreReplacedFiles`** to `_hiddenFiles` or `_more` for consistency
+13. **Consider removing `parseHint` fields** — they cost tokens for minimal value
+
+---
+
+## Stats
+
+| Metric | Value |
+|---|---|
+| Source files | 8 |
+| Total LOC (source) | ~630 |
+| Test files | 2 |
+| Test cases | 5 |
+| Runtime dependencies | 0 |
+| Bundle size | 10.6 KB |
+| Build time | ~15ms |
+| Test time | ~454ms |
+| Critical issues | 3 (2 security, 1 bug) |
+| Major issues | 6 |
+| Minor issues | 6 |
+| Gemini-isms | 5 |
+
+---
+
+*Review complete. Overall: a clean, focused v1 with real product value. Fix the security issues and the budget bug, add tests, and it's ready to ship.*