@ekanos/cli 0.16.0 → 0.17.1

package/dist/experience/integrations-codegen.js

@@ -0,0 +1,51 @@
+import { operationKey } from '@ekanos/integration-schema';
+import { toTs } from './json-schema-to-ts.js';
+export const GENERATED_BANNER = '// GENERATED by `ekanos codegen` from the pinned contracts. Do not edit; commit it.\n' +
+    '// Run `ekanos add <integration>@<version>` or `ekanos sync` to change the integrations.\n';
+/**
+ * The `declare module` file that gives `useOperation` / `operation()` /
+ * `step.tool` their types. Only operations the experience declared appear, so
+ * calling any other is a compile error as well as a runner refusal.
+ */
+export function generateIntegrationsDts(integrations) {
+    const sorted = [...integrations].sort((a, b) => a.integration < b.integration ? -1 : 1);
+    const blocks = sorted.map(({ integration, contract, operations }) => {
+        const wanted = new Set(operations);
+        const ops = contract.operations
+            .filter((op) => wanted.has(`${op.kind}/${op.name}`))
+            .sort((a, b) => (`${a.kind}/${a.name}` < `${b.kind}/${b.name}` ? -1 : 1))
+            .map((op) => {
+            const input = toTs(op.input, '          ');
+            const output = op.opaque.output
+                ? 'unknown'
+                : toTs(op.output, '          ');
+            return (`        ${JSON.stringify(`${op.kind}/${op.name}`)}: {\n` +
+                `          effect: ${JSON.stringify(op.effect)};\n` +
+                `          input: ${input};\n` +
+                `          output: ${output};\n` +
+                '        };');
+        });
+        return (`    ${JSON.stringify(integration).replace(/^"|"$/g, (q) => q)}: {\n` +
+            `      version: ${JSON.stringify(contract.compatLine)};\n` +
+            '      ops: {\n' +
+            `${ops.join('\n')}\n` +
+            '      };\n' +
+            '    };');
+    });
+    if (blocks.length === 0) {
+        return `${GENERATED_BANNER}export {};\n`;
+    }
+    return (`${GENERATED_BANNER}export {};\n\n` +
+        "declare module '@ekanos/sdk/experience' {\n" +
+        '  interface IntegrationRegistry {\n' +
+        `${blocks.join('\n')}\n` +
+        '  }\n' +
+        '}\n');
+}
+/** `kind/name` keys of an integration's declared operations (canonical ids stripped). */
+export function declaredOperationKeys(integration) {
+    return integration.operations
+        .map((id) => operationKey(id))
+        .filter((key) => key !== null);
+}
+//# sourceMappingURL=integrations-codegen.js.map

package/dist/experience/integrations-codegen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrations-codegen.js","sourceRoot":"","sources":["../../src/experience/integrations-codegen.ts"],"names":[],"mappings":"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","sourcesContent":["import { type Contract, operationKey } from '@ekanos/integration-schema';\n\nimport { toTs } from './json-schema-to-ts';\nimport type { ExperienceProject } from './project';\n\nexport const GENERATED_BANNER =\n  '// GENERATED by `ekanos codegen` from the pinned contracts. Do not edit; commit it.\\n' +\n  '// Run `ekanos add <integration>@<version>` or `ekanos sync` to change the integrations.\\n';\n\nexport interface IntegrationContract {\n  integration: string;\n  contract: Contract;\n  /** The `kind/name` keys the experience declared for this integration in `integrations[].operations`. */\n  operations: readonly string[];\n}\n\n/**\n * The `declare module` file that gives `useOperation` / `operation()` /\n * `step.tool` their types. Only operations the experience declared appear, so\n * calling any other is a compile error as well as a runner refusal.\n */\nexport function generateIntegrationsDts(\n  integrations: readonly IntegrationContract[],\n): string {\n  const sorted = [...integrations].sort((a, b) =>\n    a.integration < b.integration ? -1 : 1,\n  );\n  const blocks = sorted.map(({ integration, contract, operations }) => {\n    const wanted = new Set(operations);\n    const ops = contract.operations\n      .filter((op) => wanted.has(`${op.kind}/${op.name}`))\n      .sort((a, b) => (`${a.kind}/${a.name}` < `${b.kind}/${b.name}` ? -1 : 1))\n      .map((op) => {\n        const input = toTs(op.input, '          ');\n        const output = op.opaque.output\n          ? 'unknown'\n          : toTs(op.output, '          ');\n\n        return (\n          `        ${JSON.stringify(`${op.kind}/${op.name}`)}: {\\n` +\n          `          effect: ${JSON.stringify(op.effect)};\\n` +\n          `          input: ${input};\\n` +\n          `          output: ${output};\\n` +\n          '        };'\n        );\n      });\n\n    return (\n      `    ${JSON.stringify(integration).replace(/^\"|\"$/g, (q) => q)}: {\\n` +\n      `      version: ${JSON.stringify(contract.compatLine)};\\n` +\n      '      ops: {\\n' +\n      `${ops.join('\\n')}\\n` +\n      '      };\\n' +\n      '    };'\n    );\n  });\n\n  if (blocks.length === 0) {\n    return `${GENERATED_BANNER}export {};\\n`;\n  }\n\n  return (\n    `${GENERATED_BANNER}export {};\\n\\n` +\n    \"declare module '@ekanos/sdk/experience' {\\n\" +\n    '  interface IntegrationRegistry {\\n' +\n    `${blocks.join('\\n')}\\n` +\n    '  }\\n' +\n    '}\\n'\n  );\n}\n\n/** `kind/name` keys of an integration's declared operations (canonical ids stripped). */\nexport function declaredOperationKeys(\n  integration: ExperienceProject['integrations'][number],\n): string[] {\n  return integration.operations\n    .map((id) => operationKey(id))\n    .filter((key): key is NonNullable<typeof key> => key !== null);\n}\n"]}

