imprint-mcp 0.6.0 → 0.6.2

package/src/imprint/probe-backends.ts

@@ -107,7 +107,7 @@ export async function probeAllBackends(
   return results;
 }
 
-async function probeResolvedTool(
+export async function probeResolvedTool(
   opts: Pick<ProbeBackendsOptions, 'site' | 'paramOverrides'>,
   assetRoot: string,
   tool: ResolvedTool,
@@ -230,7 +230,7 @@ async function probeResolvedTool(
     imprintVersion: VERSION,
     schemaVersion: 2,
     workflowHash: workflowHash(tool.workflow),
-    capabilityHash: capabilityHash(tool.workflow),
+    capabilityHash: workflowCapabilityHash(tool.workflow),
     preferredOrder,
     results,
   };
@@ -323,16 +323,85 @@ function workflowHash(workflow: ResolvedTool['workflow']): string {
     .digest('hex');
 }
 
-function capabilityHash(workflow: ResolvedTool['workflow']): string {
+export function workflowCapabilityHash(workflow: ResolvedTool['workflow']): string {
   const caps = {
     bootstrap: Boolean(workflow.bootstrap),
-    captures: workflow.requests.flatMap((r) =>
-      (r.captures ?? []).map((c) => `${c.source}:${c.name}:${c.capability}`),
-    ),
+    prefersCdpReplayFirst: prefersCdpReplayFirst(workflow),
+    requestModes: normalizedUnique(workflow.requests.map((request) => request.mode ?? 'fetch')),
+    captures: normalizedUnique([
+      ...(workflow.bootstrap?.captures ?? []).map(
+        (capture) => `bootstrap:${capture.source}:${capture.capability}:${capture.required}`,
+      ),
+      ...workflow.requests.flatMap((request) =>
+        (request.captures ?? []).map(
+          (capture) => `request:${capture.source}:${capture.capability}:${capture.required}`,
+        ),
+      ),
+    ]),
   };
   return createHash('sha256').update(JSON.stringify(caps)).digest('hex');
 }
 
+function normalizedUnique(values: string[]): string[] {
+  return [...new Set(values)].sort();
+}
+
+export function canRebindBackendsCacheToWorkflow(
+  tool: Pick<ResolvedTool, 'workflow'>,
+  cache: BackendsCache,
+): boolean {
+  return (
+    typeof cache.capabilityHash === 'string' &&
+    cache.capabilityHash === workflowCapabilityHash(tool.workflow)
+  );
+}
+
+/** Carry a previously proven backend preference across a compile-time workflow
+ * revision without performing network I/O. Runtime cache loading remains
+ * hash-strict; this adapter deliberately rebinds only after the verifier has
+ * decided the existing preference is still applicable. */
+export function rebindBackendsCacheToWorkflow(
+  tool: Pick<ResolvedTool, 'workflow' | 'dir'>,
+  cache: BackendsCache,
+  outPath = pathResolve(tool.dir, 'backends.json'),
+): BackendsCache {
+  if (!canRebindBackendsCacheToWorkflow(tool, cache)) {
+    throw new Error('backend cache capabilities changed; run a fresh probe instead of rebinding');
+  }
+  const rebound: BackendsCache = {
+    ...cache,
+    workflowHash: workflowHash(tool.workflow),
+    capabilityHash: workflowCapabilityHash(tool.workflow),
+  };
+  BackendsCacheSchema.parse(rebound);
+  writeFileSync(outPath, `${JSON.stringify(rebound, null, 2)}\n`);
+  return rebound;
+}
+
+/** Rebind an already-proven cache after compile-time metadata is stamped onto
+ * workflow.json. This performs no network I/O and intentionally does nothing
+ * for missing/invalid caches. */
+export function rebindExistingBackendsCacheToWorkflow(toolDir: string): BackendsCache | null {
+  const workflowPath = pathResolve(toolDir, 'workflow.json');
+  if (!existsSync(workflowPath)) return null;
+
+  let workflow: ResolvedTool['workflow'];
+  try {
+    workflow = WorkflowSchema.parse(JSON.parse(readFileSync(workflowPath, 'utf8')));
+  } catch {
+    return null;
+  }
+
+  const assetRoot = pathResolve(toolDir, '..', '..');
+  const status = loadBackendsCacheStatus(workflow.site, assetRoot, toolDir, {
+    warn: false,
+    toolName: workflow.toolName,
+  });
+  if (status.status !== 'ok' && status.status !== 'stale') return null;
+  if (!canRebindBackendsCacheToWorkflow({ workflow }, status.cache)) return null;
+  return rebindBackendsCacheToWorkflow({ workflow, dir: toolDir }, status.cache);
+}
+
 export function persistRuntimeBackendsCache(opts: {
   tool: ResolvedTool;
   assetRoot: string;
@@ -343,6 +412,18 @@ export function persistRuntimeBackendsCache(opts: {
     warn: false,
     toolName: opts.tool.workflow.toolName,
   });
+  const soleAttempt = opts.attempts.length === 1 ? opts.attempts[0] : undefined;
+  if (
+    status.status === 'ok' &&
+    status.cache.preferredOrder[0] === opts.usedBackend &&
+    soleAttempt?.backend === opts.usedBackend &&
+    soleAttempt.outcome === 'ok'
+  ) {
+    // A normal call through the already-proven preferred backend is not a
+    // probe or a new backend-learning event. Preserve the original probe time
+    // and its richer cold/warm/ranking diagnostics byte-for-byte on disk.
+    return status.cache;
+  }
   const results: BackendsCache['results'] =
     status.status === 'ok' ? { ...status.cache.results } : {};
 
@@ -408,7 +489,7 @@ export function persistRuntimeBackendsCache(opts: {
     imprintVersion: VERSION,
     schemaVersion: 2,
     workflowHash: workflowHash(opts.tool.workflow),
-    capabilityHash: capabilityHash(opts.tool.workflow),
+    capabilityHash: workflowCapabilityHash(opts.tool.workflow),
     preferredOrder,
     results,
   };

package/src/imprint/recording-request.ts

@@ -0,0 +1,36 @@
+import type { CapturedRequest, WorkflowRequest } from './types.ts';
+
+const TEMPLATE_PLACEHOLDER = /\$\{[^}]+\}/g;
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Match a concrete recorded value against a workflow template without
+ * interpreting or substituting the dynamic values themselves. */
+function templateMatchesRecorded(template: string, recorded: string): boolean {
+  if (template === recorded) return true;
+  let cursor = 0;
+  let pattern = '^';
+  for (const match of template.matchAll(TEMPLATE_PLACEHOLDER)) {
+    pattern += escapeRegExp(template.slice(cursor, match.index));
+    pattern += '.*?';
+    cursor = (match.index ?? 0) + match[0].length;
+  }
+  if (cursor === 0) return false;
+  pattern += `${escapeRegExp(template.slice(cursor))}$`;
+  return new RegExp(pattern).test(recorded);
+}
+
+export function recordedRequestMatchesWorkflow(
+  recorded: Pick<CapturedRequest, 'method' | 'url' | 'body'>,
+  workflow: Pick<WorkflowRequest, 'method' | 'url' | 'body'>,
+): boolean {
+  return (
+    recorded.method.toUpperCase() === workflow.method.toUpperCase() &&
+    templateMatchesRecorded(workflow.url, recorded.url) &&
+    (workflow.body === undefined
+      ? recorded.body === undefined || recorded.body === ''
+      : recorded.body !== undefined && templateMatchesRecorded(workflow.body, recorded.body))
+  );
+}

package/src/imprint/request-capture.ts

@@ -1,23 +1,21 @@
 /**
  * Shared, format-agnostic helpers for resolving a `RequestCapture` against a
- * response. Used by the runtime (resolving `authConfig.sessionCapture` /
- * per-request captures during replay) and by `imprint login` (resolving the
- * same declarative captures against a recorded login response). Keeping a single
- * implementation means a capture locator behaves identically wherever it runs.
+ * response. Used by the runtime and by `imprint login` when resolving captures
+ * named by `authConfig.persist`. Keeping one implementation means a capture
+ * locator behaves identically wherever it runs.
  *
  * This is a LEAF module — it must not import other `src/imprint` modules so it
  * can be consumed from anywhere without introducing an import cycle.
  */
 
 /** Lookup a JSON path inside a parsed value. Segments may be:
- *   - an object key:            `reauth.mfaId`
+ *   - an object key:            `result.identifier`
  *   - a numeric array index:    `items[0]` (bracket) or `items.0` (dot)
- *   - a field-match predicate:  `challenges[type=push]`
+ *   - a field-match predicate:  `items[type=primary]`
+ *   - a JSONPath predicate:     `items[?(@.type=='primary')]`
  *     → the FIRST array element whose `element[field]` stringifies to the value.
- *  The predicate makes captures robust to non-deterministic array ordering — e.g.
- *  a 2FA endpoint that returns its SMS/email/push challenges in a varying order, so
- *  a fixed `challenges[0]` grabs the wrong one while `[type=push]` always selects
- *  the push one. A bracketed token that is neither a number nor a `key=value`
+ *  Predicates keep captures stable when array ordering is non-deterministic. A
+ *  bracketed token that is neither a number nor a `key=value`
  *  predicate is treated as a literal object key (so a top-level key that itself
  *  contains dots, e.g. `[customers.userInformation.accountNumber]`, is matched
  *  verbatim rather than traversed). */
@@ -39,13 +37,8 @@ export function jsonpath(root: unknown, path: string): unknown {
       if (/^\d+$/.test(inner)) {
         tokens.push({ kind: 'index', v: Number.parseInt(inner, 10) });
       } else {
-        const eq = inner.indexOf('=');
-        if (eq >= 0)
-          tokens.push({
-            kind: 'pred',
-            k: inner.slice(0, eq).trim(),
-            v: inner.slice(eq + 1).trim(),
-          });
+        const predicate = parseFieldPredicate(inner);
+        if (predicate) tokens.push(predicate);
         else tokens.push({ kind: 'key', v: inner });
       }
     }
@@ -73,6 +66,36 @@ export function jsonpath(root: unknown, path: string): unknown {
   return cur;
 }
 
+export function captureValueMatches(
+  value: unknown,
+  equals?: string | number | boolean | null,
+): boolean {
+  if (equals !== undefined) return Object.is(value, equals);
+  return value !== undefined && value !== null && value !== '';
+}
+
+function parseFieldPredicate(inner: string): { kind: 'pred'; k: string; v: string } | null {
+  const standard = /^\?\(\s*@\.([A-Za-z_$][\w$-]*)\s*==\s*(.+?)\s*\)$/.exec(inner);
+  if (standard?.[1] && standard[2] !== undefined) {
+    return { kind: 'pred', k: standard[1], v: unquotePredicateValue(standard[2]) };
+  }
+
+  const eq = inner.indexOf('=');
+  if (eq < 1 || inner[eq + 1] === '=') return null;
+  return {
+    kind: 'pred',
+    k: inner.slice(0, eq).trim(),
+    v: unquotePredicateValue(inner.slice(eq + 1).trim()),
+  };
+}
+
+function unquotePredicateValue(value: string): string {
+  const first = value[0];
+  return value.length >= 2 && (first === "'" || first === '"') && value.at(-1) === first
+    ? value.slice(1, -1)
+    : value;
+}
+
 /** Read a response header value, honoring the capture `mode`. Multi-valued
  *  headers are comma-split. `set-cookie` is never projected (cookies are handled
  *  by the cookie jar, not as plain header captures). */