@bigknoxy/hashpilot 4.6.3

package/scripts/uninstall.sh

@@ -0,0 +1,202 @@
+#!/bin/bash
+set -euo pipefail
+
+BOLD='\033[1m'
+DIM='\033[2m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+log()    { printf "${GREEN}[hashpilot]${NC} %s\n" "$1"; }
+warn()   { printf "${YELLOW}[hashpilot]${NC} %s\n" "$1"; }
+err()    { printf "${RED}[hashpilot]${NC} %s\n" "$1"; }
+detail() { printf "${DIM}  →${NC} %s\n" "$1"; }
+
+TARGET_DIR="${HASHPILOT_DIR:-${HOME}/.agentic-tools}"
+KEEP_CONFIG=false
+FORCE=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --keep-config) KEEP_CONFIG=true; shift ;;
+    --force|-f) FORCE=true; shift ;;
+    --help|-h)
+      echo "HashPilot Uninstaller"
+      echo "Usage: $0 [options]"
+      echo "  --keep-config   Preserve config and telemetry data"
+      echo "  --force, -f     Skip confirmation prompt (auto-detected when piped)"
+      echo "  --help, -h      Show this help"
+      echo ""
+      echo "One-liner: curl -fsSL https://raw.githubusercontent.com/bigknoxy/HashPilot/main/scripts/uninstall.sh | sh -s -- -f"
+      exit 0
+      ;;
+    *) err "Unknown option: $1"; exit 1 ;;
+  esac
+done
+
+echo "${BOLD}HashPilot Uninstaller${NC}"
+echo ""
+
+# ── Confirmation ─────────────────────────────────────────────────────────
+if [[ "$FORCE" != "true" ]]; then
+  # When piped (no TTY), skip prompt — auto-force
+  if ! [[ -t 0 ]]; then
+    FORCE=true
+  else
+    echo "This will remove HashPilot and all its components."
+    echo "  Target: $TARGET_DIR"
+    echo "  Keep config: $KEEP_CONFIG"
+    echo ""
+    echo -n "Continue? [y/N] "
+    read -r CONFIRM
+    if [[ "$CONFIRM" != "y" && "$CONFIRM" != "Y" ]]; then
+      log "Uninstall cancelled."
+      exit 0
+    fi
+  fi
+fi
+
+REMOVED=0
+SKIPPED=0
+
+remove_file() {
+  local path="$1"
+  local label="$2"
+  # Expand ~ if present
+  path="${path/#\~/${HOME}}"
+  if [[ -f "$path" ]]; then
+    rm -f "$path"
+    detail "Removed ${label}: ${path}"
+    REMOVED=$((REMOVED+1))
+  elif [[ -d "$path" ]]; then
+    rm -rf "$path"
+    detail "Removed ${label}: ${path}"
+    REMOVED=$((REMOVED+1))
+  else
+    detail "Already removed: ${path}"
+    SKIPPED=$((SKIPPED+1))
+  fi
+}
+
+# ── Read manifest if available ───────────────────────────────────────────
+MANIFEST="$TARGET_DIR/manifest.json"
+if [[ -f "$MANIFEST" ]]; then
+  log "Reading manifest..."
+else
+  warn "No manifest found at $MANIFEST — will attempt best-effort cleanup"
+fi
+
+# ── Claude integration ───────────────────────────────────────────────────
+log "Removing Claude integration..."
+CLAUDE_FILE="${HOME}/.claude/CLAUDE.md"
+CLAUDE_MARKER_START="HashPilot Claude"
+if [[ -f "$CLAUDE_FILE" ]]; then
+  # Remove the HashPilot section: from marker to the next ## or end
+  if grep -q "$CLAUDE_MARKER_START" "$CLAUDE_FILE" 2>/dev/null; then
+    # Use sed to remove from HashPilot heading to end (or next heading)
+    if grep -q "^## " "$CLAUDE_FILE" 2>/dev/null; then
+      # Has multiple sections — remove just this one by matching its end
+      sed -i '/^## .*HashPilot Claude/,/^## /{
+        /^## .*HashPilot Claude/d
+        /^## /!d
+      }' "$CLAUDE_FILE"
+    else
+      # Single section — remove from HashPilot heading to end
+      sed -i '/^## .*HashPilot Claude/,$d' "$CLAUDE_FILE"
+    fi
+    # Clean up trailing blank lines + deduplicate mid-file blank lines
+    sed -i -e :a -e '/^\n*$/{$d;N;ba' -e '}' "$CLAUDE_FILE" 2>/dev/null || true
+    sed -i '/^$/{ N; /^\n$/d }' "$CLAUDE_FILE" 2>/dev/null || true
+    detail "Removed HashPilot section from $CLAUDE_FILE"
+    REMOVED=$((REMOVED+1))
+  else
+    detail "HashPilot section not found in $CLAUDE_FILE (skipping)"
+    SKIPPED=$((SKIPPED+1))
+  fi
+else
+  detail "CLAUDE.md not found (skipping)"
+  SKIPPED=$((SKIPPED+1))
+fi
+
+# ── OpenCode integration ─────────────────────────────────────────────────
+log "Removing OpenCode integration..."
+remove_file "${HOME}/.config/opencode/skills/hashpilot/SKILL.md" "OpenCode skill"
+remove_file "${HOME}/.config/opencode/agent/hashpilot.md" "OpenCode agent"
+# Remove empty skill/agent dirs
+rmdir "${HOME}/.config/opencode/skills/hashpilot" 2>/dev/null || true
+rmdir "${HOME}/.config/opencode/skills" 2>/dev/null || true
+rmdir "${HOME}/.config/opencode/agent" 2>/dev/null || true
+
+# ── Pi integration ───────────────────────────────────────────────────────
+log "Removing Pi integration..."
+remove_file "${HOME}/.pi/agent/extensions/hashpilot.ts" "Pi extension"
+remove_file "${HOME}/.pi/agent/skills/hashpilot/SKILL.md" "Pi skill"
+rmdir "${HOME}/.pi/agent/extensions" 2>/dev/null || true
+rmdir "${HOME}/.pi/agent/skills/hashpilot" 2>/dev/null || true
+rmdir "${HOME}/.pi/agent/skills" 2>/dev/null || true
+
+# ── Core, bin, telemetry ─────────────────────────────────────────────────
+log "Removing Core files..."
+remove_file "$TARGET_DIR/bin/hashpilot" "CLI launcher"
+# Also remove stale symlink from old binary name (pre-3.1 installs).
+remove_file "$TARGET_DIR/bin/structured-edit" "stale CLI launcher (old name)"
+rmdir "$TARGET_DIR/bin" 2>/dev/null || true
+
+if [[ "$KEEP_CONFIG" == "true" ]]; then
+  detail "Preserving telemetry (--keep-config)"
+  # Remove core but keep logs
+  remove_file "$TARGET_DIR/structured-editing" "Core source"
+  # Preserve logs
+  detail "Preserving: $TARGET_DIR/logs"
+else
+  remove_file "$TARGET_DIR/structured-editing" "Core source"
+  remove_file "$TARGET_DIR/logs" "Telemetry logs"
+fi
+
+# ── Config ───────────────────────────────────────────────────────────────
+if [[ "$KEEP_CONFIG" == "true" ]]; then
+  detail "Preserving config (--keep-config)"
+else
+  remove_file "${HOME}/.config/hashpilot/config.json" "Config file"
+  rmdir "${HOME}/.config/hashpilot" 2>/dev/null || true
+fi
+
+# ── Remove PATH entry from shell rc ──────────────────────────────────────
+log "Removing PATH entries..."
+for rc in "${HOME}/.bashrc" "${HOME}/.zshrc" "${HOME}/.bash_profile" "${HOME}/.profile"; do
+  if [[ -f "$rc" ]]; then
+    if grep -q "# >>> hashpilot path >>>" "$rc" 2>/dev/null; then
+      # BSD sed (macOS) requires an explicit backup suffix after -i; GNU sed
+      # accepts the empty one, so `-i ''` is not portable either. Pick per-platform.
+      if sed --version >/dev/null 2>&1; then SED_INPLACE=(sed -i); else SED_INPLACE=(sed -i ''); fi
+      "${SED_INPLACE[@]}" '/^# >>> hashpilot path >>>/,/^# <<< hashpilot path <<</d' "$rc"
+      # Clean up trailing blank lines
+      "${SED_INPLACE[@]}" -e :a -e '/^\n*$/{$d;N;ba' -e '}' "$rc" 2>/dev/null || true
+      detail "Removed PATH entry from $rc"
+      REMOVED=$((REMOVED+1))
+    fi
+  fi
+done
+
+# ── Remove manifest and target dir if empty ──────────────────────────────
+remove_file "$MANIFEST" "Manifest"
+rmdir "$TARGET_DIR" 2>/dev/null || true
+
+# ── Summary ───────────────────────────────────────────────────────────────
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+printf "${GREEN} HashPilot uninstalled${NC}\n"
+printf "  Removed: %d   Skipped: %d\n" "$REMOVED" "$SKIPPED"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "Note: The following may remain if they existed before HashPilot:"
+echo "  ~/.bashrc modifications (restored)"
+echo "  ~/.claude/CLAUDE.md modifications (restored)"
+echo "  ~/.pi/agent/extensions/ (if still empty)"
+echo "  ~/.config/opencode/skills/hashpilot/ (if still empty)"
+echo ""
+echo "To complete removal, restart your shell or run:"
+echo "  hash -r 2>/dev/null || exec \$SHELL"
+echo ""
+

