imprint-mcp 0.4.0 → 0.4.2

package/README.md

@@ -180,6 +180,8 @@ When an API call gets blocked, Imprint doesn't jump to DOM replay. It escalates
 
 The full order is `fetch → fetch-bootstrap → cdp-replay → stealth-fetch → playbook`; `auto` mode walks it and stops at the first backend that works.
 
+For bot-protected sites, `imprint probe-backends <site> --tool <toolName>` writes a `backends.json` preference cache so cron and MCP start from the known-good backend instead of rediscovering blocked rungs. Use `imprint probe-backends <site> --all` to refresh every tool in a multi-tool site; `imprint mcp status` reports stale or invalid backend caches before they quietly fall back to the default ladder. CDP replay records both cold and warm timings when it succeeds: a timeout-safe cold start may rank by its fast warm runtime, but a cold start above the preferred threshold stays behind cold-safe backends in durable cache order.
+
 Every recording compiles to *both* `workflow.json` and `playbook.yaml`, so the ladder always has a DOM fallback.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imprint-mcp",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Teach an AI agent how to use any website. Once. Records a real browser session + narration; generates a deterministic MCP tool plus a DOM-replay playbook fallback.",
   "type": "module",
   "exports": {
@@ -63,6 +63,7 @@
     "playwright-extra": "^4.3.6",
     "puppeteer-extra-plugin-stealth": "^2.11.2",
     "redactum": "^1.1.0",
+    "semver": "^7.8.4",
     "yaml": "^2.8.4",
     "zod": "^3.24.0"
   },
@@ -72,6 +73,7 @@
     "@types/chrome-remote-interface": "^0.31.14",
     "@types/node": "^22.10.0",
     "@types/node-cron": "^3.0.11",
+    "@types/semver": "^7.7.1",
     "knip": "^5.0.0",
     "madge": "^8.0.0",
     "typescript": "^5.7.0"

package/src/cli.ts

@@ -346,9 +346,13 @@ export const VERB_HELP: Record<string, VerbHelp> = {
   },
   'probe-backends': {
     summary: 'Try each backend once and cache the working order to backends.json.',
-    usage: ['imprint probe-backends <site> [--tool <toolName>] [--out <path>] [--param k=v]…'],
+    usage: [
+      'imprint probe-backends <site> [--tool <toolName>] [--out <path>] [--param k=v]…',
+      'imprint probe-backends <site> --all [--param k=v]…',
+    ],
     flags: [
       { name: '--tool <toolName>', description: 'Select a generated tool for multi-tool sites.' },
+      { name: '--all', description: 'Probe every generated tool for the site.' },
       { name: '--out <path>', description: 'Override backends.json output path.' },
       { name: '--param k=v', description: 'Override a workflow parameter (repeatable).' },
     ],
@@ -451,6 +455,17 @@ export const VERB_HELP: Record<string, VerbHelp> = {
     ],
     example: 'imprint mcp status',
   },
