@unito/integration-cli 0.64.6 → 0.66.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/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,432 @@
+"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,
+        }),
+        port: core_1.Flags.integer({
+            description: 'port to start the integration on (default: 9200)',
+            default: 9200,
+        }),
+    };
+    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 = String(flags.port);
+        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: 5,
+                    followNextPage: false,
+                },
+                retryOnEmptyRelation: {
+                    maxSiblings: 3,
+                },
+            });
+            // 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;
+}

package/dist/src/resources/coverageCalculator.d.ts

@@ -0,0 +1,12 @@
+export interface CoverageResult {
+    rawApiFields: string[];
+    mappedFields: string[];
+    unmappedFields: string[];
+    coveragePercent: number;
+}
+export interface AllowlistEntry {
+    field: string;
+    reason: string;
+}
+export declare function computeCoverage(rawApiFields: string[], schemaFields: string[]): CoverageResult;
+export declare function applyAllowlist(unmappedFields: string[], allowlist: AllowlistEntry[]): string[];

package/dist/src/resources/coverageCalculator.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeCoverage = computeCoverage;
+exports.applyAllowlist = applyAllowlist;
+function computeCoverage(rawApiFields, schemaFields) {
+    if (rawApiFields.length === 0) {
+        return { rawApiFields: [], mappedFields: [], unmappedFields: [], coveragePercent: 100 };
+    }
+    const schemaSet = new Set(schemaFields);
+    const mapped = [];
+    const unmapped = [];
+    for (const field of [...rawApiFields].sort()) {
+        if (schemaSet.has(field)) {
+            mapped.push(field);
+        }
+        else {
+            unmapped.push(field);
+        }
+    }
+    const coveragePercent = Math.round((mapped.length / rawApiFields.length) * 100);
+    return {
+        rawApiFields: [...rawApiFields].sort(),
+        mappedFields: mapped,
+        unmappedFields: unmapped,
+        coveragePercent,
+    };
+}
+function applyAllowlist(unmappedFields, allowlist) {
+    if (allowlist.length === 0)
+        return [...unmappedFields].sort();
+    return unmappedFields
+        .filter(field => {
+        return !allowlist.some(entry => matchPattern(field, entry.field));
+    })
+        .sort();
+}
+// Matches dot-notation field paths against allowlist patterns:
+//   "priority"    → exact match
+//   "metadata.*"  → matches one level (metadata.created_at, not metadata.a.b)
+//   "meta.**"     → matches any depth (meta.a, meta.a.b, meta.a.b.c)
+function matchPattern(field, pattern) {
+    if (pattern.endsWith('.**')) {
+        return field.startsWith(pattern.slice(0, -2));
+    }
+    if (pattern.endsWith('.*')) {
+        const prefix = pattern.slice(0, -1);
+        return field.startsWith(prefix) && !field.slice(prefix.length).includes('.');
+    }
+    return field === pattern;
+}

package/dist/src/resources/fieldExtractor.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Recursively extract field paths from a JSON body using dot notation.
+ * Arrays of objects: extract keys from first element.
+ * Top-level arrays: extract from first item.
+ * Returns sorted, unique field paths.
+ */
+export declare function extractFields(body: unknown): string[];

package/dist/src/resources/fieldExtractor.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractFields = extractFields;
+/**
+ * Recursively extract field paths from a JSON body using dot notation.
+ * Arrays of objects: extract keys from first element.
+ * Top-level arrays: extract from first item.
+ * Returns sorted, unique field paths.
+ */
+function extractFields(body) {
+    if (body == null)
+        return [];
+    if (Array.isArray(body)) {
+        if (body.length === 0)
+            return [];
+        if (typeof body[0] === 'object' && body[0] !== null) {
+            return extractFields(body[0]);
+        }
+        return [];
+    }
+    if (typeof body !== 'object')
+        return [];
+    const fields = new Set();
+    collectFields(body, '', fields);
+    return [...fields].sort();
+}
+function collectFields(obj, prefix, fields) {
+    for (const key of Object.keys(obj)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        const value = obj[key];
+        if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            fields.add(path);
+            collectFields(value, path, fields);
+        }
+        else if (Array.isArray(value)) {
+            fields.add(path);
+            if (value.length > 0 && typeof value[0] === 'object' && value[0] !== null) {
+                collectFields(value[0], path, fields);
+            }
+        }
+        else {
+            fields.add(path);
+        }
+    }
+}

