copperhead 0.3.0 → 0.5.0

package/src/memory/synap.ts

@@ -0,0 +1,217 @@
+/**
+ * Cross-run memory via Synap (https://docs.maximem.ai).
+ *
+ * copperhead's own memory is per-repo and file-based: docs/DECISIONS.md, the
+ * constraint registry, the drift checker. Synap is the layer above that — what
+ * this user tends to want across every board they've ever asked about. It
+ * complements the docs; it does not replace them, and nothing here is a source
+ * of truth. Recalled text is advisory context in the system prompt, while
+ * as-built facts still come from the KiCad files.
+ *
+ * Three properties are load-bearing:
+ *
+ * 1. Opt-in. Inactive unless SYNAP_API_KEY is set, so the default install is
+ *    unchanged and `check` stays network-free (it never constructs this).
+ * 2. Optional at runtime. @maximem/synap-js-sdk is an optionalDependency and is
+ *    imported lazily through a non-literal specifier, so a missing package (or
+ *    a host without the Python 3.11+ runtime its bridge needs) degrades to
+ *    "no memory" instead of breaking the CLI.
+ * 3. Fail-soft on read, loud on write. A recall failure must never cost someone
+ *    a design run; a record failure is reported, because silently losing writes
+ *    lets memory drift away from what actually happened.
+ */
+import { randomUUID } from 'node:crypto';
+import { execa } from 'execa';
+import { redactSecrets } from '../util/redact.js';
+
+/** Wall-clock ceiling on any single Synap call. The bridge is a Python subprocess. */
+const RECALL_TIMEOUT_MS = 10_000;
+const RECORD_TIMEOUT_MS = 15_000;
+const MAX_RECALLED = 8;
+
+/**
+ * Structural subset of @maximem/synap-js-sdk's surface. Declared locally rather
+ * than imported so `tsc` succeeds when the optional dependency is absent.
+ */
+interface SynapSearchItem {
+  memory: string;
+  score?: number;
+  contextType?: string;
+}
+interface SynapClientLike {
+  init(): Promise<void>;
+  searchMemory(input: {
+    userId: string;
+    customerId?: string;
+    query: string;
+    maxResults?: number;
+  }): Promise<{ results: SynapSearchItem[] }>;
+  addMemory(input: {
+    userId: string;
+    customerId: string;
+    conversationId?: string;
+    messages: Array<{ role?: 'user' | 'assistant'; content: string }>;
+    metadata?: Record<string, unknown>;
+  }): Promise<{ success: boolean }>;
+  shutdown(): Promise<void>;
+}
+
+export interface RunRecord {
+  request: string;
+  outcome: 'success' | 'refused';
+  summary: string;
+  changeId: string | null;
+  filesTouched: string[];
+  decisions: string[];
+  verification: string;
+}
+
+export interface SynapMemory {
+  /** Prior context relevant to this request, as a prompt-ready markdown block. */
+  recall(request: string): Promise<string | null>;
+  /** Persist a finished run. Rejects if the write fails. */
+  record(run: RunRecord): Promise<void>;
+  /** Stop the bridge subprocess. Always call this, or the CLI will not exit. */
+  close(): Promise<void>;
+}
+
+export function synapEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return Boolean(env.SYNAP_API_KEY);
+}
+
+/**
+ * Identity for memory scoping. The git committer email is the natural stable
+ * user id here: it is already the identity every run is attributed to.
+ */
+async function resolveUserId(repoRoot: string, env: NodeJS.ProcessEnv): Promise<string> {
+  if (env.SYNAP_USER_ID) return env.SYNAP_USER_ID;
+  try {
+    const { stdout } = await execa('git', ['config', 'user.email'], { cwd: repoRoot });
+    if (stdout.trim()) return stdout.trim();
+  } catch {
+    // not configured; fall through
+  }
+  return 'copperhead-local';
+}
+
+function withTimeout<T>(p: Promise<T>, ms: number, label: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+    p.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      },
+    );
+  });
+}
+
+/**
+ * Returns null when memory is disabled or unavailable — every caller treats
+ * null as "run without cross-run memory".
+ */
+export async function openSynapMemory(opts: {
+  repoRoot: string;
+  log?: (line: string) => void;
+  env?: NodeJS.ProcessEnv;
+}): Promise<SynapMemory | null> {
+  const env = opts.env ?? process.env;
+  const log = opts.log ?? (() => {});
+  if (!synapEnabled(env)) return null;
+
+  let client: SynapClientLike;
+  try {
+    // Non-literal specifier: keeps tsc from resolving an optional dependency at
+    // build time, so the package may legitimately be absent.
+    const specifier = '@maximem/synap-js-sdk';
+    const mod = (await import(specifier)) as {
+      createClient?: (o?: Record<string, unknown>) => SynapClientLike;
+      default?: { createClient?: (o?: Record<string, unknown>) => SynapClientLike };
+    };
+    const createClient = mod.createClient ?? mod.default?.createClient;
+    if (!createClient) throw new Error('createClient not exported');
+    client = createClient({ apiKey: env.SYNAP_API_KEY, requestTimeoutMs: RECORD_TIMEOUT_MS });
+    await withTimeout(client.init(), RECORD_TIMEOUT_MS, 'synap init');
+  } catch (err) {
+    // Missing package, missing Python runtime, bad key: all non-fatal.
+    log(`synap memory unavailable (${(err as Error).message}); continuing without it`);
+    return null;
+  }
+
+  const userId = await resolveUserId(opts.repoRoot, env);
+  const customerId = env.SYNAP_CUSTOMER_ID ?? 'copperhead';
+  const conversationId = randomUUID();
+
+  return {
+    async recall(request) {
+      try {
+        const res = await withTimeout(
+          client.searchMemory({
+            userId,
+            customerId,
+            query: redactSecrets(request),
+            maxResults: MAX_RECALLED,
+          }),
+          RECALL_TIMEOUT_MS,
+          'synap recall',
+        );
+        const items = (res.results ?? []).filter((r) => r.memory?.trim());
+        if (!items.length) return null;
+        const lines = items.map((r) => `- ${r.memory.trim()}${r.contextType ? ` _(${r.contextType})_` : ''}`);
+        return [
+          '## Recalled from prior runs (Synap)',
+          '',
+          'Context from earlier work by this user, possibly on other boards. Advisory only:',
+          'the KiCad files and this repo’s docs remain the source of truth. If any of this',
+          'conflicts with what you read in the repo, the repo wins — say so rather than',
+          'acting on a stale memory.',
+          '',
+          ...lines,
+        ].join('\n');
+      } catch (err) {
+        log(`synap recall failed (${(err as Error).message}); continuing without it`);
+        return null;
+      }
+    },
+
+    async record(run) {
+      const assistant = [
+        `Outcome: ${run.outcome}`,
+        `Summary: ${run.summary}`,
+        `OpenSpec change: ${run.changeId ?? 'n/a'}`,
+        `Verification: ${run.verification}`,
+        run.filesTouched.length ? `Files: ${run.filesTouched.join(', ')}` : null,
+        run.decisions.length ? `Decisions:\n${run.decisions.map((d) => `- ${d}`).join('\n')}` : null,
+      ]
+        .filter(Boolean)
+        .join('\n');
+
+      await withTimeout(
+        client.addMemory({
+          userId,
+          customerId,
+          conversationId,
+          messages: [
+            { role: 'user', content: redactSecrets(run.request) },
+            { role: 'assistant', content: redactSecrets(assistant) },
+          ],
+          metadata: { source: 'copperhead', outcome: run.outcome, changeId: run.changeId },
+        }),
+        RECORD_TIMEOUT_MS,
+        'synap record',
+      );
+    },
+
+    async close() {
+      try {
+        await withTimeout(client.shutdown(), RECORD_TIMEOUT_MS, 'synap shutdown');
+      } catch {
+        // Best effort: a failed shutdown must not change the run's outcome.
+      }
+    },
+  };
+}

