@ekanos/cli 0.15.0 → 0.17.0

package/dist/experience/build.js

@@ -0,0 +1,90 @@
+import { ExperienceManifestSchema, } from '@ekanos/integration-schema';
+import { build as esbuild } from 'esbuild';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { preconditionError } from '../errors.js';
+import { ALLOWED_EXTERNALS } from './boundary.js';
+import { buildManifest } from './definition-checks.js';
+import { formatJson, writeIfChanged } from './project.js';
+export const DIST_ENTRY = 'dist/experience.js';
+export const DIST_TYPES = 'dist/experience.d.ts';
+export const MANIFEST_FILE = 'manifest.json';
+function readPackageJson(project) {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(project.dir, 'package.json'), 'utf8'));
+    }
+    catch (_a) {
+        throw preconditionError('package.json is missing or unreadable.', 'An experience is an npm package; run "ekanos init --kind experience" or add a package.json.');
+    }
+}
+function sdkVersion(project, declared) {
+    var _a;
+    try {
+        const installed = JSON.parse(fs.readFileSync(path.join(project.dir, 'node_modules', '@ekanos', 'sdk', 'package.json'), 'utf8'));
+        if (installed.version)
+            return installed.version;
+    }
+    catch (_b) {
+        // not installed: fall back to the declared range
+    }
+    return ((_a = declared === null || declared === void 0 ? void 0 : declared['@ekanos/sdk']) !== null && _a !== void 0 ? _a : 'unknown').replace(/^[\^~]/, '');
+}
+/**
+ * Emit `dist/experience.js` (browser ESM, runtime packages left external),
+ * `dist/experience.d.ts` and `manifest.json`. Assumes the checks passed.
+ */
+export async function emitExperience(project, result) {
+    var _a;
+    var _b, _c, _d;
+    const loaded = result.loaded;
+    if (!loaded) {
+        throw preconditionError('The experience definition was not loaded.', 'Run "ekanos check" to see why.');
+    }
+    const pkg = readPackageJson(project);
+    const version = (_b = pkg.version) !== null && _b !== void 0 ? _b : '';
+    if (!/^\d+\.\d+\.\d+/.test(version)) {
+        throw preconditionError(`package.json "version" is "${version}", not semver.`, 'Set a version such as 0.1.0.');
+    }
+    const manifest = buildManifest({
+        project,
+        definition: loaded.definition,
+        pinned: result.pinned,
+        workflows: result.workflows,
+        version,
+        sdk: sdkVersion(project, pkg.dependencies),
+    });
+    const parsed = ExperienceManifestSchema.safeParse(manifest);
+    if (!parsed.success) {
+        throw preconditionError(`The generated manifest is invalid: ${parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`, 'This is a bug in @ekanos/cli or an unsupported definition; report it.');
+    }
+    const bundle = await esbuild({
+        entryPoints: [path.join(project.dir, project.entry)],
+        bundle: true,
+        write: false,
+        format: 'esm',
+        platform: 'browser',
+        jsx: 'automatic',
+        logLevel: 'silent',
+        absWorkingDir: project.dir,
+        external: [
+            ...ALLOWED_EXTERNALS,
+            ...((_c = project.ekanos.allowImports) !== null && _c !== void 0 ? _c : []),
+        ].flatMap((n) => [n, `${n}/*`]),
+        loader: { '.css': 'empty', '.svg': 'dataurl', '.png': 'dataurl' },
+    });
+    const js = (_d = (_a = bundle.outputFiles[0]) === null || _a === void 0 ? void 0 : _a.text) !== null && _d !== void 0 ? _d : '';
+    const dts = "import type { ExperienceDefinition } from '@ekanos/sdk/experience';\n" +
+        'declare const experience: ExperienceDefinition;\n' +
+        'export default experience;\n';
+    const changed = [
+        writeIfChanged(path.join(project.dir, DIST_ENTRY), js),
+        writeIfChanged(path.join(project.dir, DIST_TYPES), dts),
+        writeIfChanged(path.join(project.dir, MANIFEST_FILE), formatJson(manifest)),
+    ].some(Boolean);
+    return {
+        manifest,
+        files: [DIST_ENTRY, DIST_TYPES, MANIFEST_FILE],
+        changed,
+    };
+}
+//# sourceMappingURL=build.js.map