package/dist/src/resources/jsonlReader.d.ts

@@ -0,0 +1,11 @@
+export interface RawResponseEntry {
+    seq: number;
+    url: string;
+    method: string;
+    status: number;
+    body: unknown;
+}
+export declare function readNewEntries(filePath: string, afterSeq: number): {
+    entries: RawResponseEntry[];
+    lastSeq: number;
+};

package/dist/src/resources/jsonlReader.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readNewEntries = readNewEntries;
+const tslib_1 = require("tslib");
+const fs_1 = tslib_1.__importDefault(require("fs"));
+function readNewEntries(filePath, afterSeq) {
+    if (!fs_1.default.existsSync(filePath)) {
+        return { entries: [], lastSeq: afterSeq };
+    }
+    const content = fs_1.default.readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n').filter(line => line.trim().length > 0);
+    const entries = [];
+    let lastSeq = afterSeq;
+    for (const line of lines) {
+        try {
+            const entry = JSON.parse(line);
+            if (entry.seq > afterSeq) {
+                entries.push(entry);
+                if (entry.seq > lastSeq) {
+                    lastSeq = entry.seq;
+                }
+            }
+        }
+        catch {
+            // Skip malformed lines.
+        }
+    }
+    return { entries, lastSeq };
+}

package/dist/test/resources/coverageCalculator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/resources/coverageCalculator.test.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const strict_1 = tslib_1.__importDefault(require("node:assert/strict"));
+const coverageCalculator_1 = require("../../src/resources/coverageCalculator");
+describe('computeCoverage', () => {
+    it('computes coverage for fully mapped fields', () => {
+        const rawApiFields = ['id', 'name', 'status'];
+        const schemaFields = ['id', 'name', 'status'];
+        const result = (0, coverageCalculator_1.computeCoverage)(rawApiFields, schemaFields);
+        strict_1.default.deepEqual(result.mappedFields, ['id', 'name', 'status']);
+        strict_1.default.deepEqual(result.unmappedFields, []);
+        strict_1.default.equal(result.coveragePercent, 100);
+    });
+    it('computes coverage with unmapped fields', () => {
+        const rawApiFields = ['id', 'name', 'status', 'priority', 'created_at'];
+        const schemaFields = ['id', 'name', 'status'];
+        const result = (0, coverageCalculator_1.computeCoverage)(rawApiFields, schemaFields);
+        strict_1.default.deepEqual(result.mappedFields, ['id', 'name', 'status']);
+        strict_1.default.deepEqual(result.unmappedFields, ['created_at', 'priority']);
+        strict_1.default.equal(result.coveragePercent, 60);
+    });
+    it('handles no raw API fields', () => {
+        const result = (0, coverageCalculator_1.computeCoverage)([], ['id', 'name']);
+        strict_1.default.deepEqual(result.mappedFields, []);
+        strict_1.default.deepEqual(result.unmappedFields, []);
+        strict_1.default.equal(result.coveragePercent, 100);
+    });
+    it('handles no schema fields', () => {
+        const result = (0, coverageCalculator_1.computeCoverage)(['id', 'name'], []);
+        strict_1.default.deepEqual(result.mappedFields, []);
+        strict_1.default.deepEqual(result.unmappedFields, ['id', 'name']);
+        strict_1.default.equal(result.coveragePercent, 0);
+    });
+    it('matches nested dot-notation fields against flat schema names', () => {
+        const rawApiFields = ['id', 'assignee', 'assignee.id', 'assignee.name'];
+        const schemaFields = ['id', 'assignee'];
+        const result = (0, coverageCalculator_1.computeCoverage)(rawApiFields, schemaFields);
+        strict_1.default.deepEqual(result.mappedFields, ['assignee', 'id']);
+        strict_1.default.deepEqual(result.unmappedFields, ['assignee.id', 'assignee.name']);
+        strict_1.default.equal(result.coveragePercent, 50);
+    });
+});
+describe('applyAllowlist', () => {
+    it('suppresses exact field matches', () => {
+        const unmappedFields = ['priority', 'created_at', 'labels'];
+        const allowlist = [{ field: 'priority', reason: 'Not useful' }];
+        const result = (0, coverageCalculator_1.applyAllowlist)(unmappedFields, allowlist);
+        strict_1.default.deepEqual(result, ['created_at', 'labels']);
+    });
+    it('suppresses glob patterns with *', () => {
+        const unmappedFields = ['metadata', 'metadata.created_at', 'metadata.updated_at', 'labels'];
+        const allowlist = [{ field: 'metadata.*', reason: 'Internal tracking' }];
+        const result = (0, coverageCalculator_1.applyAllowlist)(unmappedFields, allowlist);
+        strict_1.default.deepEqual(result, ['labels', 'metadata']);
+    });
+    it('suppresses glob patterns with **', () => {
+        const unmappedFields = ['meta', 'meta.a', 'meta.b.c', 'meta.b.c.d', 'name'];
+        const allowlist = [{ field: 'meta.**', reason: 'All metadata' }];
+        const result = (0, coverageCalculator_1.applyAllowlist)(unmappedFields, allowlist);
+        strict_1.default.deepEqual(result, ['meta', 'name']);
+    });
+    it('returns all fields when allowlist is empty', () => {
+        const unmappedFields = ['a', 'b', 'c'];
+        strict_1.default.deepEqual((0, coverageCalculator_1.applyAllowlist)(unmappedFields, []), ['a', 'b', 'c']);
+    });
+    it('sorts output even with empty allowlist', () => {
+        const unmappedFields = ['z', 'a', 'name'];
+        strict_1.default.deepEqual((0, coverageCalculator_1.applyAllowlist)(unmappedFields, []), ['a', 'name', 'z']);
+    });
+});

