@bigknoxy/hashpilot 4.6.3

package/src/commands/ast.ts

@@ -0,0 +1,255 @@
+import type { Command } from "commander";
+import {
+  findSymbolsDetailed,
+  renameSymbol,
+  replaceBody,
+  addImport,
+  removeImport,
+  insertBeforeSymbol,
+  insertAfterSymbol,
+  detectLanguage,
+  recordEvent,
+  astCapabilities,
+  toPreview,
+  ErrorCode,
+  buildProvenanceFields,
+  safeWrite,
+  finish,
+} from "../core/index";
+import type { TelemetryEvent } from "../core/telemetry";
+import { withPreview, withProvenance } from "./shared";
+
+/** Register the `ast` command group. */
+export function register(program: Command): void {
+  const astCmd = program
+    .command("ast")
+    .description("Syntax-aware editing via tree-sitter");
+
+  astCmd
+    .command("capabilities")
+    .description("Show supported AST languages, operations, and limitations")
+    .action(() => {
+      finish(astCapabilities());
+    });
+
+  astCmd
+    .command("find-symbols")
+    .description("List symbols in a file")
+    .argument("<file>", "File path")
+    .action(async (file: string) => {
+      const content = await Bun.file(file).text();
+      // Report the truncation flag rather than an array that looks complete (#39).
+      const { symbols, truncated } = findSymbolsDetailed(content, file);
+      finish({ symbols, truncated });
+    });
+
+  function recordProvenanceEvent(opts: {
+    operation: string; route: TelemetryEvent["route"]; file: string; success: boolean; elapsed_ms: number;
+    source?: string; newSource?: string; errorCode?: ErrorCode; language?: string;
+    actor?: string; taskId?: string; reason?: string; filePath?: string;
+  }) {
+    const provFields = buildProvenanceFields({
+      actor: opts.actor, taskId: opts.taskId, reason: opts.reason,
+      source: opts.source, newSource: opts.newSource, filePath: opts.filePath,
+    });
+    recordEvent({
+      operation: opts.operation, route: opts.route, file: opts.file,
+      language: opts.language, success: opts.success, elapsed_ms: opts.elapsed_ms,
+      errorCode: opts.errorCode, ...provFields,
+    });
+  }
+
+  withProvenance(
+    withPreview(
+      astCmd
+        .command("rename-symbol")
+         .description(
+            "File-scoped, binding-aware rename of a symbol and its references. " +
+            "Refuses with AMBIGUOUS_SYMBOL when the name binds more than one symbol " +
+            "in the file (a shadowed local, a foreign import, or a duplicate declaration).",
+           )
+        .argument("<file>", "File path")
+        .argument("<old-name>", "Current symbol name")
+        .argument("<new-name>", "New symbol name"),
+      "Preview only",
+    )
+  )
+
+    .action(async (file: string, oldName: string, newName: string, opts) => {
+      const start = Date.now();
+      const content = await Bun.file(file).text();
+      const result = renameSymbol(content, file, oldName, newName);
+      if (result.success && result.newSource && !opts.dryRun) {
+        await safeWrite(file, result.newSource);
+      }
+      recordProvenanceEvent({
+        operation: "rename-symbol", route: "ast", file,
+        language: detectLanguage(file) || undefined,
+        success: result.success, elapsed_ms: Date.now() - start,
+        errorCode: result.success ? undefined : ErrorCode.PARSE_ERROR,
+        source: content, newSource: result.newSource, filePath: file,
+        actor: opts.actor, taskId: opts.taskId, reason: opts.reason,
+      });
+      // A dry run previews the change; it does not hand back the whole file (#98).
+      finish(opts.dryRun ? toPreview(result, content, file, opts.includeSource) : result);
+    });
+
+  withProvenance(
+    withPreview(
+      astCmd
+        .command("replace-body")
+        .description("Replace function/method body")
+        .argument("<file>", "File path")
+        .argument("<symbol>", "Symbol name")
+        .argument("<new-body>", "New body statements only — no braces, no indentation (or @file)"),
+      "Preview only",
+    )
+  )
+
+    .action(async (file: string, symbol: string, newBody: string, opts) => {
+      const start = Date.now();
+      let body = newBody;
+      if (newBody.startsWith("@")) body = await Bun.file(newBody.slice(1)).text();
+      const content = await Bun.file(file).text();
+      const result = replaceBody(content, file, symbol, body);
+      if (result.success && result.newSource && !opts.dryRun) {
+        await safeWrite(file, result.newSource);
+      }
+      recordProvenanceEvent({
+        operation: "replace-body", route: "ast", file,
+        language: detectLanguage(file) || undefined,
+        success: result.success, elapsed_ms: Date.now() - start,
+        errorCode: result.success ? undefined : ErrorCode.PARSE_ERROR,
+        source: content, newSource: result.newSource, filePath: file,
+        actor: opts.actor, taskId: opts.taskId, reason: opts.reason,
+      });
+      // A dry run previews the change; it does not hand back the whole file (#98).
+      finish(opts.dryRun ? toPreview(result, content, file, opts.includeSource) : result);
+    });
+
+  withProvenance(
+    withPreview(
+      astCmd
+        .command("add-import")
+        .description("Add an import statement")
+        .argument("<file>", "File path")
+        .argument("<import-spec>", 'Import spec, module path quoted: \'{ Foo } from "./bar"\''),
+      "Preview only",
+    )
+  )
+
+    .action(async (file: string, importSpec: string, opts) => {
+      const start = Date.now();
+      const content = await Bun.file(file).text();
+      const result = addImport(content, file, importSpec);
+      if (result.success && result.newSource && !opts.dryRun) {
+        await safeWrite(file, result.newSource);
+      }
+      recordProvenanceEvent({
+        operation: "add-import", route: "ast", file,
+        language: detectLanguage(file) || undefined,
+        success: result.success, elapsed_ms: Date.now() - start,
+        errorCode: result.success ? undefined : ErrorCode.PARSE_ERROR,
+        source: content, newSource: result.newSource, filePath: file,
+        actor: opts.actor, taskId: opts.taskId, reason: opts.reason,
+      });
+      // A dry run previews the change; it does not hand back the whole file (#98).
+      finish(opts.dryRun ? toPreview(result, content, file, opts.includeSource) : result);
+    });
+
+  withProvenance(
+    withPreview(
+      astCmd
+        .command("remove-import")
+        .description("Remove an import statement")
+        .argument("<file>", "File path")
+        .argument("<import-spec>", 'Import spec to remove, e.g. \'{ Foo } from "./bar"\' or a bare binding name'),
+      "Preview only",
+    )
+  )
+
+    .action(async (file: string, importSpec: string, opts) => {
+      const start = Date.now();
+      const content = await Bun.file(file).text();
+      const result = removeImport(content, file, importSpec);
+      if (result.success && result.newSource && !opts.dryRun) {
+        await safeWrite(file, result.newSource);
+      }
+      recordProvenanceEvent({
+        operation: "remove-import", route: "ast", file,
+        language: detectLanguage(file) || undefined,
+        success: result.success, elapsed_ms: Date.now() - start,
+        errorCode: result.success ? undefined : ErrorCode.PARSE_ERROR,
+        source: content, newSource: result.newSource, filePath: file,
+        actor: opts.actor, taskId: opts.taskId, reason: opts.reason,
+      });
+      // A dry run previews the change; it does not hand back the whole file (#98).
+      finish(opts.dryRun ? toPreview(result, content, file, opts.includeSource) : result);
+    });
+
+  withProvenance(
+    withPreview(
+      astCmd
+        .command("insert-before")
+        .description("Insert content before a symbol")
+        .argument("<file>", "File path")
+        .argument("<symbol>", "Symbol name")
+        .argument("<content>", "Content to insert (or @file)"),
+      "Preview only",
+    )
+  )
+
+    .action(async (file: string, symbol: string, content: string, opts) => {
+      const start = Date.now();
+      let c = content;
+      if (c.startsWith("@")) c = await Bun.file(c.slice(1)).text();
+      const src = await Bun.file(file).text();
+      const result = insertBeforeSymbol(src, file, symbol, c);
+      if (result.success && result.newSource && !opts.dryRun) {
+        await safeWrite(file, result.newSource);
+      }
+      recordProvenanceEvent({
+        operation: "insert-before", route: "ast", file,
+        language: detectLanguage(file) || undefined,
+        success: result.success, elapsed_ms: Date.now() - start,
+        errorCode: result.success ? undefined : ErrorCode.PARSE_ERROR,
+        source: src, newSource: result.newSource, filePath: file,
+        actor: opts.actor, taskId: opts.taskId, reason: opts.reason,
+      });
+      // A dry run previews the change; it does not hand back the whole file (#98).
+      finish(opts.dryRun ? toPreview(result, src, file, opts.includeSource) : result);
+    });
+
+  withProvenance(
+    withPreview(
+      astCmd
+        .command("insert-after")
+        .description("Insert content after a symbol")
+        .argument("<file>", "File path")
+        .argument("<symbol>", "Symbol name")
+        .argument("<content>", "Content to insert (or @file)"),
+      "Preview only",
+    )
+  )
+
+    .action(async (file: string, symbol: string, content: string, opts) => {
+      const start = Date.now();
+      let c = content;
+      if (c.startsWith("@")) c = await Bun.file(c.slice(1)).text();
+      const src = await Bun.file(file).text();
+      const result = insertAfterSymbol(src, file, symbol, c);
+      if (result.success && result.newSource && !opts.dryRun) {
+        await safeWrite(file, result.newSource);
+      }
+      recordProvenanceEvent({
+        operation: "insert-after", route: "ast", file,
+        language: detectLanguage(file) || undefined,
+        success: result.success, elapsed_ms: Date.now() - start,
+        errorCode: result.success ? undefined : ErrorCode.PARSE_ERROR,
+        source: src, newSource: result.newSource, filePath: file,
+        actor: opts.actor, taskId: opts.taskId, reason: opts.reason,
+      });
+      // A dry run previews the change; it does not hand back the whole file (#98).
+      finish(opts.dryRun ? toPreview(result, src, file, opts.includeSource) : result);
+    });
+}

