imprint-mcp 0.4.0 → 0.4.2

package/src/imprint/probe-backends.ts

@@ -7,8 +7,9 @@
 
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { resolve as pathResolve } from 'node:path';
+import { basename, resolve as pathResolve } from 'node:path';
 import { runWithLadder } from './backend-ladder.ts';
+import type { CdpBrowserFetch } from './cdp-browser-fetch.ts';
 import { createLog } from './log.ts';
 import { imprintHomeDir } from './paths.ts';
 import { availableSitesHint } from './sites.ts';
@@ -42,6 +43,41 @@ interface ProbeBackendsResult {
 }
 
 const log = createLog('probe');
+const DEFAULT_PREFERRED_MAX_MS = 90_000;
+
+type BackendProbeCandidate = {
+  backend: ConcreteBackend;
+  durationMs: number;
+  rankingDurationMs?: number;
+  coldDurationMs?: number;
+  warmDurationMs?: number;
+  tooSlow: boolean;
+};
+
+type BackendRuntimeAttempt = {
+  backend: ConcreteBackend;
+  outcome: 'ok' | 'escalate' | 'failed' | 'unavailable';
+  detail: string;
+  durationMs: number;
+};
+
+export type BackendsCacheStatus =
+  | {
+      status: 'missing';
+      path: string | null;
+      remediation: string;
+    }
+  | {
+      status: 'ok';
+      path: string;
+      cache: BackendsCache;
+    }
+  | {
+      status: 'stale' | 'invalid';
+      path: string;
+      reason: string;
+      remediation: string;
+    };
 
 export async function probeBackends(opts: ProbeBackendsOptions): Promise<ProbeBackendsResult> {
   const assetRoot = opts.assetRoot ?? imprintHomeDir();
@@ -59,7 +95,36 @@ export async function probeBackends(opts: ProbeBackendsOptions): Promise<ProbeBa
       `No generated tool found for site "${opts.site}".\n${availableSitesHint(assetRoot, opts.site)}\n→ run \`imprint teach ${opts.site}\` or \`imprint emit ~/.imprint/${opts.site}/<toolName>/workflow.json\` first.`,
     );
   }
