@bigknoxy/hashpilot 4.6.3

package/src/core/doctor.ts

@@ -0,0 +1,303 @@
+import { existsSync, readFileSync, mkdirSync, writeFileSync, rmSync } from "fs";
+import { join } from "path";
+import { loadConfig } from "./config";
+import { diskUsage, DISK_WARN_BYTES } from "./telemetry";
+import { probeParsers } from "./ast-edit";
+import pkg from "../../package.json" with { type: "json" };
+
+const HOME = process.env.HOME || "/root";
+const AGENTIC_TOOLS = join(HOME, ".agentic-tools");
+const CORE_DIR = join(AGENTIC_TOOLS, "structured-editing");
+const BIN_DIR = join(AGENTIC_TOOLS, "bin");
+const CLI_LAUNCHER = join(BIN_DIR, "hashpilot");
+const LOG_DIR = join(AGENTIC_TOOLS, "logs");
+const MANIFEST = join(AGENTIC_TOOLS, "manifest.json");
+const CONFIG_DIR = join(HOME, ".config", "hashpilot");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+const CLAUDE_FILE = join(HOME, ".claude", "CLAUDE.md");
+const OPENCODE_SKILL = join(HOME, ".config", "opencode", "skills", "hashpilot", "SKILL.md");
+const OPENCODE_AGENT = join(HOME, ".config", "opencode", "agent", "hashpilot.md");
+const PI_EXTENSION = join(HOME, ".pi", "agent", "extensions", "hashpilot.ts");
+const PI_SKILL = join(HOME, ".pi", "agent", "skills", "hashpilot", "SKILL.md");
+
+export interface DoctorCheck {
+  name: string;
+  status: "pass" | "fail" | "warn" | "skip";
+  message: string;
+  /** Exact command that fixes this check. Required on every `fail` (#46). */
+  remediation?: string;
+}
+
+/**
+ * How this HashPilot is being run. The `~/.agentic-tools` layout checks only
+ * mean something for an `installed` copy — reporting them as failures when a
+ * contributor runs `bun run src/cli.ts doctor` from a checkout, or when a user
+ * installed via `npm i -g`, is a false alarm that makes the exit code useless
+ * as a gate (#46).
+ */
+export type InstallMode = "installed" | "source" | "package";
+
+export interface DoctorReport {
+  checks: DoctorCheck[];
+  /** True when no check failed. Warnings and skips do not make an install unhealthy. */
+  healthy: boolean;
+  timestamp: string;
+  version: string;
+  installMode: InstallMode;
+  summary: { pass: number; fail: number; warn: number; skip: number };
+  versions: Record<string, string>;
+  parsers: { lang: string; loaded: boolean; error?: string }[];
+  configPaths: { global: string; project: string; inUse: string[] };
+  /**
+   * 0 healthy · 1 warnings only · 2 one or more failures. Doctor is meant to be
+   * a CI gate and the installer's final verification step, so the health has to
+   * reach the shell (#46).
+   */
+  exitCode: 0 | 1 | 2;
+  errorCode?: string;
+  message?: string;
+  recovery?: string;
+}
+
+const HASH_VERSION: string = pkg.version;
+const CLAUDE_MARKER = "HashPilot Claude — Structured Editing Integration";
+
+function checkFile(path: string, label: string, remediation?: string): DoctorCheck {
+  if (existsSync(path)) {
+    return { name: label, status: "pass", message: `Found: ${path}` };
+  }
+  return { name: label, status: "fail", message: `Missing: ${path}`, remediation };
+}
+
+const checkDir = checkFile;
+
+/**
+ * A check that only applies to an installed layout. Outside one it reports
+ * `skip` with the reason, so `bun run src/cli.ts doctor` in a checkout and
+ * `hashpilot doctor` from an npm install both stay exit 0 (#46).
+ */
+function whenInstalled(mode: InstallMode, label: string, run: () => DoctorCheck): DoctorCheck {
+  if (mode === "installed") return run();
+  return {
+    name: label,
+    status: "skip",
+    message: mode === "source"
+      ? "Running from a source checkout — installed layout not expected"
+      : "Running from an npm package — ~/.agentic-tools layout not expected",
+  };
+}
+
+/**
+ * An adapter integration that is simply not installed is not a broken
+ * HashPilot. Nobody has every agent host on one machine, so a missing Pi
+ * extension used to fail an otherwise-perfect install (#46).
+ */
+function checkOptionalFile(path: string, label: string, what: string): DoctorCheck {
+  if (existsSync(path)) return { name: label, status: "pass", message: `Found: ${path}` };
+  return { name: label, status: "skip", message: `${what} not installed` };
+}
+
+/**
+ * Where this HashPilot is running from. `installed` means the script lives
+ * under `~/.agentic-tools`; `package` means a node_modules tree (npm install);
+ * anything else is a working checkout.
+ */
+export function detectInstallMode(dir: string = import.meta.dir): InstallMode {
+  if (dir.startsWith(AGENTIC_TOOLS + "/")) return "installed";
+  if (dir.includes("/node_modules/")) return "package";
+  return existsSync(CORE_DIR) ? "installed" : "source";
+}
+
+function checkWritable(path: string, label: string): DoctorCheck {
+  try {
+    if (!existsSync(path)) {
+      mkdirSync(path, { recursive: true });
+    }
+    const testFile = join(path, `.doctor-write-test-${Date.now()}`);
+    writeFileSync(testFile, "");
+    try { rmSync(testFile); } catch {}
+    return { name: label, status: "pass", message: `Writable: ${path}` };
+  } catch {
+    return { name: label, status: "fail", message: `Not writable: ${path}` };
+  }
+}
+
+export function doctor(): DoctorReport {
+  const checks: DoctorCheck[] = [];
+  const timestamp = new Date().toISOString();
+  const installMode = detectInstallMode();
+  const install = (label: string, run: () => DoctorCheck) => checks.push(whenInstalled(installMode, label, run));
+
+  // 1-3. Installed layout: core files, launcher, PATH, and a live CLI probe.
+  install("core-directory", () => checkDir(CORE_DIR, "core-directory", "Reinstall: curl -fsSL https://raw.githubusercontent.com/bigknoxy/HashPilot/main/scripts/install.sh | bash"));
+  install("core-cli.ts", () => checkFile(join(CORE_DIR, "src", "cli.ts"), "core-cli.ts", "Reinstall HashPilot"));
+  install("core-package.json", () => checkFile(join(CORE_DIR, "package.json"), "core-package.json", "Reinstall HashPilot"));
+  install("cli-launcher", () => checkFile(CLI_LAUNCHER, "cli-launcher", "Run `bun run install-cli`"));
+  install("bin-on-path", checkPathEntry);
+  install("cli-executable", checkCLIExecutable);
+
+  // 4. Config
+  checks.push(...checkConfig());
+
+  // 5. Agent host integrations — optional by nature.
+  checks.push(checkClaudeIntegration());
+  checks.push(checkOptionalFile(OPENCODE_SKILL, "opencode-skill", "OpenCode"));
+  checks.push(checkOptionalFile(OPENCODE_AGENT, "opencode-agent", "OpenCode"));
+  checks.push(checkOptionalFile(PI_EXTENSION, "pi-extension", "Pi"));
+  checks.push(checkOptionalFile(PI_SKILL, "pi-skill", "Pi"));
+
+  // 6. Telemetry store
+  checks.push(checkWritable(LOG_DIR, "telemetry-writable"));
+  checks.push(checkTelemetrySize());
+  install("manifest", () => checkFile(MANIFEST, "manifest", "Reinstall HashPilot"));
+
+  // 7. tree-sitter bindings. `getParser` swallows load errors and the router
+  // silently downgrades AST -> diff, so this is the only place a broken native
+  // build is visible before edit quality quietly drops (#46).
+  const parsers = probeParsers();
+  const broken = parsers.filter((p) => !p.loaded);
+  checks.push(
+    broken.length === 0
+      ? { name: "ast-parsers", status: "pass", message: `All ${parsers.length} tree-sitter parsers load` }
+      : {
+          name: "ast-parsers",
+          status: "fail",
+          message: `${broken.length}/${parsers.length} parsers failed to load: ${broken.map((p) => `${p.lang} (${p.error})`).join(", ")}`,
+          remediation: "Run `bun install` to rebuild the tree-sitter native bindings",
+        },
+  );
+
+  const summary = {
+    pass: checks.filter((c) => c.status === "pass").length,
+    fail: checks.filter((c) => c.status === "fail").length,
+    warn: checks.filter((c) => c.status === "warn").length,
+    skip: checks.filter((c) => c.status === "skip").length,
+  };
+  // A skip is "does not apply here", not "broken". Requiring every check to
+  // pass marked a perfectly good install unhealthy whenever the user had no
+  // config file or no Pi (#46).
+  const healthy = summary.fail === 0;
+  const exitCode: 0 | 1 | 2 = summary.fail > 0 ? 2 : summary.warn > 0 ? 1 : 0;
+
+  const failed = checks.filter((c) => c.status === "fail");
+  return {
+    checks,
+    healthy,
+    timestamp,
+    version: HASH_VERSION,
+    installMode,
+    summary,
+    versions: { hashpilot: HASH_VERSION, bun: Bun.version, node: process.versions.node },
+    parsers,
+    configPaths: {
+      global: CONFIG_FILE,
+      project: join(process.cwd(), ".hashpilot.json"),
+      inUse: [CONFIG_FILE, join(process.cwd(), ".hashpilot.json")].filter((p) => existsSync(p)),
+    },
+    exitCode,
+    ...(failed.length > 0
+      ? {
+          errorCode: "DOCTOR_FAILED",
+          message: `${failed.length} check(s) failed: ${failed.map((c) => c.name).join(", ")}`,
+          recovery: failed.find((c) => c.remediation)?.remediation,
+        }
+      : {}),
+  };
+}
+
+/**
+ * Report the telemetry store's size. Retention is enforced automatically, but
+ * a machine that was never pruned by an older version — or one running with a
+ * long `retentionDays` — can still be carrying hundreds of megabytes nobody
+ * knows about (#50). A warn, never a fail: a large log is not a broken install.
+ */
+function checkTelemetrySize(): DoctorCheck {
+  const bytes = diskUsage();
+  const mb = (bytes / (1024 * 1024)).toFixed(1);
+  if (bytes > DISK_WARN_BYTES) {
+    return {
+      name: "telemetry-size",
+      status: "warn",
+      message: `Telemetry store is ${mb} MB (threshold ${(DISK_WARN_BYTES / (1024 * 1024)).toFixed(0)} MB) — run 'hashpilot telemetry prune' or lower telemetry.retentionDays`,
+    };
+  }
+  return { name: "telemetry-size", status: "pass", message: `Telemetry store is ${mb} MB` };
+}
+
+/**
+ * The launcher existing is not the same as it being runnable. `install-cli`
+ * used to create the symlink and stop, leaving `hashpilot` unresolvable in a
+ * fresh shell while every other check passed. Report that as its own failure
+ * with the exact line to add.
+ */
+export function checkPathEntry(): DoctorCheck {
+  const entries = (process.env.PATH || "").split(":").filter(Boolean);
+  if (entries.includes(BIN_DIR)) {
+    return { name: "bin-on-path", status: "pass", message: `${BIN_DIR} is on PATH` };
+  }
+  return {
+    name: "bin-on-path",
+    status: "fail",
+    message: `${BIN_DIR} is not on PATH. Run \`bun run install-cli\`, or add: export PATH="$HOME/.agentic-tools/bin:$PATH"`,
+  };
+}
+
+function checkCLIExecutable(): DoctorCheck {
+  try {
+    // Invoke the launcher by absolute path: this check is about whether the
+    // CLI runs at all. PATH resolution is `checkPathEntry`'s job, and injecting
+    // BIN_DIR here is what used to hide a broken install.
+    const proc = Bun.spawnSync([CLI_LAUNCHER, "--version"]);
+    if (proc.exitCode === 0) {
+      return { name: "cli-executable", status: "pass", message: `CLI works: ${proc.stdout.toString().trim()}` };
+    }
+    return { name: "cli-executable", status: "fail", message: `CLI exited with code ${proc.exitCode}: ${proc.stderr.toString().trim()}` };
+  } catch (e: any) {
+    return { name: "cli-executable", status: "fail", message: `Cannot run CLI: ${e.message}` };
+  }
+}
+
+function checkConfig(): DoctorCheck[] {
+  const results: DoctorCheck[] = [];
+  const cfgExists = existsSync(CONFIG_FILE);
+  if (cfgExists) {
+    results.push(checkFile(CONFIG_FILE, "config-file"));
+    try {
+      const cfg = JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+      results.push({ name: "config-parseable", status: "pass", message: "Config is valid JSON" });
+      if (cfg.telemetry && typeof cfg.telemetry.enabled !== "boolean") {
+        results.push({ name: "config-telemetry-type", status: "warn", message: "telemetry.enabled should be boolean" });
+      }
+      if (cfg.routePolicy) {
+        results.push({ name: "config-has-policy", status: "pass", message: "Route policy configured" });
+      }
+    } catch {
+      results.push({ name: "config-parseable", status: "fail", message: "Config is not valid JSON" });
+    }
+  } else {
+    results.push({ name: "config-file", status: "skip", message: "No config file — using defaults" });
+  }
+  // Verify loadConfig() works regardless
+  try {
+    const cfg = loadConfig();
+    results.push({ name: "config-loadable", status: "pass", message: "Config defaults load correctly" });
+  } catch {
+    results.push({ name: "config-loadable", status: "fail", message: "Cannot load config" });
+  }
+  return results;
+}
+
+function checkClaudeIntegration(): DoctorCheck {
+  if (!existsSync(CLAUDE_FILE)) {
+    return { name: "claude-integration", status: "skip", message: "Claude CLAUDE.md not found — not installed" };
+  }
+  try {
+    const content = readFileSync(CLAUDE_FILE, "utf-8");
+    if (content.includes(CLAUDE_MARKER)) {
+      return { name: "claude-integration", status: "pass", message: "HashPilot section found in CLAUDE.md" };
+    }
+    return { name: "claude-integration", status: "warn", message: "CLAUDE.md exists but HashPilot section missing" };
+  } catch {
+    return { name: "claude-integration", status: "fail", message: "Cannot read CLAUDE.md" };
+  }
+}

