copperhead 0.9.0 → 0.10.0

package/dist/memory/synap.js

@@ -1,152 +0,0 @@
-/**
- * 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;
-export function synapEnabled(env = process.env) {
-    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, env) {
-    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(p, ms, label) {
-    return new Promise((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) {
-    const env = opts.env ?? process.env;
-    const log = opts.log ?? (() => { });
-    if (!synapEnabled(env))
-        return null;
-    let client;
-    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));
-        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.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.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.
-            }
-        },
-    };
-}
-//# sourceMappingURL=synap.js.map

package/dist/memory/synap.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"synap.js","sourceRoot":"","sources":["../../src/memory/synap.ts"],"names":[],"mappings":"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"}

package/src/memory/synap.ts

@@ -1,217 +0,0 @@
-/**
- * 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.
-      }
-    },
-  };
-}