wotann 0.5.0

package/dist/cli/commands/grep.js

@@ -0,0 +1,221 @@
+/**
+ * `wotann grep` — semantic code search via B9 ParallelGrep (Morph
+ * WarpGrep v2 port). Wires the library shipped in
+ * `src/tools/parallel-grep.ts` to the CLI surface so users can actually
+ * invoke it from a shell; prior to this wiring the library had zero
+ * runtime callers.
+ *
+ * Design contract:
+ *   - Default behaviour (no flags) => single-worker sequential dispatch
+ *     over cwd. Same semantics as a plain grep for discovery; no tokens
+ *     spent.
+ *   - `--parallel` fans out 4 workers across the supplied paths (or cwd
+ *     if none given). Concurrency cap is honored regardless of root
+ *     count by the underlying ParallelGrep.
+ *   - `--relevance-filter` enables the optional LLM scorer. When no
+ *     LlmQuery is injected (test path) or when the caller opts out,
+ *     the heuristic ripgrep-only ranking is returned unchanged and a
+ *     warning is surfaced on the result so the user isn't misled.
+ *   - `--json` returns the raw `ParallelGrepReport` verbatim so tooling
+ *     can pipe it. Human output is line-based and respects terminal
+ *     width (capped at 160 chars to avoid runaway wrapping).
+ *
+ * Honest fallbacks (QB #6):
+ *   - ripgrep unavailable => ParallelGrep's subagent falls back to the
+ *     node walker; `report.usedFallback` is true and the engine field
+ *     on each subagent report says `node-fallback`. The printed output
+ *     surfaces this so the caller knows which backend produced results.
+ *   - no paths passed => `[process.cwd()]` — honest default, not silent.
+ *   - relevance-filter requested with no provider => we leave
+ *     `llmQuery` unset, tag `relevanceFilterAvailable=false`, and add
+ *     a warning line so users know the flag was a no-op.
+ *
+ * Per-session state (QB #7): every `runGrep` call constructs a fresh
+ * `ParallelGrep`. Two concurrent CLI invocations share zero mutable
+ * state.
+ */
+import { ParallelGrep } from "../../tools/parallel-grep.js";
+// ── Constants ────────────────────────────────────────────────
+const DEFAULT_TOP_K = 20;
+const DEFAULT_PARALLEL_WORKERS = 4;
+const TERM_WIDTH_MAX = 160;
+// ── Entry point ──────────────────────────────────────────────
+/**
+ * Execute a grep dispatch. Pure logic — no `console.log`, no
+ * `process.exit`. The CLI shell (src/index.ts) is responsible for
+ * printing `lines` or the JSON payload and for the process exit code.
+ *
+ * @throws if `query` is empty (surfaced verbatim from ParallelGrep).
+ */
+export async function runGrep(query, paths, options = {}) {
+    // Honest default: no paths => cwd. The user sees exactly which root
+    // was searched via the `report.roots` field in JSON mode.
+    const rootPaths = paths.length > 0 ? paths : [process.cwd()];
+    const topK = normaliseTopK(options.topK);
+    const parallel = options.parallel === true;
+    const workers = parallel ? Math.max(1, options.parallelism ?? DEFAULT_PARALLEL_WORKERS) : 1;
+    // Relevance-filter requested but no llmQuery => heuristic fallback.
+    // We set `applied` based on whether we have a real callback to pass
+    // through, not on whether the flag was set.
+    const relevanceRequested = options.relevanceFilter === true;
+    const relevanceApplied = relevanceRequested && typeof options.llmQuery === "function";
+    // Per-session state (QB #7): allow injection for tests but default to
+    // a fresh instance so concurrent CLI runs don't share caches.
+    const pg = options.grep ?? new ParallelGrep();
+    const dispatchOptions = {
+        concurrency: workers,
+        topK,
+    };
+    if (relevanceApplied && options.llmQuery) {
+        // Only wire the LLM through when we actually have one. This keeps
+        // the fallback note honest — `applied=false` means we did zero LLM
+        // work, not that we tried and failed silently.
+        dispatchOptions.llmQuery = options.llmQuery;
+    }
+    const report = await pg.dispatch(query, rootPaths, dispatchOptions);
+    const extraWarnings = [];
+    if (relevanceRequested && !relevanceApplied) {
+        extraWarnings.push("--relevance-filter requested but no llmQuery provider wired; heuristic ranking returned instead.");
+    }
+    const lines = options.json
+        ? [] // caller will stringify the full GrepResult
+        : renderLines(report, {
+            relevanceFilterApplied: relevanceApplied,
+            extraWarnings,
+            termWidth: detectTermWidth(),
+        });
+    return {
+        report,
+        relevanceFilterApplied: relevanceApplied,
+        lines,
+        extraWarnings,
+    };
+}
+// ── Commander registration ───────────────────────────────────
+/**
+ * Attach `wotann grep` to the CLI `program`. The shell is the
+ * ONLY place that touches stdout and exit codes — the command module
+ * itself stays testable without stubbing process.
+ */
+export function registerGrepCommand(program) {
+    program
+        .command("grep <query> [paths...]")
+        .description("Semantic grep via B9 ParallelGrep — ripgrep-first with node fallback, optional LLM relevance filter")
+        .option("--parallel", "Fan out across paths with 4 workers")
+        .option("--parallelism <n>", "Override worker count when --parallel is set", `${DEFAULT_PARALLEL_WORKERS}`)
+        .option("--top-k <n>", "Return top K results", `${DEFAULT_TOP_K}`)
+        .option("--relevance-filter", "Score hits with LLM relevance (requires provider; heuristic fallback otherwise)")
+        .option("--json", "Emit JSON instead of formatted text")
+        .action(async (query, paths, opts) => {
+        // LLM binding for relevance-filter is a separate wiring task.
+        // Today the CLI shell deliberately leaves `llmQuery` unset so
+        // the honest heuristic fallback kicks in (with an on-result
+        // warning). Tests exercise the applied-path by calling
+        // `runGrep` directly with an injected `llmQuery`. This keeps
+        // the command shell free of provider/runtime knowledge.
+        const llmQuery = undefined;
+        const runOpts = {
+            parallel: opts.parallel === true,
+            parallelism: opts.parallelism
+                ? Math.max(1, Number.parseInt(opts.parallelism, 10) || DEFAULT_PARALLEL_WORKERS)
+                : DEFAULT_PARALLEL_WORKERS,
+            topK: opts.topK
+                ? Math.max(1, Number.parseInt(opts.topK, 10) || DEFAULT_TOP_K)
+                : DEFAULT_TOP_K,
+            relevanceFilter: opts.relevanceFilter === true,
+            json: opts.json === true,
+            ...(llmQuery ? { llmQuery } : {}),
+        };
+        try {
+            const result = await runGrep(query, paths ?? [], runOpts);
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(serializeResult(result), null, 2) + "\n");
+            }
+            else {
+                for (const line of result.lines) {
+                    process.stdout.write(line + "\n");
+                }
+            }
+            // Non-zero exit only on outright failure; zero hits is a
+            // legitimate answer, not an error.
+            if (result.report.warnings.length > 0 && result.report.returnedHitCount === 0) {
+                // Surface degraded runs with exit=2 so shell pipelines can
+                // detect "something was weird but we returned no hits."
+                process.exitCode = 2;
+            }
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`grep error: ${reason}\n`);
+            process.exitCode = 1;
+        }
+    });
+}
+function renderLines(report, ctx) {
+    const lines = [];
+    const engineLabel = report.usedFallback ? "ripgrep+node-fallback" : "ripgrep";
+    const filterLabel = ctx.relevanceFilterApplied ? "llm" : "heuristic";
+    lines.push(`grep "${truncate(report.query, 60)}" — ${report.returnedHitCount}/${report.rawHitCount} hit(s), ${report.roots.length} root(s), ${report.durationMs}ms (${engineLabel}, ${filterLabel})`);
+    if (ctx.extraWarnings.length > 0) {
+        for (const w of ctx.extraWarnings) {
+            lines.push(`  ! ${w}`);
+        }
+    }
+    if (report.warnings.length > 0) {
+        for (const w of report.warnings) {
+            lines.push(`  ! ${w}`);
+        }
+    }
+    if (report.hits.length === 0) {
+        lines.push("  (no matches)");
+        return lines;
+    }
+    for (const hit of report.hits) {
+        lines.push(renderHit(hit, ctx.termWidth));
+    }
+    return lines;
+}
+function renderHit(hit, termWidth) {
+    const prefix = `  ${hit.relevance.padEnd(6)} ${hit.path}:${hit.line}: `;
+    const budget = Math.max(20, termWidth - prefix.length);
+    return prefix + truncate(hit.snippet, budget);
+}
+function detectTermWidth() {
+    // Respect the caller's terminal but cap so we don't produce absurdly
+    // wide lines on 240-column monitors.
+    const reported = typeof process.stdout.columns === "number" ? process.stdout.columns : 80;
+    if (!Number.isFinite(reported) || reported <= 0)
+        return 80;
+    return Math.min(reported, TERM_WIDTH_MAX);
+}
+function truncate(raw, max) {
+    if (raw.length <= max)
+        return raw;
+    if (max <= 1)
+        return raw.slice(0, max);
+    return raw.slice(0, max - 1) + "…";
+}
+function serializeResult(result) {
+    const { report } = result;
+    return {
+        query: report.query,
+        roots: report.roots,
+        returnedHitCount: report.returnedHitCount,
+        dedupedHitCount: report.dedupedHitCount,
+        rawHitCount: report.rawHitCount,
+        durationMs: report.durationMs,
+        usedFallback: report.usedFallback,
+        relevanceFilterApplied: result.relevanceFilterApplied,
+        warnings: [...report.warnings, ...result.extraWarnings],
+        hits: report.hits,
+    };
+}
+// ── Utilities ────────────────────────────────────────────────
+function normaliseTopK(requested) {
+    if (requested === undefined || !Number.isFinite(requested))
+        return DEFAULT_TOP_K;
+    if (requested < 1)
+        return 1;
+    return Math.floor(requested);
+}
+//# sourceMappingURL=grep.js.map