package/src/commands/diff.ts

@@ -0,0 +1,98 @@
+import type { Command } from "commander";
+import {
+  detectLanguage,
+  recordEvent,
+  generateUnifiedDiff,
+  applyPatch,
+  buildProvenanceFields,
+  finish,
+  usageError,
+  ExitCode,
+} from "../core/index";
+import { join } from "path";
+import { parseIntFlag, withProvenance } from "./shared";
+
+/** Register the `diff` command group. */
+export function register(program: Command): void {
+  const diffCmd = program
+    .command("diff")
+    .description("Unified diff generation and patch application");
+
+  diffCmd
+    .command("generate")
+    .description("Generate a unified diff between old and new content")
+    .argument("<file>", "File path (for diff header)")
+    .argument("<old-content>", "Old content (or @file)")
+    .argument("<new-content>", "New content (or @file)")
+    .option("-c, --context <n>", "Context lines", "3")
+    .option("--raw", "Print the diff text alone, without the JSON envelope")
+    .action(async (file: string, oldContent: string, newContent: string, opts) => {
+      const start = Date.now();
+      let oldSrc = oldContent;
+      let newSrc = newContent;
+      if (oldContent.startsWith("@")) oldSrc = await Bun.file(oldContent.slice(1)).text();
+      if (newContent.startsWith("@")) newSrc = await Bun.file(newContent.slice(1)).text();
+      const diff = generateUnifiedDiff(oldSrc, newSrc, file, parseInt(opts.context));
+      recordEvent({
+        operation: "diff-generate",
+        route: "diff",
+        file,
+        success: true,
+        elapsed_ms: Date.now() - start,
+      });
+      // The diff itself is the payload; it rides the envelope like every other
+      // command so a consumer has one parse path (`--raw` prints it bare).
+      if (opts.raw) {
+        console.log(diff || "(no changes)");
+        return;
+      }
+      finish({ path: file, changed: diff.length > 0, diff }, ExitCode.OK);
+    });
+
+  withProvenance(
+    diffCmd
+      .command("apply")
+      .description("Apply a unified diff patch to a file")
+      .argument("<file>", "File to patch")
+      .option("--patch <file>", "Patch file to apply (or '-' for stdin)")
+      .option("--dry-run", "Preview without writing")
+      .option("-f, --fuzzy <n>", "Fuzzy match tolerance in lines; 0 = strict (exact offset and content, refuses otherwise)", "3")
+  )
+
+    .action(async (file: string, opts) => {
+      const start = Date.now();
+      let patchText: string;
+      if (opts.patch === "-") {
+        // Read from stdin
+        const chunks: string[] = [];
+        for await (const chunk of Bun.stdin.stream()) {
+          chunks.push(Buffer.from(chunk).toString());
+        }
+        patchText = chunks.join("");
+      } else if (opts.patch) {
+        patchText = await Bun.file(opts.patch).text();
+      } else {
+        // Must return: without it, patchText is unassigned and applyPatch throws.
+        return usageError("--patch is required", { path: file });
+      }
+      const fuzzy = parseIntFlag(opts.fuzzy, "--fuzzy", 3);
+      if (typeof fuzzy === "object") return usageError(fuzzy.error, { path: file });
+      const result = await applyPatch(file, patchText, {
+        dryRun: opts.dryRun,
+        fuzzyMatch: fuzzy,
+      });
+      const provFields = buildProvenanceFields({
+        actor: opts.actor, taskId: opts.taskId, reason: opts.reason, filePath: file,
+      });
+      recordEvent({
+        operation: "diff-apply",
+        route: "diff",
+        file,
+        language: detectLanguage(file) || undefined,
+        success: result.success,
+        elapsed_ms: Date.now() - start,
+        ...provFields,
+      });
+      finish(result);
+    });
+}