package/dist/experience/json-schema-to-ts.d.ts

@@ -0,0 +1 @@
+export declare function toTs(schema: unknown, indent?: string): string;

package/dist/experience/json-schema-to-ts.js

@@ -0,0 +1,90 @@
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function key(name) {
+    return IDENT.test(name) ? name : JSON.stringify(name);
+}
+function literal(value) {
+    var _a;
+    return (_a = JSON.stringify(value)) !== null && _a !== void 0 ? _a : 'unknown';
+}
+function forType(type, schema, indent) {
+    switch (type) {
+        case 'string':
+            return 'string';
+        case 'number':
+        case 'integer':
+            return 'number';
+        case 'boolean':
+            return 'boolean';
+        case 'null':
+            return 'null';
+        case 'array': {
+            const items = isRecord(schema.items)
+                ? toTs(schema.items, indent)
+                : 'unknown';
+            return items.includes(' | ') || items.includes('&')
+                ? `Array<${items}>`
+                : `${items}[]`;
+        }
+        case 'object':
+            return objectType(schema, indent);
+        default:
+            return 'unknown';
+    }
+}
+function objectType(schema, indent) {
+    const properties = isRecord(schema.properties) ? schema.properties : {};
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    const names = Object.keys(properties);
+    const extra = schema.additionalProperties;
+    if (names.length === 0) {
+        if (isRecord(extra))
+            return `Record<string, ${toTs(extra, indent)}>`;
+        if (extra === true)
+            return 'Record<string, unknown>';
+        return 'Record<string, never>';
+    }
+    const inner = `${indent}  `;
+    const lines = names.map((name) => {
+        const value = properties[name];
+        const type = isRecord(value) ? toTs(value, inner) : 'unknown';
+        return `${inner}${key(name)}${required.has(name) ? '' : '?'}: ${type};`;
+    });
+    if (isRecord(extra)) {
+        lines.push(`${inner}[key: string]: ${toTs(extra, inner)};`);
+    }
+    else if (extra === true) {
+        lines.push(`${inner}[key: string]: unknown;`);
+    }
+    return `{\n${lines.join('\n')}\n${indent}}`;
+}
+export function toTs(schema, indent = '') {
+    var _a;
+    if (schema === true || schema === undefined)
+        return 'unknown';
+    if (schema === false)
+        return 'never';
+    if (!isRecord(schema))
+        return 'unknown';
+    if ('const' in schema)
+        return literal(schema.const);
+    if (Array.isArray(schema.enum)) {
+        return schema.enum.map(literal).join(' | ') || 'never';
+    }
+    const alternatives = (_a = schema.anyOf) !== null && _a !== void 0 ? _a : schema.oneOf;
+    if (Array.isArray(alternatives)) {
+        const parts = alternatives.map((alt) => toTs(alt, indent));
+        return [...new Set(parts)].join(' | ') || 'never';
+    }
+    if (Array.isArray(schema.type)) {
+        const parts = schema.type.map((type) => forType(type, schema, indent));
+        return [...new Set(parts)].join(' | ');
+    }
+    if (typeof schema.type === 'string') {
+        return forType(schema.type, schema, indent);
+    }
+    if (isRecord(schema.properties))
+        return objectType(schema, indent);
+    return 'unknown';
+}
+//# sourceMappingURL=json-schema-to-ts.js.map

