@bigknoxy/hashpilot 4.6.3

package/scripts/doctor.sh

@@ -0,0 +1,218 @@
+#!/bin/bash
+# HashPilot Doctor — Standalone installation health check
+# Can run even when CLI is not on PATH.
+
+# Derive the version from package.json rather than hardcoding a stale literal
+# here (#156). This script is standalone (runs before the CLI is installed),
+# so it reads package.json directly instead of importing any TS module.
+# Resolve the script's real directory (not just dirname "$0") so this still
+# works if invoked via a relative path from another cwd or through a symlink —
+# the same lesson #157/#158 learned the hard way for install.sh. This script
+# is documented to run from a local checkout (`bash scripts/doctor.sh`), not
+# curl-piped, so $0 is always a real path here and this resolution is safe.
+HASHPILOT_SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd 2>/dev/null)"
+HASHPILOT_VERSION="$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "${HASHPILOT_SCRIPT_DIR:-.}/../package.json" 2>/dev/null | head -1)"
+HASHPILOT_VERSION="${HASHPILOT_VERSION:-unknown}"
+# shellcheck disable=SC2034
+BOLD='\033[1m'
+DIM='\033[2m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+PASS=0
+FAIL=0
+WARN=0
+SKIP=0
+RESULTS=()
+
+pass() { PASS=$((PASS+1)); RESULTS+=("{\"name\":\"$1\",\"status\":\"pass\",\"message\":\"$2\"}"); }
+fail() { FAIL=$((FAIL+1)); RESULTS+=("{\"name\":\"$1\",\"status\":\"fail\",\"message\":\"$2\"}"); }
+warn() { WARN=$((WARN+1)); RESULTS+=("{\"name\":\"$1\",\"status\":\"warn\",\"message\":\"$2\"}"); }
+skip() { SKIP=$((SKIP+1)); RESULTS+=("{\"name\":\"$1\",\"status\":\"skip\",\"message\":\"$2\"}"); }
+
+TARGET_DIR="${HASHPILOT_DIR:-${HOME}/.agentic-tools}"
+MANIFEST="$TARGET_DIR/manifest.json"
+
+echo "${BOLD}HashPilot Doctor v${HASHPILOT_VERSION}${NC}"
+echo ""
+
+# 1. Core directory
+if [[ -d "$TARGET_DIR/structured-editing" ]]; then
+  pass "core-directory" "Found: $TARGET_DIR/structured-editing"
+else
+  fail "core-directory" "Missing: $TARGET_DIR/structured-editing"
+fi
+
+# 2. Core source files
+if [[ -f "$TARGET_DIR/structured-editing/src/cli.ts" ]]; then
+  pass "core-cli.ts" "Found: $TARGET_DIR/structured-editing/src/cli.ts"
+else
+  fail "core-cli.ts" "Missing: $TARGET_DIR/structured-editing/src/cli.ts"
+fi
+
+if [[ -f "$TARGET_DIR/structured-editing/package.json" ]]; then
+  pass "core-package.json" "Found: $TARGET_DIR/structured-editing/package.json"
+else
+  fail "core-package.json" "Missing: $TARGET_DIR/structured-editing/package.json"
+fi
+
+# 3. Dependencies
+if [[ -d "$TARGET_DIR/structured-editing/node_modules" ]]; then
+  pass "core-dependencies" "node_modules present"
+else
+  fail "core-dependencies" "node_modules missing — run 'bun install' in $TARGET_DIR/structured-editing"
+fi
+
+# 4. CLI launcher
+if [[ -x "$TARGET_DIR/bin/hashpilot" ]]; then
+  pass "cli-launcher" "Found: $TARGET_DIR/bin/hashpilot"
+else
+  fail "cli-launcher" "Missing: $TARGET_DIR/bin/hashpilot"
+fi
+
+# 5. CLI on PATH
+if command -v hashpilot &>/dev/null; then
+  CLI_PATH=$(command -v hashpilot)
+  pass "cli-on-path" "Found at: $CLI_PATH"
+else
+  warn "cli-on-path" "hashpilot not on PATH — add $TARGET_DIR/bin to PATH"
+fi
+
+# 6. CLI executable
+if command -v hashpilot &>/dev/null; then
+  VER=$(hashpilot --version 2>/dev/null || echo "error")
+  if [[ "$VER" != "error" ]]; then
+    pass "cli-executable" "CLI works: $VER"
+  else
+    fail "cli-executable" "CLI failed to run"
+  fi
+elif [[ -x "$TARGET_DIR/bin/hashpilot" ]]; then
+  VER=$("$TARGET_DIR/bin/hashpilot" --version 2>/dev/null || echo "error")
+  if [[ "$VER" != "error" ]]; then
+    pass "cli-executable" "CLI works: $VER"
+  else
+    fail "cli-executable" "CLI failed to run (try: bun install in $TARGET_DIR/structured-editing)"
+  fi
+fi
+
+# 7. Config file
+if [[ -f "${HOME}/.config/hashpilot/config.json" ]]; then
+    if jq -e . "${HOME}/.config/hashpilot/config.json" >/dev/null 2>&1; then
+    pass "config-file" "Found valid config at ${HOME}/.config/hashpilot/config.json"
+  else
+    fail "config-file" "Config exists but is not valid JSON: ${HOME}/.config/hashpilot/config.json"
+  fi
+else
+  skip "config-file" "No config file — using defaults"
+fi
+
+# 8. Claude integration
+CLAUDE_FILE="${HOME}/.claude/CLAUDE.md"
+CLAUDE_MARKER="HashPilot Claude"
+if [[ -f "$CLAUDE_FILE" ]]; then
+  if grep -q "$CLAUDE_MARKER" "$CLAUDE_FILE" 2>/dev/null; then
+    pass "claude-integration" "HashPilot section found in $CLAUDE_FILE"
+  else
+    warn "claude-integration" "CLAUDE.md exists but HashPilot section missing"
+  fi
+else
+  skip "claude-integration" "Claude CLAUDE.md not found"
+fi
+
+# 9. OpenCode integration
+if [[ -f "${HOME}/.config/opencode/skills/hashpilot/SKILL.md" ]]; then
+  pass "opencode-skill" "Found OpenCode skill"
+else
+  fail "opencode-skill" "Missing: ~/.config/opencode/skills/hashpilot/SKILL.md"
+fi
+
+if [[ -f "${HOME}/.config/opencode/agent/hashpilot.md" ]]; then
+  pass "opencode-agent" "Found OpenCode agent"
+else
+  fail "opencode-agent" "Missing: ~/.config/opencode/agent/hashpilot.md"
+fi
+
+# 10. Pi integration
+if [[ -f "${HOME}/.pi/agent/extensions/hashpilot.ts" ]]; then
+  pass "pi-extension" "Found Pi extension"
+else
+  fail "pi-extension" "Missing: ~/.pi/agent/extensions/hashpilot.ts"
+fi
+
+if [[ -f "${HOME}/.pi/agent/skills/hashpilot/SKILL.md" ]]; then
+  pass "pi-skill" "Found Pi skill"
+else
+  fail "pi-skill" "Missing: ~/.pi/agent/skills/hashpilot/SKILL.md"
+fi
+
+# 11. Telemetry writable
+if mkdir -p "$TARGET_DIR/logs" 2>/dev/null; then
+  TESTFILE="$TARGET_DIR/logs/.doctor-write-test-$$"
+  if echo "ok" > "$TESTFILE" 2>/dev/null; then
+    rm -f "$TESTFILE"
+    pass "telemetry-writable" "Log dir is writable: $TARGET_DIR/logs"
+  else
+    fail "telemetry-writable" "Log dir not writable: $TARGET_DIR/logs"
+  fi
+else
+  fail "telemetry-writable" "Cannot create log dir: $TARGET_DIR/logs"
+fi
+
+# 12. Manifest
+if [[ -f "$MANIFEST" ]]; then
+  pass "manifest" "Found: $MANIFEST"
+else
+  fail "manifest" "Missing: $MANIFEST (rerun install.sh)"
+fi
+
+# 13. PATH entry in shell rc
+RC_CHECKED=false
+for rc in "${HOME}/.bashrc" "${HOME}/.zshrc" "${HOME}/.bash_profile" "${HOME}/.profile"; do
+  if [[ -f "$rc" ]] && grep -q "hashpilot path" "$rc" 2>/dev/null; then
+    pass "path-entry" "PATH entry found in $rc"
+    RC_CHECKED=true
+    break
+  fi
+done
+if [[ "$RC_CHECKED" != "true" ]]; then
+  warn "path-entry" "No hashpilot PATH entry found in shell rc files"
+fi
+
+# ── Summary ───────────────────────────────────────────────────────────────
+OVERALL_HEALTHY=true
+if [[ "$FAIL" -gt 0 ]]; then
+  OVERALL_HEALTHY=false
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+if [[ "$OVERALL_HEALTHY" == "true" ]]; then
+  echo " ${GREEN}HashPilot is HEALTHY${NC}"
+else
+  echo " ${RED}HashPilot has ISSUES${NC}"
+fi
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+printf "  ${GREEN}✓${NC} Pass: %d   ${RED}✗${NC} Fail: %d   ${YELLOW}!${NC} Warn: %d   ${DIM}·${NC} Skip: %d\n" "$PASS" "$FAIL" "$WARN" "$SKIP"
+echo ""
+
+# Machine-readable JSON summary on stderr (capture with 2>/dev/null to suppress)
+JSON_RESULT=$(cat <<EOF
+{
+  "version": "${HASHPILOT_VERSION}",
+  "healthy": ${OVERALL_HEALTHY},
+  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "summary": { "pass": ${PASS}, "fail": ${FAIL}, "warn": ${WARN}, "skip": ${SKIP} },
+  "checks": [
+$(IFS=,; echo "${RESULTS[*]}")
+  ]
+}
+EOF
+)
+echo "$JSON_RESULT" >&2
+
+if [[ "$OVERALL_HEALTHY" != "true" ]]; then
+  exit 1
+fi
+exit 0

