@ekanos/cli 0.16.0 → 0.17.1

package/dist/commands/check.js

@@ -0,0 +1,43 @@
+import { harnessPinsResolver } from '../dev-experience.js';
+import { runExperienceChecks } from '../experience/checks.js';
+import { readExperienceProject } from '../experience/project.js';
+import { failOnErrors } from '../experience/report.js';
+export const checkCommand = {
+    name: 'check',
+    usage: [
+        '  check      Run the experience gate: integration pins, generated types, integration-',
+        '             import boundary (source + bundle), fixtures, definition, typecheck',
+    ],
+    specs: {
+        dir: {
+            type: 'string',
+            description: 'Project directory (default: the current one)',
+        },
+        typecheck: {
+            type: 'boolean',
+            default: true,
+            description: 'Run tsc over the project (--no-typecheck skips)',
+        },
+    },
+    async run(ctx, args) {
+        const project = readExperienceProject(args.dir);
+        const result = await runExperienceChecks(project, {
+            typecheck: args.flags.typecheck !== false,
+            loadDefinition: true,
+            inlineSdk: args.env.EKANOS_INLINE_SDK,
+            pinsResolver: await harnessPinsResolver(project.dir, args.env),
+        });
+        const failed = failOnErrors(ctx, 'check', result.findings, {
+            slug: project.slug,
+            integrations: project.integrations.map((u) => u.name),
+        }, project.dir);
+        if (failed !== null)
+            return failed;
+        return ctx.succeed({
+            slug: project.slug,
+            integrations: project.integrations.map((u) => u.name),
+            findings: result.findings,
+        }, `check: OK - ${project.slug} (${project.integrations.length} integration${project.integrations.length === 1 ? '' : 's'})${result.findings.length ? `, ${result.findings.length} warning${result.findings.length === 1 ? '' : 's'}` : ''}.`);
+    },
+};
+//# sourceMappingURL=check.js.map

package/dist/commands/check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGpD,MAAM,CAAC,MAAM,YAAY,GAAsB;IAC7C,IAAI,EAAE,OAAO;IACb,KAAK,EAAE;QACL,uFAAuF;QACvF,iFAAiF;KAClF;IACD,KAAK,EAAE;QACL,GAAG,EAAE;YACH,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,8CAA8C;SAC5D;QACD,SAAS,EAAE;YACT,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,IAAI;YACb,WAAW,EAAE,iDAAiD;SAC/D;KACF;IACD,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI;QACjB,MAAM,OAAO,GAAG,qBAAqB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChD,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,OAAO,EAAE;YAChD,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,KAAK,KAAK;YACzC,cAAc,EAAE,IAAI;YACpB,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,iBAAiB;YACrC,YAAY,EAAE,MAAM,mBAAmB,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC;SAC/D,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,YAAY,CACzB,GAAG,EACH,OAAO,EACP,MAAM,CAAC,QAAQ,EACf;YACE,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,YAAY,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;SACtD,EACD,OAAO,CAAC,GAAG,CACZ,CAAC;QACF,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,MAAM,CAAC;QAEnC,OAAO,GAAG,CAAC,OAAO,CAChB;YACE,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,YAAY,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;YACrD,QAAQ,EAAE,MAAM,CAAC,QAAQ;SAC1B,EACD,eAAe,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,YAAY,CAAC,MAAM,eAAe,OAAO,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,QAAQ,CAAC,MAAM,WAAW,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAC3O,CAAC;IACJ,CAAC;CACF,CAAC","sourcesContent":["import { harnessPinsResolver } from '../dev-experience';\nimport { runExperienceChecks } from '../experience/checks';\nimport { readExperienceProject } from '../experience/project';\nimport { failOnErrors } from '../experience/report';\nimport type { ExperienceCommand } from './index-experience';\n\nexport const checkCommand: ExperienceCommand = {\n  name: 'check',\n  usage: [\n    '  check      Run the experience gate: integration pins, generated types, integration-',\n    '             import boundary (source + bundle), fixtures, definition, typecheck',\n  ],\n  specs: {\n    dir: {\n      type: 'string',\n      description: 'Project directory (default: the current one)',\n    },\n    typecheck: {\n      type: 'boolean',\n      default: true,\n      description: 'Run tsc over the project (--no-typecheck skips)',\n    },\n  },\n  async run(ctx, args) {\n    const project = readExperienceProject(args.dir);\n    const result = await runExperienceChecks(project, {\n      typecheck: args.flags.typecheck !== false,\n      loadDefinition: true,\n      inlineSdk: args.env.EKANOS_INLINE_SDK,\n      pinsResolver: await harnessPinsResolver(project.dir, args.env),\n    });\n\n    const failed = failOnErrors(\n      ctx,\n      'check',\n      result.findings,\n      {\n        slug: project.slug,\n        integrations: project.integrations.map((u) => u.name),\n      },\n      project.dir,\n    );\n    if (failed !== null) return failed;\n\n    return ctx.succeed(\n      {\n        slug: project.slug,\n        integrations: project.integrations.map((u) => u.name),\n        findings: result.findings,\n      },\n      `check: OK - ${project.slug} (${project.integrations.length} integration${project.integrations.length === 1 ? '' : 's'})${result.findings.length ? `, ${result.findings.length} warning${result.findings.length === 1 ? '' : 's'}` : ''}.`,\n    );\n  },\n};\n"]}

package/dist/commands/codegen.d.ts

@@ -0,0 +1,2 @@
+import type { ExperienceCommand } from './index-experience.js';
+export declare const codegenCommand: ExperienceCommand;

package/dist/commands/codegen.js