package/src/cli-node.cjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// Node-parseable entry point for the `hashpilot` binary.
+//
+// HashPilot runs on Bun (src/cli.ts has a `#!/usr/bin/env bun` shebang and uses
+// Bun-only APIs). Pointing `bin` straight at the TypeScript source means
+// `npm i -g hashpilot` on a Node-only machine installs cleanly and then dies with
+// a syntax error on first use. This shim is deliberately plain CommonJS so any
+// Node >= 14 can parse it, and its only job is to hand off to Bun — or, when Bun
+// is absent, to say so in one actionable line instead of a stack trace.
+//
+// `.cjs` (not `.js`) because package.json declares `"type": "module"`.
+// See issue #35, Option A.
+
+"use strict";
+
+var path = require("path");
+var spawnSync = require("child_process").spawnSync;
+
+var CLI = path.join(__dirname, "cli.ts");
+
+// Array argv, never a shell string: arguments routinely contain source code,
+// spaces, quotes, and newlines, and a shell would both mangle and execute them.
+var res = spawnSync("bun", ["run", CLI].concat(process.argv.slice(2)), {
+  stdio: "inherit",
+});
+
+if (res.error && res.error.code === "ENOENT") {
+  process.stderr.write(
+    "hashpilot requires Bun (>= 1.2.0), which was not found on your PATH.\n" +
+      "\n" +
+      "  Install it:  curl -fsSL https://bun.sh/install | bash\n" +
+      "  Then reopen your shell and re-run this command.\n" +
+      "\n" +
+      "HashPilot is Bun-only today; see the support matrix in the README.\n"
+  );
+  process.exit(127);
+}
+
+if (res.error) {
+  process.stderr.write("hashpilot: failed to launch Bun: " + res.error.message + "\n");
+  process.exit(70);
+}
+
+// Propagate the child's exit status verbatim. HashPilot's exit codes are a
+// documented contract (0 ok · 1 usage · 2 edit failed · 3 stale · 4 verify
+// failed · 5 I/O · 70 internal); collapsing them to 0/1 would break every
+// caller that branches on code 3 to retry a stale anchor.
+if (res.signal) {
+  process.exit(128 + (require("os").constants.signals[res.signal] || 0));
+}
+process.exit(res.status === null ? 70 : res.status);

