imprint-mcp 0.2.0

package/src/imprint/session-merge.ts

@@ -0,0 +1,198 @@
+/**
+ * Multi-session merge for `imprint teach`.
+ *
+ * When a user records a new session, they can combine it with past recordings
+ * of the same site so triage and candidate detection see the full picture.
+ * The merge produces a single valid Session object that the rest of the
+ * pipeline consumes unchanged.
+ */
+
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join as pathJoin } from 'node:path';
+import { localSessionsDir } from './paths.ts';
+import { friendlySessionTimestamp } from './teach-state.ts';
+import { type Session, SessionSchema } from './types.ts';
+
+/**
+ * Format an ISO timestamp string (e.g. "2026-05-24T09:00:00.000Z") into
+ * a human-readable form like "2026-05-24 09:00". Unlike friendlySessionTimestamp
+ * which expects the dashed filename format, this handles standard ISO colons.
+ */
+function friendlyIsoTimestamp(iso: string): string {
+  const m = iso.match(/(\d{4}-\d{2}-\d{2})T(\d{2})[:-](\d{2})/);
+  if (!m) return iso;
+  return `${m[1]} ${m[2]}:${m[3]}`;
+}
+
+interface SessionInfo {
+  absPath: string;
+  filename: string;
+  friendlyTimestamp: string;
+  requestCount: number;
+  narrationCount: number;
+  url: string;
+}
+
+export function listSiteSessions(site: string): SessionInfo[] {
+  const sessDir = localSessionsDir(site);
+  if (!existsSync(sessDir)) return [];
+
+  const files = readdirSync(sessDir).filter(
+    (f) =>
+      f.endsWith('.json') &&
+      !f.includes('.redacted') &&
+      !f.includes('.triaged') &&
+      !f.startsWith('combined-'),
+  );
+
+  const infos: SessionInfo[] = [];
+  for (const filename of files) {
+    const absPath = pathJoin(sessDir, filename);
+    try {
+      const raw = JSON.parse(readFileSync(absPath, 'utf8'));
+      const session = SessionSchema.parse(raw);
+      infos.push({
+        absPath,
+        filename,
+        friendlyTimestamp: friendlySessionTimestamp(filename),
+        requestCount: session.requests.length,
+        narrationCount: session.narration.length,
+        url: session.url,
+      });
+    } catch {
+      // Skip malformed sessions
+    }
+  }
+
+  infos.sort((a, b) => b.filename.localeCompare(a.filename));
+  return infos;
+}
+
+interface TaggedItem {
+  kind: 'request' | 'event' | 'narration';
+  absoluteTimestamp: number;
+  // biome-ignore lint/suspicious/noExplicitAny: union of different shapes
+  item: any;
+}
+
+export function mergeSessions(sessions: Session[]): Session {
+  if (sessions.length === 0) {
+    throw new Error('mergeSessions requires at least one session');
+  }
+  if (sessions.length === 1) {
+    const only = sessions[0] as Session;
+    return { ...only };
+  }
+
+  // Sort sessions chronologically by startedAt
+  const sorted = [...sessions].sort(
+    (a, b) => new Date(a.startedAt).getTime() - new Date(b.startedAt).getTime(),
+  );
+
+  const earliest = sorted[0] as Session;
+  const latest = sorted[sorted.length - 1] as Session;
+
+  const allItems: TaggedItem[] = [];
+
+  for (const session of sorted) {
+    const baseMs = new Date(session.startedAt).getTime();
+
+    // Synthetic boundary narration
+    allItems.push({
+      kind: 'narration',
+      absoluteTimestamp: baseMs,
+      item: {
+        seq: -1, // placeholder, will be reassigned
+        timestamp: 0,
+        text: `[Recording from ${friendlyIsoTimestamp(session.startedAt)}] ${session.url}`,
+      },
+    });
+
+    for (const request of session.requests) {
+      allItems.push({
+        kind: 'request',
+        absoluteTimestamp: baseMs + request.timestamp,
+        item: { ...request },
+      });
+    }
+
+    for (const event of session.events) {
+      allItems.push({
+        kind: 'event',
+        absoluteTimestamp: baseMs + event.timestamp,
+        item: { ...event },
+      });
+    }
+
+    for (const narration of session.narration) {
+      allItems.push({
+        kind: 'narration',
+        absoluteTimestamp: baseMs + narration.timestamp,
+        item: { ...narration },
+      });
+    }
+  }
+
+  // Sort by absolute timestamp, then by kind for stable ordering
+  const kindOrder = { narration: 0, event: 1, request: 2 };
+  allItems.sort(
+    (a, b) => a.absoluteTimestamp - b.absoluteTimestamp || kindOrder[a.kind] - kindOrder[b.kind],
+  );
+
+  // Reassign seq numbers monotonically
+  const earliestMs = new Date(earliest.startedAt).getTime();
+  const requests: Session['requests'] = [];
+  const events: Session['events'] = [];
+  const narration: Session['narration'] = [];
+
+  for (let seq = 0; seq < allItems.length; seq++) {
+    const tagged = allItems[seq] as TaggedItem;
+    const relativeTimestamp = tagged.absoluteTimestamp - earliestMs;
+
+    if (tagged.kind === 'request') {
+      requests.push({ ...tagged.item, seq, timestamp: relativeTimestamp });
+    } else if (tagged.kind === 'event') {
+      events.push({ ...tagged.item, seq, timestamp: relativeTimestamp });
+    } else {
+      narration.push({ ...tagged.item, seq, timestamp: relativeTimestamp });
+    }
+  }
+
+  // Merge cookie and storage snapshots
+  const cookieSnapshots = sorted.flatMap((s) => {
+    const baseMs = new Date(s.startedAt).getTime();
+    return s.cookieSnapshots.map((cs) => ({
+      ...cs,
+      timestamp: cs.timestamp + (baseMs - earliestMs),
+    }));
+  });
+
+  const storageSnapshots = sorted.flatMap((s) => {
+    const baseMs = new Date(s.startedAt).getTime();
+    return s.storageSnapshots.map((ss) => ({
+      ...ss,
+      timestamp: ss.timestamp + (baseMs - earliestMs),
+    }));
+  });
+
+  return {
+    site: earliest.site,
+    startedAt: earliest.startedAt,
+    url: latest.url,
+    imprintVersion: latest.imprintVersion,
+    requests,
+    events,
+    narration,
+    cookieSnapshots,
+    storageSnapshots,
+  };
+}
+
+export function writeCombinedSession(site: string, combined: Session): string {
+  const sessDir = localSessionsDir(site);
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const filename = `combined-${timestamp}.json`;
+  const absPath = pathJoin(sessDir, filename);
+  writeFileSync(absPath, `${JSON.stringify(combined, null, 2)}\n`, 'utf8');
+  return absPath;
+}