@@ -0,0 +1,49 @@
+import { preconditionError, validationError } from '../errors.js';
+import { expectedIntegrationsDts } from '../experience/checks.js';
+import { readExperienceProject } from '../experience/project.js';
+import { loadPins, regenerateIntegrations } from '../experience/regenerate.js';
+export const codegenCommand = {
+    name: 'codegen',
+    usage: [
+        '  codegen    Regenerate src/.ekanos/integrations.d.ts from the pinned contracts',
+        '             (offline, idempotent; --check fails when it is stale)',
+    ],
+    specs: {
+        dir: {
+            type: 'string',
+            description: 'Project directory (default: the current one)',
+        },
+        check: {
+            type: 'boolean',
+            description: 'Fail when the committed file differs; write nothing',
+        },
+    },
+    async run(ctx, args) {
+        const project = readExperienceProject(args.dir);
+        const { pinned, missing } = loadPins(project);
+        if (missing.length > 0) {
+            throw preconditionError(`No pinned contract for integration${missing.length === 1 ? '' : 's'}: ${missing.join(', ')}.`, 'Run "ekanos add <integration>@<version> --from-dir <contracts folder>" or "ekanos sync" first.');
+        }
+        if (args.flags.check === true) {
+            const fs = await import('node:fs');
+            const path = await import('node:path');
+            const file = path.join(project.dir, 'src/.ekanos/integrations.d.ts');
+            const current = fs.existsSync(file)
+                ? fs.readFileSync(file, 'utf8')
+                : null;
+            if (current !== expectedIntegrationsDts(pinned)) {
+                throw validationError('src/.ekanos/integrations.d.ts is stale.', 'Run "ekanos codegen" and commit the result.');
+            }
+            return ctx.succeed({ changed: false, integrations: pinned.length }, 'integrations.d.ts is up to date.');
+        }
+        const changed = regenerateIntegrations(project, pinned);
+        return ctx.succeed({
+            changed,
+            integrations: pinned.length,
+            file: 'src/.ekanos/integrations.d.ts',
+        }, changed
+            ? `Wrote src/.ekanos/integrations.d.ts (${pinned.length} integration${pinned.length === 1 ? '' : 's'}).`
+            : 'integrations.d.ts is already up to date.');
+    },
+};
+//# sourceMappingURL=codegen.js.map

package/dist/commands/codegen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.js","sourceRoot":"","sources":["../../src/commands/codegen.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAG5E,MAAM,CAAC,MAAM,cAAc,GAAsB;IAC/C,IAAI,EAAE,SAAS;IACf,KAAK,EAAE;QACL,iFAAiF;QACjF,oEAAoE;KACrE;IACD,KAAK,EAAE;QACL,GAAG,EAAE;YACH,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,8CAA8C;SAC5D;QACD,KAAK,EAAE;YACL,IAAI,EAAE,SAAS;YACf,WAAW,EAAE,qDAAqD;SACnE;KACF;IACD,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI;QACjB,MAAM,OAAO,GAAG,qBAAqB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChD,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC9C,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,iBAAiB,CACrB,qCAAqC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAC9F,gGAAgG,CACjG,CAAC;QACJ,CAAC;QAED,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YAC9B,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;YACnC,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;YACvC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,+BAA+B,CAAC,CAAC;YACrE,MAAM,OAAO,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC;gBACjC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC;gBAC/B,CAAC,CAAC,IAAI,CAAC;YACT,IAAI,OAAO,KAAK,uBAAuB,CAAC,MAAM,CAAC,EAAE,CAAC;gBAChD,MAAM,eAAe,CACnB,yCAAyC,EACzC,6CAA6C,CAC9C,CAAC;YACJ,CAAC;YAED,OAAO,GAAG,CAAC,OAAO,CAChB,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,EAC/C,kCAAkC,CACnC,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAG,sBAAsB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAExD,OAAO,GAAG,CAAC,OAAO,CAChB;YACE,OAAO;YACP,YAAY,EAAE,MAAM,CAAC,MAAM;YAC3B,IAAI,EAAE,+BAA+B;SACtC,EACD,OAAO;YACL,CAAC,CAAC,wCAAwC,MAAM,CAAC,MAAM,eAAe,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI;YACxG,CAAC,CAAC,0CAA0C,CAC/C,CAAC;IACJ,CAAC;CACF,CAAC","sourcesContent":["import { preconditionError, validationError } from '../errors';\nimport { expectedIntegrationsDts } from '../experience/checks';\nimport { readExperienceProject } from '../experience/project';\nimport { loadPins, regenerateIntegrations } from '../experience/regenerate';\nimport type { ExperienceCommand } from './index-experience';\n\nexport const codegenCommand: ExperienceCommand = {\n  name: 'codegen',\n  usage: [\n    '  codegen    Regenerate src/.ekanos/integrations.d.ts from the pinned contracts',\n    '             (offline, idempotent; --check fails when it is stale)',\n  ],\n  specs: {\n    dir: {\n      type: 'string',\n      description: 'Project directory (default: the current one)',\n    },\n    check: {\n      type: 'boolean',\n      description: 'Fail when the committed file differs; write nothing',\n    },\n  },\n  async run(ctx, args) {\n    const project = readExperienceProject(args.dir);\n    const { pinned, missing } = loadPins(project);\n    if (missing.length > 0) {\n      throw preconditionError(\n        `No pinned contract for integration${missing.length === 1 ? '' : 's'}: ${missing.join(', ')}.`,\n        'Run \"ekanos add <integration>@<version> --from-dir <contracts folder>\" or \"ekanos sync\" first.',\n      );\n    }\n\n    if (args.flags.check === true) {\n      const fs = await import('node:fs');\n      const path = await import('node:path');\n      const file = path.join(project.dir, 'src/.ekanos/integrations.d.ts');\n      const current = fs.existsSync(file)\n        ? fs.readFileSync(file, 'utf8')\n        : null;\n      if (current !== expectedIntegrationsDts(pinned)) {\n        throw validationError(\n          'src/.ekanos/integrations.d.ts is stale.',\n          'Run \"ekanos codegen\" and commit the result.',\n        );\n      }\n\n      return ctx.succeed(\n        { changed: false, integrations: pinned.length },\n        'integrations.d.ts is up to date.',\n      );\n    }\n\n    const changed = regenerateIntegrations(project, pinned);\n\n    return ctx.succeed(\n      {\n        changed,\n        integrations: pinned.length,\n        file: 'src/.ekanos/integrations.d.ts',\n      },\n      changed\n        ? `Wrote src/.ekanos/integrations.d.ts (${pinned.length} integration${pinned.length === 1 ? '' : 's'}).`\n        : 'integrations.d.ts is already up to date.',\n    );\n  },\n};\n"]}

package/dist/commands/contract.d.ts

