@bigknoxy/hashpilot 4.6.3

package/src/core/exit-codes.ts

@@ -0,0 +1,198 @@
+import { ErrorCode, recordEvent, getRecordedEventCount } from "./telemetry";
+import { wrap, currentCommandName } from "./envelope";
+import { resolveFormat, renderText, OutputFormat } from "./format";
+import { isQuiet } from "./output";
+
+/**
+ * Process exit codes. Agents branch on these, so the numbers are a contract —
+ * see docs/ADAPTER-CONTRACT.md. Never renumber an existing code.
+ */
+export enum ExitCode {
+  /** Operation succeeded. */
+  OK = 0,
+  /** Bad invocation: missing/malformed flag, denied path, unsupported operation. Retrying verbatim will not help. */
+  USAGE = 1,
+  /** The edit itself failed (symbol not found, parse error, ambiguous match). */
+  EDIT_FAILED = 2,
+  /** A precondition no longer holds (stale anchor, hash mismatch). Agent-retryable after a fresh read. */
+  PRECONDITION = 3,
+  /** The edit applied but verification (format/lint/test) failed. */
+  VERIFY_FAILED = 4,
+  /** Filesystem-level failure: file missing, unreadable, or unwritable. */
+  IO = 5,
+  /** Uncaught internal error — a bug in HashPilot. */
+  INTERNAL = 70,
+}
+
+const ERROR_CODE_EXITS: Record<string, ExitCode> = {
+  [ErrorCode.STALE_ANCHOR]: ExitCode.PRECONDITION,
+  [ErrorCode.LOCK_TIMEOUT]: ExitCode.PRECONDITION,
+  [ErrorCode.HASH_MISMATCH]: ExitCode.PRECONDITION,
+  [ErrorCode.FILE_NOT_FOUND]: ExitCode.IO,
+  [ErrorCode.WRITE_FAILED]: ExitCode.IO,
+  [ErrorCode.READ_FAILED]: ExitCode.IO,
+  [ErrorCode.PATH_DENIED]: ExitCode.USAGE,
+  [ErrorCode.INVALID_ARGUMENT]: ExitCode.USAGE,
+  [ErrorCode.UNSUPPORTED_OPERATION]: ExitCode.USAGE,
+  [ErrorCode.SYMBOL_NOT_FOUND]: ExitCode.EDIT_FAILED,
+  [ErrorCode.PARSE_ERROR]: ExitCode.EDIT_FAILED,
+  [ErrorCode.DUPLICATE_MATCH]: ExitCode.EDIT_FAILED,
+    // "Same name binds more than one symbol in this file" is a failed edit
+    // attempt (a precondition the caller didn't meet), not a stale/retryable
+    // anchor — so it shares the EDIT_FAILED band with SYMBOL_NOT_FOUND.
+    [ErrorCode.AMBIGUOUS_SYMBOL]: ExitCode.EDIT_FAILED,
+  [ErrorCode.UNSUPPORTED_LANGUAGE]: ExitCode.EDIT_FAILED,
+  // The file is fine and the operation exists; this particular import cannot
+  // be written into this particular module system. Same band as
+  // UNSUPPORTED_LANGUAGE: the edit failed on a precondition the caller can
+  // fix, and retrying the same call verbatim will not help (#139).
+  [ErrorCode.MODULE_SYSTEM_MISMATCH]: ExitCode.EDIT_FAILED,
+  // The search did not complete, so the edit did not happen for a reason the
+  // caller can act on (raise the cap, target a shallower node) — an edit
+  // failure, not a retryable precondition (#39).
+  [ErrorCode.SEARCH_TRUNCATED]: ExitCode.EDIT_FAILED,
+  [ErrorCode.VERIFY_FAILED]: ExitCode.VERIFY_FAILED,
+  // A timeout shares the verification band — the edit applied, verification did
+  // not conclude — but carries its own error code so an agent can tell "your
+  // change broke the tests" from "the suite ran out of time".
+  [ErrorCode.VERIFY_TIMEOUT]: ExitCode.VERIFY_FAILED,
+  // Same band again: the edit applied, verification produced no verdict. A
+  // separate code so an agent can tell "nothing was checked" from "the checks
+  // failed" and re-run with the flags it forgot (#106).
+  [ErrorCode.VERIFY_NO_CHECKS]: ExitCode.VERIFY_FAILED,
+  // Deliberately IO, not VERIFY_FAILED: a half-reverted tree is a filesystem
+  // problem the agent must stop and inspect, not a retryable test failure.
+  [ErrorCode.ROLLBACK_INCOMPLETE]: ExitCode.IO,
+  [ErrorCode.INTERNAL_ERROR]: ExitCode.INTERNAL,
+};
+
+/** Shape every command result is inspected through. All fields optional — results vary by command. */
+export interface ResultLike {
+  success?: boolean;
+  passed?: boolean;
+  error?: string | { code?: string };
+  errorCode?: string;
+  stale?: boolean;
+  [key: string]: unknown;
+}
+
+/**
+ * Derive an exit code from a command result. Falls back to EDIT_FAILED for an
+ * unrecognized failure rather than OK — an unmapped error must never exit 0.
+ */
+export function exitCodeFor(result: ResultLike | ResultLike[] | undefined): ExitCode {
+  if (result === undefined) return ExitCode.OK;
+
+  if (Array.isArray(result)) {
+    // Batch: worst (highest) code wins, so a single failure is never masked.
+    return result.reduce<ExitCode>((worst, r) => {
+      const code = exitCodeFor(r);
+      return code > worst ? code : worst;
+    }, ExitCode.OK);
+  }
+
+  // Wrapper results (route-edit, batch, plan steps) carry the real outcome in
+  // `result`. Ignoring it made a failed edit exit 0.
+  if (result.success === undefined && result.passed === undefined && result.error === undefined
+      && result.result && typeof result.result === "object") {
+    return exitCodeFor(result.result as ResultLike);
+  }
+
+  const explicit = result.errorCode ?? (typeof result.error === "object" ? result.error?.code : undefined);
+  if (explicit && ERROR_CODE_EXITS[explicit]) return ERROR_CODE_EXITS[explicit];
+
+  const failed =
+    result.success === false ||
+    result.passed === false ||
+    (result.error !== undefined && result.error !== null);
+  if (!failed) return ExitCode.OK;
+
+  if (result.stale === true) return ExitCode.PRECONDITION;
+  return ExitCode.EDIT_FAILED;
+}
+
+/* ── Output format (#19 B16) ───────────────────────────────────────────── */
+let outputFormat: OutputFormat = "json";
+let currentCommand = "";
+
+/** Called once by preAction; sets the global output format + running command name. */
+export function setOutputFormat(fmt: OutputFormat, command: string): void {
+  outputFormat = fmt;
+  currentCommand = command;
+}
+
+/** Current output format — used by action handlers to branch on text vs. JSON. */
+export function getOutputFormat(): OutputFormat {
+  return outputFormat;
+}
+
+/** Re-export for cli.ts convenience. */
+export { resolveFormat, renderText };
+
+/**
+ * Single exit point for every CLI command.
+ *
+ * #19 (B16): when `outputFormat === "text"` the success payload is rendered as
+ * compact human-readable output via per-command renderers. Error payloads are
+ * ALWAYS JSON — the API contract (apiVersion 1) is the canonical machine output
+ * and must not be degraded. Commands without a renderer fall back to a compact
+ * key/value dump; never raw JSON in text mode.
+ */
+// `telemetry *` reads, clears, and prunes the log; recording an event there
+// would grow the very file the command is inspecting and skew its own report.
+// `uninstall` removes the log directory outright.
+const TELEMETRY_EXEMPT_COMMANDS = ["uninstall"];
+
+const processStart = Date.now();
+
+/**
+ * CLAUDE.md says every command records a telemetry event, but a dozen commands
+ * (`capabilities`, `route`, `config`, `undo`, `provenance query`, …) recorded
+ * nothing, leaving silent holes in the health report's operation coverage.
+ * Rather than thread a recordEvent call through every action and its several
+ * finish() call sites, emit a fallback here — the one choke point every command
+ * already funnels through — but only when the action recorded nothing itself,
+ * so commands with richer events are not double-counted (#51).
+ */
+function recordFallbackEvent(exit: ExitCode): void {
+  const command = currentCommandName();
+  if (!command) return;
+  if (getRecordedEventCount() > 0) return;
+  if (command.startsWith("telemetry") || TELEMETRY_EXEMPT_COMMANDS.includes(command)) return;
+  recordEvent({
+    operation: command,
+    route: "other",
+    success: exit === ExitCode.OK,
+    elapsed_ms: Date.now() - processStart,
+  });
+}
+
+export function finish(payload: unknown, code?: ExitCode): void {
+  const exit = code ?? exitCodeFor(payload as ResultLike);
+  recordFallbackEvent(exit);
+    // In text mode: success payloads get the compact renderer; errors always emit JSON.
+  if (outputFormat === "text" && (payload as { success?: boolean }).success !== false) {
+      // `--quiet` drops the human-readable success line. It deliberately does not
+      // drop the JSON envelope below: that is the apiVersion 1 contract, and a
+      // caller who asked for JSON and got silence cannot tell ok from a crash (#47).
+    if (isQuiet()) {
+      process.exitCode = exit;
+      return;
+    }
+      // `wrap()` produces { apiVersion, ok, command, data, ... }; `data` carries
+      // the per-command payload. Render `data` when present, else the raw payload.
+    const data = (payload as { data?: Record<string, unknown> }).data;
+     const rendererTarget = data || (payload as Record<string, unknown>);
+    renderText(currentCommand, rendererTarget as Record<string, unknown>);
+    process.exitCode = exit;
+    return;
+    }
+    // JSON path: emit the envelope (apiVersion 1)
+  console.log(JSON.stringify(wrap(payload, exit), null, 2));
+  process.exitCode = exit;
+}
+
+/** Emit a usage error and exit 1. For malformed flags and missing required options. */
+export function usageError(message: string, extra: Record<string, unknown> = {}): void {
+  finish({ success: false, errorCode: ErrorCode.INVALID_ARGUMENT, message, ...extra }, ExitCode.USAGE);
+}

