@essential-apps/shopify-test-runner 1.0.0

package/dist/scripts/captureAuth.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * Capture Shopify auth state into tests/test-online/.auth/storageState.json.
+ *
+ * The captured cookies are fingerprint-bound (UA, sec-ch-ua-platform,
+ * canvas/WebGL hashes, etc.), so this script MUST run in the same
+ * browser environment that tests use:
+ *   - On host (macOS): Google Chrome via patchright.
+ *   - In container: Google Chrome via patchright (same channel),
+ *     under Xvfb. The runDockerAuth.ts wrapper exposes the Xvfb
+ *     display over VNC so the user can interactively log in.
+ *
+ * If you re-capture on host but tests run in container (or vice-versa),
+ * Cloudflare's bot heuristics will see UA / fingerprint inconsistency
+ * and challenge or block the session.
+ */
+import { mkdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname } from 'node:path';
+import { createInterface } from 'node:readline';
+import { storageStatePath, assertInVm } from '@essential-apps/shopify-test-core';
+// Auth capture must run INSIDE the VM (via runVmAuth, which sets
+// TEST_IN_CONTAINER + drives this over VNC) — never on the host, or the
+// captured cf_clearance/session is fingerprint-mismatched against the VM.
+assertInVm('capture Shopify auth');
+const require = createRequire(import.meta.url);
+const chromium = require('patchright').chromium;
+// Test Partner account (throwaway; not prod). Shown in the terminal AND
+// pinned to a bar at the top of the browser so it's readable while
+// logging in over VNC.
+const LOGIN_EMAIL = 'essential-apps-test-1@supercorp.ai';
+const LOGIN_PASSWORD = 'essential-apps-test-1-password';
+// A fixed top bar injected into every page (survives navigation) showing
+// the login creds. `pointer-events:none` so it never blocks the form;
+// re-pinned on an interval because Shopify's accounts pages re-render.
+const credsBarInitScript = `(() => {
+  const ID = '__ea_auth_creds_bar__';
+  const text = ${JSON.stringify(`TEST LOGIN  ·  ${LOGIN_EMAIL}  ·  password: ${LOGIN_PASSWORD}`)};
+  const render = () => {
+    if (!document.documentElement) return;
+    let b = document.getElementById(ID);
+    if (!b) {
+      b = document.createElement('div');
+      b.id = ID;
+      b.style.cssText = 'position:fixed;top:0;left:0;right:0;z-index:2147483647;background:#0a7d3b;color:#fff;font:600 13px/26px ui-monospace,SFMono-Regular,Menlo,monospace;text-align:center;height:26px;padding:0 10px;box-shadow:0 1px 4px rgba(0,0,0,.35);pointer-events:none';
+      (document.body || document.documentElement).appendChild(b);
+    }
+    b.textContent = text;
+  };
+  render();
+  document.addEventListener('DOMContentLoaded', render);
+  setInterval(render, 800);
+})();`;
+async function main() {
+    console.log('Opening Chrome. Please:');
+    console.log(`  Log in as:  ${LOGIN_EMAIL}`);
+    console.log(`  Password:   ${LOGIN_PASSWORD}   (also in the green bar atop the browser)`);
+    console.log('  1. Log in to Shopify Partners.');
+    console.log('  2. Then visit your test store admin (e.g. https://admin.shopify.com/store/<your-store>) —');
+    console.log('     if a Cloudflare "Verify you are human" challenge appears, click through it.');
+    console.log('     Without this step, tests will hit Turnstile and fail.');
+    console.log('  3. When both are done, return here and press Enter.');
+    console.log('');
+    // chromium.launch + newContext (matches storePool fixture model).
+    // Critically, this is NOT launchPersistentContext — the persistent
+    // profile accumulates fingerprint state that triggers Cloudflare's
+    // bot detection. Fresh-context model means the browser fingerprint
+    // CF sees here (during capture) is the SAME fingerprint it'll see
+    // at test time (when a fresh context is built from this saved
+    // storageState). cf_clearance is fingerprint-bound, so this
+    // consistency is what makes the saved cookie actually work.
+    //
+    // Patchright (no `channel: 'chrome'`) — uses its bundled
+    // chromium with stealth patches. Same browser as storePool +
+    // conformance probes, so cf_clearance carries across all three.
+    // Real Google Chrome was tried earlier but its fingerprint
+    // doesn't match patchright's, causing CF re-challenges.
+    const browser = await chromium.launch({
+        headless: false,
+        args: [
+            '--ip-address-space-overrides=127.0.0.1:0=public,[::1]:0=public',
+            '--disable-features=LocalNetworkAccessChecks,LocalNetworkAccessChecksWebSockets,LocalNetworkAccessChecksWebTransport,BlockInsecurePrivateNetworkRequests,PrivateNetworkAccessRespectPreflightResults,PrivateNetworkAccessSendPreflights',
+            '--local-network-access-permissions-policy-default-enabled',
+        ],
+    });
+    const context = (await browser.newContext({
+        viewport: { width: 1400, height: 900 },
+        ignoreHTTPSErrors: true,
+    }));
+    // Pin the creds to a bar at the top of the (VNC'd) browser.
+    await context.addInitScript(credsBarInitScript);
+    const page = await context.newPage();
+    await page.goto('https://accounts.shopify.com/lookup');
+    await waitForEnter('Press Enter once logged in AND past any admin Turnstile... ');
+    // Sanity-check cf_clearance presence and warn loudly if absent —
+    // capture without it works for Partner-API-only flows, but online
+    // tests that drive admin.shopify.com will fail on Turnstile.
+    const cookies = await context.cookies();
+    const hasCfClearance = cookies.some((c) => c.name === 'cf_clearance' && c.domain.includes('shopify.com'));
+    if (!hasCfClearance) {
+        console.warn('⚠️  No cf_clearance cookie found for *.shopify.com. The online suite will hit Turnstile.');
+        console.warn('   Visit your test store admin in this browser, pass the Cloudflare challenge, then re-run.');
+    }
+    else {
+        console.log('✓ cf_clearance cookie captured (admin.shopify.com Turnstile bypass).');
+    }
+    mkdirSync(dirname(storageStatePath), { recursive: true });
+    await context.storageState({ path: storageStatePath });
+    console.log(`✓ Auth state saved: ${storageStatePath}`);
+    await context.close();
+    await browser.close();
+}
+function waitForEnter(prompt) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((res) => rl.question(prompt, () => {
+        rl.close();
+        res();
+    }));
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=captureAuth.js.map