+  update: {
+    summary: 'Check for updates and install the latest version of imprint.',
+    usage: ['imprint update [--check]'],
+    flags: [
+      {
+        name: '--check',
+        description: 'Only check whether an update is available; do not install.',
+      },
+    ],
+    example: 'imprint update',
+  },
 };
 
 function printVerbHelp(verb: string): void {
@@ -621,7 +636,7 @@ async function main(argv: string[]): Promise<number> {
 
     case 'doctor': {
       const { doctor, reportDoctor } = await import('./imprint/doctor.ts');
-      const report = reportDoctor(doctor());
+      const report = reportDoctor(await doctor());
       for (const line of report.lines) console.log(line);
       return report.ok ? 0 : 1;
     }
@@ -1201,6 +1216,7 @@ async function main(argv: string[]): Promise<number> {
       const { values } = parseArgs({
         args: argv.slice(2),
         options: {
+          all: { type: 'boolean' },
           out: { type: 'string' },
           tool: { type: 'string' },
           param: { type: 'string', multiple: true },
@@ -1209,7 +1225,30 @@ async function main(argv: string[]): Promise<number> {
       });
       const overrides = tryParseParamKV(values.param);
       if (overrides === null) return 2;
-      const { probeBackends } = await import('./imprint/probe-backends.ts');
+      if (values.all && values.tool) {
+        console.error('error: --all cannot be combined with --tool');
+        return 2;
+      }
+      if (values.all && values.out) {
+        console.error('error: --all cannot be combined with --out');
+        return 2;
+      }
+      const { probeAllBackends, probeBackends } = await import('./imprint/probe-backends.ts');
+      if (values.all) {
+        const results = await probeAllBackends({
+          site,
+          paramOverrides: Object.keys(overrides).length > 0 ? overrides : undefined,
+        });
+        for (const result of results) {
+          console.log(`[imprint] probed → ${result.outPath}`);
+          console.log(`[imprint] preferred order: ${result.cache.preferredOrder.join(' → ')}`);
+        }
+        console.log('');
+        console.log(
+          '[imprint] cron + mcp-server now skip futile rungs at startup using these caches.',
+        );
+        return 0;
+      }
       const result = await probeBackends({
         site,
         outPath: values.out,
@@ -1482,6 +1521,38 @@ async function main(argv: string[]): Promise<number> {
       return 0;
     }
 
+    case 'update': {
+      const { checkForUpdate, performUpdate } = await import('./imprint/update.ts');
+      const checkOnly = argv.slice(1).includes('--check');
+      if (checkOnly) {
+        const result = await checkForUpdate();
+        if (!result) {
+          console.error('Could not reach npm registry.');
+          return 1;
+        }
+        console.log(`Current: v${result.current}`);
+        console.log(`Latest:  v${result.latest}`);
+        if (result.updateAvailable) {
+          console.log('\nUpdate available — run `imprint update` to install.');
+        } else {
+          console.log('\nAlready up to date.');
+        }
+        return 0;
+      }
+      console.log('Checking for updates...');
+      const result = await performUpdate();
+      if (result.from === result.to && result.ok) {
+        console.log(`imprint v${result.from} is already the latest version.`);
+        return 0;
+      }
+      if (result.ok) {
+        console.log(`Updated imprint: v${result.from} → v${result.to}`);
+        return 0;
+      }
+      console.error(`Update failed: ${result.error}`);
+      return 1;
+    }
+
     default: {
       const suggestion = closestVerb(verb);
       const tail = suggestion ? `did you mean \`imprint ${suggestion}\`?` : 'run `imprint --help`';

package/src/imprint/backend-ladder.ts

@@ -181,6 +181,20 @@ const compileLastRequestAt = new Map<string, number>();
 function sleepMs(ms: number): Promise<void> {
   return new Promise((r) => setTimeout(r, ms));
 }
+
+function withWorkflowDefaults(
+  workflow: Workflow,
+  params: Record<string, string | number | boolean>,
+): Record<string, string | number | boolean> {
+  const paramsWithDefaults: Record<string, string | number | boolean> = { ...params };
+  for (const p of workflow.parameters) {
+    if (!(p.name in paramsWithDefaults) && p.default !== undefined) {
+      paramsWithDefaults[p.name] = p.default;
+    }
+  }
+  return paramsWithDefaults;
+}
+
 /** Await the per-origin min spacing before a compile-path live request. The
  *  first call to an origin never waits (last=0); subsequent ones within the
  *  window are delayed so the suite paces itself under the rate-flag. */
@@ -303,7 +317,8 @@ export async function runWithLadder(
           result = await runCdpReplay(tool, params, options?.cdpPool);
           break;
         case 'stealth-fetch': {
-          const sf = ensureStealthFetch(tool, stealthCache);
+          const paramsWithDefaults = withWorkflowDefaults(tool.workflow, params);
+          const sf = await ensureStealthFetch(tool, stealthCache, paramsWithDefaults);
           // When the workflow declares a bootstrap block, mint its declared
           // session-token state (CSRF cookies etc.) from the SAME stealth
           // session that provides the transport cookies. Without this, a
@@ -313,19 +328,14 @@ export async function runWithLadder(
           const initialState = tool.workflow.bootstrap
             ? await stealthBootstrapState(sf, tool.workflow.bootstrap)
             : undefined;
-          result = await tool.toolFn(params, { fetchImpl: sf.fetchImpl, initialState });
+          result = await tool.toolFn(paramsWithDefaults, { fetchImpl: sf.fetchImpl, initialState });
           break;
         }
         case 'playbook': {
           // DOM-walk last resort (the anti-bot API path is fetch-bootstrap, above).
           // Apply workflow.json's declared parameter defaults — runPlaybook
           // validates and throws on absent values regardless of declared defaults.
-          const paramsWithDefaults: typeof params = { ...params };
-          for (const p of tool.workflow.parameters) {
-            if (!(p.name in paramsWithDefaults) && p.default !== undefined) {
-              paramsWithDefaults[p.name] = p.default;
-            }
-          }
+          const paramsWithDefaults = withWorkflowDefaults(tool.workflow, params);
           result = await runPlaybook({
             playbook: playbookPath(assetRoot, tool.site, tool.dir),
             params: paramsWithDefaults,
@@ -726,8 +736,9 @@ async function runFetchBootstrap(
     values: {},
     storage: [],
   };
+  const paramsWithDefaults = withWorkflowDefaults(tool.workflow, params);
   const bootstrapUrl = tool.workflow.bootstrap
-    ? substituteString(tool.workflow.bootstrap.url, params, credentials, [])
+    ? substituteString(tool.workflow.bootstrap.url, paramsWithDefaults, credentials, [])
     : undefined;
   const siteDir = pathResolve(tool.dir, '..');
 
@@ -799,7 +810,7 @@ async function runFetchBootstrap(
     );
     if (!captureResult.ok) return captureResult.result;
 
-    const result = await tool.toolFn(params, {
+    const result = await tool.toolFn(paramsWithDefaults, {
       credentials: bootstrappedCredentials,
       initialState: captureResult.state,
       fetchImpl: makeJarUaFetch(jar.ua),
@@ -860,8 +871,9 @@ async function runCdpReplay(
     values: {},
     storage: [],
   };
+  const paramsWithDefaults = withWorkflowDefaults(tool.workflow, params);
   const bootstrapUrl = tool.workflow.bootstrap
-    ? substituteString(tool.workflow.bootstrap.url, params, credentials, [])
+    ? substituteString(tool.workflow.bootstrap.url, paramsWithDefaults, credentials, [])
     : undefined;
 
   const siteDir = pathResolve(tool.dir, '..');
@@ -921,7 +933,7 @@ async function runCdpReplay(
       return captureResult.result;
     }
 
-    const result = await tool.toolFn(params, {
+    const result = await tool.toolFn(paramsWithDefaults, {
       credentials: bootstrappedCredentials,
       initialState: captureResult.state,
       fetchImpl: cf.fetchImpl,
@@ -934,6 +946,8 @@ async function runCdpReplay(
         saveJar(siteDir, postJar);
       } catch {
         // best-effort
+      } finally {
+        if (!cdpPool && ownsSession) await cf.close();
       }
     } else {
       if (ownsSession) {
@@ -1200,8 +1214,21 @@ async function stealthBootstrapState(
   return state;
 }
 
-function ensureStealthFetch(tool: ResolvedTool, cache: Map<string, StealthFetch>): StealthFetch {
-  const cached = cache.get(tool.site);
+async function ensureStealthFetch(
+  tool: ResolvedTool,
+  cache: Map<string, StealthFetch>,
+  params: Record<string, string | number | boolean>,
+): Promise<StealthFetch> {
+  const credentials = (await loadCredentialStore(tool.site)) ?? {
+    site: tool.site,
+    cookies: [],
+    values: {},
+  };
+  const bootstrapUrl = tool.workflow.bootstrap?.url
+    ? substituteString(tool.workflow.bootstrap.url, params, credentials, [], 'url')
+    : undefined;
+  const cacheKey = bootstrapUrl ? `${tool.site}:${bootstrapUrl}` : tool.site;
+  const cached = cache.get(cacheKey);
   if (cached) return cached;
   const sf = createStealthFetch({
     baseUrl: pickBaseUrl(tool),
@@ -1210,9 +1237,9 @@ function ensureStealthFetch(tool: ResolvedTool, cache: Map<string, StealthFetch>
     // minted in the same session as the anti-bot cookies. Otherwise the
     // stealth rung can't satisfy a `${state.X}` the workflow bootstrap was
     // supposed to provide, and escalation from fetch-bootstrap dead-ends.
-    bootstrapUrl: tool.workflow.bootstrap?.url,
+    bootstrapUrl,
   });
-  cache.set(tool.site, sf);
+  cache.set(cacheKey, sf);
   return sf;
 }