package/src/core/format.ts

@@ -0,0 +1,339 @@
+/**
+ * Output format selection for the CLI.
+ *
+ * #19 (B16) — a global `--format <json|text>` flag, with TTY-aware defaults:
+ *   - `--format json`  : always JSON (agent default, CI safe)
+ *   - `--format text`  : compact human-readable output (human default, interactive shell)
+ *   - no `--format`    : JSON if stdout is piped/redirected or `$CI` true; otherwise text
+ *
+ * The JSON envelope remains the canonical machine-readable contract (apiVersion 1);
+ * `text` mode is a human convenience layer that must never replace it.
+ */
+
+import { colorizeGlyphs } from "./output";
+
+/* ── Output format type ──────────────────────────────────────────────── */
+
+export type OutputFormat = "json" | "text";
+
+/**
+ * Single stdout choke point for every renderer (#47). Status glyphs are
+ * colorized here — and only here — so no renderer has to know whether color is
+ * enabled, and so an escape sequence can never reach a JSON path.
+ */
+function write(text: string): void {
+  process.stdout.write(colorizeGlyphs(text));
+}
+
+/**
+ * Resolve the output format from an explicit option, CI detection, and TTY state.
+ *
+ * Precedence:
+ * 1. Explicit `--format <json|text>` → wins always.
+ * 2. `--json` (deprecated alias for `--format json`) → emits a one-time stderr
+ *    deprecation warning.
+ * 3. `$CI` environment variable is truthy → JSON.
+ * 4. stdout is a TTY (interactive shell) → text.
+ * 5. Fall back → JSON (safe default for anything not detected above).
+ */
+export function resolveFormat(
+  opts: { format?: string; json?: boolean },
+  ctx: { isTTY?: boolean; ci?: boolean } = {}
+): { format: OutputFormat; warnDeprecate?: boolean } {
+  // 1. explicit --format
+  if (opts.format === "json" || opts.format === "text") return { format: opts.format };
+  // 2. deprecated --json alias
+  if (opts.json === true) return { format: "json", warnDeprecate: true };
+  // 3. CI env
+  const ci = ctx.ci ?? process.env.CI;
+  if (ci === "true" || ci === "1") return { format: "json" };
+  // 4. TTY
+  const isTTY = ctx.isTTY ?? process.stdout.isTTY;
+  if (isTTY) return { format: "text" };
+  // 5. default to JSON
+  return { format: "json" };
+}
+
+/* ── Text renderers ────────────────────────────────────────────────────
+ *
+ * Each renderer receives a `ResultPayload` (the `data` field that `wrap()`
+ * would produce) and prints a compact, human-readable line to stdout.
+ * Rendered lines never carry diagnostic noise — errors go through the same
+ * `finish()` path so they emit JSON, not text.
+ */
+
+type ResultPayload = {
+  success: boolean;
+  [key: string]: unknown;
+};
+
+/**
+ * Render a result payload as compact text for human readers.
+ * Each command registers its own renderer via the `registerRenderer` map;
+ * unmatched commands fall back to a generic key/value dump.
+ */
+export function renderText(command: string, payload: ResultPayload): void {
+  const renderer = renderers[command];
+  if (renderer) {
+    renderer(payload);
+  } else {
+    // Generic fallback: compact key/value dump
+    renderGenericDump(payload);
+  }
+}
+
+/**
+ * Generic renderer: print a single-line summary of the result.
+ *
+ * `finish()` only reaches a renderer when `success !== false`, so a payload with
+ * no `success` field at all (every read-only command: find-symbols, route,
+ * capabilities) is a success. Testing `payload.success` for truthiness instead
+ * marked all of them "✗ error" (#132).
+ */
+function renderGenericDump(payload: ResultPayload): void {
+  const lines: string[] = [];
+  lines.push(payload.success !== false ? "✓ ok" : "✗ " + (String(payload.errorCode || "error")));
+  for (const [k, v] of Object.entries(payload)) {
+    if (k === "success" || k === "apiVersion" || k === "error") continue;
+    if (v === null || v === undefined) continue;
+    if (Array.isArray(v)) {
+      lines.push(`  ${k}: ${v.length} item${v.length === 1 ? "" : "s"}`);
+    } else if (typeof v === "object") {
+      lines.push(`  ${k}: ${summarize(v)}`);
+    } else {
+      lines.push(`  ${k}: ${String(v)}`);
+    }
+    if (lines.length >= 8) {
+      lines.push("  …");
+      break;
+    }
+  }
+  write(lines.join("\n") + "\n");
+}
+
+/** Compact one-line summary of a value for inline display. */
+function summarize(v: unknown): string {
+  if (v === null || v === undefined) return "none";
+  if (typeof v === "string") return `"${v.length > 60 ? v.slice(0, 57) + "…" : v}"`;
+  if (typeof v === "number") return String(v);
+  if (typeof v === "boolean") return v ? "true" : "false";
+  if (Array.isArray(v)) return `[${v.length}]`;
+  return "...";
+}
+
+/* ── Per-command renderers ────────────────────────────────────────────── */
+
+const renderers: Record<string, (p: ResultPayload) => void> = {};
+
+/**
+ * Register a text renderer for a specific command.
+ * Called at module init for each command that has a dedicated renderer.
+ */
+export function registerRenderer(command: string, fn: (p: ResultPayload) => void): void {
+  renderers[command] = fn;
+}
+
+/* ── Common renderer registrations ───────────────────────────────────── */
+
+// doctor — a checklist. Reads `status`/`message`, the fields DoctorCheck
+// actually has; the original read `ok`/`detail`, so every check rendered as a
+// nameless failure (#46).
+registerRenderer("doctor", (p) => {
+  const checks = (p.checks || []) as { name: string; status: string; message: string; remediation?: string }[];
+  const s = (p.summary || {}) as Record<string, number>;
+  const glyph: Record<string, string> = { pass: "✓", fail: "✗", warn: "!", skip: "·" };
+  write(`HashPilot ${p.version} — ${p.healthy ? "✓ healthy" : "✗ issues found"} (${p.installMode} install)\n`);
+  write(`  pass ${s.pass ?? 0}  fail ${s.fail ?? 0}  warn ${s.warn ?? 0}  skip ${s.skip ?? 0}\n`);
+  for (const c of checks) {
+    write(`  ${glyph[c.status] || "?"} ${c.name}: ${c.message}\n`);
+    if (c.remediation) write(`      fix: ${c.remediation}\n`);
+  }
+});
+
+// read / read-many — print the first few lines + hash
+registerRenderer("read", (p) => {
+  printReadResult(p);
+});
+registerRenderer("read-many", (p) => {
+  const results = (p.results || p) as unknown;
+  if (Array.isArray(results)) {
+    for (const r of results as ResultPayload[]) printReadResult(r);
+  } else printReadResult(p);
+});
+registerRenderer("read-hash", (p) => printReadResult(p));
+
+/** Shared renderer for any "read" variant: show line count + hash. */
+function printReadResult(p: ResultPayload) {
+  if (p.error) {
+    write("✗ " + p.error + "\n");
+    return;
+  }
+  const lines = (p.lines as string[]) || (p.content ? [p.content] : []);
+  const n = lines.length;
+  const hash = p.hash || p.lineHash || "";
+  const filePath = p.file || p.path || "";
+  write(
+    `${filePath ? basePath(filePath) + ": " : ""}${n} line${n === 1 ? "" : "s"}${hash ? "  " + hash.slice(0, 8) : ""}\n`
+  );
+  if (lines.length > 0 && lines.length <= 5) {
+    for (const l of lines) write("  " + l + "\n");
+  }
+}
+
+// ast-replace / hash-replace / diff-apply — print success + file:line + hash
+registerRenderer("ast-replace", (p) => printEditResult(p));
+registerRenderer("hash-replace", (p) => printEditResult(p));
+registerRenderer("diff-apply", (p) => printEditResult(p));
+registerRenderer("structured-edit", (p) => printEditResult(p));
+registerRenderer("edit-many", (p) => {
+  const results = (p.results || []) as ResultPayload[];
+  const ok = results.filter((r) => r.success).length;
+  write(`${ok}/${results.length} edits succeeded\n`);
+  for (const r of results.filter((r) => !r.success)) {
+    write("✗ " + basePath(r.file || r.path || "?") + ": " + (r.error || "failed") + "\n");
+  }
+});
+
+/** Shared renderer for any single edit result. */
+function printEditResult(p: ResultPayload) {
+  const f = p.file || p.path || "";
+  const route = p.route || "?";
+  write(
+    `${p.success ? "✓" : "✗"} ${route} ${f ? basePath(f) : ""}${p.line ? ":" + p.line : ""}\n`
+  );
+  if (!p.success) write("  " + (p.error || p.message || "failed") + "\n");
+}
+
+// grep / grep-many — print N matches across M files
+registerRenderer("grep", (p) => {
+  const r = p.results || p;
+  const matches = (r?.matches || []) as unknown[];
+  write(`${matches.length} match${matches.length === 1 ? "" : "es"}\n`);
+  for (const m of (matches as any[]).slice(0, 10)) {
+    write(
+      "  " + basePath(m.file || m.path || "?") + ":" + (m.line || "?") + "  " + truncate(m.content, 60) + "\n"
+    );
+  }
+  if (matches.length > 10) write(`  … ${matches.length - 10} more\n`);
+});
+registerRenderer("grep-many", (p) => {
+  const r = p.results || p;
+  const matches = (r?.matches || []) as unknown[];
+  write(`${matches.length} match${matches.length === 1 ? "" : "es"}\n`);
+  for (const m of (matches as any[]).slice(0, 10)) {
+    write(
+      "  " + basePath(m.file || m.path || "?") + ":" + (m.line || "?") + "  " + truncate(m.content, 60) + "\n"
+    );
+  }
+});
+
+// symbol-lookup
+registerRenderer("symbol-lookup", (p) => {
+  const results = (p.results || p.symbols || []) as ResultPayload[];
+  write(`${results.length} symbol${results.length === 1 ? "" : "s"}` + "\n");
+  for (const r of results.slice(0, 10)) {
+    write(
+      `  ${r.name || r.symbol || "?"}  ${r.kind || "?"}  ${basePath(r.file || r.path || "")}:${r.line || "?"}\n`
+    );
+  }
+});
+
+// intent
+registerRenderer("intent", (p) => {
+  const plan = p.plan as ResultPayload | undefined;
+  if (p.success !== false) {
+    write("✓ plan succeeded\n");
+    if (plan?.impactSummary) write("  " + plan.impactSummary + "\n");
+  } else {
+    write("✗ " + (p.errorCode || p.error || "failed") + "\n");
+  }
+  const unresolved = plan?.unresolved;
+  if (Array.isArray(unresolved) && unresolved.length > 0) {
+    write(`  ${unresolved.length} unresolved item(s):\n`);
+    for (const u of unresolved as ResultPayload[]) {
+      write("    " + basePath(u.file || "") + ": " + (u.reason || "") + "\n");
+    }
+  }
+});
+
+// verify
+registerRenderer("verify", (p) => {
+  // "no checks ran" is its own line: printing "all checks passed" over an empty
+  // check set is exactly the false green of #106.
+  if (p.overall === "skipped") write("⚠ no checks ran — nothing was verified\n");
+  else if (p.success !== false) write("✓ all checks passed\n");
+  else write("✗ " + (p.errorCode || "checks failed") + "\n");
+  const checks = (p.checks || p.results || []) as ResultPayload[];
+  for (const c of checks.slice(0, 5)) {
+    write(`  ${c.overall === "pass" || c.success ? "✓" : "✗"} ${c.command || c.name || "?"}\n`);
+  }
+});
+
+// verify-changes — the CLI command name; the "verify" renderer above serves the
+// plan/step payloads that embed a list of checks.
+registerRenderer("verify-changes", (p) => {
+  const ran = (p.checksRun || []) as string[];
+  if (p.overall === "skipped") {
+    // Never "all checks passed" over an empty check set — that false green is
+    // the whole of #106.
+    write("⚠ no checks ran — nothing was verified\n");
+    write("  " + String(p.message || "") + "\n");
+    return;
+  }
+  const mark = p.overall === "pass" ? "✓" : "✗";
+  write(`${mark} ${p.overall} (${ran.length} check${ran.length === 1 ? "" : "s"}: ${ran.join(", ")})\n`);
+  for (const name of ran) {
+    const run = p[name] as ResultPayload | undefined;
+    if (run) write(`  ${run.passed ? "✓" : "✗"} ${name}\n`);
+  }
+});
+
+// telemetry subcommands
+registerRenderer("telemetry-show", (p) => {
+  const events = (p.events || p) as ResultPayload[];
+  const arr = Array.isArray(events) ? events : [events];
+  write(`${arr.length} event${arr.length === 1 ? "" : "s"}\n`);
+  for (const e of arr.slice(0, 10)) {
+    write(
+      "  " +
+        (e.operation || "?") +
+        " " +
+        (e.success ? "✓" : "✗") +
+        " " +
+        (e.route || "") +
+        (e.elapsed_ms ? " " + e.elapsed_ms + "ms" : "") +
+        "\n"
+    );
+  }
+});
+registerRenderer("telemetry-export", (p) => write("✓ exported " + (p.count || 0) + " event(s)\n"));
+registerRenderer("telemetry-prune", (p) => write("✓ pruned " + (p.count || 0) + " event(s)\n"));
+
+// route-query
+registerRenderer("route", (p) => {
+  write((p.success !== false ? "✓ " + (p.route || "ok") : "✗ " + (p.errorCode || "routing failed")) + "\n");
+});
+
+// ast-capabilities
+registerRenderer("ast-capabilities", (p) => {
+  const langs = (p.languages || []) as string[];
+  write(`${langs.length} language(s) supported\n`);
+});
+
+// health / telemetry-summary
+registerRenderer("health", (p) => {
+  write((p.success !== false ? "✓ " : "✗ ") + (p.message || "") + "\n");
+});
+registerRenderer("telemetry-summary", (p) => {
+  write((p.success !== false ? "✓ " : "✗ ") + (p.message || JSON.stringify(Object.keys(p)).slice(0, 120)) + "\n");
+});
+
+// ── helpers ────────────────────────────────────────────────────────────
+
+function basePath(p: string): string {
+  return p.includes("/") ? p.split("/").pop() || p : p;
+}
+function truncate(s: unknown, n: number): string {
+  const str = String(s);
+  return str.length > n ? str.slice(0, n - 1) + "…" : str;
+}