package/scripts/gen-cli-quickref.ts

@@ -0,0 +1,232 @@
+#!/usr/bin/env bun
+/**
+ * Generates the command table in docs/CLI-QUICKREF.md by walking the CLI's own
+ * `--help` output. Reading the real help (rather than importing the Commander
+ * program) means the reference can never describe a command shape the shipped
+ * binary does not actually accept — src/cli.ts calls `program.parse()` at module
+ * load, so it cannot be imported without executing it.
+ *
+ *   bun run scripts/gen-cli-quickref.ts           # rewrite the generated block
+ *   bun run scripts/gen-cli-quickref.ts --check   # exit 1 if the file is stale
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+export const BEGIN_MARKER = "<!-- BEGIN GENERATED: command reference -->";
+export const END_MARKER = "<!-- END GENERATED: command reference -->";
+
+const ROOT = join(import.meta.dir, "..");
+const DOC_PATH = join(ROOT, "docs", "CLI-QUICKREF.md");
+const CLI = join(ROOT, "src", "cli.ts");
+
+export interface CommandDoc {
+  /** Full subcommand path, e.g. `["ast", "rename-symbol"]`. */
+  path: string[];
+  description: string;
+  usage: string;
+  args: Array<{ name: string; description: string }>;
+  options: Array<{ flags: string; description: string }>;
+  /** Present only on group commands like `ast` or `telemetry`. */
+  children: string[];
+}
+
+function help(path: string[]): string {
+  const label = path.join(" ") || "(root)";
+  const res = spawnSync("bun", ["run", CLI, ...path, "--help"], {
+    encoding: "utf8",
+    cwd: ROOT,
+    env: { ...process.env, HASHPILOT_TELEMETRY: "0" },
+    timeout: 30_000,
+    maxBuffer: 8 * 1024 * 1024,
+  });
+  // Anything short of a clean exit means the captured stdout may be a partial
+  // help page, and a partial page generates plausible-looking but wrong docs
+  // that still satisfy `--check`. Refuse rather than publish it.
+  if (res.error) throw new Error(`help failed for '${label}': ${res.error.message}`);
+  if (res.signal) throw new Error(`help for '${label}' was killed by ${res.signal}`);
+  if (res.status !== 0) {
+    throw new Error(`help for '${label}' exited ${res.status}: ${res.stderr?.trim()}`);
+  }
+  if (!res.stdout.includes("Usage:")) {
+    throw new Error(`help for '${label}' produced no Usage: line (truncated output?)`);
+  }
+  return res.stdout;
+}
+
+/** Splits `--help` output into its `Usage:` line and named sections. */
+function sections(text: string): { usage: string; sections: Map<string, string[]> } {
+  const lines = text.split("\n");
+  let usage = "";
+  const out = new Map<string, string[]>();
+  let current: string | null = null;
+  for (const line of lines) {
+    if (line.startsWith("Usage:")) {
+      usage = line.slice("Usage:".length).trim();
+      current = null;
+      continue;
+    }
+    const header = /^([A-Z][A-Za-z ]*):\s*$/.exec(line);
+    if (header) {
+      current = header[1]!;
+      out.set(current, []);
+      continue;
+    }
+    if (current && line.trim()) out.get(current)!.push(line);
+  }
+  return { usage, sections: out };
+}
+
+/**
+ * Splits an entry line into its term and description. Commander pads the two
+ * columns apart with at least two spaces, and a description may wrap onto
+ * continuation lines that carry no term at all.
+ */
+function entries(lines: string[]): Array<{ term: string; description: string }> {
+  const out: Array<{ term: string; description: string }> = [];
+  for (const raw of lines) {
+    const line = raw.trimEnd();
+    const indent = line.length - line.trimStart().length;
+    const body = line.trim();
+    if (!body) continue;
+    // A continuation line is indented past the term column and has no gap.
+    const split = /^(\S.*?)\s{2,}(.*)$/.exec(body);
+    if (!split) {
+      if (out.length && indent > 4) out[out.length - 1]!.description += ` ${body}`;
+      else out.push({ term: body, description: "" });
+      continue;
+    }
+    out.push({ term: split[1]!, description: split[2]!.trim() });
+  }
+  return out;
+}
+
+/** Recursively walks every subcommand reachable from `path`. */
+export function walk(path: string[] = []): CommandDoc[] {
+  const parsed = sections(help(path));
+  const cmdEntries = entries(parsed.sections.get("Commands") ?? []);
+  const children = cmdEntries
+    .map((e) => e.term.split(/\s+/)[0]!)
+    .filter((name) => name !== "help");
+
+  const doc: CommandDoc = {
+    path,
+    description: "",
+    usage: parsed.usage,
+    args: entries(parsed.sections.get("Arguments") ?? []).map((e) => ({
+      name: e.term,
+      description: e.description,
+    })),
+    options: entries(parsed.sections.get("Options") ?? [])
+      .map((e) => ({ flags: e.term, description: e.description }))
+      .filter((o) => !/^-h, --help/.test(o.flags)),
+    children,
+  };
+
+  // The root document carries the global flags (`--allowed-root`,
+  // `--allow-outside-root`, `--no-telemetry`, `--version`), so it is kept, not
+  // dropped — those are exactly the flags an agent must not have to guess at.
+  const results: CommandDoc[] = [doc];
+  // The root's own description lives above `Usage:`; subcommand descriptions
+  // come from the parent's Commands table, so backfill them during recursion.
+  for (const child of children) {
+    const sub = walk([...path, child]);
+    const own = sub.find((s) => s.path.join(" ") === [...path, child].join(" "));
+    if (own) {
+      own.description =
+        cmdEntries.find((e) => e.term.split(/\s+/)[0] === child)?.description ?? "";
+    }
+    results.push(...sub);
+  }
+  return results;
+}
+
+function cell(text: string): string {
+  return text.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+
+export function render(docs: CommandDoc[]): string {
+  const root = docs.find((d) => d.path.length === 0);
+  const leaves = docs.filter((d) => d.path.length > 0 && d.children.length === 0);
+  const groups = docs.filter((d) => d.path.length > 0 && d.children.length > 0);
+
+  const out: string[] = [];
+  out.push(`_${leaves.length} commands, generated from \`--help\`. Do not edit by hand — run \`bun run gen:cli-quickref\`._`);
+  out.push("");
+  if (root) {
+    out.push("### Global options");
+    out.push("");
+    out.push("Accepted before the subcommand, e.g. `hashpilot --allowed-root /srv/app read-many f.ts`.");
+    out.push("");
+    out.push("```");
+    out.push(root.usage);
+    out.push("```");
+    out.push("");
+    out.push("| Flag | Meaning |");
+    out.push("|------|---------|");
+    for (const o of root.options) out.push(`| \`${cell(o.flags)}\` | ${cell(o.description)} |`);
+    out.push("");
+  }
+  out.push("### Command groups");
+  out.push("");
+  out.push("| Group | Subcommands |");
+  out.push("|-------|-------------|");
+  for (const g of groups) {
+    out.push(`| \`${g.path.join(" ")}\` | ${g.children.map((c) => `\`${c}\``).join(", ")} |`);
+  }
+  out.push("");
+  out.push("### Commands");
+  out.push("");
+
+  for (const d of leaves) {
+    out.push(`#### \`${d.path.join(" ")}\``);
+    out.push("");
+    if (d.description) out.push(d.description);
+    out.push("");
+    out.push("```");
+    out.push(d.usage);
+    out.push("```");
+    out.push("");
+    if (d.args.length) {
+      out.push("| Positional | Meaning |");
+      out.push("|------------|---------|");
+      for (const a of d.args) out.push(`| \`${cell(a.name)}\` | ${cell(a.description)} |`);
+      out.push("");
+    }
+    if (d.options.length) {
+      out.push("| Flag | Meaning |");
+      out.push("|------|---------|");
+      for (const o of d.options) out.push(`| \`${cell(o.flags)}\` | ${cell(o.description)} |`);
+      out.push("");
+    }
+  }
+  return out.join("\n").trimEnd();
+}
+
+/** Replaces the generated block in `doc`, leaving hand-written prose intact. */
+export function spliceGenerated(doc: string, generated: string): string {
+  const begin = doc.indexOf(BEGIN_MARKER);
+  const end = doc.indexOf(END_MARKER);
+  if (begin === -1 || end === -1 || end < begin) {
+    throw new Error(`docs/CLI-QUICKREF.md is missing the generated-block markers`);
+  }
+  return (
+    doc.slice(0, begin + BEGIN_MARKER.length) + "\n\n" + generated + "\n\n" + doc.slice(end)
+  );
+}
+
+if (import.meta.main) {
+  const check = process.argv.includes("--check");
+  const current = readFileSync(DOC_PATH, "utf8");
+  const next = spliceGenerated(current, render(walk()));
+  if (current === next) {
+    console.log("✓ docs/CLI-QUICKREF.md is up to date");
+    process.exit(0);
+  }
+  if (check) {
+    console.error("✗ docs/CLI-QUICKREF.md is stale. Run: bun run gen:cli-quickref");
+    process.exit(1);
+  }
+  writeFileSync(DOC_PATH, next);
+  console.log("✓ regenerated docs/CLI-QUICKREF.md");
+}