package/src/commands/edit.ts

@@ -0,0 +1,93 @@
+import type { Command } from "commander";
+import {
+  routeEdit,
+  editMany,
+  editManySerial,
+  resolveContent,
+  finish,
+} from "../core/index";
+import { withEditFlags, withProvenance } from "./shared";
+
+/** Register the `edit` command group. */
+export function register(program: Command): void {
+  withProvenance(
+    withEditFlags(
+      program
+        .command("route-edit")
+        .description("Auto-routed structured edit through AST → Hash → Diff pipeline")
+        .argument("<file>", "File path")
+        .argument("<operation>", "Operation (rename-symbol, replace-body, add-import, remove-import, insert-before, insert-after, replace-hash, replace-content)")
+    )
+      .option("--dry-run", "Preview without writing")
+      .option("--include-source", "On a dry run, return the whole post-edit file instead of a diff")
+  )
+
+    .action(async (file: string, operation: string, opts) => {
+      const result = await routeEdit({
+        filePath: file,
+        operation,
+        method: opts.method,
+        oldHash: opts.oldHash,
+        newContent: await resolveContent(opts.newContent),
+        oldContent: opts.oldContent,
+        range: opts.range ? (([s, e]: number[]) => ({ start: s, end: e }))(opts.range.split(":").map(Number)) : undefined,
+        oldName: opts.oldName,
+        newName: opts.newName,
+        symbolName: opts.symbol,
+        newBody: await resolveContent(opts.newBody),
+        importSpec: opts.importSpec,
+        content: await resolveContent(opts.content),
+        policy: opts.policy ? JSON.parse(opts.policy) : undefined,
+        dryRun: opts.dryRun,
+        includeSource: opts.includeSource,
+        actor: opts.actor,
+        taskId: opts.taskId,
+        reason: opts.reason,
+      });
+
+      finish(result);
+    });
+
+  withProvenance(
+    withEditFlags(
+      program
+        .command("batch")
+        .description("Apply the same edit to multiple files in parallel")
+        .argument("<operation>", "Operation (rename-symbol, replace-body, add-import, remove-import, insert-before, insert-after, replace-hash, replace-content)")
+        .argument("<files...>", "Files to edit")
+    )
+      .option("--serial", "Execute sequentially instead of parallel")
+      .option("--dry-run", "Preview without writing")
+      .option("--include-source", "On a dry run, return the whole post-edit file instead of a diff")
+  )
+
+    .action(async (operation: string, files: string[], opts) => {
+      const batchParams = {
+        files,
+        operation,
+        method: opts.method,
+        oldHash: opts.oldHash,
+        newContent: await resolveContent(opts.newContent),
+        oldContent: opts.oldContent,
+        range: opts.range ? (([s, e]: number[]) => ({ start: s, end: e }))(opts.range.split(":").map(Number)) : undefined,
+        oldName: opts.oldName,
+        newName: opts.newName,
+        symbolName: opts.symbol,
+        newBody: await resolveContent(opts.newBody),
+        importSpec: opts.importSpec,
+        content: await resolveContent(opts.content),
+        policy: opts.policy ? JSON.parse(opts.policy) : undefined,
+        dryRun: opts.dryRun,
+        includeSource: opts.includeSource,
+        actor: opts.actor,
+        taskId: opts.taskId,
+        reason: opts.reason,
+      };
+
+      const result = opts.serial
+        ? await editManySerial(batchParams)
+        : await editMany(batchParams);
+
+      finish(result);
+    });
+}

