imprint-mcp 0.2.0

package/src/imprint/load-json.ts

@@ -0,0 +1,54 @@
+/**
+ * Load + JSON-parse + schema-validate a config file. Errors at each step
+ * include a specific remediation hint so the user knows what to fix.
+ *
+ * Used by: cron.ts (cron.json), emit.ts (workflow.json), cli.ts redact +
+ * compile.ts (session.json). Before this helper each verb hand-rolled
+ * the same three-branch error format.
+ */
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import type { ZodTypeAny, z } from 'zod';
+
+interface LoadJsonRemediation {
+  /** What to suggest when the file doesn't exist. Should be one or more lines, each starting with "→". */
+  notFound: string;
+  /** Suggestion when JSON.parse throws. Optional. Same format. */
+  notJson?: string;
+  /** Suggestion when schema validation fails. Optional. Same format. */
+  badSchema?: string;
+}
+
+/** Read JSON from disk, validate against `schema`. Throws Error with
+ *  a multi-line message on any failure. Returns the schema's *output*
+ *  type (post-defaults), not the input type. */
+export function loadJsonFile<S extends ZodTypeAny>(
+  path: string,
+  schema: S,
+  remediation: LoadJsonRemediation,
+  noun = 'file',
+): z.infer<S> {
+  if (!existsSync(path)) {
+    throw new Error(`${noun} not found: ${path}\n${remediation.notFound}`);
+  }
+  if (!statSync(path).isFile()) {
+    throw new Error(`${noun} is not a file: ${path}\n${remediation.notFound}`);
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const tail = remediation.notJson ? `\n${remediation.notJson}` : '';
+    throw new Error(`${path} is not valid JSON: ${msg}${tail}`);
+  }
+  const parsed = schema.safeParse(raw);
+  if (!parsed.success) {
+    const issues = parsed.error.errors
+      .map((e) => `  - ${e.path.join('.') || '(root)'}: ${e.message}`)
+      .join('\n');
+    const tail = remediation.badSchema ? `\n${remediation.badSchema}` : '';
+    throw new Error(`${path} doesn't match the ${noun} schema:\n${issues}${tail}`);
+  }
+  return parsed.data;
+}

package/src/imprint/log.ts

@@ -0,0 +1,33 @@
+/** Logger factory + env-flag helpers.
+ *
+ *  createLog('cron')('hi') → stderr `[imprint cron] hi`.
+ *
+ *  Suppressed entirely when IMPRINT_QUIET=1 (set by `imprint cron --quiet`
+ *  for OS-scheduler-friendly silent runs). Errors should not flow through
+ *  this; they should go to stderr via console.error or process.stderr.write
+ *  directly so they survive --quiet.
+ *
+ *  IMPRINT_DEBUG=1 enables verbose tracing in record.ts / chromium.ts.
+ *  Both flags check the literal '1' value (not truthy coercion) so
+ *  IMPRINT_DEBUG=0 actually disables, as the user expects. */
+
+type Log = (msg: string) => void;
+
+const isQuiet = (): boolean => process.env.IMPRINT_QUIET === '1';
+export const isDebug = (): boolean => process.env.IMPRINT_DEBUG === '1';
+
+let muted = false;
+export function muteLog(): void {
+  muted = true;
+}
+export function unmuteLog(): void {
+  muted = false;
+}
+
+export function createLog(area: string): Log {
+  const prefix = `[imprint ${area}]`;
+  return (msg: string): void => {
+    if (isQuiet() || muted) return;
+    process.stderr.write(`${prefix} ${msg}\n`);
+  };
+}

package/src/imprint/login.ts