package/dist/experience/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../src/experience/build.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  type ExperienceManifest,\n  ExperienceManifestSchema,\n} from '@ekanos/integration-schema';\nimport { build as esbuild } from 'esbuild';\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport { preconditionError } from '../errors';\nimport { ALLOWED_EXTERNALS } from './boundary';\nimport type { ExperienceCheckResult } from './checks';\nimport { buildManifest } from './definition-checks';\nimport { type ExperienceProject, formatJson, writeIfChanged } from './project';\n\nexport const DIST_ENTRY = 'dist/experience.js';\nexport const DIST_TYPES = 'dist/experience.d.ts';\nexport const MANIFEST_FILE = 'manifest.json';\n\nfunction readPackageJson(project: ExperienceProject): {\n  version?: string;\n  dependencies?: Record<string, string>;\n} {\n  try {\n    return JSON.parse(\n      fs.readFileSync(path.join(project.dir, 'package.json'), 'utf8'),\n    ) as { version?: string; dependencies?: Record<string, string> };\n  } catch {\n    throw preconditionError(\n      'package.json is missing or unreadable.',\n      'An experience is an npm package; run \"ekanos init --kind experience\" or add a package.json.',\n    );\n  }\n}\n\nfunction sdkVersion(\n  project: ExperienceProject,\n  declared: Record<string, string> | undefined,\n): string {\n  try {\n    const installed = JSON.parse(\n      fs.readFileSync(\n        path.join(\n          project.dir,\n          'node_modules',\n          '@ekanos',\n          'sdk',\n          'package.json',\n        ),\n        'utf8',\n      ),\n    ) as { version?: string };\n    if (installed.version) return installed.version;\n  } catch {\n    // not installed: fall back to the declared range\n  }\n\n  return (declared?.['@ekanos/sdk'] ?? 'unknown').replace(/^[\\^~]/, '');\n}\n\nexport interface BuildOutput {\n  manifest: ExperienceManifest;\n  files: string[];\n  changed: boolean;\n}\n\n/**\n * Emit `dist/experience.js` (browser ESM, runtime packages left external),\n * `dist/experience.d.ts` and `manifest.json`. Assumes the checks passed.\n */\nexport async function emitExperience(\n  project: ExperienceProject,\n  result: ExperienceCheckResult,\n): Promise<BuildOutput> {\n  const loaded = result.loaded;\n  if (!loaded) {\n    throw preconditionError(\n      'The experience definition was not loaded.',\n      'Run \"ekanos check\" to see why.',\n    );\n  }\n  const pkg = readPackageJson(project);\n  const version = pkg.version ?? '';\n  if (!/^\\d+\\.\\d+\\.\\d+/.test(version)) {\n    throw preconditionError(\n      `package.json \"version\" is \"${version}\", not semver.`,\n      'Set a version such as 0.1.0.',\n    );\n  }\n\n  const manifest = buildManifest({\n    project,\n    definition: loaded.definition,\n    pinned: result.pinned,\n    workflows: result.workflows,\n    version,\n    sdk: sdkVersion(project, pkg.dependencies),\n  });\n  const parsed = ExperienceManifestSchema.safeParse(manifest);\n  if (!parsed.success) {\n    throw preconditionError(\n      `The generated manifest is invalid: ${parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`,\n      'This is a bug in @ekanos/cli or an unsupported definition; report it.',\n    );\n  }\n\n  const bundle = await esbuild({\n    entryPoints: [path.join(project.dir, project.entry)],\n    bundle: true,\n    write: false,\n    format: 'esm',\n    platform: 'browser',\n    jsx: 'automatic',\n    logLevel: 'silent',\n    absWorkingDir: project.dir,\n    external: [\n      ...ALLOWED_EXTERNALS,\n      ...(project.ekanos.allowImports ?? []),\n    ].flatMap((n) => [n, `${n}/*`]),\n    loader: { '.css': 'empty', '.svg': 'dataurl', '.png': 'dataurl' },\n  });\n  const js = bundle.outputFiles[0]?.text ?? '';\n\n  const dts =\n    \"import type { ExperienceDefinition } from '@ekanos/sdk/experience';\\n\" +\n    'declare const experience: ExperienceDefinition;\\n' +\n    'export default experience;\\n';\n\n  const changed = [\n    writeIfChanged(path.join(project.dir, DIST_ENTRY), js),\n    writeIfChanged(path.join(project.dir, DIST_TYPES), dts),\n    writeIfChanged(path.join(project.dir, MANIFEST_FILE), formatJson(manifest)),\n  ].some(Boolean);\n\n  return {\n    manifest,\n    files: [DIST_ENTRY, DIST_TYPES, MANIFEST_FILE],\n    changed,\n  };\n}\n"]}

package/dist/experience/checks.d.ts

@@ -0,0 +1,29 @@
+import type { Finding, WorkflowTemplate } from '@ekanos/integration-schema';
+import type { LoadedExperienceModule } from './definition-shape.js';
+import { type PinnedIntegration, type PinsResolver } from './pins.js';
+import { type ExperienceProject } from './project.js';
+export declare const GENERATED_TYPES_CHECK = "checks/generated-types";
+export declare const LOCAL_OVERRIDES_CHECK = "checks/local-overrides";
+export declare const TYPECHECK_CHECK = "checks/typecheck";
+export interface ExperienceCheckOptions {
+    typecheck: boolean;
+    /** Skip loading the entry (used by commands that only need the static stages). */
+    loadDefinition: boolean;
+    inlineSdk?: string;
+    /** The harness's pins resolver (`harnessPinsResolver`); absent = committed snapshots only. */
+    pinsResolver?: PinsResolver | null;
+}
+export interface ExperienceCheckResult {
+    findings: Finding[];
+    pinned: PinnedIntegration[];
+    loaded?: LoadedExperienceModule;
+    workflows: WorkflowTemplate[];
+}
+/** The dts the pinned contracts generate: shared by `codegen` and the freshness check. */
+export declare function expectedIntegrationsDts(pinned: readonly PinnedIntegration[]): string;
+/**
+ * The experience gate, in dependency order. Stages that need an earlier stage's
+ * output are skipped when it failed, so one root cause yields one finding, not
+ * a cascade.
+ */
+export declare function runExperienceChecks(project: ExperienceProject, options: ExperienceCheckOptions): Promise<ExperienceCheckResult>;

package/dist/experience/checks.js

@@ -0,0 +1,133 @@
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { checkExperienceBoundary } from './boundary.js';
+import { analyzeDefinition, checkFixtures, } from './definition-checks.js';
+import { generateIntegrationsDts } from './integrations-codegen.js';
+import { loadExperience } from './load-experience.js';
+import { isOverridesFileTracked } from './overrides.js';
+import { checkIntegrationPins, } from './pins.js';
+import { LOCAL_OVERRIDES_FILE, INTEGRATIONS_DTS, LEGACY_SLOTS_DTS, readLockfile, } from './project.js';
+export const GENERATED_TYPES_CHECK = 'checks/generated-types';
+export const LOCAL_OVERRIDES_CHECK = 'checks/local-overrides';
+export const TYPECHECK_CHECK = 'checks/typecheck';
+/** The dts the pinned contracts generate: shared by `codegen` and the freshness check. */
+export function expectedIntegrationsDts(pinned) {
+    return generateIntegrationsDts(pinned.map(({ use, contract }) => ({
+        integration: use.name,
+        contract,
+        operations: use.operations
+            .map((id) => { var _a; return (_a = /\/((?:tool|action)\/.+)$/.exec(id)) === null || _a === void 0 ? void 0 : _a[1]; })
+            .filter((key) => key !== undefined),
+    })));
+}
+function checkGeneratedTypes(project, pinned) {
+    const file = path.join(project.dir, INTEGRATIONS_DTS);
+    const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+    const findings = [];
+    if (fs.existsSync(path.join(project.dir, LEGACY_SLOTS_DTS))) {
+        findings.push({
+            check: GENERATED_TYPES_CHECK,
+            severity: 'warn',
+            message: `${LEGACY_SLOTS_DTS} is the previous name of ${INTEGRATIONS_DTS}.`,
+            hint: `Delete it and list ${INTEGRATIONS_DTS} in tsconfig.json "include"; until then "ekanos sync" keeps it as a re-export.`,
+            file: LEGACY_SLOTS_DTS,
+        });
+    }
+    if (current === expectedIntegrationsDts(pinned))
+        return findings;
+    return [
+        ...findings,
+        {
+            check: GENERATED_TYPES_CHECK,
+            severity: 'error',
+            message: `${INTEGRATIONS_DTS} is ${current === null ? 'missing' : 'out of date'} for the pinned contracts.`,
+            hint: 'Run "ekanos codegen" and commit the result.',
+            file: INTEGRATIONS_DTS,
+        },
+    ];
+}
+function runTypecheck(project) {
+    const tsc = path.join(project.dir, 'node_modules', '.bin', 'tsc');
+    if (!fs.existsSync(tsc) ||
+        !fs.existsSync(path.join(project.dir, 'tsconfig.json'))) {
+        return [
+            {
+                check: TYPECHECK_CHECK,
+                severity: 'warn',
+                message: 'typecheck skipped: no local TypeScript or tsconfig.json.',
+                hint: 'Install typescript and keep a tsconfig.json to type-check against the generated integrations.',
+            },
+        ];
+    }
+    const result = spawnSync(tsc, ['--noEmit', '-p', 'tsconfig.json'], {
+        cwd: project.dir,
+        encoding: 'utf8',
+    });
+    if (result.status === 0)
+        return [];
+    const lines = `${result.stdout}${result.stderr}`
+        .split('\n')
+        .filter((l) => l.trim() !== '');
+    return lines.slice(0, 20).map((line) => {
+        const m = /^(.+?)\((\d+),\d+\): (.*)$/.exec(line);
+        return Object.assign({ check: TYPECHECK_CHECK, severity: 'error', message: m ? m[3] : line, hint: 'Fix the type error; it is what the generated integration types caught.' }, (m ? { file: m[1], line: Number(m[2]) } : {}));
+    });
+}
+/**
+ * The experience gate, in dependency order. Stages that need an earlier stage's
+ * output are skipped when it failed, so one root cause yields one finding, not
+ * a cascade.
+ */
+export async function runExperienceChecks(project, options) {
+    var _a, _b;
+    const findings = [];
+    const lock = readLockfile(project);
+    const pins = checkIntegrationPins(project, lock, (_a = options.pinsResolver) !== null && _a !== void 0 ? _a : undefined);
+    findings.push(...pins.findings);
+    if (isOverridesFileTracked(project)) {
+        findings.push({
+            check: LOCAL_OVERRIDES_CHECK,
+            severity: 'error',
+            message: `${LOCAL_OVERRIDES_FILE} is tracked by git.`,
+            hint: `It is per-developer and must stay untracked: "git rm --cached ${LOCAL_OVERRIDES_FILE}" and add it to .gitignore.`,
+            file: LOCAL_OVERRIDES_FILE,
+        });
+    }
+    const pinsOk = pins.findings.length === 0;
+    if (pinsOk || pins.pinned.length > 0) {
+        findings.push(...checkGeneratedTypes(project, pins.pinned));
+    }
+    findings.push(...(await checkExperienceBoundary(project)));
+    findings.push(...checkFixtures(project, pins.pinned));
+    let loaded;
+    let analysis;
+    if (options.loadDefinition && pinsOk) {
+        const result = await loadExperience(project, {
+            inlineSdk: options.inlineSdk,
+        });
+        if (result.ok) {
+            loaded = result;
+            analysis = analyzeDefinition(project, result, pins.pinned);
+            findings.push(...analysis.findings);
+        }
+        else {
+            findings.push({
+                check: 'checks/experience-definition',
+                severity: 'error',
+                message: result.message,
+                hint: 'Fix the entry so it exports defineExperience({...}) as default.',
+                file: project.entry,
+            });
+        }
+    }
+    if (options.typecheck)
+        findings.push(...runTypecheck(project));
+    return {
+        findings,
+        pinned: pins.pinned,
+        loaded,
+        workflows: (_b = analysis === null || analysis === void 0 ? void 0 : analysis.workflows) !== null && _b !== void 0 ? _b : [],
+    };
+}
+//# sourceMappingURL=checks.js.map

package/dist/experience/checks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checks.js","sourceRoot":"","sources":["../../src/experience/checks.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Finding, WorkflowTemplate } from '@ekanos/integration-schema';\nimport { spawnSync } from 'node:child_process';\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport { checkExperienceBoundary } from './boundary';\nimport {\n  type DefinitionAnalysis,\n  analyzeDefinition,\n  checkFixtures,\n} from './definition-checks';\nimport type { LoadedExperienceModule } from './definition-shape';\nimport { generateIntegrationsDts } from './integrations-codegen';\nimport { loadExperience } from './load-experience';\nimport { isOverridesFileTracked } from './overrides';\nimport {\n  type PinnedIntegration,\n  type PinsResolver,\n  checkIntegrationPins,\n} from './pins';\nimport {\n  LOCAL_OVERRIDES_FILE,\n  type ExperienceProject,\n  INTEGRATIONS_DTS,\n  LEGACY_SLOTS_DTS,\n  readLockfile,\n} from './project';\n\nexport const GENERATED_TYPES_CHECK = 'checks/generated-types';\nexport const LOCAL_OVERRIDES_CHECK = 'checks/local-overrides';\nexport const TYPECHECK_CHECK = 'checks/typecheck';\n\nexport interface ExperienceCheckOptions {\n  typecheck: boolean;\n  /** Skip loading the entry (used by commands that only need the static stages). */\n  loadDefinition: boolean;\n  inlineSdk?: string;\n  /** The harness's pins resolver (`harnessPinsResolver`); absent = committed snapshots only. */\n  pinsResolver?: PinsResolver | null;\n}\n\nexport interface ExperienceCheckResult {\n  findings: Finding[];\n  pinned: PinnedIntegration[];\n  loaded?: LoadedExperienceModule;\n  workflows: WorkflowTemplate[];\n}\n\n/** The dts the pinned contracts generate: shared by `codegen` and the freshness check. */\nexport function expectedIntegrationsDts(\n  pinned: readonly PinnedIntegration[],\n): string {\n  return generateIntegrationsDts(\n    pinned.map(({ use, contract }) => ({\n      integration: use.name,\n      contract,\n      operations: use.operations\n        .map((id) => /\\/((?:tool|action)\\/.+)$/.exec(id)?.[1])\n        .filter((key): key is string => key !== undefined),\n    })),\n  );\n}\n\nfunction checkGeneratedTypes(\n  project: ExperienceProject,\n  pinned: readonly PinnedIntegration[],\n): Finding[] {\n  const file = path.join(project.dir, INTEGRATIONS_DTS);\n  const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;\n  const findings: Finding[] = [];\n  if (fs.existsSync(path.join(project.dir, LEGACY_SLOTS_DTS))) {\n    findings.push({\n      check: GENERATED_TYPES_CHECK,\n      severity: 'warn',\n      message: `${LEGACY_SLOTS_DTS} is the previous name of ${INTEGRATIONS_DTS}.`,\n      hint: `Delete it and list ${INTEGRATIONS_DTS} in tsconfig.json \"include\"; until then \"ekanos sync\" keeps it as a re-export.`,\n      file: LEGACY_SLOTS_DTS,\n    });\n  }\n  if (current === expectedIntegrationsDts(pinned)) return findings;\n\n  return [\n    ...findings,\n    {\n      check: GENERATED_TYPES_CHECK,\n      severity: 'error',\n      message: `${INTEGRATIONS_DTS} is ${current === null ? 'missing' : 'out of date'} for the pinned contracts.`,\n      hint: 'Run \"ekanos codegen\" and commit the result.',\n      file: INTEGRATIONS_DTS,\n    },\n  ];\n}\n\nfunction runTypecheck(project: ExperienceProject): Finding[] {\n  const tsc = path.join(project.dir, 'node_modules', '.bin', 'tsc');\n  if (\n    !fs.existsSync(tsc) ||\n    !fs.existsSync(path.join(project.dir, 'tsconfig.json'))\n  ) {\n    return [\n      {\n        check: TYPECHECK_CHECK,\n        severity: 'warn',\n        message: 'typecheck skipped: no local TypeScript or tsconfig.json.',\n        hint: 'Install typescript and keep a tsconfig.json to type-check against the generated integrations.',\n      },\n    ];\n  }\n  const result = spawnSync(tsc, ['--noEmit', '-p', 'tsconfig.json'], {\n    cwd: project.dir,\n    encoding: 'utf8',\n  });\n  if (result.status === 0) return [];\n\n  const lines = `${result.stdout}${result.stderr}`\n    .split('\\n')\n    .filter((l) => l.trim() !== '');\n\n  return lines.slice(0, 20).map((line) => {\n    const m = /^(.+?)\\((\\d+),\\d+\\): (.*)$/.exec(line);\n\n    return {\n      check: TYPECHECK_CHECK,\n      severity: 'error' as const,\n      message: m ? (m[3] as string) : line,\n      hint: 'Fix the type error; it is what the generated integration types caught.',\n      ...(m ? { file: m[1] as string, line: Number(m[2]) } : {}),\n    };\n  });\n}\n\n/**\n * The experience gate, in dependency order. Stages that need an earlier stage's\n * output are skipped when it failed, so one root cause yields one finding, not\n * a cascade.\n */\nexport async function runExperienceChecks(\n  project: ExperienceProject,\n  options: ExperienceCheckOptions,\n): Promise<ExperienceCheckResult> {\n  const findings: Finding[] = [];\n  const lock = readLockfile(project);\n\n  const pins = checkIntegrationPins(\n    project,\n    lock,\n    options.pinsResolver ?? undefined,\n  );\n  findings.push(...pins.findings);\n\n  if (isOverridesFileTracked(project)) {\n    findings.push({\n      check: LOCAL_OVERRIDES_CHECK,\n      severity: 'error',\n      message: `${LOCAL_OVERRIDES_FILE} is tracked by git.`,\n      hint: `It is per-developer and must stay untracked: \"git rm --cached ${LOCAL_OVERRIDES_FILE}\" and add it to .gitignore.`,\n      file: LOCAL_OVERRIDES_FILE,\n    });\n  }\n\n  const pinsOk = pins.findings.length === 0;\n  if (pinsOk || pins.pinned.length > 0) {\n    findings.push(...checkGeneratedTypes(project, pins.pinned));\n  }\n\n  findings.push(...(await checkExperienceBoundary(project)));\n  findings.push(...checkFixtures(project, pins.pinned));\n\n  let loaded: LoadedExperienceModule | undefined;\n  let analysis: DefinitionAnalysis | undefined;\n  if (options.loadDefinition && pinsOk) {\n    const result = await loadExperience(project, {\n      inlineSdk: options.inlineSdk,\n    });\n    if (result.ok) {\n      loaded = result;\n      analysis = analyzeDefinition(project, result, pins.pinned);\n      findings.push(...analysis.findings);\n    } else {\n      findings.push({\n        check: 'checks/experience-definition',\n        severity: 'error',\n        message: result.message,\n        hint: 'Fix the entry so it exports defineExperience({...}) as default.',\n        file: project.entry,\n      });\n    }\n  }\n\n  if (options.typecheck) findings.push(...runTypecheck(project));\n\n  return {\n    findings,\n    pinned: pins.pinned,\n    loaded,\n    workflows: analysis?.workflows ?? [],\n  };\n}\n"]}

package/dist/experience/contract-sources.d.ts

@@ -0,0 +1,36 @@
+import { type Contract, compatLine } from '@ekanos/integration-schema';
+import type { ExperienceProject } from './project.js';
+/** Where an integration's contract came from, for messages and `sync` bookkeeping. */
+export interface ResolvedContract {
+    contract: Contract;
+    origin: string;
+    kind: 'dir' | 'path' | 'snapshot';
+}
+/**
+ * A pluggable contract source. The dir/path/snapshot sources below are the
+ * offline defaults; the harness resolver (catalog, published packages) plugs
+ * in here as another source, so `add`/`sync` never learn where contracts live.
+ */
+export interface ContractSource {
+    name: string;
+    resolve(integration: string, line: string): Promise<ResolvedContract | null> | ResolvedContract | null;
+}
+export interface SourceOptions {
+    /** A directory of `*.contract.json` (the monorepo contracts folder or a registry mirror). */
+    fromDir?: string;
+    /** An integration project directory; its `contract.json` is read. */
+    fromPath?: string;
+    env?: Record<string, string | undefined>;
+}
+/** Every `*.contract.json` of `dir` for `integration`, highest contract version within `line` first. */
+export declare function contractsInDir(dir: string, integration: string, line: string): Contract[];
+export declare function dirSource(dir: string): ContractSource;
+export declare function pathSource(projectPath: string): ContractSource;
+/** The committed pin: `<contractsDir>/<integration>@<version>.contract.json`. */
+export declare function snapshotFile(project: ExperienceProject, integration: string, line: string): string;
+export declare function snapshotSource(project: ExperienceProject): ContractSource;
+/** Sources in resolution order: explicit flags, env, then (optionally) the snapshot. */
+export declare function defaultSources(project: ExperienceProject, options: SourceOptions, extra?: readonly ContractSource[], includeSnapshot?: boolean): ContractSource[];
+export declare function resolveContract(sources: readonly ContractSource[], integration: string, line: string): Promise<ResolvedContract>;
+/** Line for a package version, re-exported so callers need no schema import. */
+export { compatLine };

package/dist/experience/contract-sources.js

@@ -0,0 +1,111 @@
+import { compareSemver, compatLine, verifyContract, } from '@ekanos/integration-schema';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { notFoundError, validationError } from '../errors.js';
+function readContractFile(file) {
+    let json;
+    try {
+        json = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (_a) {
+        return null;
+    }
+    const verified = verifyContract(json);
+    if (!verified.contract || verified.problems.length > 0) {
+        const first = verified.problems[0];
+        throw validationError(`${file} is not a valid contract: ${first ? `${first.rule}: ${first.message}` : 'unreadable'}`, 'Regenerate it with "ekanos contract" in the integration, or point at a valid contracts directory.');
+    }
+    return verified.contract;
+}
+/** Every `*.contract.json` of `dir` for `integration`, highest contract version within `line` first. */
+export function contractsInDir(dir, integration, line) {
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter((n) => n.endsWith('.contract.json'));
+    }
+    catch (_a) {
+        return [];
+    }
+    const found = [];
+    for (const name of names) {
+        if (!name.startsWith(`${integration}@`) &&
+            !name.startsWith(`${integration}.`)) {
+            continue;
+        }
+        const contract = readContractFile(path.join(dir, name));
+        if (contract &&
+            contract.integration === integration &&
+            contract.compatLine === line) {
+            found.push(contract);
+        }
+    }
+    return found.sort((a, b) => compareSemver(b.contractVersion, a.contractVersion));
+}
+export function dirSource(dir) {
+    return {
+        name: `dir ${dir}`,
+        resolve(integration, line) {
+            const [best] = contractsInDir(dir, integration, line);
+            return best ? { contract: best, origin: dir, kind: 'dir' } : null;
+        },
+    };
+}
+export function pathSource(projectPath) {
+    return {
+        name: `path ${projectPath}`,
+        resolve(integration, line) {
+            const file = path.join(path.resolve(projectPath), 'contract.json');
+            if (!fs.existsSync(file)) {
+                throw notFoundError(`${file} does not exist.`, 'Run "ekanos contract" in that integration to derive its contract.json.');
+            }
+            const contract = readContractFile(file);
+            if (!contract ||
+                contract.integration !== integration ||
+                contract.compatLine !== line) {
+                return null;
+            }
+            return { contract, origin: file, kind: 'path' };
+        },
+    };
+}
+/** The committed pin: `<contractsDir>/<integration>@<version>.contract.json`. */
+export function snapshotFile(project, integration, line) {
+    return path.join(project.contractsDir, `${integration}@${line}.contract.json`);
+}
+export function snapshotSource(project) {
+    return {
+        name: 'committed snapshot',
+        resolve(integration, line) {
+            const file = snapshotFile(project, integration, line);
+            const contract = fs.existsSync(file) ? readContractFile(file) : null;
+            return contract ? { contract, origin: file, kind: 'snapshot' } : null;
+        },
+    };
+}
+/** Sources in resolution order: explicit flags, env, then (optionally) the snapshot. */
+export function defaultSources(project, options, extra = [], includeSnapshot = true) {
+    var _a;
+    const sources = [];
+    if (options.fromPath)
+        sources.push(pathSource(options.fromPath));
+    if (options.fromDir)
+        sources.push(dirSource(path.resolve(options.fromDir)));
+    const envDir = (_a = options.env) === null || _a === void 0 ? void 0 : _a.EKANOS_CONTRACTS_DIR;
+    if (!options.fromDir && envDir)
+        sources.push(dirSource(path.resolve(envDir)));
+    sources.push(...extra);
+    if (includeSnapshot)
+        sources.push(snapshotSource(project));
+    return sources;
+}
+export async function resolveContract(sources, integration, line) {
+    for (const source of sources) {
+        const hit = await source.resolve(integration, line);
+        if (hit)
+            return hit;
+    }
+    throw notFoundError(`No contract for ${integration}@${line} (looked in: ${sources.map((s) => s.name).join(', ') || 'nothing'}).`, 'Pass --from-dir <contracts folder> or --from-path <integration project>, or set EKANOS_CONTRACTS_DIR.');
+}
+/** Line for a package version, re-exported so callers need no schema import. */
+export { compatLine };
+//# sourceMappingURL=contract-sources.js.map

package/dist/experience/contract-sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-sources.js","sourceRoot":"","sources":["../../src/experience/contract-sources.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  type Contract,\n  compareSemver,\n  compatLine,\n  verifyContract,\n} from '@ekanos/integration-schema';\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport { notFoundError, validationError } from '../errors';\nimport type { ExperienceProject } from './project';\n\n/** Where an integration's contract came from, for messages and `sync` bookkeeping. */\nexport interface ResolvedContract {\n  contract: Contract;\n  origin: string;\n  kind: 'dir' | 'path' | 'snapshot';\n}\n\n/**\n * A pluggable contract source. The dir/path/snapshot sources below are the\n * offline defaults; the harness resolver (catalog, published packages) plugs\n * in here as another source, so `add`/`sync` never learn where contracts live.\n */\nexport interface ContractSource {\n  name: string;\n  resolve(\n    integration: string,\n    line: string,\n  ): Promise<ResolvedContract | null> | ResolvedContract | null;\n}\n\nexport interface SourceOptions {\n  /** A directory of `*.contract.json` (the monorepo contracts folder or a registry mirror). */\n  fromDir?: string;\n  /** An integration project directory; its `contract.json` is read. */\n  fromPath?: string;\n  env?: Record<string, string | undefined>;\n}\n\nfunction readContractFile(file: string): Contract | null {\n  let json: unknown;\n  try {\n    json = JSON.parse(fs.readFileSync(file, 'utf8'));\n  } catch {\n    return null;\n  }\n  const verified = verifyContract(json);\n  if (!verified.contract || verified.problems.length > 0) {\n    const first = verified.problems[0];\n    throw validationError(\n      `${file} is not a valid contract: ${first ? `${first.rule}: ${first.message}` : 'unreadable'}`,\n      'Regenerate it with \"ekanos contract\" in the integration, or point at a valid contracts directory.',\n    );\n  }\n\n  return verified.contract;\n}\n\n/** Every `*.contract.json` of `dir` for `integration`, highest contract version within `line` first. */\nexport function contractsInDir(\n  dir: string,\n  integration: string,\n  line: string,\n): Contract[] {\n  let names: string[];\n  try {\n    names = fs.readdirSync(dir).filter((n) => n.endsWith('.contract.json'));\n  } catch {\n    return [];\n  }\n  const found: Contract[] = [];\n  for (const name of names) {\n    if (\n      !name.startsWith(`${integration}@`) &&\n      !name.startsWith(`${integration}.`)\n    ) {\n      continue;\n    }\n    const contract = readContractFile(path.join(dir, name));\n    if (\n      contract &&\n      contract.integration === integration &&\n      contract.compatLine === line\n    ) {\n      found.push(contract);\n    }\n  }\n\n  return found.sort((a, b) =>\n    compareSemver(b.contractVersion, a.contractVersion),\n  );\n}\n\nexport function dirSource(dir: string): ContractSource {\n  return {\n    name: `dir ${dir}`,\n    resolve(integration, line) {\n      const [best] = contractsInDir(dir, integration, line);\n\n      return best ? { contract: best, origin: dir, kind: 'dir' } : null;\n    },\n  };\n}\n\nexport function pathSource(projectPath: string): ContractSource {\n  return {\n    name: `path ${projectPath}`,\n    resolve(integration, line) {\n      const file = path.join(path.resolve(projectPath), 'contract.json');\n      if (!fs.existsSync(file)) {\n        throw notFoundError(\n          `${file} does not exist.`,\n          'Run \"ekanos contract\" in that integration to derive its contract.json.',\n        );\n      }\n      const contract = readContractFile(file);\n      if (\n        !contract ||\n        contract.integration !== integration ||\n        contract.compatLine !== line\n      ) {\n        return null;\n      }\n\n      return { contract, origin: file, kind: 'path' };\n    },\n  };\n}\n\n/** The committed pin: `<contractsDir>/<integration>@<version>.contract.json`. */\nexport function snapshotFile(\n  project: ExperienceProject,\n  integration: string,\n  line: string,\n): string {\n  return path.join(\n    project.contractsDir,\n    `${integration}@${line}.contract.json`,\n  );\n}\n\nexport function snapshotSource(project: ExperienceProject): ContractSource {\n  return {\n    name: 'committed snapshot',\n    resolve(integration, line) {\n      const file = snapshotFile(project, integration, line);\n      const contract = fs.existsSync(file) ? readContractFile(file) : null;\n\n      return contract ? { contract, origin: file, kind: 'snapshot' } : null;\n    },\n  };\n}\n\n/** Sources in resolution order: explicit flags, env, then (optionally) the snapshot. */\nexport function defaultSources(\n  project: ExperienceProject,\n  options: SourceOptions,\n  extra: readonly ContractSource[] = [],\n  includeSnapshot = true,\n): ContractSource[] {\n  const sources: ContractSource[] = [];\n  if (options.fromPath) sources.push(pathSource(options.fromPath));\n  if (options.fromDir) sources.push(dirSource(path.resolve(options.fromDir)));\n  const envDir = options.env?.EKANOS_CONTRACTS_DIR;\n  if (!options.fromDir && envDir) sources.push(dirSource(path.resolve(envDir)));\n  sources.push(...extra);\n  if (includeSnapshot) sources.push(snapshotSource(project));\n\n  return sources;\n}\n\nexport async function resolveContract(\n  sources: readonly ContractSource[],\n  integration: string,\n  line: string,\n): Promise<ResolvedContract> {\n  for (const source of sources) {\n    const hit = await source.resolve(integration, line);\n    if (hit) return hit;\n  }\n\n  throw notFoundError(\n    `No contract for ${integration}@${line} (looked in: ${sources.map((s) => s.name).join(', ') || 'nothing'}).`,\n    'Pass --from-dir <contracts folder> or --from-path <integration project>, or set EKANOS_CONTRACTS_DIR.',\n  );\n}\n\n/** Line for a package version, re-exported so callers need no schema import. */\nexport { compatLine };\n"]}

