@ekanos/cli 0.15.0 → 0.17.0

package/dist/experience/load-experience.js

@@ -0,0 +1,115 @@
+import { build } from 'esbuild';
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { preconditionError } from '../errors.js';
+const stubServerOnly = {
+    name: 'ekanos-stub-server-only',
+    setup(b) {
+        b.onResolve({ filter: /^server-only$/ }, () => ({
+            path: 'server-only',
+            namespace: 'ekanos-server-only-stub',
+        }));
+        b.onLoad({ filter: /.*/, namespace: 'ekanos-server-only-stub' }, () => ({
+            contents: '',
+            loader: 'js',
+        }));
+    },
+};
+/**
+ * Evaluate the experience entry in Node to read its definition, including the
+ * workflow templates' `build()` output. Components are loaded but never
+ * rendered, so a widget needs no browser to be inspected.
+ */
+export async function loadExperience(project, options = {}) {
+    var _a;
+    const entry = path.join(project.dir, project.entry);
+    const nodeModules = path.join(project.dir, 'node_modules');
+    if (!fs.existsSync(nodeModules)) {
+        throw preconditionError(`No node_modules in ${project.dir}: the packages the experience imports are not installed.`, 'Install dependencies first, then re-run.');
+    }
+    const cacheDir = path.join(nodeModules, '.cache', 'ekanos-cli');
+    fs.mkdirSync(cacheDir, { recursive: true });
+    const outfile = path.join(cacheDir, `experience-${crypto.randomBytes(6).toString('hex')}.mjs`);
+    const inlineSdk = (_a = options.inlineSdk) !== null && _a !== void 0 ? _a : process.env.EKANOS_INLINE_SDK;
+    const external = inlineSdk
+        ? ['react', 'react-dom', '@tanstack/react-query']
+        : ['@ekanos/*', 'react', 'react-dom', '@tanstack/react-query', 'zod'];
+    const alias = inlineSdk
+        ? Object.fromEntries([
+            ['experience', 'index.ts'],
+            ['experience/client', 'client.tsx'],
+            ['experience/server', 'server.ts'],
+            ['experience/runtime', 'runtime.ts'],
+        ].map(([sub, file]) => [
+            `@ekanos/sdk/${sub}`,
+            path.join(inlineSdk, 'src', 'experience', file),
+        ]))
+        : undefined;
+    try {
+        try {
+            await build({
+                stdin: {
+                    contents: `import definition from ${JSON.stringify(entry)};\n` +
+                        "export { serializeWorkflowTemplate, slotsUsedBy } from '@ekanos/sdk/experience';\n" +
+                        'export default definition;\n',
+                    resolveDir: project.dir,
+                    sourcefile: 'ekanos-experience-loader.ts',
+                    loader: 'ts',
+                },
+                outfile,
+                alias,
+                platform: 'node',
+                format: 'esm',
+                bundle: true,
+                jsx: 'automatic',
+                external,
+                plugins: [stubServerOnly],
+                loader: { '.css': 'empty', '.svg': 'dataurl', '.png': 'dataurl' },
+                logLevel: 'silent',
+                absWorkingDir: project.dir,
+            });
+        }
+        catch (error) {
+            return {
+                ok: false,
+                message: `Could not bundle ${project.entry}: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+        let mod;
+        try {
+            mod = (await import(pathToFileURL(outfile).href));
+        }
+        catch (error) {
+            return {
+                ok: false,
+                message: `${project.entry} threw while loading: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+        const def = mod.default;
+        if (!def || typeof def !== 'object' || def.kind !== 'experience') {
+            return {
+                ok: false,
+                message: `${project.entry} must "export default defineExperience({...})".`,
+            };
+        }
+        if (typeof mod.serializeWorkflowTemplate !== 'function' ||
+            typeof mod.slotsUsedBy !== 'function') {
+            return {
+                ok: false,
+                message: 'The installed @ekanos/sdk has no experience API. Upgrade it (ekanos upgrade).',
+            };
+        }
+        return {
+            ok: true,
+            definition: def,
+            serializeWorkflowTemplate: mod.serializeWorkflowTemplate,
+            slotsUsedBy: mod.slotsUsedBy,
+        };
+    }
+    finally {
+        fs.rmSync(outfile, { force: true });
+    }
+}
+//# sourceMappingURL=load-experience.js.map

package/dist/experience/load-experience.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-experience.js","sourceRoot":"","sources":["../../src/experience/load-experience.ts"],"names":[],"mappings":"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","sourcesContent":["import { type Plugin, build } from 'esbuild';\nimport * as crypto from 'node:crypto';\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\nimport { pathToFileURL } from 'node:url';\n\nimport { preconditionError } from '../errors';\nimport type {\n  LoadedExperienceDefinition,\n  LoadedExperienceModule,\n} from './definition-shape';\nimport type { ExperienceProject } from './project';\n\nconst stubServerOnly: Plugin = {\n  name: 'ekanos-stub-server-only',\n  setup(b) {\n    b.onResolve({ filter: /^server-only$/ }, () => ({\n      path: 'server-only',\n      namespace: 'ekanos-server-only-stub',\n    }));\n    b.onLoad({ filter: /.*/, namespace: 'ekanos-server-only-stub' }, () => ({\n      contents: '',\n      loader: 'js',\n    }));\n  },\n};\n\nexport interface LoadExperienceOptions {\n  /**\n   * Root of an `@ekanos/sdk` checkout to bundle instead of importing\n   * `@ekanos/sdk` from node_modules. Needed only when the SDK's exports point\n   * at TypeScript source (the monorepo's own tests); a published SDK ships\n   * built output. Also settable as EKANOS_INLINE_SDK.\n   */\n  inlineSdk?: string;\n}\n\nexport type LoadedExperience =\n  | ({ ok: true } & LoadedExperienceModule)\n  | { ok: false; message: string };\n\n/**\n * Evaluate the experience entry in Node to read its definition, including the\n * workflow templates' `build()` output. Components are loaded but never\n * rendered, so a widget needs no browser to be inspected.\n */\nexport async function loadExperience(\n  project: ExperienceProject,\n  options: LoadExperienceOptions = {},\n): Promise<LoadedExperience> {\n  const entry = path.join(project.dir, project.entry);\n  const nodeModules = path.join(project.dir, 'node_modules');\n  if (!fs.existsSync(nodeModules)) {\n    throw preconditionError(\n      `No node_modules in ${project.dir}: the packages the experience imports are not installed.`,\n      'Install dependencies first, then re-run.',\n    );\n  }\n\n  const cacheDir = path.join(nodeModules, '.cache', 'ekanos-cli');\n  fs.mkdirSync(cacheDir, { recursive: true });\n  const outfile = path.join(\n    cacheDir,\n    `experience-${crypto.randomBytes(6).toString('hex')}.mjs`,\n  );\n\n  const inlineSdk = options.inlineSdk ?? process.env.EKANOS_INLINE_SDK;\n  const external = inlineSdk\n    ? ['react', 'react-dom', '@tanstack/react-query']\n    : ['@ekanos/*', 'react', 'react-dom', '@tanstack/react-query', 'zod'];\n  const alias = inlineSdk\n    ? Object.fromEntries(\n        [\n          ['experience', 'index.ts'],\n          ['experience/client', 'client.tsx'],\n          ['experience/server', 'server.ts'],\n          ['experience/runtime', 'runtime.ts'],\n        ].map(([sub, file]) => [\n          `@ekanos/sdk/${sub}`,\n          path.join(inlineSdk, 'src', 'experience', file as string),\n        ]),\n      )\n    : undefined;\n\n  try {\n    try {\n      await build({\n        stdin: {\n          contents:\n            `import definition from ${JSON.stringify(entry)};\\n` +\n            \"export { serializeWorkflowTemplate, slotsUsedBy } from '@ekanos/sdk/experience';\\n\" +\n            'export default definition;\\n',\n          resolveDir: project.dir,\n          sourcefile: 'ekanos-experience-loader.ts',\n          loader: 'ts',\n        },\n        outfile,\n        alias,\n        platform: 'node',\n        format: 'esm',\n        bundle: true,\n        jsx: 'automatic',\n        external,\n        plugins: [stubServerOnly],\n        loader: { '.css': 'empty', '.svg': 'dataurl', '.png': 'dataurl' },\n        logLevel: 'silent',\n        absWorkingDir: project.dir,\n      });\n    } catch (error) {\n      return {\n        ok: false,\n        message: `Could not bundle ${project.entry}: ${error instanceof Error ? error.message : String(error)}`,\n      };\n    }\n\n    let mod: Partial<LoadedExperienceModule> & { default?: unknown };\n    try {\n      mod = (await import(pathToFileURL(outfile).href)) as typeof mod;\n    } catch (error) {\n      return {\n        ok: false,\n        message: `${project.entry} threw while loading: ${error instanceof Error ? error.message : String(error)}`,\n      };\n    }\n\n    const def = mod.default as { kind?: unknown } | undefined;\n    if (!def || typeof def !== 'object' || def.kind !== 'experience') {\n      return {\n        ok: false,\n        message: `${project.entry} must \"export default defineExperience({...})\".`,\n      };\n    }\n\n    if (\n      typeof mod.serializeWorkflowTemplate !== 'function' ||\n      typeof mod.slotsUsedBy !== 'function'\n    ) {\n      return {\n        ok: false,\n        message:\n          'The installed @ekanos/sdk has no experience API. Upgrade it (ekanos upgrade).',\n      };\n    }\n\n    return {\n      ok: true,\n      definition: def as LoadedExperienceDefinition,\n      serializeWorkflowTemplate: mod.serializeWorkflowTemplate,\n      slotsUsedBy: mod.slotsUsedBy,\n    };\n  } finally {\n    fs.rmSync(outfile, { force: true });\n  }\n}\n"]}

package/dist/experience/overrides.d.ts

@@ -0,0 +1,8 @@
+import { type ExperienceProject } from './project.js';
+/**
+ * What counts as an active override (`ekanos.local.json`, `EKANOS_INTEGRATION_OVERRIDE_<INTEGRATION>`,
+ * an unreadable file) is decided once, by the harness's `activeOverrides()`;
+ * `activeOverridesFor` in `dev-experience.ts` loads it from the project.
+ */
+/** True when git tracks ekanos.local.json (it must stay per-developer). */
+export declare function isOverridesFileTracked(project: ExperienceProject): boolean;

package/dist/experience/overrides.js

@@ -0,0 +1,21 @@
+import { execFileSync } from 'node:child_process';
+import { LOCAL_OVERRIDES_FILE } from './project.js';
+/**
+ * What counts as an active override (`ekanos.local.json`, `EKANOS_INTEGRATION_OVERRIDE_<INTEGRATION>`,
+ * an unreadable file) is decided once, by the harness's `activeOverrides()`;
+ * `activeOverridesFor` in `dev-experience.ts` loads it from the project.
+ */
+/** True when git tracks ekanos.local.json (it must stay per-developer). */
+export function isOverridesFileTracked(project) {
+    try {
+        execFileSync('git', ['ls-files', '--error-unmatch', LOCAL_OVERRIDES_FILE], {
+            cwd: project.dir,
+            stdio: 'ignore',
+        });
+        return true;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+//# sourceMappingURL=overrides.js.map

package/dist/experience/overrides.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overrides.js","sourceRoot":"","sources":["../../src/experience/overrides.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,oBAAoB,EAA0B,MAAM,WAAW,CAAC;AAEzE;;;;GAIG;AAEH,2EAA2E;AAC3E,MAAM,UAAU,sBAAsB,CAAC,OAA0B;IAC/D,IAAI,CAAC;QACH,YAAY,CAAC,KAAK,EAAE,CAAC,UAAU,EAAE,iBAAiB,EAAE,oBAAoB,CAAC,EAAE;YACzE,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,KAAK,EAAE,QAAQ;SAChB,CAAC,CAAC;QAEH,OAAO,IAAI,CAAC;IACd,CAAC;eAAO,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC","sourcesContent":["import { execFileSync } from 'node:child_process';\n\nimport { LOCAL_OVERRIDES_FILE, type ExperienceProject } from './project';\n\n/**\n * What counts as an active override (`ekanos.local.json`, `EKANOS_INTEGRATION_OVERRIDE_<INTEGRATION>`,\n * an unreadable file) is decided once, by the harness's `activeOverrides()`;\n * `activeOverridesFor` in `dev-experience.ts` loads it from the project.\n */\n\n/** True when git tracks ekanos.local.json (it must stay per-developer). */\nexport function isOverridesFileTracked(project: ExperienceProject): boolean {\n  try {\n    execFileSync('git', ['ls-files', '--error-unmatch', LOCAL_OVERRIDES_FILE], {\n      cwd: project.dir,\n      stdio: 'ignore',\n    });\n\n    return true;\n  } catch {\n    return false;\n  }\n}\n"]}

package/dist/experience/pin-integration.d.ts

@@ -0,0 +1,8 @@
+import type { Contract, IntegrationEntry } from '@ekanos/integration-schema';
+import type { ExperienceProject } from './project.js';
+/** Write the contract snapshot and lock entry for one integration. Returns what changed. */
+export declare function pinIntegration(project: ExperienceProject, use: IntegrationEntry, contract: Contract): {
+    snapshotChanged: boolean;
+    lockChanged: boolean;
+};
+export declare const relativeTo: (project: ExperienceProject, file: string) => string;

package/dist/experience/pin-integration.js

@@ -0,0 +1,17 @@
+import * as path from 'node:path';
+import { snapshotFile } from './contract-sources.js';
+import { formatJson, readLockfile, writeIfChanged, writeLockfile, } from './project.js';
+/** Write the contract snapshot and lock entry for one integration. Returns what changed. */
+export function pinIntegration(project, use, contract) {
+    const snapshotChanged = writeIfChanged(snapshotFile(project, use.name, use.version), formatJson(contract));
+    const lock = readLockfile(project);
+    lock.integrations[use.name] = {
+        version: use.version,
+        contractVersion: contract.contractVersion,
+        digest: contract.digest,
+    };
+    const lockChanged = writeLockfile(project, lock);
+    return { snapshotChanged, lockChanged };
+}
+export const relativeTo = (project, file) => path.relative(project.dir, file).split(path.sep).join('/');
+//# sourceMappingURL=pin-integration.js.map

package/dist/experience/pin-integration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pin-integration.js","sourceRoot":"","sources":["../../src/experience/pin-integration.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EACL,UAAU,EACV,YAAY,EACZ,cAAc,EACd,aAAa,GACd,MAAM,WAAW,CAAC;AAGnB,4FAA4F;AAC5F,MAAM,UAAU,cAAc,CAC5B,OAA0B,EAC1B,GAAqB,EACrB,QAAkB;IAElB,MAAM,eAAe,GAAG,cAAc,CACpC,YAAY,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,EAC5C,UAAU,CAAC,QAAQ,CAAC,CACrB,CAAC;IAEF,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG;QAC5B,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,eAAe,EAAE,QAAQ,CAAC,eAAe;QACzC,MAAM,EAAE,QAAQ,CAAC,MAAM;KACxB,CAAC;IACF,MAAM,WAAW,GAAG,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAEjD,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,CAAC;AAC1C,CAAC;AAED,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,OAA0B,EAAE,IAAY,EAAE,EAAE,CACrE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC","sourcesContent":["import type { Contract, IntegrationEntry } from '@ekanos/integration-schema';\nimport * as path from 'node:path';\n\nimport { snapshotFile } from './contract-sources';\nimport {\n  formatJson,\n  readLockfile,\n  writeIfChanged,\n  writeLockfile,\n} from './project';\nimport type { ExperienceProject } from './project';\n\n/** Write the contract snapshot and lock entry for one integration. Returns what changed. */\nexport function pinIntegration(\n  project: ExperienceProject,\n  use: IntegrationEntry,\n  contract: Contract,\n): { snapshotChanged: boolean; lockChanged: boolean } {\n  const snapshotChanged = writeIfChanged(\n    snapshotFile(project, use.name, use.version),\n    formatJson(contract),\n  );\n\n  const lock = readLockfile(project);\n  lock.integrations[use.name] = {\n    version: use.version,\n    contractVersion: contract.contractVersion,\n    digest: contract.digest,\n  };\n  const lockChanged = writeLockfile(project, lock);\n\n  return { snapshotChanged, lockChanged };\n}\n\nexport const relativeTo = (project: ExperienceProject, file: string) =>\n  path.relative(project.dir, file).split(path.sep).join('/');\n"]}

package/dist/experience/pin-ops.d.ts

@@ -0,0 +1,12 @@
+import type { Contract, IntegrationEntry } from '@ekanos/integration-schema';
+import { operationId } from '@ekanos/integration-schema';
+/**
+ * Turn `--ops` tokens into canonical operation ids of `contract`. A token is a
+ * canonical id, `kind/name`, or a bare `name` that exactly one operation has.
+ */
+export declare function resolveOpTokens(contract: Contract, tokens: readonly string[]): string[];
+export declare function readOperationIds(contract: Contract): string[];
+/** Stable order: contract order, so reruns never reshuffle ekanos.json. */
+export declare function inContractOrder(contract: Contract, ids: Iterable<string>): string[];
+export { operationId };
+export type { IntegrationEntry };

package/dist/experience/pin-ops.js

@@ -0,0 +1,36 @@
+import { operationId } from '@ekanos/integration-schema';
+import { usageError } from '../errors.js';
+/**
+ * Turn `--ops` tokens into canonical operation ids of `contract`. A token is a
+ * canonical id, `kind/name`, or a bare `name` that exactly one operation has.
+ */
+export function resolveOpTokens(contract, tokens) {
+    const ids = [];
+    for (const token of tokens) {
+        const exact = contract.operations.find((op) => op.id === token || `${op.kind}/${op.name}` === token);
+        const byName = contract.operations.filter((op) => op.name === token);
+        const found = exact !== null && exact !== void 0 ? exact : (byName.length === 1 ? byName[0] : undefined);
+        if (!found) {
+            const known = contract.operations
+                .map((op) => `${op.kind}/${op.name}`)
+                .join(', ');
+            throw usageError(byName.length > 1
+                ? `"${token}" is ambiguous in ${contract.integration}@${contract.compatLine}; write tool/${token} or action/${token}.`
+                : `${contract.integration}@${contract.compatLine} has no operation "${token}".`, `Operations: ${known}.`);
+        }
+        ids.push(found.id);
+    }
+    return ids;
+}
+export function readOperationIds(contract) {
+    return contract.operations
+        .filter((op) => op.effect === 'read')
+        .map((op) => op.id);
+}
+/** Stable order: contract order, so reruns never reshuffle ekanos.json. */
+export function inContractOrder(contract, ids) {
+    const wanted = new Set(ids);
+    return contract.operations.map((op) => op.id).filter((id) => wanted.has(id));
+}
+export { operationId };
+//# sourceMappingURL=pin-ops.js.map

package/dist/experience/pin-ops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pin-ops.js","sourceRoot":"","sources":["../../src/experience/pin-ops.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAEzD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAkB,EAClB,MAAyB;IAEzB,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,QAAQ,CAAC,UAAU,CAAC,IAAI,CACpC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,KAAK,IAAI,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,CAC7D,CAAC;QACF,MAAM,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC;QACrE,MAAM,KAAK,GAAG,KAAK,aAAL,KAAK,cAAL,KAAK,GAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACrE,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,KAAK,GAAG,QAAQ,CAAC,UAAU;iBAC9B,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;iBACpC,IAAI,CAAC,IAAI,CAAC,CAAC;YACd,MAAM,UAAU,CACd,MAAM,CAAC,MAAM,GAAG,CAAC;gBACf,CAAC,CAAC,IAAI,KAAK,qBAAqB,QAAQ,CAAC,WAAW,IAAI,QAAQ,CAAC,UAAU,gBAAgB,KAAK,cAAc,KAAK,GAAG;gBACtH,CAAC,CAAC,GAAG,QAAQ,CAAC,WAAW,IAAI,QAAQ,CAAC,UAAU,sBAAsB,KAAK,IAAI,EACjF,eAAe,KAAK,GAAG,CACxB,CAAC;QACJ,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACrB,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,QAAkB;IACjD,OAAO,QAAQ,CAAC,UAAU;SACvB,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,KAAK,MAAM,CAAC;SACpC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;AACxB,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,eAAe,CAC7B,QAAkB,EAClB,GAAqB;IAErB,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAE5B,OAAO,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;AAC/E,CAAC;AAED,OAAO,EAAE,WAAW,EAAE,CAAC","sourcesContent":["import type { Contract, IntegrationEntry } from '@ekanos/integration-schema';\nimport { operationId } from '@ekanos/integration-schema';\n\nimport { usageError } from '../errors';\n\n/**\n * Turn `--ops` tokens into canonical operation ids of `contract`. A token is a\n * canonical id, `kind/name`, or a bare `name` that exactly one operation has.\n */\nexport function resolveOpTokens(\n  contract: Contract,\n  tokens: readonly string[],\n): string[] {\n  const ids: string[] = [];\n  for (const token of tokens) {\n    const exact = contract.operations.find(\n      (op) => op.id === token || `${op.kind}/${op.name}` === token,\n    );\n    const byName = contract.operations.filter((op) => op.name === token);\n    const found = exact ?? (byName.length === 1 ? byName[0] : undefined);\n    if (!found) {\n      const known = contract.operations\n        .map((op) => `${op.kind}/${op.name}`)\n        .join(', ');\n      throw usageError(\n        byName.length > 1\n          ? `\"${token}\" is ambiguous in ${contract.integration}@${contract.compatLine}; write tool/${token} or action/${token}.`\n          : `${contract.integration}@${contract.compatLine} has no operation \"${token}\".`,\n        `Operations: ${known}.`,\n      );\n    }\n    ids.push(found.id);\n  }\n\n  return ids;\n}\n\nexport function readOperationIds(contract: Contract): string[] {\n  return contract.operations\n    .filter((op) => op.effect === 'read')\n    .map((op) => op.id);\n}\n\n/** Stable order: contract order, so reruns never reshuffle ekanos.json. */\nexport function inContractOrder(\n  contract: Contract,\n  ids: Iterable<string>,\n): string[] {\n  const wanted = new Set(ids);\n\n  return contract.operations.map((op) => op.id).filter((id) => wanted.has(id));\n}\n\nexport { operationId };\nexport type { IntegrationEntry };\n"]}

package/dist/experience/pins.d.ts

@@ -0,0 +1,35 @@
+import { type Contract, type Finding, type Lockfile, type IntegrationEntry } from '@ekanos/integration-schema';
+import type { ExperienceProject } from './project.js';
+export declare const INTEGRATION_PINS_CHECK = "checks/integration-pins";
+export declare const DEPRECATED_USES = "\"uses\" in ekanos.json is deprecated: an experience declares its dependencies as \"integrations\" (name = the integration, version = the compat line). \"ekanos sync\" rewrites the file.";
+/** What a `uses` -> `integrations` upgrade changed in code terms, or null when nothing was renamed. */
+export declare function renamesNotice(renames: Record<string, string>): string | null;
+export interface PinnedIntegration {
+    use: IntegrationEntry;
+    contract: Contract;
+}
+/**
+ * Resolves an integration's contract through the harness registry chain (catalog,
+ * published-package cache, contracts directory), as `createPinsResolver`
+ * returns it. `null` falls back to the committed snapshot.
+ */
+export type PinsResolver = (integration: {
+    name: string;
+    version: string;
+}) => {
+    contract: Contract;
+    lines: string[];
+} | null;
+export declare function loadPinnedContract(project: ExperienceProject, use: IntegrationEntry): Contract | null;
+/**
+ * Every `integrations` entry must resolve, against the pinned contract snapshot, to
+ * the EXACT compat line and contain each declared operation, with the digest
+ * the lockfile recorded. Fails with the first-principles message naming the
+ * integration, so "pinning a line missing an op" is a one-line fix.
+ */
+export declare function checkIntegrationPins(project: ExperienceProject, lock: Lockfile, resolve?: PinsResolver): {
+    findings: Finding[];
+    pinned: PinnedIntegration[];
+};
+/** The effect of `integration` + `kind/name` from the pinned contracts, for workflow serialization. */
+export declare function effectLookup(pinned: readonly PinnedIntegration[]): (integration: string, op: string) => "read" | "write" | undefined;

package/dist/experience/pins.js

@@ -0,0 +1,91 @@
+import { operationKey, verifyContract, } from '@ekanos/integration-schema';
+import * as fs from 'node:fs';
+import { snapshotFile } from './contract-sources.js';
+export const INTEGRATION_PINS_CHECK = 'checks/integration-pins';
+export const DEPRECATED_USES = '"uses" in ekanos.json is deprecated: an experience declares its dependencies as "integrations" (name = the integration, version = the compat line). "ekanos sync" rewrites the file.';
+/** What a `uses` -> `integrations` upgrade changed in code terms, or null when nothing was renamed. */
+export function renamesNotice(renames) {
+    const entries = Object.entries(renames);
+    if (entries.length === 0)
+        return null;
+    return `An integration is now addressed by its own name; update your code: ${entries
+        .map(([alias, integration]) => `'${alias}' -> '${integration}'`)
+        .join(', ')}.`;
+}
+export function loadPinnedContract(project, use) {
+    const file = snapshotFile(project, use.name, use.version);
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        return verifyContract(JSON.parse(fs.readFileSync(file, 'utf8'))).contract;
+    }
+    catch (_a) {
+        return null;
+    }
+}
+const finding = (message, hint, file) => (Object.assign({ check: INTEGRATION_PINS_CHECK, severity: 'error', message,
+    hint }, (file ? { file } : {})));
+/**
+ * Every `integrations` entry must resolve, against the pinned contract snapshot, to
+ * the EXACT compat line and contain each declared operation, with the digest
+ * the lockfile recorded. Fails with the first-principles message naming the
+ * integration, so "pinning a line missing an op" is a one-line fix.
+ */
+export function checkIntegrationPins(project, lock, resolve) {
+    var _a;
+    var _b, _c;
+    const findings = [];
+    const pinned = [];
+    if (project.deprecatedUses) {
+        findings.push({
+            check: INTEGRATION_PINS_CHECK,
+            severity: 'warn',
+            message: DEPRECATED_USES,
+            hint: 'Run "ekanos sync".',
+            file: 'ekanos.json',
+        });
+    }
+    if (project.integrations.length === 0) {
+        findings.push(finding('ekanos.json declares no integrations.', 'Add one with "ekanos add <integration>@<version> --from-dir <contracts folder>".', 'ekanos.json'));
+    }
+    for (const use of project.integrations) {
+        const contract = (_b = (_a = resolve === null || resolve === void 0 ? void 0 : resolve({ name: use.name, version: use.version })) === null || _a === void 0 ? void 0 : _a.contract) !== null && _b !== void 0 ? _b : loadPinnedContract(project, use);
+        if (!contract) {
+            findings.push(finding(`integration "${use.name}": no pinned contract for ${use.name}@${use.version}.`, `Run "ekanos add ${use.name}@${use.version} --from-dir <contracts folder>" or "ekanos sync".`, 'ekanos.json'));
+            continue;
+        }
+        if (contract.compatLine !== use.version) {
+            findings.push(finding(`integration "${use.name}" pins ${use.name}@${use.version} but the pinned contract is version ${contract.compatLine}.`, 'Re-pin with "ekanos sync".', 'ekanos.json'));
+            continue;
+        }
+        const byId = new Map(contract.operations.map((op) => [op.id, op]));
+        for (const id of use.operations) {
+            const op = byId.get(id);
+            if (!op) {
+                const key = (_c = operationKey(id)) !== null && _c !== void 0 ? _c : id;
+                findings.push(finding(`integration "${use.name}": ${use.name}@${use.version} does not provide ${key}.`, `Remove ${key} from the integration's operations, or pin a version that has it (known versions come from "ekanos add").`, 'ekanos.json'));
+            }
+        }
+        const locked = lock.integrations[use.name];
+        if (!locked) {
+            findings.push(finding(`integration "${use.name}" is not in ekanos.lock.json.`, 'Run "ekanos sync" to record the pin.', 'ekanos.lock.json'));
+        }
+        else if (locked.digest !== contract.digest ||
+            locked.version !== use.version) {
+            findings.push(finding(`integration "${use.name}": the pinned contract (${contract.digest.slice(0, 15)}…) does not match ekanos.lock.json (${locked.digest.slice(0, 15)}…).`, 'Run "ekanos sync" to accept the new contract, or restore the old snapshot.', 'ekanos.lock.json'));
+        }
+        pinned.push({ use, contract });
+    }
+    return { findings, pinned };
+}
+/** The effect of `integration` + `kind/name` from the pinned contracts, for workflow serialization. */
+export function effectLookup(pinned) {
+    const effects = new Map();
+    for (const { use, contract } of pinned) {
+        for (const op of contract.operations) {
+            effects.set(`${use.name} ${op.kind}/${op.name}`, op.effect);
+        }
+    }
+    return (integration, op) => effects.get(`${integration} ${op}`);
+}
+//# sourceMappingURL=pins.js.map

package/dist/experience/pins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pins.js","sourceRoot":"","sources":["../../src/experience/pins.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  type Contract,\n  type Finding,\n  type Lockfile,\n  type IntegrationEntry,\n  operationKey,\n  verifyContract,\n} from '@ekanos/integration-schema';\nimport * as fs from 'node:fs';\n\nimport { snapshotFile } from './contract-sources';\nimport type { ExperienceProject } from './project';\n\nexport const INTEGRATION_PINS_CHECK = 'checks/integration-pins';\n\nexport const DEPRECATED_USES =\n  '\"uses\" in ekanos.json is deprecated: an experience declares its dependencies as \"integrations\" (name = the integration, version = the compat line). \"ekanos sync\" rewrites the file.';\n\n/** What a `uses` -> `integrations` upgrade changed in code terms, or null when nothing was renamed. */\nexport function renamesNotice(renames: Record<string, string>): string | null {\n  const entries = Object.entries(renames);\n  if (entries.length === 0) return null;\n\n  return `An integration is now addressed by its own name; update your code: ${entries\n    .map(([alias, integration]) => `'${alias}' -> '${integration}'`)\n    .join(', ')}.`;\n}\n\nexport interface PinnedIntegration {\n  use: IntegrationEntry;\n  contract: Contract;\n}\n\n/**\n * Resolves an integration's contract through the harness registry chain (catalog,\n * published-package cache, contracts directory), as `createPinsResolver`\n * returns it. `null` falls back to the committed snapshot.\n */\nexport type PinsResolver = (integration: {\n  name: string;\n  version: string;\n}) => { contract: Contract; lines: string[] } | null;\n\nexport function loadPinnedContract(\n  project: ExperienceProject,\n  use: IntegrationEntry,\n): Contract | null {\n  const file = snapshotFile(project, use.name, use.version);\n  if (!fs.existsSync(file)) return null;\n  try {\n    return verifyContract(JSON.parse(fs.readFileSync(file, 'utf8'))).contract;\n  } catch {\n    return null;\n  }\n}\n\nconst finding = (message: string, hint: string, file?: string): Finding => ({\n  check: INTEGRATION_PINS_CHECK,\n  severity: 'error',\n  message,\n  hint,\n  ...(file ? { file } : {}),\n});\n\n/**\n * Every `integrations` entry must resolve, against the pinned contract snapshot, to\n * the EXACT compat line and contain each declared operation, with the digest\n * the lockfile recorded. Fails with the first-principles message naming the\n * integration, so \"pinning a line missing an op\" is a one-line fix.\n */\nexport function checkIntegrationPins(\n  project: ExperienceProject,\n  lock: Lockfile,\n  resolve?: PinsResolver,\n): { findings: Finding[]; pinned: PinnedIntegration[] } {\n  const findings: Finding[] = [];\n  const pinned: PinnedIntegration[] = [];\n\n  if (project.deprecatedUses) {\n    findings.push({\n      check: INTEGRATION_PINS_CHECK,\n      severity: 'warn',\n      message: DEPRECATED_USES,\n      hint: 'Run \"ekanos sync\".',\n      file: 'ekanos.json',\n    });\n  }\n\n  if (project.integrations.length === 0) {\n    findings.push(\n      finding(\n        'ekanos.json declares no integrations.',\n        'Add one with \"ekanos add <integration>@<version> --from-dir <contracts folder>\".',\n        'ekanos.json',\n      ),\n    );\n  }\n\n  for (const use of project.integrations) {\n    const contract =\n      resolve?.({ name: use.name, version: use.version })?.contract ??\n      loadPinnedContract(project, use);\n    if (!contract) {\n      findings.push(\n        finding(\n          `integration \"${use.name}\": no pinned contract for ${use.name}@${use.version}.`,\n          `Run \"ekanos add ${use.name}@${use.version} --from-dir <contracts folder>\" or \"ekanos sync\".`,\n          'ekanos.json',\n        ),\n      );\n      continue;\n    }\n    if (contract.compatLine !== use.version) {\n      findings.push(\n        finding(\n          `integration \"${use.name}\" pins ${use.name}@${use.version} but the pinned contract is version ${contract.compatLine}.`,\n          'Re-pin with \"ekanos sync\".',\n          'ekanos.json',\n        ),\n      );\n      continue;\n    }\n\n    const byId = new Map(contract.operations.map((op) => [op.id, op]));\n    for (const id of use.operations) {\n      const op = byId.get(id);\n      if (!op) {\n        const key = operationKey(id) ?? id;\n        findings.push(\n          finding(\n            `integration \"${use.name}\": ${use.name}@${use.version} does not provide ${key}.`,\n            `Remove ${key} from the integration's operations, or pin a version that has it (known versions come from \"ekanos add\").`,\n            'ekanos.json',\n          ),\n        );\n      }\n    }\n\n    const locked = lock.integrations[use.name];\n    if (!locked) {\n      findings.push(\n        finding(\n          `integration \"${use.name}\" is not in ekanos.lock.json.`,\n          'Run \"ekanos sync\" to record the pin.',\n          'ekanos.lock.json',\n        ),\n      );\n    } else if (\n      locked.digest !== contract.digest ||\n      locked.version !== use.version\n    ) {\n      findings.push(\n        finding(\n          `integration \"${use.name}\": the pinned contract (${contract.digest.slice(0, 15)}…) does not match ekanos.lock.json (${locked.digest.slice(0, 15)}…).`,\n          'Run \"ekanos sync\" to accept the new contract, or restore the old snapshot.',\n          'ekanos.lock.json',\n        ),\n      );\n    }\n\n    pinned.push({ use, contract });\n  }\n\n  return { findings, pinned };\n}\n\n/** The effect of `integration` + `kind/name` from the pinned contracts, for workflow serialization. */\nexport function effectLookup(pinned: readonly PinnedIntegration[]) {\n  const effects = new Map<string, 'read' | 'write'>();\n  for (const { use, contract } of pinned) {\n    for (const op of contract.operations) {\n      effects.set(`${use.name} ${op.kind}/${op.name}`, op.effect);\n    }\n  }\n\n  return (integration: string, op: string) =>\n    effects.get(`${integration} ${op}`);\n}\n"]}

package/dist/experience/project.d.ts

@@ -0,0 +1,52 @@
+import { type EkanosJson, type IntegrationEntry, type Lockfile } from '@ekanos/integration-schema';
+export declare const EKANOS_JSON = "ekanos.json";
+export declare const LOCK_FILE = "ekanos.lock.json";
+export declare const LOCAL_OVERRIDES_FILE = "ekanos.local.json";
+export declare const DEFAULT_CONTRACTS_DIR = "contracts";
+export declare const INTEGRATIONS_DTS = "src/.ekanos/integrations.d.ts";
+/** The previous name of the generated file, kept as a re-export for one version. */
+export declare const LEGACY_SLOTS_DTS = "src/.ekanos/slots.d.ts";
+export interface ExperienceProject {
+    /** Absolute project directory. */
+    dir: string;
+    ekanos: EkanosJson;
+    slug: string;
+    entry: string;
+    /** The integrations it depends on; operations are canonical ids. */
+    integrations: IntegrationEntry[];
+    /** True when ekanos.json still uses the deprecated `uses` key. */
+    deprecatedUses: boolean;
+    /** Old `uses` alias -> integration, where they differ (for the sync notice). */
+    renames: Record<string, string>;
+    /** Absolute directory holding the pinned contract snapshots. */
+    contractsDir: string;
+    /** The raw ekanos.json, key order preserved, for rewrites. */
+    raw: Record<string, unknown>;
+}
+/** `integration` when ekanos.json is absent or says so; used to route commands. */
+export declare function readProjectKind(dir: string): 'integration' | 'experience';
+/**
+ * Read and validate an experience's ekanos.json with the shared schema.
+ *
+ * A fresh scaffold has no integrations yet (you add them with `ekanos add`),
+ * which the shared schema rejects ("declares at least one integration"). That
+ * one rule is suspended here so `add` can bootstrap a project; `check` and
+ * `build` report the empty state themselves.
+ *
+ * The deprecated `uses` shape is read too: its entries come back as
+ * `integrations` (alias dropped) with `deprecatedUses` set and `renames`
+ * mapping each old alias to its integration, so `ekanos sync` can rewrite the
+ * file and say what code to update.
+ */
+export declare function readExperienceProject(dir: string): ExperienceProject;
+/** 2-space JSON with a trailing newline: the format every written file uses. */
+export declare function formatJson(value: unknown): string;
+/** Write only when the bytes differ. Returns whether the file changed. */
+export declare function writeIfChanged(file: string, content: string): boolean;
+export declare function readLockfile(project: ExperienceProject): Lockfile;
+export declare function writeLockfile(project: ExperienceProject, lock: Lockfile): boolean;
+/**
+ * Rewrite `integrations` in ekanos.json (short operation form), leaving every
+ * other key where it was and dropping the deprecated `uses`.
+ */
+export declare function writeIntegrations(project: ExperienceProject, integrations: IntegrationEntry[]): boolean;

package/dist/experience/project.js

@@ -0,0 +1,149 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { EkanosJsonSchema, LockfileSchema, canonicalOperationId, experienceIntegrations, shortOperation, } from '@ekanos/integration-schema';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { notFoundError, validationError } from '../errors.js';
+export const EKANOS_JSON = 'ekanos.json';
+export const LOCK_FILE = 'ekanos.lock.json';
+export const LOCAL_OVERRIDES_FILE = 'ekanos.local.json';
+export const DEFAULT_CONTRACTS_DIR = 'contracts';
+export const INTEGRATIONS_DTS = 'src/.ekanos/integrations.d.ts';
+/** The previous name of the generated file, kept as a re-export for one version. */
+export const LEGACY_SLOTS_DTS = 'src/.ekanos/slots.d.ts';
+function readJson(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch (_a) {
+        throw notFoundError(`No ${path.basename(file)} at ${file}.`, 'Run this from an Ekanos project directory, or pass --dir <path>.');
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw validationError(`${file} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, 'Fix the syntax error and re-run.');
+    }
+}
+/** `integration` when ekanos.json is absent or says so; used to route commands. */
+export function readProjectKind(dir) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(dir, EKANOS_JSON), 'utf8'));
+        return raw.kind === 'experience' ? 'experience' : 'integration';
+    }
+    catch (_a) {
+        return 'integration';
+    }
+}
+/**
+ * Read and validate an experience's ekanos.json with the shared schema.
+ *
+ * A fresh scaffold has no integrations yet (you add them with `ekanos add`),
+ * which the shared schema rejects ("declares at least one integration"). That
+ * one rule is suspended here so `add` can bootstrap a project; `check` and
+ * `build` report the empty state themselves.
+ *
+ * The deprecated `uses` shape is read too: its entries come back as
+ * `integrations` (alias dropped) with `deprecatedUses` set and `renames`
+ * mapping each old alias to its integration, so `ekanos sync` can rewrite the
+ * file and say what code to update.
+ */
+export function readExperienceProject(dir) {
+    var _a;
+    const absolute = path.resolve(dir);
+    const raw = readJson(path.join(absolute, EKANOS_JSON));
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw validationError(`${EKANOS_JSON} must be a JSON object.`, 'Fix it.');
+    }
+    const record = raw;
+    if (record.kind !== 'experience') {
+        throw validationError(`${EKANOS_JSON} is not an experience ("kind": "experience").`, 'Run experience commands in an experience project; scaffold one with "ekanos init --kind experience --slug <slug>".');
+    }
+    const declaredNone = !(Array.isArray(record.integrations) && record.integrations.length > 0) &&
+        !(Array.isArray(record.uses) && record.uses.length > 0);
+    const probe = declaredNone
+        ? Object.assign(Object.assign({}, record), { integrations: [PLACEHOLDER_INTEGRATION], uses: undefined }) : record;
+    const parsed = EkanosJsonSchema.safeParse(probe);
+    if (!parsed.success) {
+        throw validationError(`${EKANOS_JSON}: ${parsed.error.issues
+            .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+            .join('; ')}`, 'Fix ekanos.json; the experience fields are slug, entry, integrations, contractsDir, allowImports, ignore.');
+    }
+    const ekanos = parsed.data;
+    const declared = declaredNone
+        ? { entries: [], deprecatedUses: false, renames: {} }
+        : experienceIntegrations(ekanos);
+    return {
+        dir: absolute,
+        ekanos,
+        slug: ekanos.slug,
+        entry: ekanos.entry,
+        integrations: declared.entries.map(withCanonicalOperations),
+        deprecatedUses: declared.deprecatedUses,
+        renames: declared.renames,
+        contractsDir: path.resolve(absolute, (_a = ekanos.contractsDir) !== null && _a !== void 0 ? _a : DEFAULT_CONTRACTS_DIR),
+        raw: record,
+    };
+}
+/** Operations as canonical `<integration>@<version>/<kind>/<name>` ids, for lookups against a contract. */
+function withCanonicalOperations(entry) {
+    return Object.assign(Object.assign({}, entry), { operations: entry.operations.map((id) => canonicalOperationId(entry, id)) });
+}
+/** 2-space JSON with a trailing newline: the format every written file uses. */
+export function formatJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+/** Write only when the bytes differ. Returns whether the file changed. */
+export function writeIfChanged(file, content) {
+    try {
+        if (fs.readFileSync(file, 'utf8') === content)
+            return false;
+    }
+    catch (_a) {
+        // missing: write below
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, content);
+    return true;
+}
+export function readLockfile(project) {
+    const file = path.join(project.dir, LOCK_FILE);
+    if (!fs.existsSync(file))
+        return { lockfileVersion: 1, integrations: {} };
+    const parsed = LockfileSchema.safeParse(readJson(file));
+    if (!parsed.success) {
+        throw validationError(`${LOCK_FILE}: ${parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`, 'Regenerate it with "ekanos sync".');
+    }
+    return parsed.data;
+}
+export function writeLockfile(project, lock) {
+    const integrations = Object.fromEntries(Object.entries(lock.integrations).sort(([a], [b]) => (a < b ? -1 : 1)));
+    return writeIfChanged(path.join(project.dir, LOCK_FILE), formatJson({ lockfileVersion: 1, integrations }));
+}
+const PLACEHOLDER_INTEGRATION = {
+    name: 'pending',
+    version: '0',
+    operations: ['tool/pending'],
+};
+/**
+ * Rewrite `integrations` in ekanos.json (short operation form), leaving every
+ * other key where it was and dropping the deprecated `uses`.
+ */
+export function writeIntegrations(project, integrations) {
+    const _a = project.raw, { uses: _uses } = _a, rest = __rest(_a, ["uses"]);
+    const next = Object.assign(Object.assign({}, rest), { integrations: integrations.map((entry) => (Object.assign(Object.assign({ name: entry.name, version: entry.version, operations: entry.operations.map(shortOperation) }, (entry.required === 'required' ? {} : { required: entry.required })), (entry.modes.length === 1 && entry.modes[0] === 'team'
+            ? {}
+            : { modes: entry.modes })))) });
+    return writeIfChanged(path.join(project.dir, EKANOS_JSON), formatJson(next));
+}
+//# sourceMappingURL=project.js.map