@@ -0,0 +1,166 @@
+/** `imprint login` — extract cookies + per-site values from a captured
+ *  session.json into the credential manager. */
+
+import { readFileSync } from 'node:fs';
+import {
+  type StorageRecord,
+  getCredentialBackend,
+  setManifestStorageKeys,
+  upsertManifestEntry,
+} from './credential-store.ts';
+import { type Session, SessionSchema } from './types.ts';
+
+interface LoginOptions {
+  site: string;
+  /** Path to a session.json from which to extract credentials. */
+  fromSession: string;
+}
+
+interface LoginResult {
+  backend: 'keyring' | 'encrypted-file' | 'legacy-json';
+  cookieCount: number;
+  storageCount: number;
+  values: Record<string, string>;
+  /** Pattern names that matched and contributed values. */
+  matchedExtractors: string[];
+}
+
+export async function login(opts: LoginOptions): Promise<LoginResult> {
+  const raw = JSON.parse(readFileSync(opts.fromSession, 'utf8'));
+  const session: Session = SessionSchema.parse(raw);
+
+  const cookies = collectCookies(session);
+  const storage = collectStorage(session);
+  const { values, matched } = extractKnownValues(session);
+
+  const backend = await getCredentialBackend();
+  await backend.setCookies(opts.site, cookies);
+  if (backend.setStorage) {
+    await backend.setStorage(opts.site, storage);
+    setManifestStorageKeys(
+      opts.site,
+      storage.map((s) => ({ origin: s.origin, kind: s.kind, key: s.key })),
+    );
+  }
+  for (const [name, value] of Object.entries(values)) {
+    await backend.setSecret(opts.site, name, value);
+    upsertManifestEntry(opts.site, {
+      name,
+      kind: 'opaque',
+      description: `Extracted via ${matched.join('+') || 'login'}`,
+    });
+  }
+
+  return {
+    backend: backend.id,
+    cookieCount: cookies.length,
+    storageCount: storage.length,
+    values,
+    matchedExtractors: matched,
+  };
+}
+
+/** End snapshot captures everything set during the workflow (post-login
+ *  cookies); fall back to start snapshot if absent. */
+function collectCookies(session: Session) {
+  const snaps = session.cookieSnapshots ?? [];
+  const end = snaps.find((s) => s.label === 'end');
+  const start = snaps.find((s) => s.label === 'start');
+  const chosen = end ?? start;
+  if (!chosen) return [];
+  return chosen.cookies.map((c) => ({ ...c }));
+}
+
+function collectStorage(session: Session): StorageRecord[] {
+  const snaps = session.storageSnapshots ?? [];
+  const end = snaps.filter((s) => s.label === 'end');
+  const chosen = end.length > 0 ? end : snaps.filter((s) => s.label === 'start');
+  const byKey = new Map<string, StorageRecord>();
+  for (const snap of chosen) {
+    for (const [key, value] of Object.entries(snap.localStorage ?? {})) {
+      byKey.set(`${snap.origin}\0localStorage\0${key}`, {
+        origin: snap.origin,
+        kind: 'localStorage',
+        key,
+        value,
+      });
+    }
+  }
+  return Array.from(byKey.values());
+}
+
+/** Per-site extractors pull named values out of recognized auth shapes;
+ *  ordered list, first match wins. */
+const EXTRACTORS: Array<{
+  name: string;
+  match: (session: Session) => Record<string, string> | null;
+}> = [
+  {
+    name: 'discoverandgo:Login',
+    // D&G's Login POST returns a JSON object with patronID.
+    match: (session) => {
+      const loginReq = session.requests.find(
+        (r) =>
+          r.method === 'POST' &&
+          r.url.includes('epass_server.php') &&
+          (r.body?.includes('method=Login') ?? false),
+      );
+      if (!loginReq?.response?.body) return null;
+      try {
+        const body = JSON.parse(loginReq.response.body) as {
+          patronID?: string;
+          session?: string;
+          patronEmail?: string;
+        };
+        const out: Record<string, string> = {};
+        if (body.patronID) out.patron_id = body.patronID;
+        if (body.session) out.session_id = body.session;
+        if (body.patronEmail) out.patron_email = body.patronEmail;
+        return Object.keys(out).length ? out : null;
+      } catch {
+        return null;
+      }
+    },
+  },
+  {
+    name: 'southwest:security_token',
+    // Southwest's POST /api/security/v4/security/token returns auth tokens
+    // and account info we want available to follow-up requests.
+    match: (session) => {
+      const loginReq = session.requests.find(
+        (r) =>
+          r.method === 'POST' &&
+          r.url.includes('/api/security/v4/security/token') &&
+          (r.body?.includes('username=') ?? false),
+      );
+      if (!loginReq?.response?.body) return null;
+      try {
+        const body = JSON.parse(loginReq.response.body) as Record<string, unknown>;
+        const out: Record<string, string> = {};
+        const accountNumber = body['customers.userInformation.accountNumber'];
+        const primaryEmail = body['customers.userInformation.primaryEmail'];
+        if (typeof accountNumber === 'string') out.account_number = accountNumber;
+        if (typeof primaryEmail === 'string') out.primary_email = primaryEmail;
+        return Object.keys(out).length ? out : null;
+      } catch {
+        return null;
+      }
+    },
+  },
+];
+
+function extractKnownValues(session: Session): {
+  values: Record<string, string>;
+  matched: string[];
+} {
+  const values: Record<string, string> = {};
+  const matched: string[] = [];
+  for (const ext of EXTRACTORS) {
+    const v = ext.match(session);
+    if (v) {
+      Object.assign(values, v);
+      matched.push(ext.name);
+    }
+  }
+  return { values, matched };
+}

package/src/imprint/mcp-compile-server.ts

