@ekanos/cli 0.16.0 → 0.17.1

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;

package/dist/experience/definition-checks.js

@@ -0,0 +1,201 @@
+import { WorkflowTemplateSchema, canonicalJson, sha256Hex, validateAgainstSchema, workflowTemplateProblems, } from '@ekanos/integration-schema';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { declaredOperationKeys } from './integrations-codegen.js';
+import { effectLookup } from './pins.js';
+export const DEFINITION_CHECK = 'checks/experience-definition';
+const err = (message, hint, file) => (Object.assign({ check: DEFINITION_CHECK, severity: 'error', message,
+    hint }, (file ? { file } : {})));
+const warn = (message, hint, file) => (Object.assign({ check: DEFINITION_CHECK, severity: 'warn', message,
+    hint }, (file ? { file } : {})));
+/**
+ * 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 function analyzeDefinition(project, loaded, pinned) {
+    var _a, _b, _c, _d, _e;
+    var _f, _g;
+    const { definition } = loaded;
+    const findings = [];
+    const workflows = [];
+    const declaredIntegrations = new Map(project.integrations.map((u) => [u.name, u]));
+    const declared = new Map(project.integrations.map((u) => [
+        u.name,
+        new Set(declaredOperationKeys(u)),
+    ]));
+    const contractOps = new Map(pinned.map(({ use, contract }) => [
+        use.name,
+        new Map(contract.operations.map((op) => [`${op.kind}/${op.name}`, op])),
+    ]));
+    if (definition.slug !== project.slug) {
+        findings.push(err(`the definition's slug "${definition.slug}" differs from ekanos.json "${project.slug}".`, 'Make them equal.', project.entry));
+    }
+    const checkIntegration = (integration, owner) => {
+        if (!declaredIntegrations.has(integration)) {
+            findings.push(err(`${owner} uses integration "${integration}", which ekanos.json "integrations" does not declare.`, `Add it with "ekanos add ${integration}@<version>".`, project.entry));
+            return false;
+        }
+        return true;
+    };
+    for (const widget of definition.widgets) {
+        for (const integration of widget.integrations)
+            checkIntegration(integration, `widget "${widget.id}"`);
+    }
+    for (const page of definition.pages) {
+        for (const integration of page.integrations)
+            checkIntegration(integration, `page "${page.id}"`);
+    }
+    for (const section of (_f = (_a = definition.reviewQueue) === null || _a === void 0 ? void 0 : _a.sections) !== null && _f !== void 0 ? _f : []) {
+        if (!checkIntegration(section.integration, `review section "${section.id}"`))
+            continue;
+        if (!((_b = declared.get(section.integration)) === null || _b === void 0 ? void 0 : _b.has(section.read))) {
+            findings.push(err(`review section "${section.id}" reads ${section.read}, which integration "${section.integration}" does not declare.`, 'Add the operation to the integration in ekanos.json, or read another one.', project.entry));
+        }
+        else if (((_d = (_c = contractOps.get(section.integration)) === null || _c === void 0 ? void 0 : _c.get(section.read)) === null || _d === void 0 ? void 0 : _d.effect) !== 'read') {
+            findings.push(err(`review section "${section.id}" reads ${section.read}, which is not a read operation.`, 'The review queue is reads-only; writes belong behind a workflow approval.', project.entry));
+        }
+    }
+    const effectOf = effectLookup(pinned);
+    for (const template of definition.workflows) {
+        const where = `workflow "${template.id}"`;
+        let steps;
+        try {
+            steps = template.build();
+        }
+        catch (error) {
+            findings.push(err(`${where}: build() threw: ${error instanceof Error ? error.message : String(error)}`, 'Fix the template.', project.entry));
+            continue;
+        }
+        let stepsOk = true;
+        for (const step of steps) {
+            if (step.type !== 'tool' || !step.integration || !step.op)
+                continue;
+            if (!checkIntegration(step.integration, `${where} step "${step.id}"`)) {
+                stepsOk = false;
+            }
+            else if (!((_e = declared.get(step.integration)) === null || _e === void 0 ? void 0 : _e.has(step.op))) {
+                stepsOk = false;
+                findings.push(err(`${where} step "${step.id}" calls ${step.integration} ${step.op}, which the integration does not declare.`, 'Add the operation to the integration\'s "operations" in ekanos.json (ekanos add --ops).', project.entry));
+            }
+        }
+        if (!stepsOk)
+            continue;
+        let dsl;
+        try {
+            dsl = loaded.serializeWorkflowTemplate(template, { effectOf });
+        }
+        catch (error) {
+            findings.push(err(`${where}: ${error instanceof Error ? error.message : String(error)}`, 'Fix the template.', project.entry));
+            continue;
+        }
+        const parsed = WorkflowTemplateSchema.safeParse(dsl);
+        if (!parsed.success) {
+            findings.push(err(`${where} does not serialize to a valid workflow: ${parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`, 'Fix the step definitions.', project.entry));
+            continue;
+        }
+        for (const problem of workflowTemplateProblems(parsed.data)) {
+            findings.push(err(`${where}: ${problem}.`, 'Fix the template.', project.entry));
+        }
+        const gated = new Set();
+        const preds = new Map();
+        for (const e of parsed.data.edges)
+            preds.set(e.to, [...((_g = preds.get(e.to)) !== null && _g !== void 0 ? _g : []), e.from]);
+        const hasGate = (id, seen = new Set()) => {
+            var _a;
+            if (seen.has(id))
+                return false;
+            seen.add(id);
+            return ((_a = preds.get(id)) !== null && _a !== void 0 ? _a : []).some((p) => { var _a; return ((_a = parsed.data.steps.find((s) => s.id === p)) === null || _a === void 0 ? void 0 : _a.type) === 'approval_gate' ||
+                hasGate(p, seen); });
+        };
+        for (const s of parsed.data.steps) {
+            if (s.type === 'fusion_tool' && s.effect === 'write' && !hasGate(s.id)) {
+                gated.add(s.id);
+            }
+        }
+        for (const id of gated) {
+            findings.push(warn(`${where}: write step "${id}" has no approval gate upstream.`, 'Put step.approval(...) before a write so a person confirms it.', project.entry));
+        }
+        workflows.push(parsed.data);
+    }
+    return { findings, workflows };
+}
+// ─── fixtures ───────────────────────────────────────────────────────────────
+const FIXTURE_NAME = /^(tool|action)-(.+)\.(default|empty|error)\.json$/;
+/** `fixtures/<integration>/<kind>-<name>.<variant>.json` must satisfy the pinned output schema. */
+export function checkFixtures(project, pinned) {
+    const findings = [];
+    const root = path.join(project.dir, 'fixtures');
+    if (!fs.existsSync(root))
+        return findings;
+    for (const { use, contract } of pinned) {
+        const dir = path.join(root, use.name);
+        if (!fs.existsSync(dir))
+            continue;
+        for (const name of fs.readdirSync(dir)) {
+            const rel = `fixtures/${use.name}/${name}`;
+            const match = FIXTURE_NAME.exec(name);
+            if (!match) {
+                findings.push(warn(`${rel} is not <kind>-<name>.<default|empty|error>.json.`, 'Rename it so the harness can find it.', rel));
+                continue;
+            }
+            const [, kind, op, variant] = match;
+            if (variant === 'error')
+                continue;
+            const operation = contract.operations.find((o) => o.kind === kind && o.name === op);
+            if (!operation) {
+                findings.push(err(`${rel}: ${use.name}@${use.version} has no ${kind}/${op}.`, 'Delete the fixture or fix its name.', rel));
+                continue;
+            }
+            if (operation.opaque.output)
+                continue;
+            let value;
+            try {
+                value = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'));
+            }
+            catch (_a) {
+                findings.push(err(`${rel} is not valid JSON.`, 'Fix the syntax.', rel));
+                continue;
+            }
+            const problems = validateAgainstSchema(operation.output, value);
+            if (problems.length > 0) {
+                findings.push(err(`${rel} violates the pinned output schema: ${problems[0]}`, 'A fixture must satisfy the contract, or the harness would show data the integration can never return.', rel));
+            }
+        }
+    }
+    return findings;
+}
+// ─── manifest ───────────────────────────────────────────────────────────────
+export function buildManifest(input) {
+    const { project, definition, pinned } = input;
+    const body = Object.assign(Object.assign(Object.assign({ schemaVersion: 1, slug: project.slug, form: 'composed', version: input.version, sdk: input.sdk, integrations: project.integrations, contractRefs: pinned.map(({ use, contract }) => ({
+            integration: use.name,
+            version: use.version,
+            contractVersion: contract.contractVersion,
+            digest: contract.digest,
+        })) }, (definition.sidebar ? { sidebar: definition.sidebar } : {})), { widgets: definition.widgets.map((w) => (Object.assign(Object.assign(Object.assign({ id: w.id, title: w.title, integrations: [...w.integrations] }, (w.width ? { width: w.width } : {})), (w.isCollapsible === undefined
+            ? {}
+            : { isCollapsible: w.isCollapsible })), (w.aiFooterEnabled === undefined
+            ? {}
+            : { aiFooterEnabled: w.aiFooterEnabled })))), pages: definition.pages.map((p) => ({
+            id: p.id,
+            path: p.path,
+            title: p.title,
+            integrations: [...p.integrations],
+        })), workflowTemplates: [...input.workflows] }), (definition.reviewQueue
+        ? {
+            reviewQueue: {
+                readsOnly: true,
+                sections: definition.reviewQueue.sections.map((s) => ({
+                    id: s.id,
+                    integration: s.integration,
+                    read: s.read,
+                })),
+            },
+        }
+        : {}));
+    return Object.assign(Object.assign({}, body), { digest: `sha256:${sha256Hex(canonicalJson(body))}` });
+}
+//# sourceMappingURL=definition-checks.js.map