package/dist/scripts/captureAuth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureAuth.js","sourceRoot":"","sources":["../../src/scripts/captureAuth.ts"],"names":[],"mappings":"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"}

package/dist/scripts/captureContracts.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=captureContracts.d.ts.map

package/dist/scripts/captureContracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureContracts.d.ts","sourceRoot":"","sources":["../../src/scripts/captureContracts.ts"],"names":[],"mappings":""}

package/dist/scripts/captureContracts.js

@@ -0,0 +1,517 @@
+#!/usr/bin/env node
+/**
+ * captureContracts — bootstrap step for the operation-contract
+ * conformance system. See docs/CONTRACTS.md for the full design.
+ *
+ * What it does:
+ *   1. Walk every `.ts/.tsx/.js/.jsx` file under `--glob` (default
+ *      `./app`).
+ *   2. Extract every `#graphql` template literal.
+ *   3. Execute each operation against an IN-PROCESS offline mock
+ *      (Admin GraphQL or Storefront GraphQL, per `--api`).
+ *   4. Write one JSON-per-operation under `tests/test-offline/contracts/<api>/`.
+ *
+ * The captured response is `capturedFrom: "offline"` — a tentative
+ * bootstrap. The conformance suite's `verify-contracts-from-live`
+ * probe later re-captures from real Shopify; on each successful
+ * live-capture the contract is overwritten with `capturedFrom: "live"`
+ * — the authoritative ground truth.
+ *
+ * Variables: an operation with required variables (`ID!`, `String!`,
+ * etc.) needs sample values to execute. We auto-synthesise sensible
+ * defaults for primitive types (`ID!` → first seeded product GID;
+ * `String!` → `"sample"`; `Int!` → `1`; `Boolean!` → `true`). Complex
+ * input objects are NOT synthesised — the operation is captured
+ * without execution and `response: null` + `error: "needs fixtures"`
+ * is recorded. A consuming app can hand-write `tests/test-offline/contracts/
+ * fixtures.json` mapping operation names to variables to cover those.
+ *
+ * Output is idempotent — same input + same offline mock = same
+ * contracts. Commit them.
+ */
+import { readdirSync, readFileSync, statSync, writeFileSync, mkdirSync, existsSync, } from 'node:fs';
+import { extname, resolve, dirname, basename, relative } from 'node:path';
+import { parse as parseGraphql, validate as validateGraphql, buildSchema, typeFromAST, isNonNullType, isListType, isScalarType, isEnumType, isInputObjectType, TypeInfo, visit, visitWithTypeInfo, Kind, } from 'graphql';
+import { loadAdminSdl, loadStorefrontSdl, createAdminApi, createStorefrontApi, } from '@essential-apps/shopify-test-shopify-api';
+import { ShopState } from '@essential-apps/shopify-test-storefront';
+function parseArgs() {
+    const argv = process.argv.slice(2);
+    const out = {
+        api: 'admin',
+        glob: './app',
+        outDir: '',
+        fixturesPath: '',
+        cwd: process.cwd(),
+        quiet: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? '';
+        if (a === '--api' && i + 1 < argv.length) {
+            const next = argv[++i] ?? '';
+            if (next !== 'admin' && next !== 'storefront') {
+                console.error(`--api must be "admin" or "storefront"`);
+                process.exit(2);
+            }
+            out.api = next;
+        }
+        else if (a === '--glob' && i + 1 < argv.length) {
+            out.glob = argv[++i] ?? out.glob;
+        }
+        else if (a === '--out' && i + 1 < argv.length) {
+            out.outDir = argv[++i] ?? '';
+        }
+        else if (a === '--fixtures' && i + 1 < argv.length) {
+            out.fixturesPath = argv[++i] ?? '';
+        }
+        else if (a === '--quiet') {
+            out.quiet = true;
+        }
+        else {
+            console.error(`unknown arg: ${a}`);
+            process.exit(2);
+        }
+    }
+    // Default output dir scopes contracts under the consuming app's
+    // tests/test-offline/contracts/<api>/ — co-located with the spec files.
+    if (!out.outDir) {
+        out.outDir = resolve(out.cwd, 'tests/test-offline/contracts', out.api);
+    }
+    else {
+        out.outDir = resolve(out.cwd, out.outDir);
+    }
+    if (!out.fixturesPath) {
+        out.fixturesPath = resolve(out.cwd, 'tests/test-offline/contracts/fixtures.json');
+    }
+    return out;
+}
+/**
+ * Walk a directory tree, yielding paths whose extension is a JS/TS
+ * source file. Skips `node_modules`, `dist`, `.git`, `build` — the
+ * usual non-source noise.
+ */
+function* walkSources(root) {
+    let entries;
+    try {
+        entries = readdirSync(root);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries) {
+        if (name === 'node_modules' ||
+            name === 'dist' ||
+            name === '.git' ||
+            name === 'build')
+            continue;
+        const full = resolve(root, name);
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory()) {
+            yield* walkSources(full);
+        }
+        else if (st.isFile()) {
+            const ext = extname(name);
+            if (ext === '.ts' || ext === '.tsx' || ext === '.js' || ext === '.jsx') {
+                yield full;
+            }
+        }
+    }
+}
+/**
+ * Extract every `#graphql ...` template literal from a file. Parses
+ * each to discover its operation name (so contracts get filenames
+ * that match `getShop` rather than `__anon_42__`).
+ */
+function extractOperations(file, content) {
+    const ops = [];
+    const regex = /`\s*#graphql\b([^`]*)`/g;
+    let m;
+    while ((m = regex.exec(content)) !== null) {
+        const line = content.slice(0, m.index).split('\n').length;
+        const source = m[1] ?? '';
+        const name = deriveOperationName(source, file, line);
+        ops.push({ file, line, source, name });
+    }
+    return ops;
+}
+/**
+ * Pick a stable, filesystem-safe slug for an operation. Preference
+ * order:
+ *
+ *   1. The operation's declared name —
+ *      `query getShop { ... }` → `getShop`.
+ *   2. A type+field slug derived from the first top-level selection
+ *      — `query { shop { name } }` → `anon_query_shop`. Stable across
+ *      file renames (only the first selected field is in the slug).
+ *   3. Filename+line fallback when the document is unparseable.
+ *
+ * Why anon slugs matter: contracts are committed to the consuming
+ * app; the slug is the filename. Anon ops whose slug depends on
+ * the file path produce noisy diffs whenever the call site moves.
+ * Type+field slugs survive refactors as long as the operation
+ * keeps its first selection.
+ */
+function deriveOperationName(source, file, line) {
+    const fileBase = file.split('/').pop()?.replace(/[^a-zA-Z0-9_-]/g, '_') ?? 'unknown';
+    const fallback = `__anon_${fileBase}_L${line}__`;
+    let doc;
+    try {
+        doc = parseGraphql(source);
+    }
+    catch {
+        return fallback;
+    }
+    const op = doc.definitions.find((d) => d.kind === Kind.OPERATION_DEFINITION);
+    if (!op)
+        return fallback;
+    if (op.name?.value)
+        return op.name.value;
+    // Anonymous — derive from first selection.
+    const firstField = op.selectionSet.selections.find((s) => s.kind === Kind.FIELD);
+    if (firstField && firstField.kind === Kind.FIELD) {
+        const opType = op.operation; // 'query' | 'mutation' | 'subscription'
+        const fieldName = firstField.name.value;
+        return `anon_${opType}_${fieldName}`;
+    }
+    return fallback;
+}
+/**
+ * Default per-test seed for the offline ShopState. Stable IDs so
+ * contracts captured from offline are deterministic across runs.
+ * Tests that need different data still seed via their own factories;
+ * contracts use this snapshot.
+ */
+function buildSeededState() {
+    const state = new ShopState({
+        shop: {
+            domain: 'test-shop.myshopify.com',
+            permanent_domain: 'test-shop.myshopify.com',
+        },
+    });
+    state.addProduct({
+        id: 900_000_001,
+        handle: 'sample-product',
+        title: 'Sample Product',
+        description: 'Used by contract capture as a deterministic fixture.',
+        price: 1000,
+        vendor: 'Sample Vendor',
+        type: 'Sample',
+        variants: [
+            {
+                id: 900_010_001,
+                title: 'Default Title',
+                price: 1000,
+                available: true,
+                sku: 'SAMPLE-1',
+                inventory_quantity: 100,
+                selected_options: ['Default Title'],
+            },
+        ],
+        tags: [],
+    });
+    state.addCollection({
+        id: 900_020_001,
+        handle: 'sample-collection',
+        title: 'Sample Collection',
+        productHandles: ['sample-product'],
+    });
+    return state;
+}
+/**
+ * Synthesise plausible variable values for an operation's variable
+ * definitions. Handles ID / String / Int / Float / Boolean scalars
+ * and their nullable + list variants. Complex input objects fall
+ * through to `unhandled` — the user can override via fixtures.json.
+ */
+function synthesiseVariables(op, schema, state, override) {
+    const values = {};
+    const unhandled = [];
+    for (const def of op.variableDefinitions ?? []) {
+        const name = def.variable.name.value;
+        if (name in override) {
+            values[name] = override[name];
+            continue;
+        }
+        const synthValue = synthesiseTypeNode(def.type, schema, state);
+        if (synthValue === SYNTH_UNHANDLED) {
+            unhandled.push(name);
+        }
+        else {
+            values[name] = synthValue;
+        }
+    }
+    return { values, unhandled };
+}
+const SYNTH_UNHANDLED = Symbol('unhandled');
+/**
+ * Convert an AST type-node (from a variable definition) to a
+ * resolved `GraphQLType`, then defer to the type-driven synthesiser.
+ *
+ * The two-step approach (AST → GraphQLType → value) is so that
+ * Input objects can be walked by their FIELD definitions, not by
+ * raw AST. Field types know exactly what's required vs optional, so
+ * we only fill required fields and leave optional ones absent.
+ */
+function synthesiseTypeNode(typeNode, schema, state) {
+    const resolved = typeFromAST(schema, typeNode);
+    if (!resolved)
+        return SYNTH_UNHANDLED;
+    return synthesiseGraphQLType(resolved, state);
+}
+/**
+ * Recursively synthesise a sensible default for a GraphQLType.
+ *
+ *   - NonNull → required; recurse into inner type.
+ *   - List → empty array (valid for any list).
+ *   - Scalar → primitive defaults (ID = first seeded product GID,
+ *     others sensible per name).
+ *   - Enum → first value of the enum.
+ *   - InputObject → object with only its required fields filled;
+ *     optional fields left absent.
+ *
+ * Returns `SYNTH_UNHANDLED` only for types we genuinely can't
+ * produce a value for (custom scalars with non-obvious shapes etc.).
+ * Callers should treat that as "user must override via fixtures.json".
+ */
+function synthesiseGraphQLType(type, state) {
+    if (isNonNullType(type)) {
+        return synthesiseGraphQLType(type.ofType, state);
+    }
+    if (isListType(type)) {
+        return [];
+    }
+    if (isScalarType(type)) {
+        const name = type.name;
+        if (name === 'ID') {
+            const first = Array.from(state.products.values())[0];
+            return first
+                ? `gid://shopify/Product/${first.id}`
+                : 'gid://shopify/Resource/1';
+        }
+        if (name === 'String')
+            return 'sample';
+        if (name === 'Int')
+            return 1;
+        if (name === 'Float')
+            return 1.0;
+        if (name === 'Boolean')
+            return true;
+        // Shopify-specific custom scalars we can stub with a primitive
+        // — these all serialise as strings on the wire.
+        if (name === 'URL' ||
+            name === 'DateTime' ||
+            name === 'Date' ||
+            name === 'Decimal' ||
+            name === 'Money' ||
+            name === 'HTML' ||
+            name === 'JSON' ||
+            name === 'JSONString' ||
+            name === 'FormattedString' ||
+            name === 'StorefrontID' ||
+            name === 'UnsignedInt64') {
+            if (name === 'URL')
+                return 'https://example.com';
+            if (name === 'DateTime')
+                return '2026-01-01T00:00:00Z';
+            if (name === 'Date')
+                return '2026-01-01';
+            if (name === 'JSON' || name === 'JSONString')
+                return '{}';
+            if (name === 'UnsignedInt64')
+                return '1';
+            return '1.00'; // Decimal / Money / HTML / FormattedString — primitive default
+        }
+        return SYNTH_UNHANDLED;
+    }
+    if (isEnumType(type)) {
+        const values = type.getValues();
+        return values[0]?.value ?? SYNTH_UNHANDLED;
+    }
+    if (isInputObjectType(type)) {
+        const fields = type.getFields();
+        const out = {};
+        let anyRequired = false;
+        for (const [fieldName, field] of Object.entries(fields)) {
+            // Only fill REQUIRED fields. Optional ones get omitted —
+            // keeps the variable payload minimal + valid.
+            if (!isNonNullType(field.type))
+                continue;
+            anyRequired = true;
+            const value = synthesiseGraphQLType(field.type, state);
+            if (value === SYNTH_UNHANDLED)
+                return SYNTH_UNHANDLED;
+            out[fieldName] = value;
+        }
+        // Edge case: input object with NO required fields. Empty object
+        // is a valid value.
+        return anyRequired ? out : {};
+    }
+    // Interfaces / Unions / custom scalars not covered above.
+    return SYNTH_UNHANDLED;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Hono types are loose
+function buildOfflineExecutor(api, state) {
+    const app = api === 'admin' ? createAdminApi({ state }) : createStorefrontApi({ state });
+    const endpoint = api === 'admin'
+        ? '/admin/api/2025-07/graphql.json'
+        : '/api/2025-07/graphql.json';
+    return async (source, variables) => {
+        const resp = await app.request(endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Shopify-Access-Token': 'mock-access-token',
+            },
+            body: JSON.stringify({ query: source, variables }),
+        });
+        return resp.json();
+    };
+}
+async function main() {
+    const args = parseArgs();
+    const sdl = args.api === 'admin' ? loadAdminSdl() : loadStorefrontSdl();
+    const schema = buildSchema(sdl);
+    // Load per-app fixtures if present (gives users a way to override
+    // synthesised variables for specific operations).
+    let fixtures = {};
+    if (existsSync(args.fixturesPath)) {
+        fixtures = JSON.parse(readFileSync(args.fixturesPath, 'utf8'));
+    }
+    const sourceDir = resolve(args.cwd, args.glob);
+    const files = Array.from(walkSources(sourceDir));
+    if (files.length === 0) {
+        console.error(`[capture-contracts] no source files under ${sourceDir}`);
+        process.exit(2);
+    }
+    // Collect operations + dedup by source (the same #graphql may
+    // appear in multiple files if shared via a util).
+    const opsByName = new Map();
+    for (const f of files) {
+        const content = readFileSync(f, 'utf8');
+        for (const op of extractOperations(f, content)) {
+            const existing = opsByName.get(op.name);
+            if (!existing)
+                opsByName.set(op.name, op);
+        }
+    }
+    if (!args.quiet) {
+        console.log(`[capture-contracts] api=${args.api} ${files.length} file(s) scanned, ${opsByName.size} unique operation(s)`);
+    }
+    const state = buildSeededState();
+    const executor = buildOfflineExecutor(args.api, state);
+    mkdirSync(args.outDir, { recursive: true });
+    let captured = 0;
+    let skipped = 0;
+    let drift = 0;
+    for (const op of opsByName.values()) {
+        let doc;
+        try {
+            doc = parseGraphql(op.source);
+        }
+        catch (err) {
+            writeFileSync(resolve(args.outDir, `${op.name}.json`), JSON.stringify({
+                operationName: op.name,
+                source: op.source,
+                variables: {},
+                response: null,
+                capturedFrom: 'offline',
+                capturedAt: new Date().toISOString(),
+                warning: `parse failed: ${err.message}`,
+            }, null, 2) + '\n');
+            skipped++;
+            continue;
+        }
+        // Validate against schema before executing — operations that
+        // reference fields the SDL doesn't have are recorded as drift.
+        const validationErrors = validateGraphql(schema, doc);
+        if (validationErrors.length > 0) {
+            writeFileSync(resolve(args.outDir, `${op.name}.json`), JSON.stringify({
+                operationName: op.name,
+                source: op.source,
+                variables: {},
+                response: null,
+                capturedFrom: 'offline',
+                capturedAt: new Date().toISOString(),
+                warning: `schema validation failed: ${validationErrors
+                    .map((e) => e.message)
+                    .join(' | ')}`,
+            }, null, 2) + '\n');
+            drift++;
+            continue;
+        }
+        // Synthesise variables (with fixture overrides).
+        const opDef = doc.definitions.find((d) => d.kind === Kind.OPERATION_DEFINITION);
+        let variables = {};
+        let warning;
+        if (opDef) {
+            const synth = synthesiseVariables(opDef, schema, state, fixtures[op.name] ?? {});
+            variables = synth.values;
+            if (synth.unhandled.length > 0) {
+                warning =
+                    `variables not synthesised: ${synth.unhandled.join(', ')}. ` +
+                        `Add to ${relative(args.cwd, args.fixturesPath)} under "${op.name}" to capture this operation.`;
+            }
+        }
+        // If we couldn't fill required vars, record + skip execution.
+        if (warning) {
+            writeFileSync(resolve(args.outDir, `${op.name}.json`), JSON.stringify({
+                operationName: op.name,
+                source: op.source,
+                variables,
+                response: null,
+                capturedFrom: 'offline',
+                capturedAt: new Date().toISOString(),
+                warning,
+            }, null, 2) + '\n');
+            skipped++;
+            continue;
+        }
+        // Execute and capture.
+        let response;
+        try {
+            response = await executor(op.source, variables);
+        }
+        catch (err) {
+            writeFileSync(resolve(args.outDir, `${op.name}.json`), JSON.stringify({
+                operationName: op.name,
+                source: op.source,
+                variables,
+                response: null,
+                capturedFrom: 'offline',
+                capturedAt: new Date().toISOString(),
+                warning: `execution failed: ${err.message}`,
+            }, null, 2) + '\n');
+            drift++;
+            continue;
+        }
+        writeFileSync(resolve(args.outDir, `${op.name}.json`), JSON.stringify({
+            operationName: op.name,
+            source: op.source,
+            variables,
+            response,
+            capturedFrom: 'offline',
+            capturedAt: new Date().toISOString(),
+        }, null, 2) + '\n');
+        captured++;
+    }
+    if (!args.quiet) {
+        console.log(`[capture-contracts] ${captured} captured, ${skipped} skipped (need fixtures), ${drift} drift. Output: ${relative(args.cwd, args.outDir)}/`);
+    }
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(2);
+});
+// Silence the unused-typeinfo warning — the imports are used by the
+// validate / TypeInfo path the script extends in follow-ups.
+void TypeInfo;
+void visit;
+void visitWithTypeInfo;
+void dirname;
+void basename;
+//# sourceMappingURL=captureContracts.js.map