package/dist/experience/definition-checks.d.ts

@@ -0,0 +1,26 @@
+import { type ExperienceManifest, type Finding, type WorkflowTemplate } from '@ekanos/integration-schema';
+import type { LoadedExperienceDefinition, LoadedExperienceModule } from './definition-shape.js';
+import { type PinnedIntegration } from './pins.js';
+import type { ExperienceProject } from './project.js';
+export declare const DEFINITION_CHECK = "checks/experience-definition";
+export interface DefinitionAnalysis {
+    findings: Finding[];
+    workflows: WorkflowTemplate[];
+}
+/**
+ * Cross-check the loaded definition against `ekanos.json` and the pinned
+ * contracts: every integration a widget, page, review section or workflow step names
+ * must be declared, every operation must be in that integration's allowlist, the
+ * review queue reads only, and each template serializes to the engine's DSL.
+ */
+export declare function analyzeDefinition(project: ExperienceProject, loaded: LoadedExperienceModule, pinned: readonly PinnedIntegration[]): DefinitionAnalysis;
+/** `fixtures/<integration>/<kind>-<name>.<variant>.json` must satisfy the pinned output schema. */
+export declare function checkFixtures(project: ExperienceProject, pinned: readonly PinnedIntegration[]): Finding[];
+export declare function buildManifest(input: {
+    project: ExperienceProject;
+    definition: LoadedExperienceDefinition;
+    pinned: readonly PinnedIntegration[];
+    workflows: readonly WorkflowTemplate[];
+    version: string;
+    sdk: string;
+}): ExperienceManifest;