@bigknoxy/hashpilot 4.6.3

package/src/core/provenance.ts

@@ -0,0 +1,214 @@
+import { exportEvents, type TelemetryEvent } from "./telemetry";
+import { computeHash } from "./read";
+import { generateUnifiedDiff } from "./diff-engine";
+import { loadConfig, type HashPilotConfig } from "./config";
+import { isSensitiveFile, redactSecrets } from "./redact";
+
+// ── Types ──────────────────────────────────────────────────────────────
+
+export interface ProvenanceInput {
+  actor?: string;
+  taskId?: string;
+  changeSetId?: string;
+  reason?: string;
+  source?: string;
+  newSource?: string;
+  stepIndex?: number;
+  stepTotal?: number;
+  context?: string;
+  filePath?: string;
+}
+
+export interface ProvenanceEntry {
+  timestamp: string;
+  sessionId: string;
+  actor: string;
+  taskId?: string;
+  changeSetId?: string;
+  reason: string;
+  operation: string;
+  route: string;
+  success: boolean;
+  beforeHash?: string;
+  afterHash?: string;
+  diff?: string;
+  stepIndex?: number;
+  stepTotal?: number;
+  context?: string;
+  verification?: "pass" | "fail" | "skip";
+}
+
+export interface ChangeSetResult {
+  changeSetId: string;
+  taskId?: string;
+  actor: string;
+  reason: string;
+  editCount: number;
+  entries: ProvenanceEntry[];
+  timeRange: { first: string; last: string };
+}
+
+// ── Config cache ───────────────────────────────────────────────────────
+
+let _cachedConfig: HashPilotConfig | null = null;
+
+function getConfig(): HashPilotConfig {
+  if (!_cachedConfig) _cachedConfig = loadConfig();
+  return _cachedConfig;
+}
+
+/**
+ * Drop the cached config so the next call re-reads it. Pass an override to pin
+ * a config instead of loading from disk (tests use this to exercise opt-in
+ * behavior like `provenance.captureDiffs` without touching the user's files).
+ */
+export function clearConfigCache(override?: HashPilotConfig): void {
+  _cachedConfig = override ?? null;
+}
+
+// ── Factory ────────────────────────────────────────────────────────────
+
+export function createChangeSet(): string {
+  return crypto.randomUUID();
+}
+
+// ── Field builder ──────────────────────────────────────────────────────
+
+function truncate(val: string, maxLen: number): string {
+  return val.length > maxLen ? val.slice(0, maxLen) : val;
+}
+
+export function buildProvenanceFields(input: ProvenanceInput): Partial<TelemetryEvent> {
+  const fields: Partial<TelemetryEvent> = {};
+  const config = getConfig();
+
+  const actor = input.actor ?? config.provenance?.defaultActor;
+  if (actor !== undefined)            fields.actor = truncate(actor, 80);
+  if (input.taskId !== undefined)     fields.taskId = truncate(input.taskId, 80);
+  if (input.changeSetId !== undefined) fields.changeSetId = input.changeSetId;
+  if (input.reason !== undefined)     fields.reason = truncate(input.reason, 200);
+  if (input.stepIndex !== undefined)  fields.stepIndex = input.stepIndex;
+  if (input.stepTotal !== undefined)  fields.stepTotal = input.stepTotal;
+
+  if (input.source !== undefined) {
+    fields.beforeHash = computeHash(input.source);
+  }
+
+  if (input.source !== undefined && input.newSource !== undefined) {
+    fields.afterHash = computeHash(input.newSource);
+    // Diff capture is opt-in and never applies to files that are secret by
+    // definition. Hashes still record *that* the file changed.
+    const captureDiffs = config.provenance?.captureDiffs === true;
+    const sensitive = input.filePath !== undefined && isSensitiveFile(input.filePath);
+    if (captureDiffs && !sensitive && input.source !== input.newSource) {
+      fields.diff = redactSecrets(generateUnifiedDiff(
+        input.source, input.newSource,
+        input.filePath ? input.filePath.replace(/^\//, "") : "unknown", 3
+      ));
+    }
+  }
+
+  if (input.context !== undefined) {
+    const maxLen = config.provenance?.maxContextLength ?? 500;
+    fields.context = input.context.length > maxLen
+      ? input.context.slice(0, maxLen) + "..."
+      : input.context;
+  }
+
+  return fields;
+}
+
+// ── Query functions ────────────────────────────────────────────────────
+
+function diffCoversLine(diff: string, targetLine: number): boolean {
+  const hunkRe = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/gm;
+  let match: RegExpExecArray | null;
+  while ((match = hunkRe.exec(diff)) !== null) {
+    const newStart = parseInt(match[3], 10);
+    const newCount = match[4] ? parseInt(match[4], 10) : 1;
+    if (targetLine >= newStart && targetLine < newStart + newCount) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function toProvenanceEntry(e: TelemetryEvent): ProvenanceEntry {
+  return {
+    timestamp: e.timestamp,
+    sessionId: e.sessionId,
+    actor: e.actor ?? "unknown",
+    taskId: e.taskId,
+    changeSetId: e.changeSetId,
+    reason: e.reason ?? e.operation,
+    operation: e.operation,
+    route: e.route,
+    success: e.success,
+    beforeHash: e.beforeHash,
+    afterHash: e.afterHash,
+    diff: e.diff,
+    stepIndex: e.stepIndex,
+    stepTotal: e.stepTotal,
+    context: e.context,
+    // Maps from telemetry's `verification_result` field
+    verification: e.verification_result,
+  };
+}
+
+export function provenanceQuery(file: string, line?: number, fuzzy?: boolean): ProvenanceEntry[] {
+  const all = exportEvents();
+  const fileEvents = all.filter((e) => e.file === file);
+
+  const filtered = line !== undefined
+    ? fileEvents.filter((e) => {
+        if (!e.diff) return fuzzy;  // no diff → only include if fuzzy
+        return diffCoversLine(e.diff, line);
+      })
+    : fileEvents;
+
+  return filtered
+    .map(toProvenanceEntry)
+    .sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+}
+
+export function changeSetQuery(changeSetId: string): ChangeSetResult | null {
+  const all = exportEvents();
+  const entries = all
+    .filter((e) => e.changeSetId === changeSetId)
+    .map(toProvenanceEntry)
+    .sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+
+  if (entries.length === 0) return null;
+
+  const first = entries[0];
+  const last = entries[entries.length - 1];
+
+  return {
+    changeSetId,
+    taskId: first.taskId,
+    actor: first.actor,
+    reason: first.reason,
+    editCount: entries.length,
+    entries,
+    timeRange: { first: first.timestamp, last: last.timestamp },
+  };
+}
+
+// ── Human-readable formatting ──────────────────────────────────────────
+
+export function formatProvenanceHuman(entries: ProvenanceEntry[]): string {
+  if (entries.length === 0) return "No edits found for this file.";
+
+  const lines: string[] = [];
+  for (const e of entries) {
+    const ts = e.timestamp.slice(0, 19).replace("T", " ");
+    const status = e.success ? "OK" : "FAIL";
+    const step = e.stepTotal ? ` [${(e.stepIndex ?? 0) + 1}/${e.stepTotal}]` : "";
+    const task = e.taskId ? ` task=${e.taskId}` : "";
+    const reason = e.reason !== e.operation ? ` "${e.reason}"` : "";
+    lines.push(
+      `${ts}  ${e.actor}${task}  ${e.operation}  ${e.route}  ${status}${step}${reason}`
+    );
+  }
+  return lines.join("\n");
+}

package/src/core/read.ts

@@ -0,0 +1,111 @@
+import { createHash } from "crypto";
+import { readDecoded } from "./encoding";
+
+export interface ReadResult {
+  path: string;
+  content: string;
+  hash: string;
+  lines: number;
+  error?: string;
+}
+
+/** Hash width, shared by every anchor. See `computeLineHash`. */
+const HASH_WIDTH = 12;
+
+export function computeHash(content: string): string {
+  return createHash("sha256").update(content).digest("hex").slice(0, HASH_WIDTH);
+}
+
+/**
+ * A single line's anchor hash. Identical to `computeHash` — it exists to name
+ * the intent, not to compute something different.
+ *
+ * It used to truncate to 8 characters while `computeHash` used 12, so the
+ * `lineHash` from `read-hash` never matched what `replace-hash` computed: the
+ * read → write round-trip always failed with `STALE_ANCHOR`, which is
+ * documented as retryable, so an agent retried it forever.
+ */
+export function computeLineHash(line: string): string {
+  return computeHash(line);
+}
+
+export async function readMany(files: string[]): Promise<ReadResult[]> {
+  const results = await Promise.all(
+    files.map(async (p) => {
+      try {
+        const { text: content } = await readDecoded(p);
+        return {
+          path: p,
+          content,
+          hash: computeHash(content),
+          lines: content.split("\n").length - (content.endsWith("\n") ? 1 : 0),
+        };
+      } catch (e: any) {
+        return { path: p, content: "", hash: "", lines: 0, error: e.message };
+      }
+    })
+  );
+  return results;
+}
+
+export interface ReadHashResult {
+  path: string;
+  line: number;
+  content: string;
+  lineHash: string;
+  contextHash: string;
+  contextBefore: string[];
+  contextAfter: string[];
+  error?: string;
+}
+
+export async function readHash(
+  filePath: string,
+  line: number,
+  contextLines: number = 3
+): Promise<ReadHashResult> {
+  try {
+    const { text: content } = await readDecoded(filePath);
+    const lines = content.split("\n");
+    const targetLine = lines[line - 1];
+    // A blank line is an empty string, which is falsy — checking truthiness here
+    // reported a legitimate blank line as out of range (#40 falsy-parameter audit).
+    if (targetLine === undefined) {
+      return {
+        path: filePath,
+        line,
+        content: "",
+        lineHash: "",
+        contextHash: "",
+        contextBefore: [],
+        contextAfter: [],
+        error: `Line ${line} out of range (file has ${lines.length} lines)`,
+      };
+    }
+    const start = Math.max(0, line - 1 - contextLines);
+    const end = Math.min(lines.length, line - 1 + contextLines + 1);
+    const before = lines.slice(start, line - 1);
+    const after = lines.slice(line, end);
+    const contextText = [...before, targetLine, ...after].join("\n");
+    return {
+      path: filePath,
+      line,
+      content: targetLine,
+      lineHash: computeLineHash(targetLine),
+      contextHash: computeHash(contextText),
+      contextBefore: before,
+      contextAfter: after,
+    };
+  } catch (e: any) {
+    return {
+      path: filePath,
+      line,
+      content: "",
+      lineHash: "",
+      contextHash: "",
+      contextBefore: [],
+      contextAfter: [],
+      error: e.message,
+    };
+  }
+}

package/src/core/redact.ts

@@ -0,0 +1,98 @@
+import { basename } from "node:path";
+
+/**
+ * Secret redaction for anything that reaches the telemetry log.
+ *
+ * Telemetry is written to `~/.agentic-tools/logs/` in plaintext and may be
+ * exported or shared. Provenance diffs put real source lines in there, so a
+ * `.env` edit or a pasted key would be persisted verbatim. Redaction runs on
+ * every string field before the event is serialized.
+ */
+
+const REDACTED = "[REDACTED]";
+
+interface Rule {
+  name: string;
+  pattern: RegExp;
+  /** Replacement; `$1` etc. refer to capture groups kept as context. */
+  replacement: string;
+}
+
+const RULES: Rule[] = [
+  { name: "aws-access-key-id", pattern: /\b(?:AKIA|ASIA|AGPA|AIDA|AROA|ANPA|ANVA)[0-9A-Z]{16}\b/g, replacement: REDACTED },
+  { name: "aws-secret-access-key", pattern: /\b(aws_secret_access_key\s*[:=]\s*)\S+/gi, replacement: `$1${REDACTED}` },
+  { name: "openai-key", pattern: /\bsk-[A-Za-z0-9_-]{16,}\b/g, replacement: REDACTED },
+  { name: "anthropic-key", pattern: /\bsk-ant-[A-Za-z0-9_-]{16,}\b/g, replacement: REDACTED },
+  { name: "github-token", pattern: /\b(?:ghp|gho|ghu|ghs|ghr|github_pat)_[A-Za-z0-9_]{16,}\b/g, replacement: REDACTED },
+  { name: "slack-token", pattern: /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g, replacement: REDACTED },
+  { name: "google-api-key", pattern: /\bAIza[0-9A-Za-z_-]{35}\b/g, replacement: REDACTED },
+  { name: "jwt", pattern: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, replacement: REDACTED },
+  { name: "private-key-block", pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, replacement: `-----BEGIN PRIVATE KEY-----${REDACTED}-----END PRIVATE KEY-----` },
+  { name: "authorization-header", pattern: /\b(authorization\s*[:=]\s*["']?)(?:bearer|basic|token)\s+\S+/gi, replacement: `$1${REDACTED}` },
+  { name: "connection-string-password", pattern: /(\b[a-z][a-z0-9+.-]*:\/\/[^\s:@/]+:)[^\s@/]+(@)/gi, replacement: `$1${REDACTED}$2` },
+  // Assignments whose *name* implies a secret. Deliberately last: the value is
+  // replaced wholesale rather than pattern-matched, so it catches formats the
+  // rules above do not know about.
+  {
+    name: "secretish-assignment",
+    pattern: /\b([A-Za-z0-9_.-]*(?:secret|token|password|passwd|api[_-]?key|access[_-]?key|credential)[A-Za-z0-9_.-]*\s*[:=]\s*)(["']?)([^\s"',;)}]{6,})\2/gi,
+    replacement: `$1$2${REDACTED}$2`,
+  },
+  // Bare cloud-credential "*Key" field names (Azure AccountKey, Cosmos DB
+  // PrimaryKey/MasterKey, Redis AuthKey, non-PEM PrivateKey). The prefix word
+  // must sit immediately before "key" *and* "key" must be the end of the
+  // identifier (right before `:`/`=`), so this doesn't fire on identifiers
+  // that merely contain "key" followed by more name, e.g. `primaryKeyColumn`.
+  {
+    name: "cloud-credential-key",
+    pattern: /\b([A-Za-z0-9_.-]*(?:account|primary|master|auth|private)[_-]?key["']?\s*[:=]\s*)(["']?)([^\s"',;)}]{20,})\2/gi,
+    replacement: `$1$2${REDACTED}$2`,
+  },
+];
+
+/** Redact every known secret shape in a string. Returns the input unchanged when nothing matches. */
+export function redactSecrets(input: string): string {
+  let out = input;
+  for (const rule of RULES) out = out.replace(rule.pattern, rule.replacement);
+  return out;
+}
+
+/**
+ * Files whose *contents* are secret by definition. Their diffs and source are
+ * never recorded, regardless of what redaction would catch.
+ */
+const SENSITIVE_FILE_PATTERNS: RegExp[] = [
+  /^\.env(\..*)?$/i,
+  /\.pem$/i,
+  /\.key$/i,
+  /\.p12$/i,
+  /\.pfx$/i,
+  /^id_(rsa|dsa|ecdsa|ed25519)(\.pub)?$/i,
+  /^credentials$/i,
+  /^\.npmrc$/i,
+  /^\.netrc$/i,
+  /^.*\.keystore$/i,
+  /^secrets?\.(ya?ml|json|toml)$/i,
+];
+
+/** True when the file's contents must never appear in telemetry. */
+export function isSensitiveFile(filePath: string): boolean {
+  const name = basename(filePath);
+  return SENSITIVE_FILE_PATTERNS.some((re) => re.test(name));
+}
+
+/**
+ * Recursively redact the string fields of a telemetry event. Object keys and
+ * non-string values pass through untouched — only values can carry secrets.
+ */
+export function redactEvent<T>(event: T): T {
+  const walk = (value: unknown): unknown => {
+    if (typeof value === "string") return redactSecrets(value);
+    if (Array.isArray(value)) return value.map(walk);
+    if (value && typeof value === "object") {
+      return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([k, v]) => [k, walk(v)]));
+    }
+    return value;
+  };
+  return walk(event) as T;
+}

package/src/core/resolve-content.ts

@@ -0,0 +1,12 @@
+/**
+ * Resolve a CLI content argument: `@path` reads the file, anything else is
+ * taken literally.
+ *
+ * An explicit empty string is a deletion, not an omitted argument (#40), so
+ * only `undefined` short-circuits.
+ */
+export async function resolveContent(val?: string): Promise<string | undefined> {
+  if (val === undefined) return undefined;
+  if (val.startsWith("@")) return await Bun.file(val.slice(1)).text();
+  return val;
+}