package/dist/test/resources/fieldExtractor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/resources/fieldExtractor.test.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const strict_1 = tslib_1.__importDefault(require("node:assert/strict"));
+const fieldExtractor_1 = require("../../src/resources/fieldExtractor");
+describe('extractFields', () => {
+    it('extracts top-level primitive fields', () => {
+        const body = { id: '123', name: 'Task', status: 'open' };
+        strict_1.default.deepEqual((0, fieldExtractor_1.extractFields)(body), ['id', 'name', 'status']);
+    });
+    it('extracts nested object fields with dot notation', () => {
+        const body = { id: '123', assignee: { id: '456', name: 'Alice' } };
+        strict_1.default.deepEqual((0, fieldExtractor_1.extractFields)(body), ['assignee', 'assignee.id', 'assignee.name', 'id']);
+    });
+    it('extracts deeply nested fields', () => {
+        const body = { meta: { creator: { id: '1', name: 'Bob' } } };
+        strict_1.default.deepEqual((0, fieldExtractor_1.extractFields)(body), ['meta', 'meta.creator', 'meta.creator.id', 'meta.creator.name']);
+    });
+    it('handles arrays of primitives as a single field', () => {
+        const body = { id: '123', labels: ['bug', 'urgent'] };
+        strict_1.default.deepEqual((0, fieldExtractor_1.extractFields)(body), ['id', 'labels']);
+    });
+    it('extracts fields from first item of array of objects', () => {
+        const body = { id: '123', items: [{ name: 'A', value: 1 }, { name: 'B' }] };
+        strict_1.default.deepEqual((0, fieldExtractor_1.extractFields)(body), ['id', 'items', 'items.name', 'items.value']);
+    });
+    it('handles top-level array by extracting from first item', () => {
+        const body = [{ id: '1', name: 'Task' }, { id: '2' }];
+        strict_1.default.deepEqual((0, fieldExtractor_1.extractFields)(body), ['id', 'name']);
+    });
+    it('returns empty array for null/undefined', () => {
+        strict_1.default.deepEqual((0, fieldExtractor_1.extractFields)(null), []);
+        strict_1.default.deepEqual((0, fieldExtractor_1.extractFields)(undefined), []);
+    });
+    it('returns empty array for empty object', () => {
+        strict_1.default.deepEqual((0, fieldExtractor_1.extractFields)({}), []);
+    });
+    it('returns empty array for empty array', () => {
+        strict_1.default.deepEqual((0, fieldExtractor_1.extractFields)([]), []);
+    });
+    it('handles mixed nested structures', () => {
+        const body = {
+            id: '123',
+            owner: { id: '456', profile: { avatar: 'url', bio: 'hello' } },
+            tags: ['a', 'b'],
+            settings: { color: 'blue' },
+        };
+        strict_1.default.deepEqual((0, fieldExtractor_1.extractFields)(body), [
+            'id',
+            'owner',
+            'owner.id',
+            'owner.profile',
+            'owner.profile.avatar',
+            'owner.profile.bio',
+            'settings',
+            'settings.color',
+            'tags',
+        ]);
+    });
+});