package/src/commands/hash.ts

@@ -0,0 +1,64 @@
+import type { Command } from "commander";
+import {
+  replaceHash,
+  detectLanguage,
+  recordEvent,
+  buildProvenanceFields,
+  finish,
+  usageError,
+} from "../core/index";
+import { parseRange, withProvenance } from "./shared";
+
+/** Register the `hash` command group. */
+export function register(program: Command): void {
+  withProvenance(
+    program
+      .command("replace-hash")
+      .description("Replace content identified by hash anchor")
+      .argument("<file>", "File path")
+      .argument("<old-hash>", "Hash of content to replace")
+      .argument("<new-content>", "New content (or @file to read from file)")
+      .option("--range <start:end>", "Line range (1-indexed). N or N:M")
+      .option("--no-recover", "Fail immediately on a stale anchor instead of attempting relocation")
+      .option("--dry-run", "Preview without writing")
+  )
+
+    .action(async (file: string, oldHash: string, newContent: string, opts) => {
+      const start = Date.now();
+      let content = newContent;
+      if (newContent.startsWith("@")) {
+        content = await Bun.file(newContent.slice(1)).text();
+      }
+      let range: { start: number; end: number } | undefined;
+      if (opts.range) {
+        const parsed = parseRange(opts.range);
+        if ("error" in parsed) return usageError(parsed.error, { path: file });
+        range = parsed.range;
+      }
+      const result = await replaceHash(file, oldHash, content, {
+        range,
+        dryRun: opts.dryRun,
+        // Commander maps --no-recover to opts.recover === false.
+        recovery: opts.recover === false ? "off" : "relocate",
+        skipParseCheck: Boolean(program.opts().allowParseErrors),
+      });
+      const provFields = buildProvenanceFields({
+        actor: opts.actor,
+        taskId: opts.taskId,
+        reason: opts.reason,
+        filePath: file,
+      });
+      recordEvent({
+        operation: "replace-hash",
+        route: "hash",
+        file,
+        language: detectLanguage(file) || undefined,
+        success: result.success,
+        fallback_reason: result.stale ? "stale-anchor" : undefined,
+        retries: result.retries ?? 0,
+        elapsed_ms: Date.now() - start,
+        ...provFields,
+      });
+      finish(result);
+    });
+}