-  const outPath = opts.outPath ?? pathResolve(tool.dir, 'backends.json');
+  return await probeResolvedTool(opts, assetRoot, tool, opts.outPath);
+}
+
+export async function probeAllBackends(
+  opts: Omit<ProbeBackendsOptions, 'outPath' | 'toolName'>,
+): Promise<ProbeBackendsResult[]> {
+  const assetRoot = opts.assetRoot ?? imprintHomeDir();
+  const discovered = await discoverTools(assetRoot, opts.site, '[imprint probe]');
+  if (discovered.length === 0) {
+    throw new Error(
+      `No generated tools found for site "${opts.site}".\n${availableSitesHint(assetRoot, opts.site)}\n→ run \`imprint teach ${opts.site}\` or \`imprint emit ~/.imprint/${opts.site}/<toolName>/workflow.json\` first.`,
+    );
+  }
+
+  const results: ProbeBackendsResult[] = [];
+  for (const tool of [...discovered].sort((a, b) =>
+    a.workflow.toolName.localeCompare(b.workflow.toolName),
+  )) {
+    results.push(await probeResolvedTool(opts, assetRoot, tool));
+  }
+  return results;
+}
+
+async function probeResolvedTool(
+  opts: Pick<ProbeBackendsOptions, 'site' | 'paramOverrides'>,
+  assetRoot: string,
+  tool: ResolvedTool,
+  explicitOutPath?: string,
+): Promise<ProbeBackendsResult> {
+  const outPath = explicitOutPath ?? pathResolve(tool.dir, 'backends.json');
 
   const params = resolveParams(tool, opts.paramOverrides);
 
@@ -72,59 +137,96 @@ export async function probeBackends(opts: ProbeBackendsOptions): Promise<ProbeBa
   // falls through fetch-bootstrap (~30-60s) before reaching the spliced-in
   // cdp-replay rung, wasting time on every call.
   const stealthCache = new Map<string, StealthFetch>();
+  const cdpPool = new Map<string, CdpBrowserFetch>();
   const allBackends: ConcreteBackend[] = workflowNeedsBootstrap(tool.workflow)
     ? ['fetch', 'fetch-bootstrap', 'cdp-replay', 'stealth-fetch', 'playbook']
     : ['fetch', 'stealth-fetch', 'playbook'];
   const results: BackendsCache['results'] = {};
-  const working: ConcreteBackend[] = [];
-
-  for (const backend of allBackends) {
-    log(`probing ${backend}…`);
-    const t0 = Date.now();
-    const { result, attempts } = await runWithLadder(
-      [backend],
-      tool,
-      params,
-      assetRoot,
-      stealthCache,
-    );
-    const durationMs = Date.now() - t0;
-    const attempt = attempts[0];
+  const working: BackendProbeCandidate[] = [];
+  const preferredMaxMs = preferredBackendMaxMs();
 
-    if (!attempt) {
-      results[backend] = { outcome: 'skipped', detail: 'no attempt recorded' };
-      continue;
-    }
+  try {
+    for (const backend of allBackends) {
+      log(`probing ${backend}…`);
+      const t0 = Date.now();
+      const { result, attempts } = await runWithLadder(
+        [backend],
+        tool,
+        params,
+        assetRoot,
+        stealthCache,
+        backend === 'cdp-replay' ? { cdpPool, skipBootstrapSplice: true } : undefined,
+      );
+      const durationMs = Date.now() - t0;
+      const attempt = attempts[0];
 
-    if (attempt.outcome === 'unavailable') {
-      results[backend] = { outcome: 'unavailable', detail: attempt.detail };
-      log(`  ${backend}: unavailable (${attempt.detail})`);
-      continue;
-    }
+      if (!attempt) {
+        results[backend] = { outcome: 'skipped', detail: 'no attempt recorded' };
+        continue;
+      }
 
-    if (result.ok) {
-      results[backend] = { outcome: 'ok', durationMs };
-      working.push(backend);
-      log(`  ${backend}: OK in ${durationMs}ms`);
-      continue;
-    }
+      if (attempt.outcome === 'unavailable') {
+        results[backend] = { outcome: 'unavailable', detail: attempt.detail };
+        log(`  ${backend}: unavailable (${attempt.detail})`);
+        continue;
+      }
 
-    if (result.error === 'FORBIDDEN') {
-      results[backend] = {
-        outcome: 'forbidden',
-        durationMs,
-        detail: result.message.slice(0, 200),
-      };
-      log(`  ${backend}: FORBIDDEN`);
-    } else {
-      results[backend] = {
-        outcome: 'failed',
-        durationMs,
-        error: result.error,
-        detail: result.message.slice(0, 200),
-      };
-      log(`  ${backend}: ${result.error} — ${result.message.slice(0, 100)}`);
+      if (result.ok) {
+        const warm =
+          backend === 'cdp-replay'
+            ? await probeWarmCdpReplay(tool, params, assetRoot, stealthCache, cdpPool)
+            : null;
+        const tooSlow = durationMs > preferredMaxMs;
+        const rankingDurationMs = warm?.ok ? warm.durationMs : durationMs;
+        const detailParts: string[] = [];
+        if (tooSlow)
+          detailParts.push(`cold start exceeded preferred backend threshold ${preferredMaxMs}ms`);
+        if (warm?.ok) detailParts.push(`warm cdp-replay succeeded in ${warm.durationMs}ms`);
+        else if (warm) detailParts.push(`warm cdp-replay failed: ${warm.detail}`);
+        results[backend] = {
+          outcome: 'ok',
+          durationMs,
+          ...(backend === 'cdp-replay'
+            ? {
+                coldDurationMs: durationMs,
+                ...(warm?.ok ? { warmDurationMs: warm.durationMs, rankingDurationMs } : {}),
+              }
+            : {}),
+          ...(tooSlow ? { tooSlow: true } : {}),
+          ...(detailParts.length ? { detail: detailParts.join('; ') } : {}),
+        };
+        working.push({
+          backend,
+          durationMs,
+          ...(backend === 'cdp-replay' ? { coldDurationMs: durationMs } : {}),
+          ...(warm?.ok ? { warmDurationMs: warm.durationMs, rankingDurationMs } : {}),
+          tooSlow,
+        });
+        log(
+          `  ${backend}: OK in ${durationMs}ms${warm?.ok ? ` (warm ${warm.durationMs}ms)` : ''}${tooSlow ? ' (cold slow)' : ''}`,
+        );
+        continue;
+      }
+
+      if (result.error === 'FORBIDDEN') {
+        results[backend] = {
+          outcome: 'forbidden',
+          durationMs,
+          detail: result.message.slice(0, 200),
+        };
+        log(`  ${backend}: FORBIDDEN`);
+      } else {
+        results[backend] = {
+          outcome: 'failed',
+          durationMs,
+          error: result.error,
+          detail: result.message.slice(0, 200),
+        };
+        log(`  ${backend}: ${result.error} — ${result.message.slice(0, 100)}`);
+      }
     }
+  } finally {
+    await closeProbeCdpPool(cdpPool);
   }
 
   if (working.length === 0) {
@@ -135,23 +237,71 @@ export async function probeBackends(opts: ProbeBackendsOptions): Promise<ProbeBa
     );
   }
 
+  const preferredOrder = rankSuccessfulBackends(working);
   const cache: BackendsCache = {
     probedAt: new Date().toISOString(),
     imprintVersion: VERSION,
     schemaVersion: 2,
     workflowHash: workflowHash(tool.workflow),
     capabilityHash: capabilityHash(tool.workflow),
-    preferredOrder: working,
+    preferredOrder,
     results,
   };
   BackendsCacheSchema.parse(cache); // catch schema drift early
 
   writeFileSync(outPath, `${JSON.stringify(cache, null, 2)}\n`);
-  log(`wrote ${outPath} — preferred: ${working.join(' → ')}`);
+  log(`wrote ${outPath} — preferred: ${preferredOrder.join(' → ')}`);
 
   return { cache, outPath };
 }
 
+export function rankSuccessfulBackends(candidates: BackendProbeCandidate[]): ConcreteBackend[] {
+  return [...candidates]
+    .sort((a, b) => {
+      if (a.tooSlow !== b.tooSlow) return a.tooSlow ? 1 : -1;
+      return effectiveRankingDuration(a) - effectiveRankingDuration(b);
+    })
+    .map((c) => c.backend);
+}
+
+function effectiveRankingDuration(candidate: BackendProbeCandidate): number {
+  return candidate.rankingDurationMs ?? candidate.warmDurationMs ?? candidate.durationMs;
+}
+
+function backendResultTooSlow(result: BackendsCache['results'][string] | undefined): boolean {
+  return result?.outcome === 'ok' && result.tooSlow === true;
+}
+
+async function probeWarmCdpReplay(
+  tool: ResolvedTool,
+  params: Record<string, string | number | boolean>,
+  assetRoot: string,
+  stealthCache: Map<string, StealthFetch>,
+  cdpPool: Map<string, CdpBrowserFetch>,
+): Promise<{ ok: true; durationMs: number } | { ok: false; detail: string } | null> {
+  if (!cdpPool.has(tool.site)) return null;
+  log('probing cdp-replay warm reuse…');
+  const t0 = Date.now();
+  const { result } = await runWithLadder(['cdp-replay'], tool, params, assetRoot, stealthCache, {
+    cdpPool,
+    skipBootstrapSplice: true,
+  });
+  const durationMs = Date.now() - t0;
+  if (result.ok) return { ok: true, durationMs };
+  return { ok: false, detail: `${result.error}: ${result.message.slice(0, 160)}` };
+}
+
+async function closeProbeCdpPool(cdpPool: Map<string, CdpBrowserFetch>): Promise<void> {
+  const sessions = [...cdpPool.values()];
+  cdpPool.clear();
+  await Promise.allSettled(sessions.map((session) => session.close()));
+}
+
+function preferredBackendMaxMs(): number {
+  const raw = Number(process.env.IMPRINT_BACKEND_PREFERRED_MAX_MS ?? DEFAULT_PREFERRED_MAX_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_PREFERRED_MAX_MS;
+}
+
 function workflowNeedsBootstrap(workflow: ResolvedTool['workflow']): boolean {
   if (workflow.bootstrap) return true;
   return workflow.requests.some((r) =>
@@ -177,16 +327,19 @@ function capabilityHash(workflow: ResolvedTool['workflow']): string {
   return createHash('sha256').update(JSON.stringify(caps)).digest('hex');
 }
 
-/** Read backends.json. Returns null on missing/malformed — runtime
- *  falls back to the default ladder; a stale cache must never break cron. */
-export function loadBackendsCache(
+/** Read backends.json with status information. Runtime can still fall back to
+ *  the default ladder, while status commands can explain why a cache was not
+ *  usable. */
+export function loadBackendsCacheStatus(
   site: string,
   _assetRoot: string,
   toolDir?: string,
-): BackendsCache | null {
-  if (!toolDir) return null;
+  opts: { warn?: boolean; toolName?: string } = {},
+): BackendsCacheStatus {
+  const remediation = backendsCacheRemediation(site, opts.toolName ?? toolDirName(toolDir));
+  if (!toolDir) return { status: 'missing', path: null, remediation };
   const path = pathResolve(toolDir, 'backends.json');
-  if (!existsSync(path)) return null;
+  if (!existsSync(path)) return { status: 'missing', path, remediation };
   try {
     const raw = JSON.parse(readFileSync(path, 'utf8'));
     const parsed = BackendsCacheSchema.parse(raw);
@@ -195,20 +348,129 @@ export function loadBackendsCache(
       if (existsSync(workflowPath)) {
         const currentHash = workflowHashSync(readFileSync(workflowPath, 'utf8'));
         if (currentHash !== parsed.workflowHash) {
-          process.stderr.write(
-            `[imprint] backends.json at ${path} is stale for current workflow — ignoring (run \`imprint probe-backends ${site}\` to regenerate)\n`,
-          );
-          return null;
+          const reason = 'workflow hash changed';
+          if (opts.warn !== false) {
+            process.stderr.write(
+              `[imprint] backends.json at ${path} is stale for current workflow — ignoring (run \`${remediation}\` to regenerate)\n`,
+            );
+          }
+          return { status: 'stale', path, reason, remediation };
         }
       }
     }
-    return parsed;
+    return { status: 'ok', path, cache: parsed };
   } catch (err) {
-    process.stderr.write(
-      `[imprint] backends.json at ${path} failed to parse — ignoring (run \`imprint probe-backends ${site}\` to regenerate): ${err instanceof Error ? err.message : String(err)}\n`,
-    );
-    return null;
+    const reason = err instanceof Error ? err.message : String(err);
+    if (opts.warn !== false) {
+      process.stderr.write(
+        `[imprint] backends.json at ${path} failed to parse — ignoring (run \`${remediation}\` to regenerate): ${reason}\n`,
+      );
+    }
+    return { status: 'invalid', path, reason, remediation };
+  }
+}
+
+/** Read backends.json. Returns null on missing/malformed — runtime
+ *  falls back to the default ladder; a stale cache must never break cron. */
+export function loadBackendsCache(
+  site: string,
+  _assetRoot: string,
+  toolDir?: string,
+): BackendsCache | null {
+  const status = loadBackendsCacheStatus(site, _assetRoot, toolDir);
+  return status.status === 'ok' ? status.cache : null;
+}
+
+export function persistRuntimeBackendsCache(opts: {
+  tool: ResolvedTool;
+  assetRoot: string;
+  usedBackend: ConcreteBackend;
+  attempts: BackendRuntimeAttempt[];
+}): BackendsCache | null {
+  const status = loadBackendsCacheStatus(opts.tool.site, opts.assetRoot, opts.tool.dir, {
+    warn: false,
+    toolName: opts.tool.workflow.toolName,
+  });
+  const results: BackendsCache['results'] =
+    status.status === 'ok' ? { ...status.cache.results } : {};
+
+  for (const attempt of opts.attempts) {
+    if (attempt.outcome === 'ok') {
+      const tooSlow = attempt.durationMs > preferredBackendMaxMs();
+      results[attempt.backend] = {
+        outcome: 'ok',
+        durationMs: attempt.durationMs,
+        ...(tooSlow
+          ? {
+              tooSlow: true,
+              detail: `exceeded preferred backend threshold ${preferredBackendMaxMs()}ms`,
+            }
+          : {}),
+      };
+    } else if (attempt.outcome === 'unavailable') {
+      results[attempt.backend] = { outcome: 'unavailable', detail: attempt.detail };
+    } else if (attempt.detail.startsWith('FORBIDDEN:')) {
+      results[attempt.backend] = {
+        outcome: 'forbidden',
+        durationMs: attempt.durationMs,
+        detail: attempt.detail.slice(0, 200),
+      };
+    } else {
+      const error = attempt.detail.split(':')[0] || 'UNKNOWN';
+      results[attempt.backend] = {
+        outcome: 'failed',
+        durationMs: attempt.durationMs,
+        error,
+        detail: attempt.detail.slice(0, 200),
+      };
+    }
   }
+
+  const existingPreferred = status.status === 'ok' ? status.cache.preferredOrder : [];
+  const observedOkAttempts = opts.attempts
+    .filter((a) => a.outcome === 'ok')
+    .sort((a, b) => a.durationMs - b.durationMs);
+  const observedOk = observedOkAttempts.map((a) => a.backend);
+  const slowObservedOk = observedOkAttempts
+    .filter((a) => a.durationMs > preferredBackendMaxMs())
+    .map((a) => a.backend);
+  const fastObservedOk = observedOk.filter((backend) => !slowObservedOk.includes(backend));
+  const usedOkAttempt = observedOkAttempts.find((a) => a.backend === opts.usedBackend);
+  const usedBackendTooSlow =
+    usedOkAttempt !== undefined && usedOkAttempt.durationMs > preferredBackendMaxMs();
+  const existingFast = existingPreferred.filter(
+    (backend) => !backendResultTooSlow(results[backend]),
+  );
+  const existingSlow = existingPreferred.filter((backend) =>
+    backendResultTooSlow(results[backend]),
+  );
+  const structuralFallbacks: ConcreteBackend[] = existsSync(
+    pathResolve(opts.tool.dir, 'playbook.yaml'),
+  )
+    ? ['playbook']
+    : [];
+  const preferredOrder = uniqueBackends([
+    ...(usedOkAttempt && !usedBackendTooSlow ? [opts.usedBackend] : []),
+    ...existingFast,
+    ...fastObservedOk,
+    ...existingSlow,
+    ...slowObservedOk,
+    ...(usedOkAttempt && usedBackendTooSlow ? [opts.usedBackend] : []),
+    ...structuralFallbacks,
+  ]);
+  const cache: BackendsCache = {
+    probedAt: new Date().toISOString(),
+    imprintVersion: VERSION,
+    schemaVersion: 2,
+    workflowHash: workflowHash(opts.tool.workflow),
+    capabilityHash: capabilityHash(opts.tool.workflow),
+    preferredOrder,
+    results,
+  };
+
+  BackendsCacheSchema.parse(cache);
+  writeFileSync(pathResolve(opts.tool.dir, 'backends.json'), `${JSON.stringify(cache, null, 2)}\n`);
+  return cache;
 }
 
 function workflowHashSync(workflowJson: string): string {
@@ -217,6 +479,27 @@ function workflowHashSync(workflowJson: string): string {
     .digest('hex');
 }
 
+function backendsCacheRemediation(site: string, toolName?: string): string {
+  return toolName
+    ? `imprint probe-backends ${site} --tool ${toolName}`
+    : `imprint probe-backends ${site}`;
+}
+
+function toolDirName(toolDir?: string): string | undefined {
+  return toolDir ? basename(toolDir) : undefined;
+}
+
+function uniqueBackends(backends: ConcreteBackend[]): ConcreteBackend[] {
+  const seen = new Set<ConcreteBackend>();
+  const out: ConcreteBackend[] = [];
+  for (const backend of backends) {
+    if (seen.has(backend)) continue;
+    seen.add(backend);
+    out.push(backend);
+  }
+  return out;
+}
+
 /** Param priority: caller overrides → cron.json → workflow defaults. */
 function resolveParams(
   tool: ResolvedTool,

package/src/imprint/types.ts

@@ -380,6 +380,18 @@ const BackendProbeResultSchema = z.discriminatedUnion('outcome', [
   z.object({
     outcome: z.literal('ok'),
     durationMs: z.number(),
+    /** Optional cdp-replay cold-start measurement. `durationMs` remains the
+     *  first-call duration for backward compatibility. */
+    coldDurationMs: z.number().optional(),
+    /** Optional cdp-replay warm-pool measurement from a second call against the
+     *  same pooled Chrome. Used to explain why CDP may outrank stealth when its
+     *  cold start is still under the operator timeout. */
+    warmDurationMs: z.number().optional(),
+    /** Effective duration used for preference ranking when it differs from the
+     *  first-call duration, e.g. warm cdp-replay. */
+    rankingDurationMs: z.number().optional(),
+    tooSlow: z.boolean().optional(),
+    detail: z.string().optional(),
   }),
   z.object({
     outcome: z.literal('forbidden'),

package/src/imprint/update.ts

@@ -0,0 +1,73 @@
+import { spawnSync } from 'node:child_process';
+import semver from 'semver';
+import { VERSION } from './version.ts';
+
+const PACKAGE_NAME = 'imprint-mcp';
+const REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+
+interface UpdateCheckResult {
+  current: string;
+  latest: string;
+  updateAvailable: boolean;
+}
+
+interface UpdateResult {
+  ok: boolean;
+  from: string;
+  to: string;
+  error?: string;
+}
+
+export async function checkForUpdate(): Promise<UpdateCheckResult | null> {
+  try {
+    const res = await fetch(REGISTRY_URL, {
+      headers: { accept: 'application/json' },
+      signal: AbortSignal.timeout(5_000),
+    });
+    if (!res.ok) return null;
+    const data = (await res.json()) as { version?: string };
+    const latest = data.version;
+    if (!latest) return null;
+    return { current: VERSION, latest, updateAvailable: semver.gt(latest, VERSION) };
+  } catch {
+    return null;
+  }
+}
+
+const IS_COMPILED = typeof (globalThis as Record<string, unknown>).__IMPRINT_VERSION__ === 'string';
+
+export async function performUpdate(): Promise<UpdateResult> {
+  const check = await checkForUpdate();
+  if (!check) {
+    return { ok: false, from: VERSION, to: VERSION, error: 'could not reach npm registry' };
+  }
+  if (!check.updateAvailable) {
+    return { ok: true, from: VERSION, to: VERSION };
+  }
+
+  const result = IS_COMPILED
+    ? spawnSync(
+        'bash',
+        [
+          '-c',
+          'curl -fsSL https://raw.githubusercontent.com/ashaychangwani/imprint/main/scripts/install.sh | bash',
+        ],
+        { stdio: 'pipe', timeout: 60_000 },
+      )
+    : spawnSync('bun', ['install', '-g', `${PACKAGE_NAME}@latest`], {
+        stdio: 'pipe',
+        timeout: 60_000,
+      });
+
+  if (result.status !== 0) {
+    const stderr = result.stderr?.toString().trim();
+    return {
+      ok: false,
+      from: check.current,
+      to: check.latest,
+      error: stderr || result.error?.message || `install exited with code ${result.status}`,
+    };
+  }
+
+  return { ok: true, from: check.current, to: check.latest };
+}