package/dist/test/resources/jsonlReader.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/resources/jsonlReader.test.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const strict_1 = tslib_1.__importDefault(require("node:assert/strict"));
+const fs_1 = tslib_1.__importDefault(require("fs"));
+const tmp_1 = tslib_1.__importDefault(require("tmp"));
+const jsonlReader_1 = require("../../src/resources/jsonlReader");
+describe('readNewEntries', () => {
+    let tempFile;
+    beforeEach(() => {
+        tempFile = tmp_1.default.fileSync({ postfix: '.jsonl' });
+    });
+    afterEach(() => {
+        tempFile.removeCallback();
+    });
+    it('reads all entries from a new file', () => {
+        const entries = [
+            { seq: 1, url: 'https://api.example.com/items', method: 'GET', status: 200, body: { id: '1', name: 'A' } },
+            {
+                seq: 2,
+                url: 'https://api.example.com/items/1',
+                method: 'GET',
+                status: 200,
+                body: { id: '1', name: 'A', desc: 'B' },
+            },
+        ];
+        fs_1.default.writeFileSync(tempFile.name, entries.map(e => JSON.stringify(e)).join('\n') + '\n');
+        const result = (0, jsonlReader_1.readNewEntries)(tempFile.name, 0);
+        strict_1.default.equal(result.entries.length, 2);
+        strict_1.default.equal(result.entries[0].seq, 1);
+        strict_1.default.equal(result.entries[1].seq, 2);
+        strict_1.default.equal(result.lastSeq, 2);
+    });
+    it('reads only entries after a given seq', () => {
+        const entries = [
+            { seq: 1, url: 'https://api.example.com/a', method: 'GET', status: 200, body: {} },
+            { seq: 2, url: 'https://api.example.com/b', method: 'GET', status: 200, body: {} },
+            { seq: 3, url: 'https://api.example.com/c', method: 'GET', status: 200, body: {} },
+        ];
+        fs_1.default.writeFileSync(tempFile.name, entries.map(e => JSON.stringify(e)).join('\n') + '\n');
+        const result = (0, jsonlReader_1.readNewEntries)(tempFile.name, 1);
+        strict_1.default.equal(result.entries.length, 2);
+        strict_1.default.equal(result.entries[0].seq, 2);
+        strict_1.default.equal(result.lastSeq, 3);
+    });
+    it('returns empty when no new entries', () => {
+        const entries = [
+            { seq: 1, url: 'https://api.example.com/a', method: 'GET', status: 200, body: {} },
+        ];
+        fs_1.default.writeFileSync(tempFile.name, entries.map(e => JSON.stringify(e)).join('\n') + '\n');
+        const result = (0, jsonlReader_1.readNewEntries)(tempFile.name, 1);
+        strict_1.default.equal(result.entries.length, 0);
+        strict_1.default.equal(result.lastSeq, 1);
+    });
+    it('returns empty when file does not exist', () => {
+        const result = (0, jsonlReader_1.readNewEntries)('/nonexistent/path.jsonl', 0);
+        strict_1.default.equal(result.entries.length, 0);
+        strict_1.default.equal(result.lastSeq, 0);
+    });
+    it('skips malformed lines gracefully', () => {
+        fs_1.default.writeFileSync(tempFile.name, '{"seq":1,"url":"a","method":"GET","status":200,"body":{}}\nnot-json\n{"seq":2,"url":"b","method":"GET","status":200,"body":{}}\n');
+        const result = (0, jsonlReader_1.readNewEntries)(tempFile.name, 0);
+        strict_1.default.equal(result.entries.length, 2);
+        strict_1.default.equal(result.lastSeq, 2);
+    });
+});

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/baseCommand.ts","../src/configurationTypes.ts","../src/errors.ts","../src/index.ts","../src/commands/activity.ts","../src/commands/dev.ts","../src/commands/encrypt.ts","../src/commands/graph.ts","../src/commands/init.ts","../src/commands/invite.ts","../src/commands/login.ts","../src/commands/oauth2.ts","../src/commands/publish.ts","../src/commands/test.ts","../src/commands/upgrade.ts","../src/hooks/init/displayLogo.ts","../src/hooks/init/updateNotifier.ts","../src/resources/configuration.ts","../src/resources/credentials.ts","../src/resources/decryption.ts","../src/resources/fileSystem.ts","../src/resources/globalConfiguration.ts","../src/resources/integrations.ts","../src/resources/integrationsPlatform.ts","../src/resources/oauth2.ts","../src/resources/template.ts","../src/services/integrationsPlatform.ts","../src/services/integrationsPlatformClient.ts","../src/services/oauth2.ts","../test/errors.test.ts","../test/commands/activity.test.ts","../test/commands/dev.test.ts","../test/commands/encrypt.test.ts","../test/commands/graph.test.ts","../test/commands/init.test.ts","../test/commands/invite.test.ts","../test/commands/login.test.ts","../test/commands/oauth2.test.ts","../test/commands/publish.test.ts","../test/commands/test.test.ts","../test/commands/upgrade.test.ts","../test/helpers/init.js","../test/helpers/integrations.ts","../test/helpers/styles.ts","../test/hooks/updateNotifier.test.ts","../test/resources/configuration.test.ts","../test/resources/decryption.test.ts","../test/resources/globalConfiguration.test.ts","../test/resources/integrations.test.ts","../test/resources/oauth2.test.ts","../test/resources/template.test.ts","../test/services/integrationsPlatform.test.ts","../test/services/oauth2.test.ts","../scripts/generateTypes.ts","../.eslintrc.js"],"version":"5.9.3"}
+{"root":["../src/baseCommand.ts","../src/configurationTypes.ts","../src/errors.ts","../src/index.ts","../src/commands/activity.ts","../src/commands/dev.ts","../src/commands/encrypt.ts","../src/commands/graph.ts","../src/commands/init.ts","../src/commands/invite.ts","../src/commands/login.ts","../src/commands/oauth2.ts","../src/commands/publish.ts","../src/commands/schema-snapshot.ts","../src/commands/test.ts","../src/commands/upgrade.ts","../src/hooks/init/displayLogo.ts","../src/hooks/init/updateNotifier.ts","../src/resources/configuration.ts","../src/resources/coverageCalculator.ts","../src/resources/credentials.ts","../src/resources/decryption.ts","../src/resources/fieldExtractor.ts","../src/resources/fileSystem.ts","../src/resources/globalConfiguration.ts","../src/resources/integrations.ts","../src/resources/integrationsPlatform.ts","../src/resources/jsonlReader.ts","../src/resources/oauth2.ts","../src/resources/template.ts","../src/services/integrationsPlatform.ts","../src/services/integrationsPlatformClient.ts","../src/services/oauth2.ts","../test/errors.test.ts","../test/commands/activity.test.ts","../test/commands/dev.test.ts","../test/commands/encrypt.test.ts","../test/commands/graph.test.ts","../test/commands/init.test.ts","../test/commands/invite.test.ts","../test/commands/login.test.ts","../test/commands/oauth2.test.ts","../test/commands/publish.test.ts","../test/commands/test.test.ts","../test/commands/upgrade.test.ts","../test/helpers/init.js","../test/helpers/integrations.ts","../test/helpers/styles.ts","../test/hooks/updateNotifier.test.ts","../test/resources/configuration.test.ts","../test/resources/coverageCalculator.test.ts","../test/resources/decryption.test.ts","../test/resources/fieldExtractor.test.ts","../test/resources/globalConfiguration.test.ts","../test/resources/integrations.test.ts","../test/resources/jsonlReader.test.ts","../test/resources/oauth2.test.ts","../test/resources/template.test.ts","../test/services/integrationsPlatform.test.ts","../test/services/oauth2.test.ts","../scripts/generateTypes.ts","../.eslintrc.js"],"version":"5.9.3"}