package/src/core/encoding.ts

@@ -0,0 +1,116 @@
+/**
+ * Byte-fidelity for file content (issue #30).
+ *
+ * A structured-editing tool has exactly one non-negotiable property: it must
+ * not change bytes it was not asked to change. Reading a file with
+ * `.split("\n")` and writing it back with `.join("\n")` breaks that three ways
+ * — it deletes `\r` from every line of a CRLF file, folds a BOM into line 1
+ * where it corrupts that line's hash, and drops or invents a trailing newline.
+ * The result is a one-line edit that produces a diff touching every line.
+ *
+ * The fix is to normalize at the boundary: `decodeText` strips the BOM and
+ * converts every line ending to `\n`, all the editing tiers operate on that
+ * plain-LF text, and `encodeText` puts the original bytes back. Everything in
+ * between stays simple, and only this module knows about `\r`.
+ */
+
+/** How a file's bytes were laid out, so a write can reproduce them. */
+export interface FileEncoding {
+  /** File began with U+FEFF. */
+  bom: boolean;
+  /** Dominant line ending, used for any line the edit created. */
+  eol: "\n" | "\r\n" | "\r";
+  /**
+   * The original ending of each line, when the file mixed styles. Lines the
+   * edit did not add keep their own ending; anything past the end of this
+   * array falls back to `eol`. Absent when the file was consistent.
+   */
+  endings?: string[];
+  /** File ended with a line ending. */
+  trailingNewline: boolean;
+}
+
+const BOM = "";
+
+/** Matches every line terminator we preserve: CRLF, lone LF, lone CR. */
+const EOL_RE = /\r\n|\n|\r/g;
+
+/**
+ * Split raw file text into plain-LF content plus the information needed to
+ * write the original bytes back. `encodeText(decodeText(raw))` is the
+ * identity for any input.
+ */
+export function decodeText(raw: string): { text: string; encoding: FileEncoding } {
+  const bom = raw.startsWith(BOM);
+  const body = bom ? raw.slice(BOM.length) : raw;
+
+  const endings: string[] = [];
+  let counts = { "\n": 0, "\r\n": 0, "\r": 0 };
+  let text = "";
+  let last = 0;
+  EOL_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = EOL_RE.exec(body)) !== null) {
+    text += body.slice(last, m.index) + "\n";
+    endings.push(m[0]);
+    counts[m[0] as keyof typeof counts]++;
+    last = m.index + m[0].length;
+  }
+  text += body.slice(last);
+
+  const trailingNewline = endings.length > 0 && last === body.length;
+
+  // Dominant style, with LF as the tiebreak: a file with no line endings at
+  // all has no evidence either way, and LF is what a new line should use.
+  let eol: FileEncoding["eol"] = "\n";
+  let best = 0;
+  for (const style of ["\n", "\r\n", "\r"] as const) {
+    if (counts[style] > best) {
+      best = counts[style];
+      eol = style;
+    }
+  }
+
+  const consistent = endings.every((e) => e === eol);
+  return {
+    text,
+    encoding: { bom, eol, trailingNewline, ...(consistent ? {} : { endings }) },
+  };
+}
+
+/**
+ * Reassemble plain-LF text into the file's original byte layout.
+ *
+ * Line endings are restored by position, so an edit that rewrites line 3 of a
+ * mixed-ending file leaves lines 1, 2, and 4 exactly as they were. Lines the
+ * edit added take the dominant style — there is no original ending to copy.
+ *
+ * Trailing-newline presence follows the original file, not the edit: an agent
+ * that hands back content with or without a final newline is describing the
+ * lines it wants, not asking to change how the file terminates.
+ */
+export function encodeText(text: string, encoding: FileEncoding): string {
+  // Emptying a file means an empty file. Restoring the trailing newline here
+  // would turn a deletion into a file containing one blank line.
+  if (text === "") return encoding.bom ? BOM : "";
+
+  const hadTrailing = text.endsWith("\n");
+  const body = hadTrailing ? text.slice(0, -1) : text;
+  const lines = body.split("\n");
+
+  let out = encoding.bom ? BOM : "";
+  for (let i = 0; i < lines.length; i++) {
+    out += lines[i];
+    const isLast = i === lines.length - 1;
+    if (isLast && !encoding.trailingNewline) break;
+    out += encoding.endings?.[i] ?? encoding.eol;
+  }
+  return out;
+}
+
+/** Read a file and decode it in one step. */
+export async function readDecoded(
+  filePath: string
+): Promise<{ text: string; encoding: FileEncoding }> {
+  return decodeText(await Bun.file(filePath).text());
+}