@@ -0,0 +1,52 @@
+import { type Contract } from '@ekanos/integration-schema';
+import type { CliContext } from '../context.js';
+import { type HarnessResolver } from '../dev-experience.js';
+import type { ExitCode } from '../exit-codes.js';
+import type { ExperienceCommand } from './index-experience.js';
+/** The slice of `@ekanos/sdk/contract` this command uses. */
+export interface ContractModule {
+    analyzeContract(definition: unknown, options: {
+        packageVersion: string;
+        contractVersion: string;
+        previous?: Contract | null;
+        examples?: Readonly<Record<string, unknown>>;
+    }): {
+        contract: Contract;
+        diagnostics: Array<{
+            rule: string;
+            severity: 'error' | 'warn' | 'info';
+            message: string;
+            operation?: string;
+        }>;
+    };
+    synthesizeExample(schema: unknown): unknown;
+}
+export interface ContractArgs {
+    dir: string;
+    check: boolean;
+    record: boolean;
+    bump: boolean;
+    env?: Record<string, string | undefined>;
+    /**
+     * `--record --op tool/x[,action/y]`: record REAL examples for these
+     * operations from a run through the harness runner, instead of writing
+     * placeholders.
+     */
+    ops?: string[];
+    /** Which run mode produces the example (default `fixtures`). */
+    from?: 'fixtures' | 'live';
+    /** JSON input for the recorded run (single `--op` only); default: synthesized from the input schema. */
+    input?: string;
+    /** Test seam; the default loads the project's installed `@ekanos/harness/resolver`. */
+    loadHarness?: (projectDir: string) => Promise<HarnessResolver>;
+    /** Test seam; the default loads `@ekanos/sdk/contract` from the project. */
+    loadModule?: (projectDir: string) => Promise<ContractModule>;
+}
+/** The smallest contractVersion that satisfies the transition rules. */
+export declare function nextContractVersion(previous: Contract, next: Contract): string | null;
+/**
+ * `ekanos contract`: derive `contract.json` from the integration definition.
+ * See the command's usage text for the three modes.
+ */
+export declare function runContract(ctx: CliContext, args: ContractArgs): Promise<ExitCode>;
+export declare const contractCommand: ExperienceCommand;

package/dist/commands/contract.js