package/src/cli.ts

@@ -0,0 +1,209 @@
+#!/usr/bin/env bun
+import { Command, CommanderError } from "commander";
+// Single source of truth for the version. Bun inlines this JSON import at build
+// time, so dist/ carries the real version instead of a hardcoded literal.
+import pkg from "../package.json" with { type: "json" };
+import {
+  loadConfig,
+  createChangeSet,
+  configureSnapshots,
+  setCurrentChangeSet,
+  pruneSnapshots,
+  PathDeniedError,
+  configureWriteBoundary,
+  finish,
+  usageError,
+  setCommand,
+  setAllowParseErrors,
+  ErrorCode,
+  ExitCode,
+  configureTelemetry,
+  enableTelemetry,
+  resolveTelemetryEnabled,
+  setOutputFormat,
+  configureOutput,
+  resolveFormat,
+  TelemetryReadError,
+} from "./core/index";
+
+// Every command group registers itself onto `program`. The registration order
+// below is the order the groups appear in `--help`; do not reshuffle it (#48).
+import { register as registerRead } from "./commands/read";
+import { register as registerHash } from "./commands/hash";
+import { register as registerAst } from "./commands/ast";
+import { register as registerEdit } from "./commands/edit";
+import { register as registerIntent } from "./commands/intent";
+import { register as registerDiff } from "./commands/diff";
+import { register as registerVerify } from "./commands/verify";
+import { register as registerTelemetry } from "./commands/telemetry";
+import { register as registerProvenance } from "./commands/provenance";
+import { register as registerMcp } from "./commands/mcp";
+import { register as registerMaintenance } from "./commands/maintenance";
+import { register as registerRoute } from "./commands/route";
+
+const VERSION: string = pkg.version;
+
+const program = new Command();
+
+program
+  .name("hashpilot")
+  .description("HashPilot — Structured Editing Core for Coding Agents")
+  .version(VERSION)
+  .option("--allow-outside-root", "Permit writes outside the project root (credentials and system paths stay blocked)")
+  .option("--allowed-root <dir...>", "Additional directory writes may target")
+  .option("--no-telemetry", "Disable telemetry logging for this invocation")
+  .option("--allow-parse-errors", "Edit a file that already has syntax errors (the post-edit parse check still applies)")
+    .option("--format <fmt>", "Output format: json or text (default: json if piped/CI, text if TTY)")
+    .option("--json", "[deprecated: use --format json] Force JSON output", false)
+  .option("-q, --quiet", "Suppress the human-readable success line (the JSON envelope is never suppressed)")
+  .option("-v, --verbose", "Write routing and timing diagnostics to stderr")
+  .option("--no-color", "Disable ANSI color in text output (also honors NO_COLOR)")
+  .hook("preAction", (thisCommand, actionCommand) => {
+    // Name the running subcommand so the envelope can report it. Walk up so
+    // nested commands read as "telemetry show", not "show".
+    const path: string[] = [];
+    for (let c: typeof actionCommand | null = actionCommand; c && c.parent; c = c.parent) path.unshift(c.name());
+    setCommand(path.join(" "));
+
+     // #19 (B16): resolve output format and set it globally
+    const globals = thisCommand.opts();
+    const { format, warnDeprecate } = resolveFormat(globals, { ci: process.env.CI === "true" || process.env.CI === "1" });
+    setOutputFormat(format, path.join(" "));
+    // Color and verbosity resolve from the same globals, after the format is
+    // known: color is text-mode only, so JSON output can never carry escapes (#47).
+    configureOutput({
+      quiet: Boolean(globals.quiet),
+      verbose: Boolean(globals.verbose),
+      color: globals.color,
+      format,
+      isTTY: Boolean(process.stdout.isTTY),
+    });
+    if (warnDeprecate) process.stderr.write("[deprecation] --json is deprecated; use --format json\n");
+    const config = loadConfig();
+    configureWriteBoundary({
+      allowOutsideRoot: Boolean(globals.allowOutsideRoot),
+      allowedRoots: [...(config.allowedRoots || []), ...(globals.allowedRoot || [])],
+    });
+    // Apply sizing/retention from config, then the kill switch, so the CLI flag
+    // and env var win over `telemetry.enabled`.
+    configureTelemetry(config.telemetry);
+    enableTelemetry(resolveTelemetryEnabled(config.telemetry, globals.telemetry === false));
+    setAllowParseErrors(Boolean(globals.allowParseErrors));
+
+    // Every write this invocation makes belongs to one changeSet, so `undo`
+    // has a unit to work in even for commands that never mint one themselves.
+    configureSnapshots(config.snapshots);
+    setCurrentChangeSet(config.snapshots?.enabled === false ? null : createChangeSet());
+    pruneSnapshots();
+  });
+registerRead(program);
+registerHash(program);
+registerAst(program);
+registerEdit(program);
+registerIntent(program);
+registerDiff(program);
+registerVerify(program);
+registerTelemetry(program);
+registerProvenance(program);
+registerMcp(program);
+registerMaintenance(program);
+registerRoute(program);
+
+/** Node syscall codes that mean "the filesystem said no", not "HashPilot has a bug". */
+const IO_SYSCALL_CODES = new Set([
+  "ENOENT", "EACCES", "EPERM", "EISDIR", "ENOTDIR", "ENOSPC", "EROFS", "EMFILE", "ENFILE", "EBUSY",
+]);
+
+/**
+ * Nothing below a command action should ever surface a raw stack trace to an
+ * agent parsing stdout. Uncaught failures exit 70 with the same JSON envelope
+ * shape as every other error.
+ */
+function reportInternalError(err: unknown): void {
+  const message = err instanceof Error ? err.message : String(err);
+  if (err instanceof TelemetryReadError) {
+    // A log that exists but cannot be read is an I/O failure, not an empty log.
+    // Returning `[]` here would report a broken telemetry store as a healthy one.
+    finish(
+      {
+        success: false,
+        errorCode: ErrorCode.READ_FAILED,
+        path: err.file,
+        message,
+        recovery: "Check that the telemetry log is readable, or run `hashpilot telemetry clear`.",
+      },
+      ExitCode.IO,
+    );
+    return;
+  }
+  if (err instanceof PathDeniedError) {
+    finish({ success: false, errorCode: err.errorCode, path: err.path, message }, ExitCode.USAGE);
+    return;
+  }
+  // Commander's async actions reject outside the try/catch around `parse()`,
+  // so a plain missing file lands here. Those are ordinary I/O failures, not
+  // HashPilot bugs — reporting them as exit 70 tells an agent to file a bug
+  // report instead of fixing its path.
+  const syscall = (err as { code?: string } | undefined)?.code;
+  if (syscall !== undefined && IO_SYSCALL_CODES.has(syscall)) {
+    finish(
+      {
+        success: false,
+        errorCode: syscall === "ENOENT" ? ErrorCode.FILE_NOT_FOUND : ErrorCode.WRITE_FAILED,
+        message,
+        recovery: "Check that the path exists and is readable and writable.",
+      },
+      ExitCode.IO,
+    );
+    return;
+  }
+  finish(
+    {
+      success: false,
+      errorCode: "INTERNAL_ERROR",
+      message,
+      detail: err instanceof Error ? err.stack : undefined,
+      recovery: "This is a bug in HashPilot. Please report it with the command that triggered it.",
+    },
+    ExitCode.INTERNAL,
+  );
+}
+
+process.on("uncaughtException", reportInternalError);
+process.on("unhandledRejection", reportInternalError);
+
+/**
+ * Route Commander's own parse failures (unknown flag, missing required
+ * argument, bad choice) through the JSON usage envelope instead of letting a
+ * bare `error: unknown option '--x'` line escape to stderr. An agent that
+ * cannot parse the failure cannot self-correct from it (#57).
+ *
+ * `--help` and `--version` also arrive here as CommanderErrors; those already
+ * wrote their output to stdout and must exit with their own code.
+ */
+function applyExitOverride(cmd: Command): void {
+  cmd.exitOverride();
+  cmd.configureOutput({ writeErr: () => {} });
+  for (const sub of cmd.commands) applyExitOverride(sub as Command);
+}
+
+applyExitOverride(program);
+
+try {
+  program.parse();
+} catch (err) {
+  if (err instanceof CommanderError) {
+    if (err.code === "commander.helpDisplayed" || err.code === "commander.version" || err.code === "commander.help") {
+      process.exit(err.exitCode);
+    }
+    const attempted = process.argv[2];
+    if (attempted && program.commands.some((c) => (c as Command).name() === attempted)) {
+      setCommand(attempted);
+    }
+    usageError(err.message.replace(/^error: /, ""), {
+      recovery: `Run \`hashpilot ${attempted && !attempted.startsWith("-") ? attempted + " " : ""}--help\` for the accepted arguments.`,
+    });
+  } else {
+    reportInternalError(err);
+  }
+}