@unito/integration-cli 0.64.5 → 0.65.0

package/dist/boilerplate/package-lock.json

@@ -866,37 +866,24 @@
         "typescript": ">=4.8.4 <6.0.0"
       }
     },
-    "node_modules/@typescript-eslint/typescript-estree/node_modules/balanced-match": {
-      "version": "4.0.4",
-      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
-      "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": "18 || 20 || >=22"
-      }
-    },
     "node_modules/@typescript-eslint/typescript-estree/node_modules/brace-expansion": {
-      "version": "5.0.3",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.3.tgz",
-      "integrity": "sha512-fy6KJm2RawA5RcHkLa1z/ScpBeA762UF9KmZQxwIbDtRJrgLzM10depAiEQ+CXYcoiqW1/m96OAAoke2nE9EeA==",
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz",
+      "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "balanced-match": "^4.0.2"
-      },
-      "engines": {
-        "node": "18 || 20 || >=22"
+        "balanced-match": "^1.0.0"
       }
     },
     "node_modules/@typescript-eslint/typescript-estree/node_modules/minimatch": {
-      "version": "9.0.6",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.6.tgz",
-      "integrity": "sha512-kQAVowdR33euIqeA0+VZTDqU+qo1IeVY+hrKYtZMio3Pg0P0vuh/kwRylLUddJhB6pf3q/botcOvRtx4IN1wqQ==",
+      "version": "9.0.9",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.9.tgz",
+      "integrity": "sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
-        "brace-expansion": "^5.0.2"
+        "brace-expansion": "^2.0.2"
       },
       "engines": {
         "node": ">=16 || 14 >=14.17"
@@ -2294,9 +2281,9 @@
       }
     },
     "node_modules/minimatch": {
-      "version": "3.1.3",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.3.tgz",
-      "integrity": "sha512-M2GCs7Vk83NxkUyQV1bkABc4yxgz9kILhHImZiBPAZ9ybuvCb0/H7lEl5XvIg3g+9d4eNotkZA5IWwYl0tibaA==",
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
+      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
       "dev": true,
       "license": "ISC",
       "dependencies": {

package/dist/src/commands/graph.d.ts

@@ -0,0 +1,21 @@
+import { BaseCommand } from '../baseCommand';
+import * as GlobalConfiguration from '../resources/globalConfiguration';
+export default class Graph extends BaseCommand<typeof Graph> {
+    static description: string;
+    static examples: string[];
+    static args: {
+        operation: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    catch(error: Error): Promise<void>;
+    static flags: {
+        path: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        port: import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
+        environment: import("@oclif/core/lib/interfaces").OptionFlag<GlobalConfiguration.Environment, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'test-account': import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'credential-payload': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'credential-id': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'config-path': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        output: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/src/commands/graph.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const crypto_1 = tslib_1.__importDefault(require("crypto"));
+const fs_1 = tslib_1.__importDefault(require("fs"));
+const core_1 = require("@oclif/core");
+const baseCommand_1 = require("../baseCommand");
+const errors_1 = require("../errors");
+const GlobalConfiguration = tslib_1.__importStar(require("../resources/globalConfiguration"));
+const integrations_1 = require("../resources/integrations");
+const configuration_1 = require("../resources/configuration");
+const decryption_1 = require("../resources/decryption");
+const credentials_1 = require("../resources/credentials");
+class Graph extends baseCommand_1.BaseCommand {
+    static description = 'Query a running integration graph and print the response';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --path=/sobjects/Opportunity/records/abc123',
+        '<%= config.bin %> <%= command.id %> get --path=/sobjects/Opportunity --port=9201',
+    ];
+    static args = {
+        operation: core_1.Args.string({
+            description: 'Operation to perform on the graph path',
+            required: false,
+            default: 'get',
+            options: ['get', 'getItem', 'getCollection', 'createItem', 'updateItem', 'deleteItem'],
+        }),
+    };
+    async catch(error) {
+        /* istanbul ignore if */
+        if ((0, errors_1.handleError)(this, error)) {
+            this.exit(-1);
+        }
+        throw error;
+    }
+    static flags = {
+        path: core_1.Flags.string({
+            description: 'Graph path to fetch (must start with /), e.g. /sobjects/Opportunity/records/abc123',
+            required: true,
+        }),
+        port: core_1.Flags.integer({
+            description: 'Port the integration is running on',
+            default: 9200,
+        }),
+        environment: core_1.Flags.custom({
+            description: 'the environment of the platform',
+            options: Object.values(GlobalConfiguration.Environment),
+            default: GlobalConfiguration.Environment.Production,
+        })(),
+        'test-account': core_1.Flags.string({
+            description: 'test account to use',
+            options: Object.values(configuration_1.CredentialScope),
+            default: configuration_1.CredentialScope.DEVELOPMENT,
+        }),
+        'credential-payload': core_1.Flags.string({
+            description: '(advanced) credential payload to use.',
+            exclusive: ['credential-id'],
+        }),
+        'credential-id': core_1.Flags.string({
+            description: '(advanced) credential to use.',
+            exclusive: ['credential-payload'],
+        }),
+        'config-path': core_1.Flags.string({
+            summary: 'relative path to a custom ".unito.json" file',
+            description: `Use a custom configuration file instead of the default '.unito.json'.
+
+      If you want to force the CLI to use a specific configuration file, you can use this flag to specify the relative
+      path from your integration's root folder (with a leading '/').
+
+      Usage: <%= config.bin %> <%= command.id %> --config-path=/myCustomConfig.json`,
+        }),
+        output: core_1.Flags.string({
+            char: 'o',
+            description: 'Write response body to file instead of stdout',
+        }),
+    };
+    async run() {
+        (0, integrations_1.validateIsIntegrationDirectory)();
+        const { args, flags } = await this.parse(Graph);
+        const operation = args.operation ?? 'get';
+        if (operation === 'createItem' || operation === 'updateItem' || operation === 'deleteItem') {
+            this.error(`Operation "${operation}" is not yet implemented`, { exit: 1 });
+        }
+        const environment = flags.environment ?? GlobalConfiguration.Environment.Production;
+        const configuration = await (0, configuration_1.getConfiguration)(environment, flags['config-path']);
+        // Credential resolution — identical to dev.ts
+        let credentialPayload = '{}';
+        if (flags['credential-id']) {
+            const credential = await (0, credentials_1.fetchCredential)(environment, this.config.configDir, flags['credential-id']);
+            credentialPayload = JSON.stringify({
+                ...credential.payload,
+                unitoCredentialId: credential.id,
+                unitoUserId: credential.unitoUserId,
+            });
+        }
+        else if (flags['credential-payload']) {
+            credentialPayload = flags['credential-payload'];
+        }
+        else {
+            const credentials = configuration.testAccounts?.[flags['test-account']];
+            if (credentials) {
+                const decryptedEntries = await (0, decryption_1.decryptEntries)(configuration.name, environment, this.config.configDir, credentials);
+                if (decryptedEntries.failed.length) {
+                    throw new errors_1.EntryDecryptionError(decryptedEntries.failed.at(0), environment);
+                }
+                credentialPayload = JSON.stringify({
+                    ...decryptedEntries.successful,
+                    unitoCredentialId: flags['test-account'],
+                    unitoUserId: flags['test-account'],
+                });
+            }
+        }
+        // Load secrets — identical to dev.ts
+        const { successful: secrets, failed: failedSecrets } = await (0, decryption_1.decryptEntries)(configuration.name, environment, this.config.configDir, configuration.secrets ?? {});
+        if (failedSecrets.length) {
+            throw new errors_1.EntryDecryptionError(failedSecrets.at(0), environment);
+        }
+        // Build Unito request headers.
+        // Encoding: base64(JSON.stringify(payload)) — same as integrationDebugger/src/services/crawlerDriver.ts line 424.
+        const headers = {
+            'X-Unito-Credentials': Buffer.from(credentialPayload).toString('base64'),
+            'X-Unito-Secrets': Buffer.from(JSON.stringify(secrets)).toString('base64'),
+            'X-Unito-Correlation-Id': crypto_1.default.randomUUID(),
+            'Content-Type': 'application/json',
+        };
+        const url = `http://localhost:${flags.port}${flags.path}`;
+        const response = await fetch(url, { headers });
+        if (!response.ok) {
+            const body = await response.json().catch(() => undefined);
+            if (body !== undefined) {
+                this.logToStderr(JSON.stringify(body, null, 2));
+            }
+            this.error(`HTTP ${response.status} from ${url}`, { exit: response.status });
+        }
+        const body = (await response.json());
+        const json = JSON.stringify(body, null, 2);
+        if (flags.output) {
+            await fs_1.default.promises.writeFile(flags.output, json, 'utf8');
+        }
+        else {
+            this.log(json);
+        }
+    }
+}
+exports.default = Graph;

package/dist/src/commands/schema-snapshot.d.ts

@@ -0,0 +1,9 @@
+import { FlagInput } from '@oclif/core/lib/interfaces/parser';
+import { BaseCommand } from '../baseCommand';
+export default class SchemaSnapshot extends BaseCommand<typeof SchemaSnapshot> {
+    static description: string;
+    static examples: string[];
+    static flags: FlagInput;
+    catch(error: Error): Promise<void>;
+    run(): Promise<void>;
+}

package/dist/src/commands/schema-snapshot.js

@@ -0,0 +1,425 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const child_process_1 = tslib_1.__importDefault(require("child_process"));
+const fs_1 = tslib_1.__importDefault(require("fs"));
+const os_1 = tslib_1.__importDefault(require("os"));
+const path_1 = tslib_1.__importDefault(require("path"));
+const core_1 = require("@oclif/core");
+const chalk_1 = tslib_1.__importDefault(require("chalk"));
+const baseCommand_1 = require("../baseCommand");
+const errors_1 = require("../errors");
+const configuration_1 = require("../resources/configuration");
+const coverageCalculator_1 = require("../resources/coverageCalculator");
+const decryption_1 = require("../resources/decryption");
+const fieldExtractor_1 = require("../resources/fieldExtractor");
+const GlobalConfiguration = tslib_1.__importStar(require("../resources/globalConfiguration"));
+const integrations_1 = require("../resources/integrations");
+const jsonlReader_1 = require("../resources/jsonlReader");
+class SchemaSnapshot extends baseCommand_1.BaseCommand {
+    static description = 'Generate a schema snapshot by crawling the integration graph';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --output=./schema-snapshot.json',
+        '<%= config.bin %> <%= command.id %> --output=./schema-snapshot.json --diff=./previous-snapshot.json',
+    ];
+    static flags = {
+        output: core_1.Flags.string({
+            description: 'path to write the schema snapshot',
+            required: true,
+        }),
+        diff: core_1.Flags.string({
+            description: 'path to a previous snapshot for comparison',
+        }),
+        environment: core_1.Flags.custom({
+            description: 'the environment of the platform',
+            options: Object.values(GlobalConfiguration.Environment),
+            default: GlobalConfiguration.Environment.Production,
+        })(),
+        'test-account': core_1.Flags.string({
+            description: 'test account to use',
+            default: configuration_1.CredentialScope.DEVELOPMENT,
+        }),
+        'config-path': core_1.Flags.string({
+            description: 'relative path to a custom ".unito.json" file',
+        }),
+        'skip-install': core_1.Flags.boolean({
+            description: 'skip npm install before starting',
+            default: false,
+        }),
+        strict: core_1.Flags.boolean({
+            description: 'fail if any fields are unmapped and not in the allowlist',
+            default: false,
+        }),
+    };
+    async catch(error) {
+        if ((0, errors_1.handleError)(this, error)) {
+            this.exit(-1);
+        }
+        throw error;
+    }
+    async run() {
+        (0, integrations_1.validateIsIntegrationDirectory)();
+        const { flags } = await this.parse(SchemaSnapshot);
+        const environment = flags.environment ?? GlobalConfiguration.Environment.Production;
+        const config = await (0, configuration_1.getConfiguration)(environment, flags['config-path']);
+        if (!flags['skip-install']) {
+            core_1.ux.action.start('Installing NPM dependencies', undefined, { stdout: true });
+            child_process_1.default.execSync('npm install', {
+                env: { ...process.env, NODE_ENV: 'development' },
+                stdio: ['ignore', 'ignore', 'inherit'],
+            });
+            core_1.ux.action.stop();
+        }
+        // Resolve credentials.
+        const testAccount = flags['test-account'];
+        const credentials = config.testAccounts?.[testAccount] || {};
+        const decryptedCreds = await (0, decryption_1.decryptEntries)(config.name, environment, this.config.configDir, credentials);
+        if (decryptedCreds.failed.length) {
+            throw new errors_1.EntryDecryptionError(decryptedCreds.failed.at(0), environment);
+        }
+        const credentialPayload = {
+            ...decryptedCreds.successful,
+            unitoCredentialId: flags['test-account'],
+            unitoUserId: flags['test-account'],
+        };
+        // Load secrets.
+        const { successful: secrets, failed: failedSecrets } = await (0, decryption_1.decryptEntries)(config.name, environment, this.config.configDir, config.secrets ?? {});
+        if (failedSecrets.length) {
+            throw new errors_1.EntryDecryptionError(failedSecrets.at(0), environment);
+        }
+        core_1.ux.action.start('Starting integration', undefined, { stdout: true });
+        const integrationPort = '9200';
+        let modernProcess;
+        const recordingPath = path_1.default.join(os_1.default.tmpdir(), `schema-snapshot-recording-${Date.now()}.jsonl`);
+        // Pre-create recording file with restrictive permissions (owner-only read/write).
+        fs_1.default.writeFileSync(recordingPath, '', { mode: 0o600 });
+        try {
+            modernProcess = child_process_1.default.spawn('npm', ['run', 'dev'], {
+                detached: false,
+                stdio: 'ignore',
+                env: {
+                    ...process.env,
+                    NODE_ENV: 'development',
+                    PORT: integrationPort,
+                    UNITO_SCHEMA_SNAPSHOT_RECORD_PATH: recordingPath,
+                },
+            });
+            await new Promise(resolve => setTimeout(resolve, 3000));
+            core_1.ux.action.stop();
+            // Load allowlist if present.
+            const allowlistPath = path_1.default.join(process.cwd(), '.schema-snapshot-ignore');
+            let allowlistConfig = {};
+            if (fs_1.default.existsSync(allowlistPath)) {
+                try {
+                    allowlistConfig = JSON.parse(fs_1.default.readFileSync(allowlistPath, 'utf-8'));
+                }
+                catch (err) {
+                    core_1.ux.log(chalk_1.default.yellow(`Warning: Failed to parse ${allowlistPath}, ignoring allowlist. ${err}`));
+                }
+            }
+            // Create crawler in sample mode (read-only, limited items).
+            const { createWithDirectCrawler, Operation } = await Promise.resolve().then(() => tslib_1.__importStar(require('@unito/integration-debugger/dist/src/services/crawlerDriver')));
+            const crawlerDriver = await createWithDirectCrawler(`http://localhost:${integrationPort}`, config.graphRelativeUrl ?? '/', config.credentialAccountRelativeUrl ?? '/me', config.webhookParsingRelativeUrl ?? undefined, config.webhookSubscriptionsRelativeUrl ?? undefined, config.webhookAcknowledgeRelativeUrl ?? undefined, credentialPayload, secrets, {
+                readOnly: true,
+                timeout: 20,
+                [Operation.GetCollection]: {
+                    itemsPerPage: 1,
+                    followNextPage: false,
+                },
+            });
+            // Only crawl graph structure, skip all step checks.
+            crawlerDriver.stepCheckKeys = [];
+            const credentialAccountPath = config.credentialAccountRelativeUrl ?? '/me';
+            crawlerDriver.startFrom(makeCrawlerStep(credentialAccountPath, Operation.GetCredentialAccount));
+            core_1.ux.action.start('Crawling credential account', undefined, { stdout: true });
+            await crawlerDriver.next();
+            core_1.ux.action.stop();
+            const startingPath = config.graphRelativeUrl ?? '/';
+            crawlerDriver.startFrom(makeCrawlerStep(startingPath, Operation.GetItem));
+            core_1.ux.action.start('Crawling graph for schemas', undefined, { stdout: true });
+            const resources = [];
+            let step = await crawlerDriver.next();
+            let lastSeq = 0;
+            // Raw API responses keyed by schemaPath (the relation collection path they belong to).
+            const rawResponsesBySchemaPath = new Map();
+            while (step) {
+                const payload = step.payloadOut;
+                if (step.operation === Operation.GetItem && payload?.relations) {
+                    const relations = payload.relations;
+                    const relationSnapshots = relations.map(rel => ({
+                        name: rel.name,
+                        path: rel.path,
+                        label: rel.label,
+                        semantic: rel.semantic,
+                        canCreateItem: rel.schema.canCreateItem,
+                        fields: normalizeFields(rel.schema.fields ?? []),
+                    }));
+                    relationSnapshots.sort((a, b) => a.name.localeCompare(b.name));
+                    resources.push({
+                        path: step.path,
+                        operation: step.operation,
+                        schemaPath: step.schemaPath,
+                        relations: relationSnapshots,
+                    });
+                }
+                // Read raw API responses recorded during this step.
+                const { entries: newEntries, lastSeq: newLastSeq } = (0, jsonlReader_1.readNewEntries)(recordingPath, lastSeq);
+                lastSeq = newLastSeq;
+                // Associate raw responses with their schemaPath (the relation's collection path).
+                // This links item-level API calls (e.g. /pokemons/bulbasaur) back to the relation
+                // schema defined on the parent resource (e.g. the "pokemons" relation at /).
+                if (step.operation === Operation.GetItem && step.schemaPath && newEntries.length > 0) {
+                    const existing = rawResponsesBySchemaPath.get(step.schemaPath) ?? [];
+                    existing.push(...newEntries.map(e => ({ url: e.url, body: e.body })));
+                    rawResponsesBySchemaPath.set(step.schemaPath, existing);
+                }
+                step = await crawlerDriver.next();
+            }
+            core_1.ux.action.stop();
+            // Sort resources by path for deterministic output.
+            resources.sort((a, b) => a.path.localeCompare(b.path));
+            // Compute coverage for each relation using raw API responses.
+            // Raw responses are keyed by schemaPath — each relation's `path` is the schemaPath
+            // for items crawled under that relation.
+            for (const resource of resources) {
+                for (const relation of resource.relations) {
+                    const rawResponses = rawResponsesBySchemaPath.get(relation.path) ?? [];
+                    if (rawResponses.length === 0)
+                        continue;
+                    // Combine fields from all raw API responses for this relation.
+                    const allRawFields = new Set();
+                    const endpoints = [];
+                    for (const resp of rawResponses) {
+                        for (const field of (0, fieldExtractor_1.extractFields)(resp.body)) {
+                            allRawFields.add(field);
+                        }
+                        endpoints.push(resp.url);
+                    }
+                    const key = relationKey(resource.path, relation.name);
+                    const allowlist = allowlistConfig[key]?.unmapped ?? [];
+                    const relFieldNames = relation.fields.map(f => f.name);
+                    const rawFieldsArray = [...allRawFields];
+                    const coverageResult = (0, coverageCalculator_1.computeCoverage)(rawFieldsArray, relFieldNames);
+                    // Apply allowlist to filter intentionally unmapped fields.
+                    const filteredUnmapped = (0, coverageCalculator_1.applyAllowlist)(coverageResult.unmappedFields, allowlist);
+                    // Recalculate coverage after allowlist.
+                    const effectiveMapped = rawFieldsArray.length - filteredUnmapped.length;
+                    const effectiveCoveragePercent = rawFieldsArray.length > 0 ? Math.round((effectiveMapped / rawFieldsArray.length) * 100) : 100;
+                    relation.coverage = {
+                        rawApiFields: coverageResult.rawApiFields,
+                        mappedFields: coverageResult.mappedFields,
+                        unmappedFields: filteredUnmapped,
+                        coveragePercent: effectiveCoveragePercent,
+                        rawApiEndpoints: [...new Set(endpoints)],
+                    };
+                }
+            }
+            const snapshot = {
+                generatedAt: new Date().toISOString(),
+                resources,
+            };
+            fs_1.default.writeFileSync(flags.output, JSON.stringify(snapshot, null, 2));
+            core_1.ux.log(chalk_1.default.green(`\nSnapshot written to ${flags.output}`));
+            core_1.ux.log(chalk_1.default.gray(`  ${resources.length} resource(s), ${resources.reduce((sum, r) => sum + r.relations.length, 0)} relation(s)`));
+            // Display coverage summary.
+            const relationsWithCoverage = resources.flatMap(r => r.relations).filter(rel => rel.coverage);
+            if (relationsWithCoverage.length > 0) {
+                core_1.ux.log(chalk_1.default.bold('\nCoverage Summary'));
+                core_1.ux.log(chalk_1.default.bold('================\n'));
+                for (const rel of relationsWithCoverage) {
+                    const cov = rel.coverage;
+                    const color = coverageColor(cov.coveragePercent);
+                    core_1.ux.log(`  ${rel.name}: ${color(`${cov.coveragePercent}%`)} (${cov.mappedFields.length}/${cov.rawApiFields.length} fields)`);
+                    if (cov.unmappedFields.length > 0) {
+                        core_1.ux.log(chalk_1.default.gray(`    unmapped: ${cov.unmappedFields.slice(0, 10).join(', ')}${cov.unmappedFields.length > 10 ? ` (+${cov.unmappedFields.length - 10} more)` : ''}`));
+                    }
+                }
+            }
+            // Strict mode: fail if any unmapped fields remain after allowlist.
+            if (flags.strict) {
+                const failures = relationsWithCoverage.filter(rel => rel.coverage.unmappedFields.length > 0);
+                if (failures.length > 0) {
+                    core_1.ux.log(chalk_1.default.red('\n--strict: unmapped fields detected\n'));
+                    for (const rel of failures) {
+                        core_1.ux.log(chalk_1.default.red(`  ${rel.name}: ${rel.coverage.unmappedFields.length} unmapped fields`));
+                    }
+                    core_1.ux.log(chalk_1.default.yellow('\nAdd missing fields to the schema or justify them in .schema-snapshot-ignore'));
+                    this.exit(1);
+                }
+            }
+            // Diff against previous snapshot if requested.
+            if (flags.diff) {
+                const diffPath = flags.diff;
+                if (!fs_1.default.existsSync(diffPath)) {
+                    core_1.ux.log(chalk_1.default.yellow(`\nDiff file not found: ${diffPath}`));
+                }
+                else {
+                    const previousRaw = fs_1.default.readFileSync(diffPath, 'utf-8');
+                    const previous = JSON.parse(previousRaw);
+                    const diff = diffSnapshots(previous, snapshot);
+                    core_1.ux.log(chalk_1.default.bold('\nSchema Diff'));
+                    core_1.ux.log(chalk_1.default.bold('===========\n'));
+                    if (diff.added.length === 0 && diff.removed.length === 0 && diff.changed.length === 0) {
+                        core_1.ux.log(chalk_1.default.green('No differences found.'));
+                    }
+                    else {
+                        for (const added of diff.added) {
+                            core_1.ux.log(chalk_1.default.green(`  + ${added}`));
+                        }
+                        for (const removed of diff.removed) {
+                            core_1.ux.log(chalk_1.default.red(`  - ${removed}`));
+                        }
+                        for (const changed of diff.changed) {
+                            core_1.ux.log(chalk_1.default.yellow(`  ~ ${changed.path}: ${changed.details}`));
+                        }
+                        core_1.ux.log(`\n  ${chalk_1.default.green(`${diff.added.length} added`)}, ${chalk_1.default.red(`${diff.removed.length} removed`)}, ${chalk_1.default.yellow(`${diff.changed.length} changed`)}`);
+                    }
+                    if (diff.coverageChanges.length > 0) {
+                        core_1.ux.log(chalk_1.default.bold('\nCoverage Changes'));
+                        core_1.ux.log(chalk_1.default.bold('================\n'));
+                        for (const change of diff.coverageChanges) {
+                            const color = change.details.startsWith('↓') ? chalk_1.default.red : chalk_1.default.green;
+                            core_1.ux.log(color(`  ${change.path}: ${change.details}`));
+                        }
+                    }
+                }
+            }
+        }
+        finally {
+            modernProcess?.kill('SIGTERM');
+            try {
+                fs_1.default.unlinkSync(recordingPath);
+            }
+            catch {
+                /* Best-effort cleanup. */
+            }
+        }
+    }
+}
+exports.default = SchemaSnapshot;
+function relationKey(resourcePath, relationName) {
+    return `${resourcePath} → ${relationName}`;
+}
+function makeCrawlerStep(stepPath, operation) {
+    return {
+        path: stepPath,
+        operation,
+        schemaPath: undefined,
+        parentOperation: undefined,
+        parentPath: undefined,
+        requestSchema: undefined,
+        warnings: [],
+        errors: [],
+    };
+}
+function coverageColor(percent) {
+    if (percent >= 80)
+        return chalk_1.default.green;
+    if (percent >= 50)
+        return chalk_1.default.yellow;
+    return chalk_1.default.red;
+}
+const OPTIONAL_FIELD_KEYS = [
+    'semantic',
+    'nullable',
+    'isArray',
+    'canSetOnCreate',
+    'canSetOnUpdate',
+    'readOnly',
+];
+function normalizeFields(fields) {
+    return fields
+        .map(f => {
+        const snapshot = {
+            name: f.name,
+            type: f.type,
+        };
+        for (const key of OPTIONAL_FIELD_KEYS) {
+            if (f[key] !== undefined) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                snapshot[key] = f[key];
+            }
+        }
+        return snapshot;
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+function diffSnapshots(previous, current) {
+    const result = { added: [], removed: [], changed: [], coverageChanges: [] };
+    const prevMap = buildSchemaMap(previous);
+    const currMap = buildSchemaMap(current);
+    const allKeys = new Set([...prevMap.keys(), ...currMap.keys()]);
+    for (const key of allKeys) {
+        const prev = prevMap.get(key);
+        const curr = currMap.get(key);
+        if (!prev && curr) {
+            result.added.push(key);
+        }
+        else if (prev && !curr) {
+            result.removed.push(key);
+        }
+        else if (prev && curr) {
+            const prevFields = new Set(prev);
+            const currFields = new Set(curr);
+            const addedFields = [...currFields].filter(f => !prevFields.has(f));
+            const removedFields = [...prevFields].filter(f => !currFields.has(f));
+            if (addedFields.length > 0 || removedFields.length > 0) {
+                const details = [];
+                if (addedFields.length > 0)
+                    details.push(`+fields: ${addedFields.join(', ')}`);
+                if (removedFields.length > 0)
+                    details.push(`-fields: ${removedFields.join(', ')}`);
+                result.changed.push({ path: key, details: details.join('; ') });
+            }
+        }
+    }
+    // Coverage changes.
+    const prevCoverageMap = buildCoverageMap(previous);
+    const currCoverageMap = buildCoverageMap(current);
+    const allCoverageKeys = new Set([...prevCoverageMap.keys(), ...currCoverageMap.keys()]);
+    for (const key of allCoverageKeys) {
+        const prev = prevCoverageMap.get(key);
+        const curr = currCoverageMap.get(key);
+        if (prev && curr && prev.coveragePercent !== curr.coveragePercent) {
+            const direction = curr.coveragePercent > prev.coveragePercent ? '↑' : '↓';
+            const newUnmapped = curr.unmappedFields.filter(f => !prev.unmappedFields.includes(f));
+            const newlyMapped = prev.unmappedFields.filter(f => !curr.unmappedFields.includes(f));
+            let details = `${direction} coverage ${prev.coveragePercent}% → ${curr.coveragePercent}%`;
+            const annotations = [];
+            if (newUnmapped.length > 0)
+                annotations.push(`new unmapped: ${newUnmapped.join(', ')}`);
+            if (newlyMapped.length > 0)
+                annotations.push(`newly mapped: ${newlyMapped.join(', ')}`);
+            if (annotations.length > 0)
+                details += ` (${annotations.join(', ')})`;
+            result.coverageChanges.push({ path: key, details });
+        }
+        else if (!prev && curr) {
+            result.coverageChanges.push({
+                path: key,
+                details: `new coverage data: ${curr.coveragePercent}% (${curr.unmappedFields.length} unmapped)`,
+            });
+        }
+    }
+    return result;
+}
+function buildCoverageMap(snapshot) {
+    const map = new Map();
+    for (const resource of snapshot.resources) {
+        for (const relation of resource.relations) {
+            if (relation.coverage) {
+                map.set(relationKey(resource.path, relation.name), relation.coverage);
+            }
+        }
+    }
+    return map;
+}
+function buildSchemaMap(snapshot) {
+    const map = new Map();
+    for (const resource of snapshot.resources) {
+        for (const relation of resource.relations) {
+            map.set(relationKey(resource.path, relation.name), relation.fields.map(f => f.name));
+        }
+    }
+    return map;
+}