package/src/core/envelope.ts

@@ -0,0 +1,163 @@
+import { ErrorCode } from "./telemetry";
+import { ExitCode, exitCodeFor, type ResultLike } from "./exit-codes";
+
+/**
+ * The single JSON shape every command writes to stdout.
+ *
+ * Before this existed, each of the 24 commands returned its own ad-hoc shape —
+ * some a bare array, some an object — so an adapter had to special-case the
+ * command it had just run, and had no field to detect a contract change with.
+ * See docs/ADAPTER-CONTRACT.md and schema/hashpilot-envelope.schema.json.
+ */
+export interface Envelope<T = unknown> {
+  /** Bumped only on a breaking change to the envelope itself. */
+  apiVersion: string;
+  /** The one boolean an adapter checks. Always agrees with the exit code. */
+  ok: boolean;
+  /** The subcommand path that produced this, e.g. `telemetry show`. */
+  command: string;
+  /** The per-command payload — the shape commands used to return at top level. */
+  data: T | null;
+  error: EnvelopeError | null;
+  /** Non-fatal notices (route fallback, anchor relocation, corrupt log lines). */
+  warnings: EnvelopeWarning[];
+}
+
+export interface EnvelopeError {
+  /** A member of `ErrorCode`. Adapters branch on this, never on `message`. */
+  code: string;
+  message: string;
+  /**
+   * The literal next command to run, where one exists — not prose. This is what
+   * turns a dead end into a retry, so prefer a runnable string over advice.
+   */
+  recovery?: string;
+  details?: Record<string, unknown>;
+}
+
+export interface EnvelopeWarning {
+  code: string;
+  message: string;
+  [key: string]: unknown;
+}
+
+/** Current envelope version. Bump only when the envelope's own shape breaks. */
+export const API_VERSION = "1";
+
+let currentCommand = "";
+let warnings: EnvelopeWarning[] = [];
+
+/** Records which subcommand is running, so `wrap` can name it. Set by the CLI's preAction hook. */
+export function setCommand(name: string): void {
+  currentCommand = name;
+  warnings = [];
+}
+
+export function currentCommandName(): string {
+  return currentCommand;
+}
+
+/**
+ * Attach a non-fatal notice to the envelope the current command will emit.
+ *
+ * Route fallbacks and anchor relocations used to be entirely invisible: an AST
+ * edit that silently became a diff edit looked identical to one that did not.
+ */
+export function addWarning(warning: EnvelopeWarning): void {
+  warnings.push(warning);
+}
+
+export function takeWarnings(): EnvelopeWarning[] {
+  const taken = warnings;
+  warnings = [];
+  return taken;
+}
+
+/** Fields a command result may carry that the envelope lifts out of `data`. */
+interface ErrorBearing {
+  success?: boolean;
+  passed?: boolean;
+  error?: unknown;
+  errorCode?: string;
+  message?: string;
+  recovery?: string;
+}
+
+function firstFailure(payload: unknown): ErrorBearing | undefined {
+  if (Array.isArray(payload)) {
+    // Batch results: report the first failing element, since the exit code
+    // already reflects the worst one.
+    for (const item of payload) {
+      const found = firstFailure(item);
+      if (found) return found;
+    }
+    return undefined;
+  }
+  if (!payload || typeof payload !== "object") return undefined;
+  const p = payload as ErrorBearing & { result?: unknown };
+  // `errorCode` alone counts as a failure. `verify-changes` returns neither
+  // `success` nor `error` — only `errorCode` — so its failures used to reach the
+  // envelope as `{code: "UNKNOWN", message: "Operation failed."}` beside a
+  // perfectly specific `data.errorCode` (#106).
+  const failed =
+    p.success === false || p.passed === false || (p.error !== undefined && p.error !== null) || !!p.errorCode;
+  if (failed) return p;
+  // Wrapper shapes (route-edit, batch) nest the real outcome under `result`.
+  return p.result ? firstFailure(p.result) : undefined;
+}
+
+function messageOf(p: ErrorBearing): string {
+  if (typeof p.message === "string" && p.message) return p.message;
+  if (typeof p.error === "string" && p.error) return p.error;
+  if (p.error && typeof p.error === "object") {
+    const nested = (p.error as { message?: string }).message;
+    if (nested) return nested;
+  }
+  return "Operation failed.";
+}
+
+function codeOf(p: ErrorBearing): string {
+  if (p.errorCode) return p.errorCode;
+  if (p.error && typeof p.error === "object") {
+    const nested = (p.error as { code?: string }).code;
+    if (nested) return nested;
+  }
+  // An unmapped failure is still a failure. Naming it beats emitting `ok: false`
+  // with no code for an adapter to branch on.
+  return ErrorCode.UNKNOWN;
+}
+
+/**
+ * Wrap a command result in the envelope.
+ *
+ * `ok` is derived from the same exit code the process will use, so the two
+ * cannot disagree — an adapter that trusts `ok` and one that trusts `$?` reach
+ * the same conclusion.
+ */
+export function wrap<T>(payload: T, code: ExitCode, command = currentCommand): Envelope<T> {
+  const failure = code === ExitCode.OK ? undefined : firstFailure(payload);
+  const error: EnvelopeError | null =
+    code === ExitCode.OK
+      ? null
+      : failure
+        ? {
+            code: codeOf(failure),
+            message: messageOf(failure),
+            ...(failure.recovery ? { recovery: failure.recovery } : {}),
+          }
+        : { code: ErrorCode.UNKNOWN, message: "Operation failed." };
+
+  return {
+    apiVersion: API_VERSION,
+    ok: code === ExitCode.OK,
+    command,
+    data: payload ?? null,
+    error,
+    warnings: takeWarnings(),
+  };
+}
+
+/** Convenience for callers that have a result but not yet an exit code. */
+export function wrapResult<T>(payload: T, command?: string): Envelope<T> {
+  return wrap(payload, exitCodeFor(payload as ResultLike), command);
+}