package/dist/experience/json-schema-to-ts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema-to-ts.js","sourceRoot":"","sources":["../../src/experience/json-schema-to-ts.ts"],"names":[],"mappings":"AAWA,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAmB,EAAE,CACnD,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAEvE,MAAM,KAAK,GAAG,4BAA4B,CAAC;AAE3C,SAAS,GAAG,CAAC,IAAY;IACvB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;AACxD,CAAC;AAED,SAAS,OAAO,CAAC,KAAc;;IAC7B,aAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,mCAAI,SAAS,CAAC;AAC5C,CAAC;AAED,SAAS,OAAO,CAAC,IAAY,EAAE,MAAc,EAAE,MAAc;IAC3D,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ;YACX,OAAO,QAAQ,CAAC;QAClB,KAAK,QAAQ,CAAC;QACd,KAAK,SAAS;YACZ,OAAO,QAAQ,CAAC;QAClB,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC;QACnB,KAAK,MAAM;YACT,OAAO,MAAM,CAAC;QAChB,KAAK,OAAO,EAAE,CAAC;YACb,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC;gBAClC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC;gBAC5B,CAAC,CAAC,SAAS,CAAC;YAEd,OAAO,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;gBACjD,CAAC,CAAC,SAAS,KAAK,GAAG;gBACnB,CAAC,CAAC,GAAG,KAAK,IAAI,CAAC;QACnB,CAAC;QACD,KAAK,QAAQ;YACX,OAAO,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACpC;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,MAAc,EAAE,MAAc;IAChD,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;IACxE,MAAM,QAAQ,GAAG,IAAI,GAAG,CACtB,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAE,MAAM,CAAC,QAAqB,CAAC,CAAC,CAAC,EAAE,CACpE,CAAC;IACF,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,MAAM,CAAC,oBAAoB,CAAC;IAE1C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,IAAI,QAAQ,CAAC,KAAK,CAAC;YAAE,OAAO,kBAAkB,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC;QACrE,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,yBAAyB,CAAC;QAErD,OAAO,uBAAuB,CAAC;IACjC,CAAC;IAED,MAAM,KAAK,GAAG,GAAG,MAAM,IAAI,CAAC;IAC5B,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QAC/B,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QAC/B,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAE9D,OAAO,GAAG,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,GAAG,CAAC;IAC1E,CAAC,CAAC,CAAC;IACH,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACpB,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,kBAAkB,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9D,CAAC;SAAM,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,yBAAyB,CAAC,CAAC;IAChD,CAAC;IAED,OAAO,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,MAAM,GAAG,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,MAAe,EAAE,MAAM,GAAG,EAAE;;IAC/C,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC9D,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,OAAO,CAAC;IACrC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IAExC,IAAI,OAAO,IAAI,MAAM;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAEpD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC;IACzD,CAAC;IAED,MAAM,YAAY,SAAG,MAAM,CAAC,KAAK,mCAAI,MAAM,CAAC,KAAK,CAAC;IAClD,IAAI,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;QAE3D,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC;IACpD,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAI,MAAM,CAAC,IAAiB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CACnD,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAC9B,CAAC;QAEF,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;IAED,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACpC,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC;QAAE,OAAO,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEnE,OAAO,SAAS,CAAC;AACnB,CAAC","sourcesContent":["/**\n * JSON Schema (the contract dialect) to a TypeScript type expression.\n *\n * Deliberately small: contracts only carry the subset `validateAgainstSchema`\n * understands (type, properties/required/additionalProperties, items, enum,\n * const, anyOf/oneOf, nullable type arrays). Anything else degrades to\n * `unknown`, never to a wrong type. Output is deterministic (property order is\n * the schema's own), so regenerating is a byte-for-byte no-op.\n */\ntype Schema = Record<string, unknown>;\n\nconst isRecord = (value: unknown): value is Schema =>\n  typeof value === 'object' && value !== null && !Array.isArray(value);\n\nconst IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;\n\nfunction key(name: string): string {\n  return IDENT.test(name) ? name : JSON.stringify(name);\n}\n\nfunction literal(value: unknown): string {\n  return JSON.stringify(value) ?? 'unknown';\n}\n\nfunction forType(type: string, schema: Schema, indent: string): string {\n  switch (type) {\n    case 'string':\n      return 'string';\n    case 'number':\n    case 'integer':\n      return 'number';\n    case 'boolean':\n      return 'boolean';\n    case 'null':\n      return 'null';\n    case 'array': {\n      const items = isRecord(schema.items)\n        ? toTs(schema.items, indent)\n        : 'unknown';\n\n      return items.includes(' | ') || items.includes('&')\n        ? `Array<${items}>`\n        : `${items}[]`;\n    }\n    case 'object':\n      return objectType(schema, indent);\n    default:\n      return 'unknown';\n  }\n}\n\nfunction objectType(schema: Schema, indent: string): string {\n  const properties = isRecord(schema.properties) ? schema.properties : {};\n  const required = new Set(\n    Array.isArray(schema.required) ? (schema.required as string[]) : [],\n  );\n  const names = Object.keys(properties);\n  const extra = schema.additionalProperties;\n\n  if (names.length === 0) {\n    if (isRecord(extra)) return `Record<string, ${toTs(extra, indent)}>`;\n    if (extra === true) return 'Record<string, unknown>';\n\n    return 'Record<string, never>';\n  }\n\n  const inner = `${indent}  `;\n  const lines = names.map((name) => {\n    const value = properties[name];\n    const type = isRecord(value) ? toTs(value, inner) : 'unknown';\n\n    return `${inner}${key(name)}${required.has(name) ? '' : '?'}: ${type};`;\n  });\n  if (isRecord(extra)) {\n    lines.push(`${inner}[key: string]: ${toTs(extra, inner)};`);\n  } else if (extra === true) {\n    lines.push(`${inner}[key: string]: unknown;`);\n  }\n\n  return `{\\n${lines.join('\\n')}\\n${indent}}`;\n}\n\nexport function toTs(schema: unknown, indent = ''): string {\n  if (schema === true || schema === undefined) return 'unknown';\n  if (schema === false) return 'never';\n  if (!isRecord(schema)) return 'unknown';\n\n  if ('const' in schema) return literal(schema.const);\n\n  if (Array.isArray(schema.enum)) {\n    return schema.enum.map(literal).join(' | ') || 'never';\n  }\n\n  const alternatives = schema.anyOf ?? schema.oneOf;\n  if (Array.isArray(alternatives)) {\n    const parts = alternatives.map((alt) => toTs(alt, indent));\n\n    return [...new Set(parts)].join(' | ') || 'never';\n  }\n\n  if (Array.isArray(schema.type)) {\n    const parts = (schema.type as string[]).map((type) =>\n      forType(type, schema, indent),\n    );\n\n    return [...new Set(parts)].join(' | ');\n  }\n\n  if (typeof schema.type === 'string') {\n    return forType(schema.type, schema, indent);\n  }\n\n  if (isRecord(schema.properties)) return objectType(schema, indent);\n\n  return 'unknown';\n}\n"]}

package/dist/experience/load-experience.d.ts

@@ -0,0 +1,23 @@
+import type { LoadedExperienceModule } from './definition-shape.js';
+import type { ExperienceProject } from './project.js';
+export interface LoadExperienceOptions {
+    /**
+     * Root of an `@ekanos/sdk` checkout to bundle instead of importing
+     * `@ekanos/sdk` from node_modules. Needed only when the SDK's exports point
+     * at TypeScript source (the monorepo's own tests); a published SDK ships
+     * built output. Also settable as EKANOS_INLINE_SDK.
+     */
+    inlineSdk?: string;
+}
+export type LoadedExperience = ({
+    ok: true;
+} & LoadedExperienceModule) | {
+    ok: false;
+    message: string;
+};
+/**
+ * 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 declare function loadExperience(project: ExperienceProject, options?: LoadExperienceOptions): Promise<LoadedExperience>;

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"]}