@@ -0,0 +1,300 @@
+import { assessContractTransition, checkContractFreshness, diffContract, validateAgainstSchema, verifyContract, } from '@ekanos/integration-schema';
+import * as fs from 'node:fs';
+import { createRequire } from 'node:module';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { loadHarnessResolver } from '../dev-experience.js';
+import { preconditionError, usageError, validationError } from '../errors.js';
+import { loadDefinition } from '../load-definition.js';
+import { loadProject } from '../project.js';
+async function loadProjectModule(projectDir) {
+    try {
+        const require = createRequire(path.join(projectDir, 'package.json'));
+        return (await import(pathToFileURL(require.resolve('@ekanos/sdk/contract')).href));
+    }
+    catch (_a) {
+        throw preconditionError('This project\'s @ekanos/sdk does not provide "@ekanos/sdk/contract".', 'Upgrade @ekanos/sdk to a version that ships contract emission, then re-run.');
+    }
+}
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (_a) {
+        return null;
+    }
+}
+function readExamples(dir) {
+    const out = {};
+    if (!fs.existsSync(dir))
+        return out;
+    for (const name of fs.readdirSync(dir)) {
+        const match = /^(tool|action)-(.+)\.json$/.exec(name);
+        const value = match ? readJson(path.join(dir, name)) : null;
+        if (match && value !== null)
+            out[`${match[1]}/${match[2]}`] = value;
+    }
+    return out;
+}
+/** The smallest contractVersion that satisfies the transition rules. */
+export function nextContractVersion(previous, next) {
+    const diff = diffContract(previous, next);
+    if (diff.breaking.length === 0 && diff.compatible.length === 0) {
+        return canonicalSurfaceEqual(previous, next)
+            ? null
+            : bump(previous.contractVersion, 'patch');
+    }
+    const zero = previous.compatLine.startsWith('0.');
+    if (diff.breaking.length > 0)
+        return bump(previous.contractVersion, zero ? 'minor' : 'major');
+    return bump(previous.contractVersion, zero ? 'patch' : 'minor');
+}
+function canonicalSurfaceEqual(a, b) {
+    return checkContractFreshness(b, a).length === 0;
+}
+function bump(version, part) {
+    const [major = 0, minor = 0, patch = 0] = version.split(/[.+-]/).map(Number);
+    if (part === 'major')
+        return `${major + 1}.0.0`;
+    if (part === 'minor')
+        return `${major}.${minor + 1}.0`;
+    return `${major}.${minor}.${patch + 1}`;
+}
+function describe(problem) {
+    return `${problem.operation ? `${problem.operation}: ` : ''}${problem.message}`;
+}
+/**
+ * `ekanos contract`: derive `contract.json` from the integration definition.
+ * See the command's usage text for the three modes.
+ */
+export async function runContract(ctx, args) {
+    var _a;
+    var _b, _c, _d, _e, _f;
+    if (args.check && (args.record || args.bump)) {
+        throw usageError('--check cannot be combined with --record or --bump.', 'Run them separately: "ekanos contract --record", then "ekanos contract --check".');
+    }
+    const loaded = loadProject(args.dir);
+    if (loaded.project.kind === 'experience') {
+        throw preconditionError('An experience has no contract of its own.', 'Run "ekanos contract" in the integration project.');
+    }
+    const configPath = loaded.configPath;
+    const declared = (_a = loaded.project.contract) === null || _a === void 0 ? void 0 : _a.version;
+    if (!declared) {
+        throw preconditionError('ekanos.json declares no contract version.', 'Add "contract": { "version": "0.1.0" } to ekanos.json; the compat line follows it.');
+    }
+    const pkg = readJson(path.join(loaded.projectDir, 'package.json'));
+    if (!(pkg === null || pkg === void 0 ? void 0 : pkg.version)) {
+        throw preconditionError('package.json has no readable "version".', 'Add a semver version to package.json.');
+    }
+    const sdk = await ((_b = args.loadModule) !== null && _b !== void 0 ? _b : loadProjectModule)(loaded.projectDir);
+    const def = await loadDefinition(loaded.primary.entryPath, loaded.projectDir);
+    if (!def.ok) {
+        throw validationError(`The integration definition did not load: ${def.message}`, 'Run "ekanos validate" first and fix what it reports.');
+    }
+    const contractFile = path.join(loaded.projectDir, 'contract.json');
+    const examplesDir = path.join(loaded.projectDir, 'contracts', 'examples');
+    const previous = fs.existsSync(contractFile)
+        ? verifyContract(readJson(contractFile)).contract
+        : null;
+    let contractVersion = declared;
+    const analyze = () => sdk.analyzeContract(def.definition, {
+        packageVersion: pkg.version,
+        contractVersion,
+        previous,
+        examples: readExamples(examplesDir),
+    });
+    let result = analyze();
+    const wanted = (_c = args.ops) !== null && _c !== void 0 ? _c : [];
+    if (wanted.length > 0 && !args.record) {
+        throw usageError('--op only applies with --record.', 'Run "ekanos contract --record --op tool/<name>".');
+    }
+    if (args.input !== undefined && wanted.length !== 1) {
+        throw usageError('--input needs exactly one --op.', 'Record one operation at a time with its own --input.');
+    }
+    if (args.record && wanted.length > 0) {
+        let input;
+        if (args.input !== undefined) {
+            try {
+                input = JSON.parse(args.input);
+            }
+            catch (_g) {
+                throw usageError('--input is not valid JSON.', 'Pass the operation input as a JSON object, e.g. --input \'{"limit":5}\'.');
+            }
+        }
+        const mode = (_d = args.from) !== null && _d !== void 0 ? _d : 'fixtures';
+        const harness = await ((_e = args.loadHarness) !== null && _e !== void 0 ? _e : loadHarnessResolver)(loaded.projectDir);
+        if (typeof harness.runOperationOnce !== 'function') {
+            throw preconditionError('The installed @ekanos/harness cannot run an operation for recording.', 'Upgrade @ekanos/harness and @ekanos/cli together, then re-run.');
+        }
+        const wrote = [];
+        for (const key of wanted) {
+            const op = result.contract.operations.find((o) => o.id.endsWith(`/${key}`));
+            if (!op) {
+                throw validationError(`The contract has no operation "${key}".`, `Known operations: ${result.contract.operations.map((o) => `${o.kind}/${o.name}`).join(', ') || 'none'}.`);
+            }
+            if (op.effect === 'write') {
+                // A write is only ever recorded from a scenario fixture: reading a
+                // file performs nothing. Running it live would perform it for real.
+                const fixture = writeFixturePath(loaded.primary.slug, key);
+                if (mode === 'live') {
+                    throw validationError(`${key} is a write; --from live would perform it for real, and a recording never does.`, `Add ${fixture} (a real-shaped response), then run "ekanos contract --record --op ${key} --from fixtures".`);
+                }
+                if (!fs.existsSync(path.join(loaded.projectDir, fixture))) {
+                    throw validationError(`${key} is a write with no scenario fixture to record from.`, `Add ${fixture} holding a real-shaped response, then re-run "ekanos contract --record --op ${key} --from fixtures". Nothing is called.`);
+                }
+            }
+            if (op.opaque.output) {
+                throw validationError(`${key} has an opaque output schema, so a recording cannot be validated.`, 'Declare an output schema first.');
+            }
+            const run = await harness.runOperationOnce({
+                projectRoot: loaded.projectDir,
+                op: key,
+                input: input !== null && input !== void 0 ? input : sdk.synthesizeExample(op.input),
+                mode,
+                env: args.env,
+                deriveContract: () => result.contract,
+            });
+            if (!run.ok) {
+                throw validationError(`Recording ${key} (${mode}) failed: ${run.reason}${run.detail ? ` - ${run.detail}` : ` - ${run.message}`}`, mode === 'live'
+                    ? 'Check the credentials (ekanos dev -> Connect) and the input, then re-run.'
+                    : `Fixtures mode reads fixtures/<slug>/${key.replace('/', '-')}.default.json (or an existing outputExample). Author that file, or record from a real run with "--from live".`);
+            }
+            const problems = validateAgainstSchema(op.output, run.data);
+            if (problems.length > 0) {
+                throw validationError(`${key} returned data that does not satisfy its output schema: ${problems[0]}`, 'Fix the output schema or the handler; nothing was written.');
+            }
+            const file = path.join(examplesDir, `${key.replace('/', '-')}.json`);
+            fs.mkdirSync(examplesDir, { recursive: true });
+            fs.writeFileSync(file, `${JSON.stringify(run.data, null, 2)}\n`);
+            wrote.push(path.relative(loaded.projectDir, file));
+        }
+        ctx.log(`Recorded ${wrote.length} example(s) from a ${mode} run: ${wrote.join(', ')}. Review them before committing${mode === 'live' ? ' (live data may contain real records)' : ''}.`);
+        result = analyze();
+    }
+    else if (args.record) {
+        const wrote = [];
+        const advice = [];
+        for (const diag of result.diagnostics) {
+            if (diag.rule !== 'contract/example-missing' || !diag.operation)
+                continue;
+            const op = result.contract.operations.find((o) => o.id.endsWith(`/${diag.operation}`));
+            if (!op || op.opaque.output)
+                continue;
+            const file = path.join(examplesDir, `${diag.operation.replace('/', '-')}.json`);
+            fs.mkdirSync(examplesDir, { recursive: true });
+            fs.writeFileSync(file, `${JSON.stringify(sdk.synthesizeExample(op.output), null, 2)}\n`);
+            wrote.push(path.relative(loaded.projectDir, file));
+            advice.push(op.effect === 'write'
+                ? `${diag.operation}: add ${writeFixturePath(loaded.primary.slug, diag.operation)} with a real-shaped response, then "ekanos contract --record --op ${diag.operation} --from fixtures" (writes are never recorded live)`
+                : `${diag.operation}: add ${writeFixturePath(loaded.primary.slug, diag.operation)}, or "ekanos contract --record --op ${diag.operation} --from live"`);
+        }
+        if (wrote.length > 0) {
+            ctx.log(`Wrote ${wrote.length} placeholder example(s) synthesized from the output schema (not recorded from a run): ${wrote.join(', ')}. Fixtures mode will serve these placeholders until you replace them:\n  ${advice.join('\n  ')}`);
+            result = analyze();
+        }
+    }
+    if (args.bump && previous) {
+        const wanted = nextContractVersion(previous, result.contract);
+        if (wanted && wanted !== contractVersion) {
+            contractVersion = wanted;
+            const raw = (_f = readJson(configPath)) !== null && _f !== void 0 ? _f : {};
+            raw.contract = Object.assign(Object.assign({}, raw.contract), { version: wanted });
+            fs.writeFileSync(configPath, `${JSON.stringify(raw, null, 2)}\n`);
+            ctx.log(`contract.version ${declared} -> ${wanted} in ekanos.json`);
+            result = analyze();
+        }
+    }
+    for (const diag of result.diagnostics) {
+        ctx.log(`${diag.severity === 'error' ? 'error' : diag.severity === 'warn' ? 'warn ' : 'info '} ${diag.operation ? `${diag.operation}: ` : ''}${diag.message} (${diag.rule})`);
+    }
+    const errors = result.diagnostics.filter((d) => d.severity === 'error');
+    if (errors.length > 0) {
+        throw validationError(`${errors.length} contract error(s): ${errors
+            .slice(0, 3)
+            .map((e) => { var _a; return `${(_a = e.operation) !== null && _a !== void 0 ? _a : ''} ${e.message}`.trim(); })
+            .join('; ')}`, 'Fix them (declare outputs and examples, or run "ekanos contract --record"), then re-run.');
+    }
+    const transition = previous
+        ? assessContractTransition(previous, result.contract).problems
+        : [];
+    if (args.check) {
+        const problems = checkContractFreshness(result.contract, previous, {
+            strictPackageVersion: true,
+        });
+        if (problems.length > 0) {
+            throw validationError(`contract.json is out of date: ${problems.map(describe).join(' | ')}`, 'Run "ekanos contract" (add --bump for the version) and commit contract.json.');
+        }
+        return ctx.succeed({
+            ok: true,
+            digest: result.contract.digest,
+            operations: result.contract.operations.length,
+            diagnostics: result.diagnostics,
+        }, `contract.json is current (${result.contract.operations.length} operations).`);
+    }
+    if (transition.length > 0) {
+        throw validationError(`This change is not allowed on the current contract version: ${transition.map(describe).join(' | ')}`, 'Run "ekanos contract --bump", or set contract.version in ekanos.json by hand (a breaking change needs a new compat line).');
+    }
+    fs.writeFileSync(contractFile, `${JSON.stringify(result.contract, null, 2)}\n`);
+    return ctx.succeed({
+        written: 'contract.json',
+        digest: result.contract.digest,
+        operations: result.contract.operations.length,
+        diagnostics: result.diagnostics,
+    }, `Wrote contract.json (${result.contract.operations.length} operations, ${result.contract.compatLine} line, contract ${result.contract.contractVersion}).`);
+}
+export const contractCommand = {
+    name: 'contract',
+    usage: [
+        '  contract   Derive ./contract.json from the integration definition;',
+        '             --check fails on a stale file (CI, prepack), --record writes',
+        '             missing output examples, --bump bumps the contract version',
+    ],
+    specs: {
+        dir: {
+            type: 'string',
+            description: 'Project directory (default: the current one)',
+        },
+        check: {
+            type: 'boolean',
+            description: 'Derive in memory and fail if contract.json differs',
+        },
+        record: {
+            type: 'boolean',
+            description: 'Write placeholder examples (contracts/examples) for operations that have none; with --op, record real ones from a run',
+        },
+        op: {
+            type: 'string',
+            description: 'With --record: operation(s) to record from a real run, comma separated (tool/list_posts)',
+        },
+        from: {
+            type: 'string',
+            description: 'With --op: run mode to record from, fixtures (default) or live',
+        },
+        input: {
+            type: 'string',
+            description: 'With --op: JSON input for the recorded run',
+        },
+        bump: {
+            type: 'boolean',
+            description: 'Rewrite ekanos.json contract.version to match the surface change',
+        },
+    },
+    run(ctx, args) {
+        const from = args.flags.from;
+        if (from !== undefined && from !== 'live' && from !== 'fixtures') {
+            throw usageError(`--from must be "fixtures" or "live", not "${String(from)}".`, 'Run "ekanos contract --record --op tool/<name> --from live".');
+        }
+        return runContract(ctx, Object.assign(Object.assign(Object.assign({ dir: args.dir, check: args.flags.check === true, record: args.flags.record === true, bump: args.flags.bump === true, env: args.env }, (typeof args.flags.op === 'string' && args.flags.op !== ''
+            ? { ops: args.flags.op.split(',').map((o) => o.trim()) }
+            : {})), (args.flags.from === 'live' || args.flags.from === 'fixtures'
+            ? { from: args.flags.from }
+            : {})), (typeof args.flags.input === 'string'
+            ? { input: args.flags.input }
+            : {})));
+    },
+};
+/** Where a scenario fixture for an operation lives, project-relative. */
+function writeFixturePath(slug, opKey) {
+    return path.join('fixtures', slug, `${opKey.replace('/', '-')}.default.json`);
+}
+//# sourceMappingURL=contract.js.map