package/dist/cli/commands/grep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grep.js","sourceRoot":"","sources":["../../../src/cli/commands/grep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AA6C5D,gEAAgE;AAEhE,MAAM,aAAa,GAAG,EAAE,CAAC;AACzB,MAAM,wBAAwB,GAAG,CAAC,CAAC;AACnC,MAAM,cAAc,GAAG,GAAG,CAAC;AAE3B,gEAAgE;AAEhE;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,KAAa,EACb,KAAwB,EACxB,UAA8B,EAAE;IAEhC,oEAAoE;IACpE,0DAA0D;IAC1D,MAAM,SAAS,GAAsB,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAEhF,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,KAAK,IAAI,CAAC;IAC3C,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,WAAW,IAAI,wBAAwB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE5F,oEAAoE;IACpE,oEAAoE;IACpE,4CAA4C;IAC5C,MAAM,kBAAkB,GAAG,OAAO,CAAC,eAAe,KAAK,IAAI,CAAC;IAC5D,MAAM,gBAAgB,GAAG,kBAAkB,IAAI,OAAO,OAAO,CAAC,QAAQ,KAAK,UAAU,CAAC;IAEtF,sEAAsE;IACtE,8DAA8D;IAC9D,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,YAAY,EAAE,CAAC;IAE9C,MAAM,eAAe,GAA4C;QAC/D,WAAW,EAAE,OAAO;QACpB,IAAI;KACL,CAAC;IACF,IAAI,gBAAgB,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACzC,kEAAkE;QAClE,mEAAmE;QACnE,+CAA+C;QAC9C,eAA2C,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAC3E,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,eAAe,CAAC,CAAC;IAEpE,MAAM,aAAa,GAAa,EAAE,CAAC;IACnC,IAAI,kBAAkB,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC5C,aAAa,CAAC,IAAI,CAChB,kGAAkG,CACnG,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI;QACxB,CAAC,CAAC,EAAE,CAAC,4CAA4C;QACjD,CAAC,CAAC,WAAW,CAAC,MAAM,EAAE;YAClB,sBAAsB,EAAE,gBAAgB;YACxC,aAAa;YACb,SAAS,EAAE,eAAe,EAAE;SAC7B,CAAC,CAAC;IAEP,OAAO;QACL,MAAM;QACN,sBAAsB,EAAE,gBAAgB;QACxC,KAAK;QACL,aAAa;KACd,CAAC;AACJ,CAAC;AAED,gEAAgE;AAEhE;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAgB;IAClD,OAAO;SACJ,OAAO,CAAC,yBAAyB,CAAC;SAClC,WAAW,CACV,qGAAqG,CACtG;SACA,MAAM,CAAC,YAAY,EAAE,qCAAqC,CAAC;SAC3D,MAAM,CACL,mBAAmB,EACnB,8CAA8C,EAC9C,GAAG,wBAAwB,EAAE,CAC9B;SACA,MAAM,CAAC,aAAa,EAAE,sBAAsB,EAAE,GAAG,aAAa,EAAE,CAAC;SACjE,MAAM,CACL,oBAAoB,EACpB,iFAAiF,CAClF;SACA,MAAM,CAAC,QAAQ,EAAE,qCAAqC,CAAC;SACvD,MAAM,CACL,KAAK,EACH,KAAa,EACb,KAAe,EACf,IAMC,EACD,EAAE;QACF,8DAA8D;QAC9D,8DAA8D;QAC9D,4DAA4D;QAC5D,uDAAuD;QACvD,6DAA6D;QAC7D,wDAAwD;QACxD,MAAM,QAAQ,GAAyB,SAAS,CAAC;QAEjD,MAAM,OAAO,GAAuB;YAClC,QAAQ,EAAE,IAAI,CAAC,QAAQ,KAAK,IAAI;YAChC,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC3B,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC,IAAI,wBAAwB,CAAC;gBAChF,CAAC,CAAC,wBAAwB;YAC5B,IAAI,EAAE,IAAI,CAAC,IAAI;gBACb,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,aAAa,CAAC;gBAC9D,CAAC,CAAC,aAAa;YACjB,eAAe,EAAE,IAAI,CAAC,eAAe,KAAK,IAAI;YAC9C,IAAI,EAAE,IAAI,CAAC,IAAI,KAAK,IAAI;YACxB,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAClC,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,KAAK,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;YAC1D,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBACd,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;YAChF,CAAC;iBAAM,CAAC;gBACN,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;oBAChC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;gBACpC,CAAC;YACH,CAAC;YACD,yDAAyD;YACzD,mCAAmC;YACnC,IAAI,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,gBAAgB,KAAK,CAAC,EAAE,CAAC;gBAC9E,2DAA2D;gBAC3D,wDAAwD;gBACxD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAChE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,MAAM,IAAI,CAAC,CAAC;YAChD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC,CACF,CAAC;AACN,CAAC;AAUD,SAAS,WAAW,CAAC,MAA0B,EAAE,GAAkB;IACjE,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,WAAW,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9E,MAAM,WAAW,GAAG,GAAG,CAAC,sBAAsB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC;IAErE,KAAK,CAAC,IAAI,CACR,SAAS,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,MAAM,CAAC,gBAAgB,IAAI,MAAM,CAAC,WAAW,YAAY,MAAM,CAAC,KAAK,CAAC,MAAM,aAAa,MAAM,CAAC,UAAU,OAAO,WAAW,KAAK,WAAW,GAAG,CAC1L,CAAC;IAEF,IAAI,GAAG,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjC,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,aAAa,EAAE,CAAC;YAClC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YAChC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QAC7B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAC9B,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,SAAS,CAAC,GAAoB,EAAE,SAAiB;IACxD,MAAM,MAAM,GAAG,KAAK,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,CAAC;IACxE,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IACvD,OAAO,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,eAAe;IACtB,qEAAqE;IACrE,qCAAqC;IACrC,MAAM,QAAQ,GAAG,OAAO,OAAO,CAAC,MAAM,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1F,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IAC3D,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;AAC5C,CAAC;AAED,SAAS,QAAQ,CAAC,GAAW,EAAE,GAAW;IACxC,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC;IAClC,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACvC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;AACrC,CAAC;AAiBD,SAAS,eAAe,CAAC,MAAkB;IACzC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAC1B,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;QACzC,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,sBAAsB,EAAE,MAAM,CAAC,sBAAsB;QACrD,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,EAAE,GAAG,MAAM,CAAC,aAAa,CAAC;QACvD,IAAI,EAAE,MAAM,CAAC,IAAI;KAClB,CAAC;AACJ,CAAC;AAED,gEAAgE;AAEhE,SAAS,aAAa,CAAC,SAA6B;IAClD,IAAI,SAAS,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,aAAa,CAAC;IACjF,IAAI,SAAS,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IAC5B,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;AAC/B,CAAC"}