package/oclif.manifest.json

@@ -667,6 +667,102 @@
         "publish.js"
       ]
     },
+    "schema-snapshot": {
+      "aliases": [],
+      "args": {},
+      "description": "Generate a schema snapshot by crawling the integration graph",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --output=./schema-snapshot.json",
+        "<%= config.bin %> <%= command.id %> --output=./schema-snapshot.json --diff=./previous-snapshot.json"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "output": {
+          "description": "path to write the schema snapshot",
+          "name": "output",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "diff": {
+          "description": "path to a previous snapshot for comparison",
+          "name": "diff",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "environment": {
+          "description": "the environment of the platform",
+          "name": "environment",
+          "default": "production",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "local",
+            "staging",
+            "production"
+          ],
+          "type": "option"
+        },
+        "test-account": {
+          "description": "test account to use",
+          "name": "test-account",
+          "default": "development",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "config-path": {
+          "description": "relative path to a custom \".unito.json\" file",
+          "name": "config-path",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "skip-install": {
+          "description": "skip npm install before starting",
+          "name": "skip-install",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "strict": {
+          "description": "fail if any fields are unmapped and not in the allowlist",
+          "name": "strict",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "port": {
+          "description": "port to start the integration on (default: 9200)",
+          "name": "port",
+          "default": 9200,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "schema-snapshot",
+      "pluginAlias": "@unito/integration-cli",
+      "pluginName": "@unito/integration-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": false,
+      "relativePath": [
+        "dist",
+        "src",
+        "commands",
+        "schema-snapshot.js"
+      ]
+    },
     "test": {
       "aliases": [],
       "args": {},
@@ -873,5 +969,5 @@
       ]
     }
   },
-  "version": "0.64.6"
+  "version": "0.66.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unito/integration-cli",
-  "version": "0.64.6",
+  "version": "0.66.0",
   "description": "Integration CLI",
   "bin": {
     "integration-cli": "./bin/run"
@@ -39,7 +39,7 @@
     "@ngrok/ngrok": "^1.4.1",
     "@oazapfts/runtime": "1.x",
     "@oclif/core": "3.x",
-    "@unito/integration-debugger": "0.28.10",
+    "@unito/integration-debugger": "0.29.0",
     "ajv": "8.x",
     "ajv-formats": "3.x",
     "better-ajv-errors": "1.x",