package/scripts/install-cli.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Dev install: symlink the CLI launcher into ~/.agentic-tools/bin and make sure
+# that directory is actually on PATH.
+#
+# The symlink alone is not an install. Before this script, `bun run install-cli`
+# created the link and stopped, so `hashpilot` was not a runnable command in a
+# fresh shell and `doctor` reported a broken installation. PATH wiring lives in
+# scripts/install.sh for the full install; this is the same block, so the two
+# paths converge on one marker and `scripts/uninstall.sh` removes either.
+set -euo pipefail
+
+BIN_DIR="${HOME}/.agentic-tools/bin"
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+LAUNCHER="${REPO_ROOT}/src/cli-node.cjs"
+
+mkdir -p "$BIN_DIR"
+ln -sf "$LAUNCHER" "$BIN_DIR/hashpilot"
+echo "Linked $BIN_DIR/hashpilot -> $LAUNCHER"
+
+# Stale symlink from the pre-3.1 binary name; leaving it makes `doctor` and the
+# manifest disagree about what is installed.
+if [ -L "$BIN_DIR/structured-edit" ]; then
+  rm -f "$BIN_DIR/structured-edit"
+  echo "Removed stale symlink: $BIN_DIR/structured-edit"
+fi
+
+detect_rc() {
+  if [ -n "${HASHPILOT_SHELL_RC:-}" ]; then echo "$HASHPILOT_SHELL_RC"; return; fi
+  case "${SHELL:-}" in
+    */zsh) echo "${HOME}/.zshrc"; return ;;
+    */bash) [ -f "${HOME}/.bashrc" ] && { echo "${HOME}/.bashrc"; return; } ;;
+  esac
+  for f in "${HOME}/.bashrc" "${HOME}/.zshrc" "${HOME}/.bash_profile" "${HOME}/.profile"; do
+    if [ -f "$f" ]; then echo "$f"; return; fi
+  done
+  echo "${HOME}/.bashrc"
+}
+
+RC_FILE=$(detect_rc)
+PATH_MARKER_START="# >>> hashpilot path >>>"
+PATH_MARKER_END="# <<< hashpilot path <<<"
+PATH_LINE="export PATH=\"\$HOME/.agentic-tools/bin:\$PATH\""
+
+if grep -q "$PATH_MARKER_START" "$RC_FILE" 2>/dev/null; then
+  echo "PATH entry already present in $RC_FILE"
+else
+  {
+    echo ""
+    echo "$PATH_MARKER_START"
+    echo "$PATH_LINE"
+    echo "$PATH_MARKER_END"
+  } >> "$RC_FILE"
+  echo "Added PATH entry to $RC_FILE"
+fi
+
+case ":${PATH}:" in
+  *":${BIN_DIR}:"*) echo "hashpilot is on PATH in this shell." ;;
+  *) echo "Run this to use hashpilot in the current shell:"
+     echo "  export PATH=\"\$HOME/.agentic-tools/bin:\$PATH\"" ;;
+esac