package/src/imprint/session-writer.ts

@@ -0,0 +1,149 @@
+/** JSONL streaming writer (crash-safe) + sidecar Session JSON on close. */
+
+import { type WriteStream, createWriteStream, mkdirSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import {
+  type CapturedEvent,
+  type CapturedRequest,
+  type CookieSnapshot,
+  type Narration,
+  type Session,
+  SessionSchema,
+  type StorageSnapshot,
+} from './types.ts';
+
+type Record =
+  | { kind: 'request'; data: CapturedRequest }
+  | { kind: 'event'; data: CapturedEvent }
+  | { kind: 'narration'; data: Narration }
+  | { kind: 'request-body'; data: { seq: number; body: string } }
+  | { kind: 'cookies'; data: CookieSnapshot }
+  | { kind: 'storage'; data: StorageSnapshot };
+
+interface SessionWriter {
+  request(req: CapturedRequest): void;
+  /** Late-arriving response body for a request already written. Merged on assemble. */
+  requestBody(seq: number, body: string): void;
+  event(ev: CapturedEvent): void;
+  narration(n: Narration): void;
+  cookies(snapshot: CookieSnapshot): void;
+  storage(snapshot: StorageSnapshot): void;
+  /** Flush + close the JSONL stream and write the assembled Session object. */
+  close(): Promise<{ jsonlPath: string; sessionPath: string }>;
+}
+
+interface SessionMeta {
+  site: string;
+  url: string;
+  imprintVersion: string;
+  startedAt: string;
+}
+
+export function createSessionWriter(jsonlPath: string, meta: SessionMeta): SessionWriter {
+  mkdirSync(dirname(jsonlPath), { recursive: true });
+  const stream: WriteStream = createWriteStream(jsonlPath, { flags: 'w', encoding: 'utf8' });
+
+  // First line: meta header so a partial JSONL still rehydrates.
+  stream.write(`${JSON.stringify({ kind: 'meta', data: meta })}\n`);
+
+  let closed = false;
+
+  const writeLine = (rec: Record): void => {
+    if (closed) return;
+    stream.write(`${JSON.stringify(rec)}\n`);
+  };
+
+  return {
+    request: (data) => writeLine({ kind: 'request', data }),
+    requestBody: (seq, body) => writeLine({ kind: 'request-body', data: { seq, body } }),
+    event: (data) => writeLine({ kind: 'event', data }),
+    narration: (data) => writeLine({ kind: 'narration', data }),
+    cookies: (data) => writeLine({ kind: 'cookies', data }),
+    storage: (data) => writeLine({ kind: 'storage', data }),
+    async close() {
+      if (closed) return { jsonlPath, sessionPath: jsonlPath.replace(/\.jsonl$/, '.json') };
+      closed = true;
+      await new Promise<void>((resolve, reject) => {
+        stream.end((err?: Error | null) => (err ? reject(err) : resolve()));
+      });
+
+      const session = assembleFromJsonl(jsonlPath);
+      const sessionPath = jsonlPath.replace(/\.jsonl$/, '.json');
+      const fs = await import('node:fs/promises');
+      await fs.writeFile(sessionPath, `${JSON.stringify(session, null, 2)}\n`, 'utf8');
+      return { jsonlPath, sessionPath };
+    },
+  };
+}
+
+/** Rehydrate a JSONL recording into a Session object. */
+export function assembleFromJsonl(jsonlPath: string): Session {
+  const text = readFileSync(jsonlPath, 'utf8');
+  const lines = text.split('\n').filter((line) => line.trim().length > 0);
+
+  let meta: SessionMeta | null = null;
+  const requests: CapturedRequest[] = [];
+  const events: CapturedEvent[] = [];
+  const narration: Narration[] = [];
+  const cookieSnapshots: CookieSnapshot[] = [];
+  const storageSnapshots: StorageSnapshot[] = [];
+
+  for (const line of lines) {
+    const rec = JSON.parse(line) as
+      | { kind: 'meta'; data: SessionMeta }
+      | { kind: 'request'; data: CapturedRequest }
+      | { kind: 'request-body'; data: { seq: number; body: string } }
+      | { kind: 'event'; data: CapturedEvent }
+      | { kind: 'narration'; data: Narration }
+      | { kind: 'cookies'; data: CookieSnapshot }
+      | { kind: 'storage'; data: StorageSnapshot };
+
+    switch (rec.kind) {
+      case 'meta':
+        meta = rec.data;
+        break;
+      case 'request':
+        requests.push(rec.data);
+        break;
+      case 'request-body': {
+        const target = requests.find((r) => r.seq === rec.data.seq);
+        if (target?.response) {
+          target.response = { ...target.response, body: rec.data.body };
+        }
+        break;
+      }
+      case 'event':
+        events.push(rec.data);
+        break;
+      case 'narration':
+        narration.push(rec.data);
+        break;
+      case 'cookies':
+        cookieSnapshots.push(rec.data);
+        break;
+      case 'storage':
+        storageSnapshots.push(rec.data);
+        break;
+    }
+  }
+
+  if (!meta) {
+    throw new Error(
+      `Session JSONL ${jsonlPath} has no meta header — cannot rehydrate.\n→ this usually means recording was killed before the first event fired; re-record.`,
+    );
+  }
+
+  const session: Session = {
+    site: meta.site,
+    startedAt: meta.startedAt,
+    url: meta.url,
+    imprintVersion: meta.imprintVersion,
+    requests,
+    events,
+    narration,
+    cookieSnapshots,
+    storageSnapshots,
+  };
+
+  return SessionSchema.parse(session); // fail loud if malformed
+}

package/src/imprint/sites.ts

@@ -0,0 +1,27 @@
+/** Site-discovery helpers shared by verbs that take a <site> arg.
+ *  When a verb gets a site name it doesn't recognize, list what's
+ *  actually under the generated asset root so the user can spot a typo. */
+
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { resolve as pathResolve } from 'node:path';
+
+/** List the configured sites under the asset root to suggest in error messages.
+ *  Returns a single line starting with "→" for inclusion in a multi-line
+ *  Error message. Always returns *something* (so callers can concat
+ *  unconditionally). */
+export function availableSitesHint(assetRoot: string, badSite: string): string {
+  if (!existsSync(assetRoot)) {
+    return `→ generated asset root doesn't exist at ${assetRoot} — run \`imprint teach <site>\` or \`imprint emit <workflow.json>\` to create a generated tool.`;
+  }
+  const sites = readdirSync(assetRoot).filter((d) => {
+    try {
+      return statSync(pathResolve(assetRoot, d)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+  if (sites.length === 0) {
+    return `→ generated asset root is empty at ${assetRoot} — run \`imprint teach <site>\` or \`imprint emit <workflow.json>\` to create a generated tool.`;
+  }
+  return `→ available sites: ${sites.join(', ')} (you asked for "${badSite}").`;
+}