package/dist/experience/definition-checks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition-checks.js","sourceRoot":"","sources":["../../src/experience/definition-checks.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  type ExperienceManifest,\n  type Finding,\n  type WorkflowTemplate,\n  WorkflowTemplateSchema,\n  canonicalJson,\n  sha256Hex,\n  validateAgainstSchema,\n  workflowTemplateProblems,\n} from '@ekanos/integration-schema';\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport type {\n  LoadedExperienceDefinition,\n  LoadedExperienceModule,\n} from './definition-shape';\nimport { declaredOperationKeys } from './integrations-codegen';\nimport { type PinnedIntegration, effectLookup } from './pins';\nimport type { ExperienceProject } from './project';\n\nexport const DEFINITION_CHECK = 'checks/experience-definition';\n\nconst err = (message: string, hint: string, file?: string): Finding => ({\n  check: DEFINITION_CHECK,\n  severity: 'error',\n  message,\n  hint,\n  ...(file ? { file } : {}),\n});\n\nconst warn = (message: string, hint: string, file?: string): Finding => ({\n  check: DEFINITION_CHECK,\n  severity: 'warn',\n  message,\n  hint,\n  ...(file ? { file } : {}),\n});\n\nexport interface DefinitionAnalysis {\n  findings: Finding[];\n  workflows: WorkflowTemplate[];\n}\n\n/**\n * Cross-check the loaded definition against `ekanos.json` and the pinned\n * contracts: every integration a widget, page, review section or workflow step names\n * must be declared, every operation must be in that integration's allowlist, the\n * review queue reads only, and each template serializes to the engine's DSL.\n */\nexport function analyzeDefinition(\n  project: ExperienceProject,\n  loaded: LoadedExperienceModule,\n  pinned: readonly PinnedIntegration[],\n): DefinitionAnalysis {\n  const { definition } = loaded;\n  const findings: Finding[] = [];\n  const workflows: WorkflowTemplate[] = [];\n  const declaredIntegrations = new Map(\n    project.integrations.map((u) => [u.name, u]),\n  );\n  const declared = new Map(\n    project.integrations.map((u) => [\n      u.name,\n      new Set(declaredOperationKeys(u)),\n    ]),\n  );\n  const contractOps = new Map(\n    pinned.map(({ use, contract }) => [\n      use.name,\n      new Map(contract.operations.map((op) => [`${op.kind}/${op.name}`, op])),\n    ]),\n  );\n\n  if (definition.slug !== project.slug) {\n    findings.push(\n      err(\n        `the definition's slug \"${definition.slug}\" differs from ekanos.json \"${project.slug}\".`,\n        'Make them equal.',\n        project.entry,\n      ),\n    );\n  }\n\n  const checkIntegration = (integration: string, owner: string) => {\n    if (!declaredIntegrations.has(integration)) {\n      findings.push(\n        err(\n          `${owner} uses integration \"${integration}\", which ekanos.json \"integrations\" does not declare.`,\n          `Add it with \"ekanos add ${integration}@<version>\".`,\n          project.entry,\n        ),\n      );\n\n      return false;\n    }\n\n    return true;\n  };\n\n  for (const widget of definition.widgets) {\n    for (const integration of widget.integrations)\n      checkIntegration(integration, `widget \"${widget.id}\"`);\n  }\n  for (const page of definition.pages) {\n    for (const integration of page.integrations)\n      checkIntegration(integration, `page \"${page.id}\"`);\n  }\n\n  for (const section of definition.reviewQueue?.sections ?? []) {\n    if (\n      !checkIntegration(section.integration, `review section \"${section.id}\"`)\n    )\n      continue;\n    if (!declared.get(section.integration)?.has(section.read)) {\n      findings.push(\n        err(\n          `review section \"${section.id}\" reads ${section.read}, which integration \"${section.integration}\" does not declare.`,\n          'Add the operation to the integration in ekanos.json, or read another one.',\n          project.entry,\n        ),\n      );\n    } else if (\n      contractOps.get(section.integration)?.get(section.read)?.effect !== 'read'\n    ) {\n      findings.push(\n        err(\n          `review section \"${section.id}\" reads ${section.read}, which is not a read operation.`,\n          'The review queue is reads-only; writes belong behind a workflow approval.',\n          project.entry,\n        ),\n      );\n    }\n  }\n\n  const effectOf = effectLookup(pinned);\n  for (const template of definition.workflows) {\n    const where = `workflow \"${template.id}\"`;\n    let steps: ReturnType<typeof template.build>;\n    try {\n      steps = template.build();\n    } catch (error) {\n      findings.push(\n        err(\n          `${where}: build() threw: ${error instanceof Error ? error.message : String(error)}`,\n          'Fix the template.',\n          project.entry,\n        ),\n      );\n      continue;\n    }\n\n    let stepsOk = true;\n    for (const step of steps) {\n      if (step.type !== 'tool' || !step.integration || !step.op) continue;\n      if (!checkIntegration(step.integration, `${where} step \"${step.id}\"`)) {\n        stepsOk = false;\n      } else if (!declared.get(step.integration)?.has(step.op)) {\n        stepsOk = false;\n        findings.push(\n          err(\n            `${where} step \"${step.id}\" calls ${step.integration} ${step.op}, which the integration does not declare.`,\n            'Add the operation to the integration\\'s \"operations\" in ekanos.json (ekanos add --ops).',\n            project.entry,\n          ),\n        );\n      }\n    }\n    if (!stepsOk) continue;\n\n    let dsl: unknown;\n    try {\n      dsl = loaded.serializeWorkflowTemplate(template, { effectOf });\n    } catch (error) {\n      findings.push(\n        err(\n          `${where}: ${error instanceof Error ? error.message : String(error)}`,\n          'Fix the template.',\n          project.entry,\n        ),\n      );\n      continue;\n    }\n    const parsed = WorkflowTemplateSchema.safeParse(dsl);\n    if (!parsed.success) {\n      findings.push(\n        err(\n          `${where} does not serialize to a valid workflow: ${parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`,\n          'Fix the step definitions.',\n          project.entry,\n        ),\n      );\n      continue;\n    }\n    for (const problem of workflowTemplateProblems(parsed.data)) {\n      findings.push(\n        err(`${where}: ${problem}.`, 'Fix the template.', project.entry),\n      );\n    }\n\n    const gated = new Set<string>();\n    const preds = new Map<string, string[]>();\n    for (const e of parsed.data.edges)\n      preds.set(e.to, [...(preds.get(e.to) ?? []), e.from]);\n    const hasGate = (id: string, seen = new Set<string>()): boolean => {\n      if (seen.has(id)) return false;\n      seen.add(id);\n\n      return (preds.get(id) ?? []).some(\n        (p) =>\n          parsed.data.steps.find((s) => s.id === p)?.type === 'approval_gate' ||\n          hasGate(p, seen),\n      );\n    };\n    for (const s of parsed.data.steps) {\n      if (s.type === 'fusion_tool' && s.effect === 'write' && !hasGate(s.id)) {\n        gated.add(s.id);\n      }\n    }\n    for (const id of gated) {\n      findings.push(\n        warn(\n          `${where}: write step \"${id}\" has no approval gate upstream.`,\n          'Put step.approval(...) before a write so a person confirms it.',\n          project.entry,\n        ),\n      );\n    }\n\n    workflows.push(parsed.data);\n  }\n\n  return { findings, workflows };\n}\n\n// ─── fixtures ───────────────────────────────────────────────────────────────\n\nconst FIXTURE_NAME = /^(tool|action)-(.+)\\.(default|empty|error)\\.json$/;\n\n/** `fixtures/<integration>/<kind>-<name>.<variant>.json` must satisfy the pinned output schema. */\nexport function checkFixtures(\n  project: ExperienceProject,\n  pinned: readonly PinnedIntegration[],\n): Finding[] {\n  const findings: Finding[] = [];\n  const root = path.join(project.dir, 'fixtures');\n  if (!fs.existsSync(root)) return findings;\n\n  for (const { use, contract } of pinned) {\n    const dir = path.join(root, use.name);\n    if (!fs.existsSync(dir)) continue;\n    for (const name of fs.readdirSync(dir)) {\n      const rel = `fixtures/${use.name}/${name}`;\n      const match = FIXTURE_NAME.exec(name);\n      if (!match) {\n        findings.push(\n          warn(\n            `${rel} is not <kind>-<name>.<default|empty|error>.json.`,\n            'Rename it so the harness can find it.',\n            rel,\n          ),\n        );\n        continue;\n      }\n      const [, kind, op, variant] = match;\n      if (variant === 'error') continue;\n      const operation = contract.operations.find(\n        (o) => o.kind === kind && o.name === op,\n      );\n      if (!operation) {\n        findings.push(\n          err(\n            `${rel}: ${use.name}@${use.version} has no ${kind}/${op}.`,\n            'Delete the fixture or fix its name.',\n            rel,\n          ),\n        );\n        continue;\n      }\n      if (operation.opaque.output) continue;\n      let value: unknown;\n      try {\n        value = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'));\n      } catch {\n        findings.push(err(`${rel} is not valid JSON.`, 'Fix the syntax.', rel));\n        continue;\n      }\n      const problems = validateAgainstSchema(operation.output, value);\n      if (problems.length > 0) {\n        findings.push(\n          err(\n            `${rel} violates the pinned output schema: ${problems[0]}`,\n            'A fixture must satisfy the contract, or the harness would show data the integration can never return.',\n            rel,\n          ),\n        );\n      }\n    }\n  }\n\n  return findings;\n}\n\n// ─── manifest ───────────────────────────────────────────────────────────────\n\nexport function buildManifest(input: {\n  project: ExperienceProject;\n  definition: LoadedExperienceDefinition;\n  pinned: readonly PinnedIntegration[];\n  workflows: readonly WorkflowTemplate[];\n  version: string;\n  sdk: string;\n}): ExperienceManifest {\n  const { project, definition, pinned } = input;\n  const body = {\n    schemaVersion: 1 as const,\n    slug: project.slug,\n    form: 'composed' as const,\n    version: input.version,\n    sdk: input.sdk,\n    integrations: project.integrations,\n    contractRefs: pinned.map(({ use, contract }) => ({\n      integration: use.name,\n      version: use.version,\n      contractVersion: contract.contractVersion,\n      digest: contract.digest,\n    })),\n    ...(definition.sidebar ? { sidebar: definition.sidebar } : {}),\n    widgets: definition.widgets.map((w) => ({\n      id: w.id,\n      title: w.title,\n      integrations: [...w.integrations],\n      ...(w.width ? { width: w.width } : {}),\n      ...(w.isCollapsible === undefined\n        ? {}\n        : { isCollapsible: w.isCollapsible }),\n      ...(w.aiFooterEnabled === undefined\n        ? {}\n        : { aiFooterEnabled: w.aiFooterEnabled }),\n    })),\n    pages: definition.pages.map((p) => ({\n      id: p.id,\n      path: p.path,\n      title: p.title,\n      integrations: [...p.integrations],\n    })),\n    workflowTemplates: [...input.workflows],\n    ...(definition.reviewQueue\n      ? {\n          reviewQueue: {\n            readsOnly: true as const,\n            sections: definition.reviewQueue.sections.map((s) => ({\n              id: s.id,\n              integration: s.integration,\n              read: s.read,\n            })),\n          },\n        }\n      : {}),\n  };\n\n  return {\n    ...body,\n    digest: `sha256:${sha256Hex(canonicalJson(body))}`,\n  };\n}\n"]}

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

@@ -0,0 +1,60 @@
+/**
+ * The structural slice of an `ExperienceDefinition` the CLI reads. The CLI does
+ * not depend on `@ekanos/sdk`: the definition is produced by whichever SDK the
+ * project installed, and anything the CLI needs computed (workflow
+ * serialization) is obtained from that same SDK at load time.
+ */
+export interface LoadedWorkflowTemplate {
+    id: string;
+    name: string;
+    build(): ReadonlyArray<{
+        type: string;
+        id: string;
+        integration?: string;
+        op?: string;
+    }>;
+}
+export interface LoadedExperienceDefinition {
+    kind: 'experience';
+    slug: string;
+    name: string;
+    description?: string;
+    sidebar?: {
+        section: string;
+        icon: string;
+        label: string;
+    };
+    widgets: ReadonlyArray<{
+        id: string;
+        title: string;
+        integrations: readonly string[];
+        width?: string;
+        isCollapsible?: boolean;
+        isPinnable?: boolean;
+        aiFooterEnabled?: boolean;
+    }>;
+    pages: ReadonlyArray<{
+        id: string;
+        path: string;
+        title: string;
+        integrations: readonly string[];
+    }>;
+    workflows: readonly LoadedWorkflowTemplate[];
+    reviewQueue?: {
+        readsOnly: true;
+        sections: ReadonlyArray<{
+            id: string;
+            integration: string;
+            read: string;
+        }>;
+    };
+}
+export interface SerializedWorkflowOptions {
+    effectOf: (integration: string, op: string) => 'read' | 'write' | undefined;
+}
+export interface LoadedExperienceModule {
+    definition: LoadedExperienceDefinition;
+    /** The project's own SDK serializer, so the output matches the SDK that authored it. */
+    serializeWorkflowTemplate(template: LoadedWorkflowTemplate, options: SerializedWorkflowOptions): unknown;
+    slotsUsedBy(definition: LoadedExperienceDefinition): string[];
+}

package/dist/experience/definition-shape.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=definition-shape.js.map

package/dist/experience/definition-shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition-shape.js","sourceRoot":"","sources":["../../src/experience/definition-shape.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * The structural slice of an `ExperienceDefinition` the CLI reads. The CLI does\n * not depend on `@ekanos/sdk`: the definition is produced by whichever SDK the\n * project installed, and anything the CLI needs computed (workflow\n * serialization) is obtained from that same SDK at load time.\n */\nexport interface LoadedWorkflowTemplate {\n  id: string;\n  name: string;\n  build(): ReadonlyArray<{\n    type: string;\n    id: string;\n    integration?: string;\n    op?: string;\n  }>;\n}\n\nexport interface LoadedExperienceDefinition {\n  kind: 'experience';\n  slug: string;\n  name: string;\n  description?: string;\n  sidebar?: { section: string; icon: string; label: string };\n  widgets: ReadonlyArray<{\n    id: string;\n    title: string;\n    integrations: readonly string[];\n    width?: string;\n    isCollapsible?: boolean;\n    isPinnable?: boolean;\n    aiFooterEnabled?: boolean;\n  }>;\n  pages: ReadonlyArray<{\n    id: string;\n    path: string;\n    title: string;\n    integrations: readonly string[];\n  }>;\n  workflows: readonly LoadedWorkflowTemplate[];\n  reviewQueue?: {\n    readsOnly: true;\n    sections: ReadonlyArray<{ id: string; integration: string; read: string }>;\n  };\n}\n\nexport interface SerializedWorkflowOptions {\n  effectOf: (integration: string, op: string) => 'read' | 'write' | undefined;\n}\n\nexport interface LoadedExperienceModule {\n  definition: LoadedExperienceDefinition;\n  /** The project's own SDK serializer, so the output matches the SDK that authored it. */\n  serializeWorkflowTemplate(\n    template: LoadedWorkflowTemplate,\n    options: SerializedWorkflowOptions,\n  ): unknown;\n  slotsUsedBy(definition: LoadedExperienceDefinition): string[];\n}\n"]}

package/dist/experience/init.d.ts

@@ -0,0 +1,10 @@
+import type { CliContext } from '../context.js';
+import type { ExitCode } from '../exit-codes.js';
+export interface InitExperienceArgs {
+    slug?: string;
+    dir?: string;
+    cwd: string;
+    force: boolean;
+}
+/** `ekanos init --kind experience`: scaffold a project with no integrations yet. */
+export declare function runInitExperience(ctx: CliContext, args: InitExperienceArgs): ExitCode;

package/dist/experience/init.js

@@ -0,0 +1,64 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { invalidStateError, usageError } from '../errors.js';
+import { classifyPath, writeFileNoFollow } from '../safe-fs.js';
+import { readTemplate, toDisplayName } from '../templates.js';
+const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** template (under templates/experience/) -> destination. */
+const FILES = [
+    { template: 'ekanos.json.tmpl', dest: 'ekanos.json' },
+    { template: 'package.json.tmpl', dest: 'package.json' },
+    { template: 'tsconfig.json.tmpl', dest: 'tsconfig.json' },
+    { template: 'gitignore.tmpl', dest: '.gitignore' },
+    { template: 'eslint.config.mjs.tmpl', dest: 'eslint.config.mjs' },
+    { template: 'AGENTS.md.tmpl', dest: 'AGENTS.md' },
+    { template: 'ekanos.lock.json.tmpl', dest: 'ekanos.lock.json' },
+    { template: 'src/experience.ts.tmpl', dest: 'src/experience.ts' },
+    {
+        template: 'src/widgets/hello-widget.tsx.tmpl',
+        dest: 'src/widgets/hello-widget.tsx',
+    },
+    {
+        template: 'src/.ekanos/integrations.d.ts.tmpl',
+        dest: 'src/.ekanos/integrations.d.ts',
+    },
+];
+/** `ekanos init --kind experience`: scaffold a project with no integrations yet. */
+export function runInitExperience(ctx, args) {
+    var _a;
+    const slug = args.slug;
+    if (!slug || !SLUG_PATTERN.test(slug)) {
+        throw usageError(slug ? `Invalid slug "${slug}".` : 'init requires a slug.', 'Pass kebab-case: "ekanos init --kind experience --slug content-engine".');
+    }
+    const targetDir = path.resolve(args.cwd, (_a = args.dir) !== null && _a !== void 0 ? _a : slug);
+    if (fs.existsSync(targetDir) && fs.lstatSync(targetDir).isSymbolicLink()) {
+        throw invalidStateError(`The target directory ${targetDir} is a symlink.`, 'Scaffold into the real directory.');
+    }
+    fs.mkdirSync(targetDir, { recursive: true });
+    const vars = { SLUG: slug, DISPLAY_NAME: toDisplayName(slug) };
+    const created = [];
+    const skipped = [];
+    for (const { template, dest } of FILES) {
+        const destPath = path.join(targetDir, dest);
+        const kind = classifyPath(destPath);
+        if (kind !== 'missing' && kind !== 'symlink' && !args.force) {
+            skipped.push(dest);
+            continue;
+        }
+        writeFileNoFollow(targetDir, destPath, readTemplate(`experience/${template}`, vars));
+        created.push(dest);
+    }
+    for (const keep of ['contracts/.gitkeep', 'fixtures/.gitkeep']) {
+        const destPath = path.join(targetDir, keep);
+        if (classifyPath(destPath) === 'missing') {
+            writeFileNoFollow(targetDir, destPath, '');
+            created.push(keep);
+        }
+    }
+    for (const file of created)
+        ctx.log(`  created ${file}`);
+    for (const file of skipped)
+        ctx.log(`  skipped ${file} (already exists; --force overwrites)`);
+    return ctx.succeed({ kind: 'experience', slug, dir: targetDir, created, skipped }, `Scaffolded experience "${slug}". Next: cd ${path.relative(args.cwd, targetDir) || '.'} && install, then "ekanos add <integration>@<version> --from-dir <contracts folder>".`);
+}
+//# sourceMappingURL=init.js.map

package/dist/experience/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/experience/init.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport type { CliContext } from '../context';\nimport { invalidStateError, usageError } from '../errors';\nimport type { ExitCode } from '../exit-codes';\nimport { classifyPath, writeFileNoFollow } from '../safe-fs';\nimport { readTemplate, toDisplayName } from '../templates';\n\nconst SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;\n\n/** template (under templates/experience/) -> destination. */\nconst FILES: ReadonlyArray<{ template: string; dest: string }> = [\n  { template: 'ekanos.json.tmpl', dest: 'ekanos.json' },\n  { template: 'package.json.tmpl', dest: 'package.json' },\n  { template: 'tsconfig.json.tmpl', dest: 'tsconfig.json' },\n  { template: 'gitignore.tmpl', dest: '.gitignore' },\n  { template: 'eslint.config.mjs.tmpl', dest: 'eslint.config.mjs' },\n  { template: 'AGENTS.md.tmpl', dest: 'AGENTS.md' },\n  { template: 'ekanos.lock.json.tmpl', dest: 'ekanos.lock.json' },\n  { template: 'src/experience.ts.tmpl', dest: 'src/experience.ts' },\n  {\n    template: 'src/widgets/hello-widget.tsx.tmpl',\n    dest: 'src/widgets/hello-widget.tsx',\n  },\n  {\n    template: 'src/.ekanos/integrations.d.ts.tmpl',\n    dest: 'src/.ekanos/integrations.d.ts',\n  },\n];\n\nexport interface InitExperienceArgs {\n  slug?: string;\n  dir?: string;\n  cwd: string;\n  force: boolean;\n}\n\n/** `ekanos init --kind experience`: scaffold a project with no integrations yet. */\nexport function runInitExperience(\n  ctx: CliContext,\n  args: InitExperienceArgs,\n): ExitCode {\n  const slug = args.slug;\n  if (!slug || !SLUG_PATTERN.test(slug)) {\n    throw usageError(\n      slug ? `Invalid slug \"${slug}\".` : 'init requires a slug.',\n      'Pass kebab-case: \"ekanos init --kind experience --slug content-engine\".',\n    );\n  }\n  const targetDir = path.resolve(args.cwd, args.dir ?? slug);\n  if (fs.existsSync(targetDir) && fs.lstatSync(targetDir).isSymbolicLink()) {\n    throw invalidStateError(\n      `The target directory ${targetDir} is a symlink.`,\n      'Scaffold into the real directory.',\n    );\n  }\n  fs.mkdirSync(targetDir, { recursive: true });\n\n  const vars = { SLUG: slug, DISPLAY_NAME: toDisplayName(slug) };\n  const created: string[] = [];\n  const skipped: string[] = [];\n  for (const { template, dest } of FILES) {\n    const destPath = path.join(targetDir, dest);\n    const kind = classifyPath(destPath);\n    if (kind !== 'missing' && kind !== 'symlink' && !args.force) {\n      skipped.push(dest);\n      continue;\n    }\n    writeFileNoFollow(\n      targetDir,\n      destPath,\n      readTemplate(`experience/${template}`, vars),\n    );\n    created.push(dest);\n  }\n  for (const keep of ['contracts/.gitkeep', 'fixtures/.gitkeep']) {\n    const destPath = path.join(targetDir, keep);\n    if (classifyPath(destPath) === 'missing') {\n      writeFileNoFollow(targetDir, destPath, '');\n      created.push(keep);\n    }\n  }\n\n  for (const file of created) ctx.log(`  created ${file}`);\n  for (const file of skipped)\n    ctx.log(`  skipped ${file} (already exists; --force overwrites)`);\n\n  return ctx.succeed(\n    { kind: 'experience', slug, dir: targetDir, created, skipped },\n    `Scaffolded experience \"${slug}\". Next: cd ${path.relative(args.cwd, targetDir) || '.'} && install, then \"ekanos add <integration>@<version> --from-dir <contracts folder>\".`,\n  );\n}\n"]}

package/dist/experience/integrations-codegen.d.ts

@@ -0,0 +1,17 @@
+import { type Contract } from '@ekanos/integration-schema';
+import type { ExperienceProject } from './project.js';
+export declare const GENERATED_BANNER: string;
+export interface IntegrationContract {
+    integration: string;
+    contract: Contract;
+    /** The `kind/name` keys the experience declared for this integration in `integrations[].operations`. */
+    operations: readonly string[];
+}
+/**
+ * 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 declare function generateIntegrationsDts(integrations: readonly IntegrationContract[]): string;
+/** `kind/name` keys of an integration's declared operations (canonical ids stripped). */
+export declare function declaredOperationKeys(integration: ExperienceProject['integrations'][number]): string[];