package/dist/commands/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/commands/contract.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  type Contract,\n  type ContractProblem,\n  assessContractTransition,\n  checkContractFreshness,\n  diffContract,\n  validateAgainstSchema,\n  verifyContract,\n} from '@ekanos/integration-schema';\nimport * as fs from 'node:fs';\nimport { createRequire } from 'node:module';\nimport * as path from 'node:path';\nimport { pathToFileURL } from 'node:url';\n\nimport type { CliContext } from '../context';\nimport { type HarnessResolver, loadHarnessResolver } from '../dev-experience';\nimport { preconditionError, usageError, validationError } from '../errors';\nimport type { ExitCode } from '../exit-codes';\nimport { loadDefinition } from '../load-definition';\nimport { loadProject } from '../project';\nimport type { ExperienceCommand } from './index-experience';\n\n/** The slice of `@ekanos/sdk/contract` this command uses. */\nexport interface ContractModule {\n  analyzeContract(\n    definition: unknown,\n    options: {\n      packageVersion: string;\n      contractVersion: string;\n      previous?: Contract | null;\n      examples?: Readonly<Record<string, unknown>>;\n    },\n  ): {\n    contract: Contract;\n    diagnostics: Array<{\n      rule: string;\n      severity: 'error' | 'warn' | 'info';\n      message: string;\n      operation?: string;\n    }>;\n  };\n  synthesizeExample(schema: unknown): unknown;\n}\n\nexport interface ContractArgs {\n  dir: string;\n  check: boolean;\n  record: boolean;\n  bump: boolean;\n  env?: Record<string, string | undefined>;\n  /**\n   * `--record --op tool/x[,action/y]`: record REAL examples for these\n   * operations from a run through the harness runner, instead of writing\n   * placeholders.\n   */\n  ops?: string[];\n  /** Which run mode produces the example (default `fixtures`). */\n  from?: 'fixtures' | 'live';\n  /** JSON input for the recorded run (single `--op` only); default: synthesized from the input schema. */\n  input?: string;\n  /** Test seam; the default loads the project's installed `@ekanos/harness/resolver`. */\n  loadHarness?: (projectDir: string) => Promise<HarnessResolver>;\n  /** Test seam; the default loads `@ekanos/sdk/contract` from the project. */\n  loadModule?: (projectDir: string) => Promise<ContractModule>;\n}\n\nasync function loadProjectModule(projectDir: string): Promise<ContractModule> {\n  try {\n    const require = createRequire(path.join(projectDir, 'package.json'));\n    return (await import(\n      pathToFileURL(require.resolve('@ekanos/sdk/contract')).href\n    )) as ContractModule;\n  } catch {\n    throw preconditionError(\n      'This project\\'s @ekanos/sdk does not provide \"@ekanos/sdk/contract\".',\n      'Upgrade @ekanos/sdk to a version that ships contract emission, then re-run.',\n    );\n  }\n}\n\nfunction readJson<T>(file: string): T | null {\n  try {\n    return JSON.parse(fs.readFileSync(file, 'utf8')) as T;\n  } catch {\n    return null;\n  }\n}\n\nfunction readExamples(dir: string): Record<string, unknown> {\n  const out: Record<string, unknown> = {};\n  if (!fs.existsSync(dir)) return out;\n  for (const name of fs.readdirSync(dir)) {\n    const match = /^(tool|action)-(.+)\\.json$/.exec(name);\n    const value = match ? readJson<unknown>(path.join(dir, name)) : null;\n    if (match && value !== null) out[`${match[1]}/${match[2]}`] = value;\n  }\n  return out;\n}\n\n/** The smallest contractVersion that satisfies the transition rules. */\nexport function nextContractVersion(\n  previous: Contract,\n  next: Contract,\n): string | null {\n  const diff = diffContract(previous, next);\n  if (diff.breaking.length === 0 && diff.compatible.length === 0) {\n    return canonicalSurfaceEqual(previous, next)\n      ? null\n      : bump(previous.contractVersion, 'patch');\n  }\n  const zero = previous.compatLine.startsWith('0.');\n  if (diff.breaking.length > 0)\n    return bump(previous.contractVersion, zero ? 'minor' : 'major');\n  return bump(previous.contractVersion, zero ? 'patch' : 'minor');\n}\n\nfunction canonicalSurfaceEqual(a: Contract, b: Contract): boolean {\n  return checkContractFreshness(b, a).length === 0;\n}\n\nfunction bump(version: string, part: 'major' | 'minor' | 'patch'): string {\n  const [major = 0, minor = 0, patch = 0] = version.split(/[.+-]/).map(Number);\n  if (part === 'major') return `${major + 1}.0.0`;\n  if (part === 'minor') return `${major}.${minor + 1}.0`;\n  return `${major}.${minor}.${patch + 1}`;\n}\n\nfunction describe(problem: ContractProblem): string {\n  return `${problem.operation ? `${problem.operation}: ` : ''}${problem.message}`;\n}\n\n/**\n * `ekanos contract`: derive `contract.json` from the integration definition.\n * See the command's usage text for the three modes.\n */\nexport async function runContract(\n  ctx: CliContext,\n  args: ContractArgs,\n): Promise<ExitCode> {\n  if (args.check && (args.record || args.bump)) {\n    throw usageError(\n      '--check cannot be combined with --record or --bump.',\n      'Run them separately: \"ekanos contract --record\", then \"ekanos contract --check\".',\n    );\n  }\n  const loaded = loadProject(args.dir);\n  if (loaded.project.kind === 'experience') {\n    throw preconditionError(\n      'An experience has no contract of its own.',\n      'Run \"ekanos contract\" in the integration project.',\n    );\n  }\n  const configPath = loaded.configPath;\n  const declared = loaded.project.contract?.version;\n  if (!declared) {\n    throw preconditionError(\n      'ekanos.json declares no contract version.',\n      'Add \"contract\": { \"version\": \"0.1.0\" } to ekanos.json; the compat line follows it.',\n    );\n  }\n  const pkg = readJson<{ version?: string }>(\n    path.join(loaded.projectDir, 'package.json'),\n  );\n  if (!pkg?.version) {\n    throw preconditionError(\n      'package.json has no readable \"version\".',\n      'Add a semver version to package.json.',\n    );\n  }\n\n  const sdk = await (args.loadModule ?? loadProjectModule)(loaded.projectDir);\n  const def = await loadDefinition(loaded.primary.entryPath, loaded.projectDir);\n  if (!def.ok) {\n    throw validationError(\n      `The integration definition did not load: ${def.message}`,\n      'Run \"ekanos validate\" first and fix what it reports.',\n    );\n  }\n\n  const contractFile = path.join(loaded.projectDir, 'contract.json');\n  const examplesDir = path.join(loaded.projectDir, 'contracts', 'examples');\n  const previous = fs.existsSync(contractFile)\n    ? verifyContract(readJson<unknown>(contractFile)).contract\n    : null;\n\n  let contractVersion = declared;\n  const analyze = () =>\n    sdk.analyzeContract(def.definition, {\n      packageVersion: pkg.version as string,\n      contractVersion,\n      previous,\n      examples: readExamples(examplesDir),\n    });\n\n  let result = analyze();\n\n  const wanted = args.ops ?? [];\n  if (wanted.length > 0 && !args.record) {\n    throw usageError(\n      '--op only applies with --record.',\n      'Run \"ekanos contract --record --op tool/<name>\".',\n    );\n  }\n  if (args.input !== undefined && wanted.length !== 1) {\n    throw usageError(\n      '--input needs exactly one --op.',\n      'Record one operation at a time with its own --input.',\n    );\n  }\n\n  if (args.record && wanted.length > 0) {\n    let input: unknown;\n    if (args.input !== undefined) {\n      try {\n        input = JSON.parse(args.input);\n      } catch {\n        throw usageError(\n          '--input is not valid JSON.',\n          'Pass the operation input as a JSON object, e.g. --input \\'{\"limit\":5}\\'.',\n        );\n      }\n    }\n    const mode = args.from ?? 'fixtures';\n    const harness = await (args.loadHarness ?? loadHarnessResolver)(\n      loaded.projectDir,\n    );\n    if (typeof harness.runOperationOnce !== 'function') {\n      throw preconditionError(\n        'The installed @ekanos/harness cannot run an operation for recording.',\n        'Upgrade @ekanos/harness and @ekanos/cli together, then re-run.',\n      );\n    }\n    const wrote: string[] = [];\n    for (const key of wanted) {\n      const op = result.contract.operations.find((o) =>\n        o.id.endsWith(`/${key}`),\n      );\n      if (!op) {\n        throw validationError(\n          `The contract has no operation \"${key}\".`,\n          `Known operations: ${result.contract.operations.map((o) => `${o.kind}/${o.name}`).join(', ') || 'none'}.`,\n        );\n      }\n      if (op.effect === 'write') {\n        // A write is only ever recorded from a scenario fixture: reading a\n        // file performs nothing. Running it live would perform it for real.\n        const fixture = writeFixturePath(loaded.primary.slug, key);\n        if (mode === 'live') {\n          throw validationError(\n            `${key} is a write; --from live would perform it for real, and a recording never does.`,\n            `Add ${fixture} (a real-shaped response), then run \"ekanos contract --record --op ${key} --from fixtures\".`,\n          );\n        }\n        if (!fs.existsSync(path.join(loaded.projectDir, fixture))) {\n          throw validationError(\n            `${key} is a write with no scenario fixture to record from.`,\n            `Add ${fixture} holding a real-shaped response, then re-run \"ekanos contract --record --op ${key} --from fixtures\". Nothing is called.`,\n          );\n        }\n      }\n      if (op.opaque.output) {\n        throw validationError(\n          `${key} has an opaque output schema, so a recording cannot be validated.`,\n          'Declare an output schema first.',\n        );\n      }\n      const run = await harness.runOperationOnce({\n        projectRoot: loaded.projectDir,\n        op: key,\n        input: input ?? sdk.synthesizeExample(op.input),\n        mode,\n        env: args.env,\n        deriveContract: () => result.contract,\n      });\n      if (!run.ok) {\n        throw validationError(\n          `Recording ${key} (${mode}) failed: ${run.reason}${run.detail ? ` - ${run.detail}` : ` - ${run.message}`}`,\n          mode === 'live'\n            ? 'Check the credentials (ekanos dev -> Connect) and the input, then re-run.'\n            : `Fixtures mode reads fixtures/<slug>/${key.replace('/', '-')}.default.json (or an existing outputExample). Author that file, or record from a real run with \"--from live\".`,\n        );\n      }\n      const problems = validateAgainstSchema(op.output, run.data);\n      if (problems.length > 0) {\n        throw validationError(\n          `${key} returned data that does not satisfy its output schema: ${problems[0]}`,\n          'Fix the output schema or the handler; nothing was written.',\n        );\n      }\n      const file = path.join(examplesDir, `${key.replace('/', '-')}.json`);\n      fs.mkdirSync(examplesDir, { recursive: true });\n      fs.writeFileSync(file, `${JSON.stringify(run.data, null, 2)}\\n`);\n      wrote.push(path.relative(loaded.projectDir, file));\n    }\n    ctx.log(\n      `Recorded ${wrote.length} example(s) from a ${mode} run: ${wrote.join(', ')}. Review them before committing${mode === 'live' ? ' (live data may contain real records)' : ''}.`,\n    );\n    result = analyze();\n  } else if (args.record) {\n    const wrote: string[] = [];\n    const advice: string[] = [];\n    for (const diag of result.diagnostics) {\n      if (diag.rule !== 'contract/example-missing' || !diag.operation) continue;\n      const op = result.contract.operations.find((o) =>\n        o.id.endsWith(`/${diag.operation}`),\n      );\n      if (!op || op.opaque.output) continue;\n      const file = path.join(\n        examplesDir,\n        `${diag.operation.replace('/', '-')}.json`,\n      );\n      fs.mkdirSync(examplesDir, { recursive: true });\n      fs.writeFileSync(\n        file,\n        `${JSON.stringify(sdk.synthesizeExample(op.output), null, 2)}\\n`,\n      );\n      wrote.push(path.relative(loaded.projectDir, file));\n      advice.push(\n        op.effect === 'write'\n          ? `${diag.operation}: add ${writeFixturePath(loaded.primary.slug, diag.operation)} with a real-shaped response, then \"ekanos contract --record --op ${diag.operation} --from fixtures\" (writes are never recorded live)`\n          : `${diag.operation}: add ${writeFixturePath(loaded.primary.slug, diag.operation)}, or \"ekanos contract --record --op ${diag.operation} --from live\"`,\n      );\n    }\n    if (wrote.length > 0) {\n      ctx.log(\n        `Wrote ${wrote.length} placeholder example(s) synthesized from the output schema (not recorded from a run): ${wrote.join(', ')}. Fixtures mode will serve these placeholders until you replace them:\\n  ${advice.join('\\n  ')}`,\n      );\n      result = analyze();\n    }\n  }\n\n  if (args.bump && previous) {\n    const wanted = nextContractVersion(previous, result.contract);\n    if (wanted && wanted !== contractVersion) {\n      contractVersion = wanted;\n      const raw = readJson<Record<string, unknown>>(configPath) ?? {};\n      raw.contract = {\n        ...(raw.contract as object | undefined),\n        version: wanted,\n      };\n      fs.writeFileSync(configPath, `${JSON.stringify(raw, null, 2)}\\n`);\n      ctx.log(`contract.version ${declared} -> ${wanted} in ekanos.json`);\n      result = analyze();\n    }\n  }\n\n  for (const diag of result.diagnostics) {\n    ctx.log(\n      `${diag.severity === 'error' ? 'error' : diag.severity === 'warn' ? 'warn ' : 'info '} ${diag.operation ? `${diag.operation}: ` : ''}${diag.message} (${diag.rule})`,\n    );\n  }\n  const errors = result.diagnostics.filter((d) => d.severity === 'error');\n  if (errors.length > 0) {\n    throw validationError(\n      `${errors.length} contract error(s): ${errors\n        .slice(0, 3)\n        .map((e) => `${e.operation ?? ''} ${e.message}`.trim())\n        .join('; ')}`,\n      'Fix them (declare outputs and examples, or run \"ekanos contract --record\"), then re-run.',\n    );\n  }\n\n  const transition = previous\n    ? assessContractTransition(previous, result.contract).problems\n    : [];\n\n  if (args.check) {\n    const problems = checkContractFreshness(result.contract, previous, {\n      strictPackageVersion: true,\n    });\n    if (problems.length > 0) {\n      throw validationError(\n        `contract.json is out of date: ${problems.map(describe).join(' | ')}`,\n        'Run \"ekanos contract\" (add --bump for the version) and commit contract.json.',\n      );\n    }\n    return ctx.succeed(\n      {\n        ok: true,\n        digest: result.contract.digest,\n        operations: result.contract.operations.length,\n        diagnostics: result.diagnostics,\n      },\n      `contract.json is current (${result.contract.operations.length} operations).`,\n    );\n  }\n\n  if (transition.length > 0) {\n    throw validationError(\n      `This change is not allowed on the current contract version: ${transition.map(describe).join(' | ')}`,\n      'Run \"ekanos contract --bump\", or set contract.version in ekanos.json by hand (a breaking change needs a new compat line).',\n    );\n  }\n  fs.writeFileSync(\n    contractFile,\n    `${JSON.stringify(result.contract, null, 2)}\\n`,\n  );\n  return ctx.succeed(\n    {\n      written: 'contract.json',\n      digest: result.contract.digest,\n      operations: result.contract.operations.length,\n      diagnostics: result.diagnostics,\n    },\n    `Wrote contract.json (${result.contract.operations.length} operations, ${result.contract.compatLine} line, contract ${result.contract.contractVersion}).`,\n  );\n}\n\nexport const contractCommand: ExperienceCommand = {\n  name: 'contract',\n  usage: [\n    '  contract   Derive ./contract.json from the integration definition;',\n    '             --check fails on a stale file (CI, prepack), --record writes',\n    '             missing output examples, --bump bumps the contract version',\n  ],\n  specs: {\n    dir: {\n      type: 'string',\n      description: 'Project directory (default: the current one)',\n    },\n    check: {\n      type: 'boolean',\n      description: 'Derive in memory and fail if contract.json differs',\n    },\n    record: {\n      type: 'boolean',\n      description:\n        'Write placeholder examples (contracts/examples) for operations that have none; with --op, record real ones from a run',\n    },\n    op: {\n      type: 'string',\n      description:\n        'With --record: operation(s) to record from a real run, comma separated (tool/list_posts)',\n    },\n    from: {\n      type: 'string',\n      description:\n        'With --op: run mode to record from, fixtures (default) or live',\n    },\n    input: {\n      type: 'string',\n      description: 'With --op: JSON input for the recorded run',\n    },\n    bump: {\n      type: 'boolean',\n      description:\n        'Rewrite ekanos.json contract.version to match the surface change',\n    },\n  },\n  run(ctx, args) {\n    const from = args.flags.from;\n    if (from !== undefined && from !== 'live' && from !== 'fixtures') {\n      throw usageError(\n        `--from must be \"fixtures\" or \"live\", not \"${String(from)}\".`,\n        'Run \"ekanos contract --record --op tool/<name> --from live\".',\n      );\n    }\n\n    return runContract(ctx, {\n      dir: args.dir,\n      check: args.flags.check === true,\n      record: args.flags.record === true,\n      bump: args.flags.bump === true,\n      env: args.env,\n      ...(typeof args.flags.op === 'string' && args.flags.op !== ''\n        ? { ops: args.flags.op.split(',').map((o) => o.trim()) }\n        : {}),\n      ...(args.flags.from === 'live' || args.flags.from === 'fixtures'\n        ? { from: args.flags.from }\n        : {}),\n      ...(typeof args.flags.input === 'string'\n        ? { input: args.flags.input }\n        : {}),\n    });\n  },\n};\n\n/** Where a scenario fixture for an operation lives, project-relative. */\nfunction writeFixturePath(slug: string, opKey: string): string {\n  return path.join('fixtures', slug, `${opKey.replace('/', '-')}.default.json`);\n}\n"]}

package/dist/commands/dev.d.ts

@@ -1,4 +1,6 @@
+import { type SourceCatalog } from '@ekanos/integration-schema';
 import type { CliContext } from '../context.js';
+import { type HarnessResolver } from '../dev-experience.js';
 export interface DevArgs {
     /** Project directory (contains ekanos.json). Defaults to cwd. */
     dir: string;
@@ -21,6 +23,11 @@ export interface DevArgs {
      */
     start?: boolean;
     env?: Record<string, string | undefined>;
+    /** Experience projects: an offline directory of contracts (`--contracts-dir`). */
+    contractsDir?: string;
+    /** Test seams. */
+    loadResolver?: (projectDir: string) => Promise<HarnessResolver>;
+    fetchCatalog?: () => Promise<SourceCatalog | null>;
 }
 /**
  * `dev` — scaffold the local harness shell into the partner's project, then