package/dist/cli/commands/intent.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `wotann intent` — spec management + BYOA status/test (P1-C4).
+ *
+ * Pure handler — returns structured result lines; the `src/index.ts`
+ * entrypoint decides exit codes and how to print. No side effects on
+ * the shell beyond SPEC.md reads/writes.
+ *
+ * Actions:
+ *   spec-init             Initialize SPEC.md in the workspace
+ *   spec-show             Print the current spec
+ *   decision-add          Append a decision with rationale
+ *   byoa-status           Detect BYOA key, print masked form
+ *   byoa-test             Validate BYOA key against Anthropic
+ *
+ * The caller passes `envOverride` in tests; in production the CLI
+ * shell wires it to `{ envVars: process.env, homeDir: homedir() }`.
+ * Similarly the validator is injected so tests never hit the network.
+ *
+ * WOTANN quality bars:
+ *  - QB #6 honest failures: `byoa-test` surfaces the distinct
+ *    invalid-key vs unreachable errors verbatim.
+ *  - QB #7 per-call state: a fresh environment snapshot per call.
+ *  - QB #11 scope-bounded: writes only SPEC.md in the workspace.
+ */
+import { type ByoaEnv, type ByoaValidator } from "../../intent/byoa-detector.js";
+export type IntentAction = "spec-init" | "spec-show" | "decision-add" | "byoa-status" | "byoa-test";
+export interface IntentCommandOptions {
+    readonly action: IntentAction;
+    readonly workspaceRoot: string;
+    readonly decision?: string;
+    readonly rationale?: string;
+    readonly decisionTimestamp?: string;
+    readonly envOverride?: ByoaEnv;
+    readonly validator?: ByoaValidator;
+}
+export interface IntentCommandResult {
+    readonly success: boolean;
+    readonly action: IntentAction;
+    readonly lines: readonly string[];
+    readonly error?: string;
+}
+export declare function runIntentCommand(options: IntentCommandOptions): Promise<IntentCommandResult>;
+//# sourceMappingURL=intent.d.ts.map