@@ -0,0 +1,282 @@
+/**
+ * Stdio MCP server that exposes the compile-agent's tools to claude-cli.
+ *
+ * Spawned by `claude-cli-compile.ts` via `--mcp-config`. The server registers
+ * the same 8 read/write tools the in-process loop uses, plus a custom `done`
+ * tool that runs external verification inline and writes a sentinel file when
+ * complete. claude-cli polls the sentinel and SIGTERMs us when it appears.
+ *
+ * Why in-tool verification: the in-process loop (agent.ts) restarts after a
+ * verification failure with a continuation message. Doing the same here would
+ * require killing claude-cli and re-spawning, losing context. Instead, we
+ * return the failure list as the tool_result content so claude continues
+ * iterating in the same conversation — same up-to-5-cycle bound, no context
+ * loss.
+ */
+
+import { writeFileSync } from 'node:fs';
+import { join as pathJoin } from 'node:path';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  type CallToolResult,
+  ListToolsRequestSchema,
+  type Tool,
+} from '@modelcontextprotocol/sdk/types.js';
+import { buildCompileTools, externalVerification } from './compile-tools.ts';
+import { loadJsonFile } from './load-json.ts';
+import { createLog } from './log.ts';
+import { redactSession } from './redact.ts';
+import type { SharedCompileContext, ToolCandidate } from './tool-candidates.ts';
+import { type Session, SessionSchema } from './types.ts';
+
+const log = createLog('mcp-compile');
+
+interface RunCompileMcpServerOptions {
+  /** Path to the recorded session JSON. */
+  sessionPath: string;
+  /** Absolute path to the generated tool directory where artifacts go. */
+  toolDir: string;
+  /** Hard cap on done() verification failures before we permanently fail.
+   *  Mirrors compile-agent.ts MAX_VERIFICATION_CYCLES. */
+  maxVerificationCycles?: number;
+  candidate?: ToolCandidate;
+  sharedContext?: SharedCompileContext;
+}
+
+const DONE_SENTINEL = '.compile-done.json';
+const GIVE_UP_SENTINEL = '.compile-give-up.json';
+
+export async function runCompileMcpServer(opts: RunCompileMcpServerOptions): Promise<void> {
+  const maxVerificationCycles = opts.maxVerificationCycles ?? 5;
+
+  // Load + auto-redact the session, exactly as compile-agent.ts does.
+  let session: Session = loadJsonFile(
+    opts.sessionPath,
+    SessionSchema,
+    {
+      notFound: '→ run `imprint record <site>` to create one.',
+      notJson: `→ if it's a partial .jsonl, run \`imprint assemble ${opts.sessionPath}\` first.`,
+      badSchema: '→ check the file came from `imprint record`.',
+    },
+    'session',
+  );
+  const looksRedacted = JSON.stringify(session).includes('[REDACTED:');
+  if (!looksRedacted) {
+    session = redactSession(session).session;
+  }
+
+  // Build the 8 read/write tools (same as the in-process loop).
+  const compileTools = buildCompileTools(session, opts.toolDir, opts.sessionPath, {
+    candidate: opts.candidate,
+    sharedContext: opts.sharedContext,
+  });
+
+  // The custom done/give_up tools live alongside in MCP space.
+  const doneTool: Tool = {
+    name: 'done',
+    description:
+      'Call this when you have successfully completed the task. Triggers external verification of the artifacts. If verification fails, the result will list the issues and you should fix them and call done again.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        summary: { type: 'string', description: 'Brief summary of what was accomplished' },
+      },
+      required: ['summary'],
+    },
+  };
+  const giveUpTool: Tool = {
+    name: 'give_up',
+    description:
+      'Call this when you have encountered a categorical impossibility and cannot proceed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        reason: { type: 'string', description: 'Why you cannot complete the task' },
+        what_was_tried: {
+          type: 'string',
+          description: 'Summary of approaches you tried before giving up',
+        },
+      },
+      required: ['reason', 'what_was_tried'],
+    },
+  };
+
+  let verificationFailures = 0;
+
+  const server = new Server(
+    { name: 'imprint-compile', version: '0.1.0' },
+    {
+      capabilities: { tools: {} },
+      instructions:
+        'These tools let you reverse-engineer the captured session into workflow.json + parser.ts + parser.test.ts. Read the recording, write the artifacts, run tests, and call done() when verified. The done tool runs external verification and will tell you what to fix if anything is wrong.',
+    },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      ...compileTools.map(
+        (t): Tool => ({
+          name: t.name,
+          description: t.description,
+          inputSchema: t.input_schema as Tool['inputSchema'],
+        }),
+      ),
+      doneTool,
+      giveUpTool,
+    ],
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (req): Promise<CallToolResult> => {
+    const name = req.params.name;
+    const args = req.params.arguments ?? {};
+
+    // Custom done — runs verification inline.
+    if (name === 'done') {
+      const summary = (args as { summary?: string }).summary ?? 'Task completed';
+      log(`done() called: ${summary}`);
+      const { failures, warnings } = await externalVerification(
+        opts.toolDir,
+        session,
+        opts.sessionPath,
+        {
+          expectedToolName: opts.candidate?.toolName,
+          likelyParams: opts.candidate?.likelyParams,
+          candidateRequestSeqs: opts.candidate?.requestSeqs,
+        },
+      );
+      if (warnings.length > 0) {
+        log(`verification warnings (non-blocking):\n${warnings.join('\n')}`);
+      }
+      if (failures.length === 0) {
+        const sentinel = pathJoin(opts.toolDir, DONE_SENTINEL);
+        writeFileSync(
+          sentinel,
+          JSON.stringify(
+            { summary, verification: 'passed', warnings, timestamp: Date.now() },
+            null,
+            2,
+          ),
+          'utf8',
+        );
+        log(`verification passed; wrote ${sentinel}`);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: 'DONE_VERIFIED — verification passed. The orchestrator will exit shortly. Do not call any more tools.',
+            },
+          ],
+        };
+      }
+
+      verificationFailures++;
+      log(`verification failed (cycle ${verificationFailures}/${maxVerificationCycles})`);
+      if (verificationFailures >= maxVerificationCycles) {
+        const sentinel = pathJoin(opts.toolDir, DONE_SENTINEL);
+        writeFileSync(
+          sentinel,
+          JSON.stringify(
+            {
+              summary,
+              verification: 'failed',
+              cycles: verificationFailures,
+              failures,
+              warnings,
+              timestamp: Date.now(),
+            },
+            null,
+            2,
+          ),
+          'utf8',
+        );
+        return {
+          isError: true,
+          content: [
+            {
+              type: 'text',
+              text: `Verification failed after ${maxVerificationCycles} cycles. Giving up. Final failures:\n${failures.map((f) => `- ${f}`).join('\n')}`,
+            },
+          ],
+        };
+      }
+
+      const continuationMessage = `You called done but verification failed (cycle ${verificationFailures}/${maxVerificationCycles}):
+
+${failures.map((f) => `- ${f}`).join('\n')}
+
+Resume your work. Read the files you wrote (workflow.json, parser.ts, parser.test.ts), fix the issues, re-run tests, and call done again when fixed.`;
+      return {
+        isError: true,
+        content: [{ type: 'text', text: continuationMessage }],
+      };
+    }
+
+    // Custom give_up — writes sentinel and exits.
+    if (name === 'give_up') {
+      const reason = (args as { reason?: string }).reason ?? 'unknown';
+      const whatWasTried = (args as { what_was_tried?: string }).what_was_tried ?? '';
+      log(`give_up() called: ${reason}`);
+      const sentinel = pathJoin(opts.toolDir, GIVE_UP_SENTINEL);
+      writeFileSync(
+        sentinel,
+        JSON.stringify({ reason, what_was_tried: whatWasTried, timestamp: Date.now() }, null, 2),
+        'utf8',
+      );
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'GIVE_UP_RECORDED — the orchestrator will exit shortly. Do not call any more tools.',
+          },
+        ],
+      };
+    }
+
+    // Standard read/write tools — delegate to the shared handlers.
+    const tool = compileTools.find((t) => t.name === name);
+    if (!tool) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+      };
+    }
+
+    let result: { result: string; isError?: boolean };
+    try {
+      result = await tool.handler(args);
+    } catch (err) {
+      result = {
+        result: err instanceof Error ? err.message : String(err),
+        isError: true,
+      };
+    }
+
+    return {
+      content: [{ type: 'text', text: result.result }],
+      isError: result.isError ?? false,
+    };
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  log(`stdio transport ready (${compileTools.length + 2} tools)`);
+
+  // Block until the orchestrator closes us. Mirrors mcp-server.ts:230.
+  await new Promise<void>((resolve) => {
+    const close = (reason: string): void => {
+      log(`closing: ${reason}`);
+      resolve();
+    };
+    transport.onclose = () => close('client disconnected');
+    process.once('SIGINT', () => close('SIGINT'));
+    process.once('SIGTERM', () => close('SIGTERM'));
+  });
+}
+
+/** Sentinel file names exposed for the orchestrator to poll. */
+export const COMPILE_SENTINELS = {
+  done: DONE_SENTINEL,
+  giveUp: GIVE_UP_SENTINEL,
+} as const;