@ekanos/cli 0.15.0 → 0.17.0

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":"AAAA,OAAO,EAIL,sBAAsB,EACtB,aAAa,EACb,SAAS,EACT,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAMlC,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAA0B,YAAY,EAAE,MAAM,QAAQ,CAAC;AAG9D,MAAM,CAAC,MAAM,gBAAgB,GAAG,8BAA8B,CAAC;AAE/D,MAAM,GAAG,GAAG,CAAC,OAAe,EAAE,IAAY,EAAE,IAAa,EAAW,EAAE,CAAC,iBACrE,KAAK,EAAE,gBAAgB,EACvB,QAAQ,EAAE,OAAO,EACjB,OAAO;IACP,IAAI,IACD,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EACzB,CAAC;AAEH,MAAM,IAAI,GAAG,CAAC,OAAe,EAAE,IAAY,EAAE,IAAa,EAAW,EAAE,CAAC,iBACtE,KAAK,EAAE,gBAAgB,EACvB,QAAQ,EAAE,MAAM,EAChB,OAAO;IACP,IAAI,IACD,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EACzB,CAAC;AAOH;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAA0B,EAC1B,MAA8B,EAC9B,MAAoC;;;IAEpC,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC;IAC9B,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,MAAM,SAAS,GAAuB,EAAE,CAAC;IACzC,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAClC,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAC7C,CAAC;IACF,MAAM,QAAQ,GAAG,IAAI,GAAG,CACtB,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QAC9B,CAAC,CAAC,IAAI;QACN,IAAI,GAAG,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;KAClC,CAAC,CACH,CAAC;IACF,MAAM,WAAW,GAAG,IAAI,GAAG,CACzB,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;QAChC,GAAG,CAAC,IAAI;QACR,IAAI,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;KACxE,CAAC,CACH,CAAC;IAEF,IAAI,UAAU,CAAC,IAAI,KAAK,OAAO,CAAC,IAAI,EAAE,CAAC;QACrC,QAAQ,CAAC,IAAI,CACX,GAAG,CACD,0BAA0B,UAAU,CAAC,IAAI,+BAA+B,OAAO,CAAC,IAAI,IAAI,EACxF,kBAAkB,EAClB,OAAO,CAAC,KAAK,CACd,CACF,CAAC;IACJ,CAAC;IAED,MAAM,gBAAgB,GAAG,CAAC,WAAmB,EAAE,KAAa,EAAE,EAAE;QAC9D,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;YAC3C,QAAQ,CAAC,IAAI,CACX,GAAG,CACD,GAAG,KAAK,sBAAsB,WAAW,uDAAuD,EAChG,2BAA2B,WAAW,cAAc,EACpD,OAAO,CAAC,KAAK,CACd,CACF,CAAC;YAEF,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,KAAK,MAAM,MAAM,IAAI,UAAU,CAAC,OAAO,EAAE,CAAC;QACxC,KAAK,MAAM,WAAW,IAAI,MAAM,CAAC,YAAY;YAC3C,gBAAgB,CAAC,WAAW,EAAE,WAAW,MAAM,CAAC,EAAE,GAAG,CAAC,CAAC;IAC3D,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,KAAK,EAAE,CAAC;QACpC,KAAK,MAAM,WAAW,IAAI,IAAI,CAAC,YAAY;YACzC,gBAAgB,CAAC,WAAW,EAAE,SAAS,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;IACvD,CAAC;IAED,KAAK,MAAM,OAAO,UAAI,MAAA,UAAU,CAAC,WAAW,0CAAE,QAAQ,mCAAI,EAAE,EAAE,CAAC;QAC7D,IACE,CAAC,gBAAgB,CAAC,OAAO,CAAC,WAAW,EAAE,mBAAmB,OAAO,CAAC,EAAE,GAAG,CAAC;YAExE,SAAS;QACX,IAAI,EAAC,MAAA,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,0CAAE,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA,EAAE,CAAC;YAC1D,QAAQ,CAAC,IAAI,CACX,GAAG,CACD,mBAAmB,OAAO,CAAC,EAAE,WAAW,OAAO,CAAC,IAAI,wBAAwB,OAAO,CAAC,WAAW,qBAAqB,EACpH,2EAA2E,EAC3E,OAAO,CAAC,KAAK,CACd,CACF,CAAC;QACJ,CAAC;aAAM,IACL,CAAA,MAAA,MAAA,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,0CAAE,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,0CAAE,MAAM,MAAK,MAAM,EAC1E,CAAC;YACD,QAAQ,CAAC,IAAI,CACX,GAAG,CACD,mBAAmB,OAAO,CAAC,EAAE,WAAW,OAAO,CAAC,IAAI,kCAAkC,EACtF,2EAA2E,EAC3E,OAAO,CAAC,KAAK,CACd,CACF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACtC,KAAK,MAAM,QAAQ,IAAI,UAAU,CAAC,SAAS,EAAE,CAAC;QAC5C,MAAM,KAAK,GAAG,aAAa,QAAQ,CAAC,EAAE,GAAG,CAAC;QAC1C,IAAI,KAAwC,CAAC;QAC7C,IAAI,CAAC;YACH,KAAK,GAAG,QAAQ,CAAC,KAAK,EAAE,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,QAAQ,CAAC,IAAI,CACX,GAAG,CACD,GAAG,KAAK,oBAAoB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EACpF,mBAAmB,EACnB,OAAO,CAAC,KAAK,CACd,CACF,CAAC;YACF,SAAS;QACX,CAAC;QAED,IAAI,OAAO,GAAG,IAAI,CAAC;QACnB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,EAAE;gBAAE,SAAS;YACpE,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,KAAK,UAAU,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;gBACtE,OAAO,GAAG,KAAK,CAAC;YAClB,CAAC;iBAAM,IAAI,EAAC,MAAA,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,0CAAE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA,EAAE,CAAC;gBACzD,OAAO,GAAG,KAAK,CAAC;gBAChB,QAAQ,CAAC,IAAI,CACX,GAAG,CACD,GAAG,KAAK,UAAU,IAAI,CAAC,EAAE,WAAW,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,EAAE,2CAA2C,EAC1G,yFAAyF,EACzF,OAAO,CAAC,KAAK,CACd,CACF,CAAC;YACJ,CAAC;QACH,CAAC;QACD,IAAI,CAAC,OAAO;YAAE,SAAS;QAEvB,IAAI,GAAY,CAAC;QACjB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,CAAC,yBAAyB,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;QACjE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,QAAQ,CAAC,IAAI,CACX,GAAG,CACD,GAAG,KAAK,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EACrE,mBAAmB,EACnB,OAAO,CAAC,KAAK,CACd,CACF,CAAC;YACF,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,sBAAsB,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACrD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,QAAQ,CAAC,IAAI,CACX,GAAG,CACD,GAAG,KAAK,4CAA4C,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EACpI,2BAA2B,EAC3B,OAAO,CAAC,KAAK,CACd,CACF,CAAC;YACF,SAAS;QACX,CAAC;QACD,KAAK,MAAM,OAAO,IAAI,wBAAwB,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5D,QAAQ,CAAC,IAAI,CACX,GAAG,CAAC,GAAG,KAAK,KAAK,OAAO,GAAG,EAAE,mBAAmB,EAAE,OAAO,CAAC,KAAK,CAAC,CACjE,CAAC;QACJ,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;QAChC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAC;QAC1C,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK;YAC/B,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,OAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,mCAAI,EAAE,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACxD,MAAM,OAAO,GAAG,CAAC,EAAU,EAAE,IAAI,GAAG,IAAI,GAAG,EAAU,EAAW,EAAE;;YAChE,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,OAAO,KAAK,CAAC;YAC/B,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAEb,OAAO,OAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,mCAAI,EAAE,CAAC,CAAC,IAAI,CAC/B,CAAC,CAAC,EAAE,EAAE,kBACJ,CAAA,MAAA,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,0CAAE,IAAI,MAAK,eAAe;gBACnE,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,GAAA,CACnB,CAAC;QACJ,CAAC,CAAC;QACF,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YAClC,IAAI,CAAC,CAAC,IAAI,KAAK,aAAa,IAAI,CAAC,CAAC,MAAM,KAAK,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;gBACvE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAClB,CAAC;QACH,CAAC;QACD,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;YACvB,QAAQ,CAAC,IAAI,CACX,IAAI,CACF,GAAG,KAAK,iBAAiB,EAAE,kCAAkC,EAC7D,gEAAgE,EAChE,OAAO,CAAC,KAAK,CACd,CACF,CAAC;QACJ,CAAC;QAED,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;AACjC,CAAC;AAED,+EAA+E;AAE/E,MAAM,YAAY,GAAG,mDAAmD,CAAC;AAEzE,mGAAmG;AACnG,MAAM,UAAU,aAAa,CAC3B,OAA0B,EAC1B,MAAoC;IAEpC,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IAChD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,QAAQ,CAAC;IAE1C,KAAK,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,MAAM,EAAE,CAAC;QACvC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QAClC,KAAK,MAAM,IAAI,IAAI,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;YACvC,MAAM,GAAG,GAAG,YAAY,GAAG,CAAC,IAAI,IAAI,IAAI,EAAE,CAAC;YAC3C,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACtC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,QAAQ,CAAC,IAAI,CACX,IAAI,CACF,GAAG,GAAG,mDAAmD,EACzD,uCAAuC,EACvC,GAAG,CACJ,CACF,CAAC;gBACF,SAAS;YACX,CAAC;YACD,MAAM,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC;YACpC,IAAI,OAAO,KAAK,OAAO;gBAAE,SAAS;YAClC,MAAM,SAAS,GAAG,QAAQ,CAAC,UAAU,CAAC,IAAI,CACxC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,IAAI,KAAK,EAAE,CACxC,CAAC;YACF,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,QAAQ,CAAC,IAAI,CACX,GAAG,CACD,GAAG,GAAG,KAAK,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,OAAO,WAAW,IAAI,IAAI,EAAE,GAAG,EAC1D,qCAAqC,EACrC,GAAG,CACJ,CACF,CAAC;gBACF,SAAS;YACX,CAAC;YACD,IAAI,SAAS,CAAC,MAAM,CAAC,MAAM;gBAAE,SAAS;YACtC,IAAI,KAAc,CAAC;YACnB,IAAI,CAAC;gBACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;YACpE,CAAC;uBAAO,CAAC;gBACP,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,qBAAqB,EAAE,iBAAiB,EAAE,GAAG,CAAC,CAAC,CAAC;gBACxE,SAAS;YACX,CAAC;YACD,MAAM,QAAQ,GAAG,qBAAqB,CAAC,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YAChE,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxB,QAAQ,CAAC,IAAI,CACX,GAAG,CACD,GAAG,GAAG,uCAAuC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAC1D,uGAAuG,EACvG,GAAG,CACJ,CACF,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,+EAA+E;AAE/E,MAAM,UAAU,aAAa,CAAC,KAO7B;IACC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IAC9C,MAAM,IAAI,+CACR,aAAa,EAAE,CAAU,EACzB,IAAI,EAAE,OAAO,CAAC,IAAI,EAClB,IAAI,EAAE,UAAmB,EACzB,OAAO,EAAE,KAAK,CAAC,OAAO,EACtB,GAAG,EAAE,KAAK,CAAC,GAAG,EACd,YAAY,EAAE,OAAO,CAAC,YAAY,EAClC,YAAY,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC;YAC/C,WAAW,EAAE,GAAG,CAAC,IAAI;YACrB,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,eAAe,EAAE,QAAQ,CAAC,eAAe;YACzC,MAAM,EAAE,QAAQ,CAAC,MAAM;SACxB,CAAC,CAAC,IACA,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,KAC9D,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,6CACrC,EAAE,EAAE,CAAC,CAAC,EAAE,EACR,KAAK,EAAE,CAAC,CAAC,KAAK,EACd,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,IAC9B,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,GACnC,CAAC,CAAC,CAAC,aAAa,KAAK,SAAS;YAC/B,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,aAAa,EAAE,CAAC,GACpC,CAAC,CAAC,CAAC,eAAe,KAAK,SAAS;YACjC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC,eAAe,EAAE,CAAC,EAC3C,CAAC,EACH,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAClC,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC;SAClC,CAAC,CAAC,EACH,iBAAiB,EAAE,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,KACpC,CAAC,UAAU,CAAC,WAAW;QACxB,CAAC,CAAC;YACE,WAAW,EAAE;gBACX,SAAS,EAAE,IAAa;gBACxB,QAAQ,EAAE,UAAU,CAAC,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBACpD,EAAE,EAAE,CAAC,CAAC,EAAE;oBACR,WAAW,EAAE,CAAC,CAAC,WAAW;oBAC1B,IAAI,EAAE,CAAC,CAAC,IAAI;iBACb,CAAC,CAAC;aACJ;SACF;QACH,CAAC,CAAC,EAAE,CAAC,CACR,CAAC;IAEF,uCACK,IAAI,KACP,MAAM,EAAE,UAAU,SAAS,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,EAAE,IAClD;AACJ,CAAC","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[];

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":"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","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>;