package/dist/cli/commands/intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/intent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAWH,OAAO,EAKL,KAAK,OAAO,EACZ,KAAK,aAAa,EACnB,MAAM,+BAA+B,CAAC;AAIvC,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,WAAW,GAAG,cAAc,GAAG,aAAa,GAAG,WAAW,CAAC;AAEpG,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAG/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAIpC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAG/B,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;CACpC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAID,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAsB9B"}

package/dist/cli/commands/intent.js

@@ -0,0 +1,282 @@
+/**
+ * `wotann intent` — spec management + BYOA status/test (P1-C4).
+ *
+ * Pure handler — returns structured result lines; the `src/index.ts`
+ * entrypoint decides exit codes and how to print. No side effects on
+ * the shell beyond SPEC.md reads/writes.
+ *
+ * Actions:
+ *   spec-init             Initialize SPEC.md in the workspace
+ *   spec-show             Print the current spec
+ *   decision-add          Append a decision with rationale
+ *   byoa-status           Detect BYOA key, print masked form
+ *   byoa-test             Validate BYOA key against Anthropic
+ *
+ * The caller passes `envOverride` in tests; in production the CLI
+ * shell wires it to `{ envVars: process.env, homeDir: homedir() }`.
+ * Similarly the validator is injected so tests never hit the network.
+ *
+ * WOTANN quality bars:
+ *  - QB #6 honest failures: `byoa-test` surfaces the distinct
+ *    invalid-key vs unreachable errors verbatim.
+ *  - QB #7 per-call state: a fresh environment snapshot per call.
+ *  - QB #11 scope-bounded: writes only SPEC.md in the workspace.
+ */
+import { addDecision, initSpec, readSpec, SpecNotFoundError, specPath, } from "../../intent/living-spec.js";
+import { ANTHROPIC_API_VERSION_LISTING } from "../../providers/header-injection.js";
+import { detectByoa, validateByoaKey, ByoaKeyInvalidError, ByoaValidationUnreachableError, } from "../../intent/byoa-detector.js";
+// ── Entry point ───────────────────────────────────────────────────────────
+export async function runIntentCommand(options) {
+    switch (options.action) {
+        case "spec-init":
+            return handleSpecInit(options);
+        case "spec-show":
+            return handleSpecShow(options);
+        case "decision-add":
+            return handleDecisionAdd(options);
+        case "byoa-status":
+            return handleByoaStatus(options);
+        case "byoa-test":
+            return handleByoaTest(options);
+        default: {
+            const exhaustive = options.action;
+            return {
+                success: false,
+                action: options.action,
+                lines: [],
+                error: `unknown action: ${String(exhaustive)}`,
+            };
+        }
+    }
+}
+// ── spec handlers ─────────────────────────────────────────────────────────
+function handleSpecInit(opts) {
+    try {
+        initSpec(opts.workspaceRoot);
+        return {
+            success: true,
+            action: "spec-init",
+            lines: [`✓ Initialized SPEC.md at ${specPath(opts.workspaceRoot)}`],
+        };
+    }
+    catch (err) {
+        return {
+            success: false,
+            action: "spec-init",
+            lines: [],
+            error: err instanceof Error ? err.message : "unknown",
+        };
+    }
+}
+function handleSpecShow(opts) {
+    try {
+        const doc = readSpec(opts.workspaceRoot);
+        return {
+            success: true,
+            action: "spec-show",
+            lines: formatSpec(doc),
+        };
+    }
+    catch (err) {
+        if (err instanceof SpecNotFoundError) {
+            return {
+                success: false,
+                action: "spec-show",
+                lines: [],
+                error: `SpecNotFound: SPEC.md not found in ${opts.workspaceRoot}`,
+            };
+        }
+        return {
+            success: false,
+            action: "spec-show",
+            lines: [],
+            error: err instanceof Error ? err.message : "unknown",
+        };
+    }
+}
+function handleDecisionAdd(opts) {
+    if (!opts.decision || !opts.rationale) {
+        return {
+            success: false,
+            action: "decision-add",
+            lines: [],
+            error: "decision-add requires --decision and --rationale",
+        };
+    }
+    try {
+        const doc = addDecision(opts.workspaceRoot, {
+            decision: opts.decision,
+            rationale: opts.rationale,
+            ...(opts.decisionTimestamp ? { timestamp: opts.decisionTimestamp } : {}),
+        });
+        const last = doc.decisionsLog[doc.decisionsLog.length - 1];
+        return {
+            success: true,
+            action: "decision-add",
+            lines: [
+                `✓ Appended decision (${doc.decisionsLog.length} total)`,
+                `  [${last?.timestamp ?? "?"}] ${last?.decision ?? ""}`,
+                `  rationale: ${last?.rationale ?? ""}`,
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            success: false,
+            action: "decision-add",
+            lines: [],
+            error: err instanceof Error ? err.message : "unknown",
+        };
+    }
+}
+// ── BYOA handlers ─────────────────────────────────────────────────────────
+function requireEnv(opts) {
+    if (opts.envOverride)
+        return opts.envOverride;
+    // Fallback to process env — kept narrow so we don't leak globals.
+    return {
+        envVars: process.env,
+        homeDir: process.env["HOME"] ?? process.env["USERPROFILE"] ?? "",
+    };
+}
+function handleByoaStatus(opts) {
+    const env = requireEnv(opts);
+    const result = detectByoa(env);
+    if (!result.detected) {
+        return {
+            success: true,
+            action: "byoa-status",
+            lines: ["BYOA: not detected (no ANTHROPIC_API_KEY or ~/.claude.json key found)"],
+        };
+    }
+    return {
+        success: true,
+        action: "byoa-status",
+        lines: [
+            `BYOA: detected`,
+            `  source: ${result.source}`,
+            `  key:    ${result.masked ?? "<unknown>"}`,
+        ],
+    };
+}
+async function handleByoaTest(opts) {
+    const env = requireEnv(opts);
+    const detection = detectByoa(env);
+    if (!detection.detected || !detection.apiKey) {
+        return {
+            success: false,
+            action: "byoa-test",
+            lines: [],
+            error: "BYOA key not detected (ANTHROPIC_API_KEY is not set)",
+        };
+    }
+    const validator = opts.validator ?? defaultValidator;
+    try {
+        const res = await validateByoaKey(detection.apiKey, validator);
+        return {
+            success: true,
+            action: "byoa-test",
+            lines: [
+                `✓ BYOA key validated`,
+                `  source: ${detection.source}`,
+                `  key:    ${res.maskedKey}`,
+            ],
+        };
+    }
+    catch (err) {
+        // Both ByoaKeyInvalidError and ByoaValidationUnreachableError
+        // carry only masked text in their messages, so it's safe to
+        // surface them directly.
+        if (err instanceof ByoaKeyInvalidError) {
+            return {
+                success: false,
+                action: "byoa-test",
+                lines: [`✗ BYOA key invalid`, `  key: ${err.maskedKey}`, `  reason: ${err.message}`],
+                error: err.message,
+            };
+        }
+        if (err instanceof ByoaValidationUnreachableError) {
+            return {
+                success: false,
+                action: "byoa-test",
+                lines: [
+                    `✗ BYOA validator unreachable`,
+                    `  key: ${err.maskedKey}`,
+                    `  reason: ${err.message}`,
+                ],
+                error: err.message,
+            };
+        }
+        return {
+            success: false,
+            action: "byoa-test",
+            lines: [],
+            error: err instanceof Error ? err.message : "unknown",
+        };
+    }
+}
+/**
+ * Production validator: hits Anthropic's `/v1/models` endpoint with
+ * the x-api-key header. Cheap (models list is small, cacheable) and
+ * the 401 response is the canonical "key is bad" signal.
+ *
+ * Mocked in tests via `opts.validator`. This function is separated
+ * so it stays exactly one fetch call — any change to the real
+ * endpoint is a one-line edit.
+ */
+async function defaultValidator(apiKey) {
+    const res = await fetch("https://api.anthropic.com/v1/models", {
+        method: "GET",
+        headers: {
+            "x-api-key": apiKey,
+            "anthropic-version": ANTHROPIC_API_VERSION_LISTING,
+        },
+    });
+    let body = null;
+    try {
+        body = await res.json();
+    }
+    catch {
+        body = null;
+    }
+    return { status: res.status, body };
+}
+// ── Format helpers ────────────────────────────────────────────────────────
+function formatSpec(doc) {
+    const lines = [];
+    lines.push("## Goal");
+    lines.push(doc.goal);
+    lines.push("");
+    lines.push("## Scope");
+    if (doc.scope.length === 0)
+        lines.push("  (none)");
+    else
+        for (const s of doc.scope)
+            lines.push(`  - ${s}`);
+    lines.push("");
+    lines.push("## Constraints");
+    if (doc.constraints.length === 0)
+        lines.push("  (none)");
+    else
+        for (const c of doc.constraints)
+            lines.push(`  - ${c}`);
+    lines.push("");
+    lines.push("## Decisions Log");
+    if (doc.decisionsLog.length === 0)
+        lines.push("  (no decisions)");
+    else
+        for (const d of doc.decisionsLog) {
+            lines.push(`  - [${d.timestamp}] ${d.decision}`);
+            lines.push(`    rationale: ${d.rationale}`);
+        }
+    lines.push("");
+    lines.push("## Glossary");
+    const terms = Object.keys(doc.glossary);
+    if (terms.length === 0)
+        lines.push("  (no terms)");
+    else
+        for (const t of terms)
+            lines.push(`  ${t}: ${doc.glossary[t]}`);
+    return lines;
+}
+//# sourceMappingURL=intent.js.map

package/dist/cli/commands/intent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent.js","sourceRoot":"","sources":["../../../src/cli/commands/intent.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/magic.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `wotann magic` — V9 Tier 12 T12.17 wire.
+ *
+ * The 15 dot-shortcut handlers in `src/magic/handlers/` (.fix, .test,
+ * .review, .refactor, .explain, .docstring, .format, .optimize,
+ * .investigate-issue, .investigate-pr, .investigate-workflow,
+ * .ai-commit, .pr-content, .merge-conflict, .release-notes) were
+ * previously unreachable from any CLI surface. This module exposes
+ * `runMagicCommand` so a `wotann magic <command> [args...]` verb can
+ * invoke any of them and emit the expanded prompt + optional system
+ * augmentation back to the caller.
+ *
+ * Honest envelope: handlers that fail validation surface the error
+ * verbatim. An unknown command returns a structured error rather than
+ * throwing — callers may inspect `ok` to decide exit codes.
+ */
+export interface RunMagicCommandOptions {
+    readonly command: string;
+    readonly args: readonly string[];
+}
+export interface RunMagicCommandResult {
+    readonly ok: boolean;
+    readonly output?: string;
+    readonly error?: string;
+}
+/**
+ * Invoke a magic handler with positional args joined as the input
+ * payload. Mirrors `resolveMagicInput` semantics — args after the
+ * command name become the user-supplied input the handler sees.
+ *
+ * Pure function: no console writes, no process.exit. The shell decides
+ * how to render the envelope.
+ */
+export declare function runMagicCommand(opts: RunMagicCommandOptions): RunMagicCommandResult;
+/**
+ * Help text body — built from MAGIC_COMMANDS so a new shortcut shows up
+ * without touching this file. Returned as a string so the caller can
+ * inject it into commander's `description` or print it directly.
+ */
+export declare function listMagicCommands(): string;
+//# sourceMappingURL=magic.d.ts.map

package/dist/cli/commands/magic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"magic.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/magic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAcD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,qBAAqB,CAoBnF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAG1C"}