package/src/commands/intent.ts

@@ -0,0 +1,68 @@
+import type { Command } from "commander";
+import {
+  executeIntent,
+  finish,
+  exitCodeFor,
+  getOutputFormat,
+} from "../core/index";
+import { withProvenance } from "./shared";
+
+/** Register the `intent` command group. */
+export function register(program: Command): void {
+  withProvenance(
+    program
+      .command("intent")
+      .description("Execute an editing intent — one command, full blast radius")
+      .argument("<intent>", "Intent as JSON: {\"operation\":\"add-parameter\",\"symbol\":\"fn\",\"param\":{\"name\":\"x\"}}")
+      .option("--project-root <dir>", "Project root directory")
+      .option("--dry-run", "Preview plan without modifying files")
+      .option("--yes", "Apply the plan even though part of the intent could not be resolved")
+      .option("--no-verify", "Skip verification after execution")
+      .option("--no-revert", "Don't roll back on failure")
+      .option("--timeout <ms>", "Timeout per operation in ms", "30000")
+  )
+    .option("--context <text>", "Agent prompt/context (or @file)")
+
+    .action(async (intent: string, opts) => {
+      try {
+        let context = opts.context;
+        if (context && context.startsWith("@")) {
+          context = await Bun.file(context.slice(1)).text();
+        }
+
+        const result = await executeIntent(intent, {
+          projectRoot: opts.projectRoot || process.cwd(),
+          dryRun: opts.dryRun,
+          yes: Boolean(opts.yes),
+          verify: opts.verify,
+          revertOnFailure: opts.revert,
+          timeout: parseInt(opts.timeout),
+          actor: opts.actor,
+          taskId: opts.taskId,
+          reason: opts.reason,
+          context,
+        });
+
+        if (getOutputFormat() === "json") {
+          finish(result);
+        } else {
+          console.log(`Intent: ${result.plan.intent.operation} on '${result.plan.definition.name}'`);
+          console.log(`Impact: ${result.plan.impactSummary}`);
+          for (const u of result.plan.unresolved) {
+            console.log(`Unresolved (${u.file}): ${u.reason}`);
+            console.log(`  → ${u.resolution}`);
+          }
+          console.log(`Success: ${result.success}`);
+          if (result.execution.verification) {
+            console.log(`Verification: ${result.execution.verification.overall}`);
+          }
+          // Human output still has to carry the exit contract — an agent may run
+          // without --json and branch on the code.
+          process.exitCode = exitCodeFor(result);
+        }
+      } catch (err: any) {
+        console.error(`Intent failed: ${err.message}`);
+        process.exitCode = 1;
+      }
+    });
+}