package/src/util/git.ts

@@ -1,4 +1,9 @@
 import { execa } from 'execa';
+import { cp, mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { PreflightError } from './preflight.js';
 
 export interface GitSnapshot {
   head: string;
@@ -19,11 +24,54 @@ export async function isGitRepo(repo: string): Promise<boolean> {
   }
 }
 
+/** False on an unborn HEAD (fresh `git init` with no commits yet). */
+export async function hasCommits(repo: string): Promise<boolean> {
+  try {
+    await git(repo, ['rev-parse', '--quiet', '--verify', 'HEAD']);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export async function isDirty(repo: string): Promise<boolean> {
   const status = await git(repo, ['status', '--porcelain']);
   return status.length > 0;
 }
 
+/**
+ * The run-blocking git gates, in order: repo -> commits -> dirty (AC-3.8).
+ * Throws a PreflightError whose message explains why the run is refused and
+ * how to fix it; a caller that catches only needs err.message.
+ */
+export async function gitPreflight(repo: string, opts: { allowDirty?: boolean } = {}): Promise<void> {
+  if (!(await isGitRepo(repo))) {
+    throw new PreflightError(
+      'not a git repository; copperhead requires git for snapshots and rollback',
+      'every run snapshots HEAD before editing so a failed run can be rolled back losslessly; without git there is no snapshot and no undo',
+      ['git init', 'git add -A && git commit -m "initial commit"', 'rerun the same copperhead command'],
+    );
+  }
+  if (!(await hasCommits(repo))) {
+    throw new PreflightError(
+      'repository has no commits; copperhead requires at least one commit for snapshots and rollback',
+      'the pre-run snapshot is the current HEAD commit; with an unborn HEAD there is nothing to roll back to if verification fails',
+      ['git add -A && git commit -m "initial commit"', 'rerun the same copperhead command'],
+    );
+  }
+  if ((await isDirty(repo)) && !opts.allowDirty) {
+    throw new PreflightError(
+      'working tree is dirty; copperhead refuses to run on uncommitted changes by default',
+      'a rollback hard-resets to the pre-run snapshot, which would silently destroy your uncommitted work',
+      [
+        'git add -A && git commit — to keep your changes (recommended)',
+        'git stash — to set them aside for now',
+        'or rerun with --allow-dirty to let copperhead preserve them via "git stash create"',
+      ],
+    );
+  }
+}
+
 /**
  * Snapshot the working tree before a run. On a clean tree HEAD is enough;
  * with --allow-dirty we keep a `git stash create` object so uncommitted work
@@ -43,13 +91,95 @@ export async function snapshot(repo: string): Promise<GitSnapshot> {
  * (.copperhead/runs/) survives rollback: it is the evidence of what failed.
  */
 export async function restore(repo: string, snap: GitSnapshot): Promise<void> {
-  await git(repo, ['reset', '--hard', snap.head]);
-  await git(repo, ['clean', '-fd', '-e', '.copperhead/runs']);
-  if (snap.stash) {
-    await git(repo, ['stash', 'apply', snap.stash]);
+  // `git clean -e` only protects untracked paths. A run directory can become
+  // staged (for example while preserving failed work), and `reset --hard`
+  // deletes such paths before clean runs. Copy it outside the repository so
+  // the audit trail survives regardless of its index state.
+  const runs = path.join(repo, '.copperhead', 'runs');
+  let backupRoot: string | null = null;
+  let backup: string | null = null;
+  try {
+    try {
+      backupRoot = await mkdtemp(path.join(tmpdir(), 'copperhead-runs-'));
+      backup = path.join(backupRoot, 'runs');
+      if (existsSync(runs)) await cp(runs, backup, { recursive: true });
+    } catch (err) {
+      backup = null;
+      console.warn(`warning: could not preserve failed-run audit trail before rollback: ${(err as Error).message}`);
+    }
+
+    try {
+      await git(repo, ['reset', '--hard', snap.head]);
+      await git(repo, ['clean', '-fd', '-e', '.copperhead/runs']);
+      if (snap.stash) {
+        await git(repo, ['stash', 'apply', snap.stash]);
+      }
+    } finally {
+      if (backup && existsSync(backup)) {
+        try {
+          await mkdir(path.dirname(runs), { recursive: true });
+          // Restored runs are intentionally untracked; their audit contents
+          // are ignored by the target-repository convention.
+          await cp(backup, runs, { recursive: true, force: true });
+        } catch (err) {
+          console.warn(`warning: could not restore failed-run audit trail: ${(err as Error).message}`);
+        }
+      }
+    }
+  } finally {
+    if (backupRoot) {
+      try {
+        await rm(backupRoot, { recursive: true, force: true });
+      } catch (err) {
+        console.warn(`warning: could not clean failed-run audit backup: ${(err as Error).message}`);
+      }
+    }
   }
 }
 
+/**
+ * Preserve a failed run's work as a stash entry before rollback, so a failure
+ * is recoverable instead of destroyed. `git stash create` alone ignores
+ * untracked files (most of what a docs-stage run produces), so everything is
+ * staged first; restore() resets the index anyway. Never throws: preservation
+ * must not be able to block the rollback itself.
+ */
+export async function preserveFailedRun(repo: string, runId: string): Promise<string | null> {
+  try {
+    if (!(await isDirty(repo))) return null;
+    // Never leave the audit trail staged: a staged-but-not-in-HEAD path is
+    // deleted by restore()'s `reset --hard`, which silently defeats its
+    // `clean -e .copperhead/runs` protection (that flag only spares untracked
+    // files) — the in-flight run's transcript dir vanishes mid-run. Staging
+    // then unstaging (rather than an exclude pathspec) because `git add`
+    // errors outright when a pathspec touches gitignored paths, and runs/ is
+    // gitignored in some target repos but tracked in others.
+    await git(repo, ['add', '-A']);
+    await git(repo, ['reset', '-q', '--', '.copperhead/runs']);
+    const sha = await git(repo, ['stash', 'create']);
+    if (!sha) return null;
+    await git(repo, ['stash', 'store', '-m', `copperhead failed run ${runId}`, sha]);
+    return sha;
+  } catch {
+    return null;
+  }
+}
+
+/** Current branch name, or "HEAD" when detached. Read-only metadata probe. */
+export async function branchName(repo: string): Promise<string> {
+  return git(repo, ['rev-parse', '--abbrev-ref', 'HEAD']);
+}
+
+export async function headCommit(repo: string): Promise<string> {
+  return git(repo, ['rev-parse', 'HEAD']);
+}
+
+/** Count of uncommitted paths (staged, unstaged, and untracked). */
+export async function uncommittedCount(repo: string): Promise<number> {
+  const status = await git(repo, ['status', '--porcelain']);
+  return status ? status.split('\n').length : 0;
+}
+
 export async function commitAll(repo: string, message: string): Promise<string> {
   await git(repo, ['add', '-A']);
   await git(repo, ['commit', '-m', message]);

package/src/util/preflight.ts

@@ -0,0 +1,22 @@
+/**
+ * A run-blocking environment failure. Distinct from a mid-run error: nothing
+ * has been written yet, so the message alone is the whole user experience.
+ * The formatted message carries the reason, why copperhead refuses to run,
+ * and concrete remedy steps — every CLI catch path prints err.message, so
+ * embedding the explanation here means no call site needs special rendering.
+ */
+export class PreflightError extends Error {
+  constructor(
+    readonly reason: string,
+    readonly why: string,
+    readonly remedy: string[],
+  ) {
+    super(formatPreflightFailure(reason, why, remedy));
+    this.name = 'PreflightError';
+  }
+}
+
+export function formatPreflightFailure(reason: string, why: string, remedy: string[]): string {
+  const steps = remedy.map((step, i) => `  ${i + 1}. ${step}`);
+  return [reason, '', `why it failed: ${why}`, 'to fix:', ...steps].join('\n');
+}