@calliopelabs/ui 0.7.0 → 0.11.0

package/dist/workflow/portable.js

@@ -0,0 +1,547 @@
+/**
+ * Reading, comparing and moving workflow definitions: a strict reader that
+ * keeps only the fields the format knows (so nothing else, a credential or a
+ * grant, rides along), a diff that says what a change does to what runs, and
+ * versioned packages with a preview of what importing one does at a
+ * destination. Pure: the host reads and writes the files and owns authority.
+ */
+import { WORKFLOW_DEFINITION_VERSION, WORKFLOW_NODE_KINDS, WORKFLOW_SELECTORS, edgeId, findGateKind, } from "./definition.js";
+import { checkDefinition, definitionAvailability, nodeAvailability, } from "./problems.js";
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const str = (v) => (typeof v === "string" ? v : undefined);
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
+const bool = (v) => (typeof v === "boolean" ? v : undefined);
+const arr = (v) => (Array.isArray(v) ? v : []);
+const strs = (v) => arr(v).filter((x) => typeof x === "string");
+/** Drops the keys whose value is undefined, so a read definition compares equal to a written one. */
+function clean(o) {
+    for (const k of Object.keys(o))
+        if (o[k] === undefined)
+            delete o[k];
+    return o;
+}
+class ReadError extends Error {
+    path;
+    constructor(path) {
+        super(path);
+        this.path = path;
+    }
+}
+function need(v, path) {
+    if (v === undefined)
+        throw new ReadError(path);
+    return v;
+}
+function readPort(raw, path) {
+    const o = isObj(raw) ? raw : {};
+    return clean({
+        id: need(str(o.id), `${path}.id`),
+        label: need(str(o.label), `${path}.label`),
+        type: need(str(o.type), `${path}.type`),
+        optional: bool(o.optional),
+    });
+}
+const readPorts = (raw, path) => raw === undefined ? undefined : arr(raw).map((p, i) => readPort(p, `${path}[${i}]`));
+function readCondition(raw, path) {
+    const o = isObj(raw) ? raw : {};
+    const value = o.value;
+    return clean({
+        fact: need(str(o.fact), `${path}.fact`),
+        node: str(o.node),
+        op: need(str(o.op), `${path}.op`),
+        value: typeof value === "string" || typeof value === "boolean" || num(value) !== undefined
+            ? value
+            : undefined,
+    });
+}
+function readRef(raw, path) {
+    if (raw === undefined)
+        return undefined;
+    const o = isObj(raw) ? raw : {};
+    return { module: need(str(o.module), `${path}.module`), id: need(str(o.id), `${path}.id`) };
+}
+function readNode(raw, path) {
+    const o = isObj(raw) ? raw : {};
+    const kind = str(o.kind);
+    if (!kind || !WORKFLOW_NODE_KINDS.includes(kind))
+        throw new ReadError(`${path}.kind`);
+    const at = isObj(o.at) && num(o.at.x) !== undefined && num(o.at.y) !== undefined
+        ? { x: o.at.x, y: o.at.y }
+        : undefined;
+    const base = {
+        id: need(str(o.id), `${path}.id`),
+        label: need(str(o.label), `${path}.label`),
+        at,
+        note: str(o.note),
+    };
+    switch (kind) {
+        case "step":
+            return clean({
+                ...base,
+                kind,
+                preset: readRef(o.preset, `${path}.preset`),
+                inputs: readPorts(o.inputs, `${path}.inputs`),
+                outputs: readPorts(o.outputs, `${path}.outputs`),
+                model: str(o.model),
+                harness: str(o.harness),
+                effort: str(o.effort),
+            });
+        case "subflow":
+            return clean({ ...base, kind, flow: str(o.flow) ?? "", each: str(o.each) });
+        case "gate": {
+            const p = isObj(o.policy) ? o.policy : undefined;
+            const onTimeout = str(p?.onTimeout);
+            return clean({
+                ...base,
+                kind,
+                gate: need(str(o.gate), `${path}.gate`),
+                policy: p
+                    ? clean({
+                        roles: p.roles === undefined ? undefined : strs(p.roles),
+                        members: p.members === undefined ? undefined : strs(p.members),
+                        quorum: num(p.quorum),
+                        timeoutHours: num(p.timeoutHours),
+                        onTimeout: onTimeout === "fail" || onTimeout === "escalate" ? onTimeout : undefined,
+                    })
+                    : undefined,
+                threshold: num(o.threshold),
+                rule: str(o.rule),
+            });
+        }
+        case "condition":
+            return clean({
+                ...base,
+                kind,
+                cases: arr(o.cases).map((c, i) => {
+                    const co = isObj(c) ? c : {};
+                    return {
+                        id: need(str(co.id), `${path}.cases[${i}].id`),
+                        label: need(str(co.label), `${path}.cases[${i}].label`),
+                        when: readCondition(co.when, `${path}.cases[${i}].when`),
+                    };
+                }),
+            });
+        case "goto":
+            return clean({ ...base, kind, target: str(o.target) ?? "", max: num(o.max) });
+        case "fanout":
+            return clean({ ...base, kind });
+        case "join": {
+            const wait = str(o.wait);
+            return clean({
+                ...base,
+                kind,
+                wait: wait === "any" || wait === "n" ? wait : "all",
+                n: num(o.n),
+            });
+        }
+        case "variants": {
+            const select = str(o.select);
+            return clean({
+                ...base,
+                kind,
+                preset: readRef(o.preset, `${path}.preset`),
+                variants: arr(o.variants).map((v, i) => {
+                    const vo = isObj(v) ? v : {};
+                    return clean({
+                        id: need(str(vo.id), `${path}.variants[${i}].id`),
+                        label: need(str(vo.label), `${path}.variants[${i}].label`),
+                        model: str(vo.model),
+                        harness: str(vo.harness),
+                        effort: str(vo.effort),
+                    });
+                }),
+                select: WORKFLOW_SELECTORS.includes(select ?? "")
+                    ? select
+                    : undefined,
+                evaluator: str(o.evaluator),
+            });
+        }
+        case "evaluator":
+            return clean({
+                ...base,
+                kind,
+                question: str(o.question),
+                levels: strs(o.levels),
+                threshold: num(o.threshold),
+                routes: bool(o.routes) ?? false,
+                minConfidence: num(o.minConfidence),
+            });
+        case "classifier":
+            return clean({
+                ...base,
+                kind,
+                question: str(o.question),
+                options: arr(o.options).map((v, i) => {
+                    const vo = isObj(v) ? v : {};
+                    return clean({
+                        id: need(str(vo.id), `${path}.options[${i}].id`),
+                        label: need(str(vo.label), `${path}.options[${i}].label`),
+                        description: str(vo.description),
+                    });
+                }),
+                other: bool(o.other) ?? false,
+                minConfidence: num(o.minConfidence),
+            });
+        case "check":
+            return clean({
+                ...base,
+                kind,
+                question: str(o.question) ?? "",
+                threshold: num(o.threshold) ?? 0.5,
+            });
+    }
+}
+function readEdge(raw, path) {
+    const o = isObj(raw) ? raw : {};
+    const kind = str(o.kind);
+    if (kind !== "next" && kind !== "loop" && kind !== "data")
+        throw new ReadError(`${path}.kind`);
+    return clean({
+        kind,
+        from: need(str(o.from), `${path}.from`),
+        to: need(str(o.to), `${path}.to`),
+        port: str(o.port),
+        input: str(o.input),
+        label: str(o.label),
+        max: num(o.max),
+        until: o.until === undefined ? undefined : readCondition(o.until, `${path}.until`),
+    });
+}
+function readFlow(raw, path) {
+    if (!isObj(raw))
+        throw new ReadError(path);
+    return clean({
+        label: str(raw.label),
+        inputs: readPorts(raw.inputs, `${path}.inputs`),
+        outputs: readPorts(raw.outputs, `${path}.outputs`),
+        nodes: arr(raw.nodes).map((n, i) => readNode(n, `${path}.nodes[${i}]`)),
+        edges: arr(raw.edges).map((e, i) => readEdge(e, `${path}.edges[${i}]`)),
+    });
+}
+function readDefinitionObject(raw) {
+    if (!isObj(raw))
+        throw new ReadError("$");
+    if (raw.version !== WORKFLOW_DEFINITION_VERSION)
+        throw new VersionError(raw.version);
+    if (!isObj(raw.flows))
+        throw new ReadError("$.flows");
+    const flows = {};
+    for (const [name, f] of Object.entries(raw.flows))
+        flows[name] = readFlow(f, `$.flows.${name}`);
+    return clean({
+        version: WORKFLOW_DEFINITION_VERSION,
+        name: need(str(raw.name), "$.name"),
+        description: str(raw.description),
+        module: str(raw.module),
+        main: need(str(raw.main), "$.main"),
+        flows,
+    });
+}
+class VersionError extends Error {
+    version;
+    constructor(version) {
+        super("version");
+        this.version = version;
+    }
+}
+function attempt(read) {
+    try {
+        return { ok: true, value: read() };
+    }
+    catch (e) {
+        if (e instanceof VersionError)
+            return { ok: false, error: { code: "unsupported-version", version: e.version } };
+        if (e instanceof ReadError)
+            return { ok: false, error: { code: "not-a-definition", path: e.path } };
+        throw e;
+    }
+}
+/**
+ * Reads a definition from parsed JSON or a JSON string. Keeps only the fields
+ * the format knows; anything else is dropped, never carried.
+ */
+export function readWorkflowDefinition(raw) {
+    if (typeof raw === "string") {
+        try {
+            raw = JSON.parse(raw);
+        }
+        catch {
+            return { ok: false, error: { code: "not-json" } };
+        }
+    }
+    return attempt(() => readDefinitionObject(raw));
+}
+/** JSON with sorted keys and no undefined values: two documents that say the same compare equal. */
+const json = (v) => JSON.stringify(v, (_key, value) => isObj(value)
+    ? Object.fromEntries(Object.keys(value)
+        .sort()
+        .filter((k) => value[k] !== undefined)
+        .map((k) => [k, value[k]]))
+    : value);
+const withoutAt = (n) => json({ ...n, at: undefined });
+const flowShape = (f) => json({ label: f.label, inputs: f.inputs, outputs: f.outputs });
+/** What changing `before` into `after` does to what runs. Positions are reported apart, as `moved`. */
+export function diffDefinitions(before, after) {
+    const details = [];
+    for (const k of ["name", "description", "module", "main"])
+        if (before[k] !== after[k])
+            details.push(k);
+    const flowsAdded = Object.keys(after.flows).filter((n) => !before.flows[n]);
+    const flowsRemoved = Object.keys(before.flows).filter((n) => !after.flows[n]);
+    const flows = [];
+    let shapeChanged = false;
+    for (const [name, b] of Object.entries(after.flows)) {
+        const a = before.flows[name];
+        if (!a)
+            continue;
+        if (flowShape(a) !== flowShape(b))
+            shapeChanged = true;
+        const an = new Map(a.nodes.map((n) => [n.id, n]));
+        const bn = new Map(b.nodes.map((n) => [n.id, n]));
+        const ae = new Map(a.edges.map((e) => [edgeId(e), e]));
+        const be = new Map(b.edges.map((e) => [edgeId(e), e]));
+        const item = (n) => ({ id: n.id, label: n.label });
+        const edge = (f, e) => {
+            const l = (id) => f.nodes.find((n) => n.id === id)?.label ?? id;
+            return { id: edgeId(e), kind: e.kind, from: l(e.from), to: l(e.to) };
+        };
+        const d = {
+            flow: name,
+            nodesAdded: b.nodes.filter((n) => !an.has(n.id)).map(item),
+            nodesRemoved: a.nodes.filter((n) => !bn.has(n.id)).map(item),
+            nodesChanged: b.nodes
+                .filter((n) => an.has(n.id) && withoutAt(an.get(n.id)) !== withoutAt(n))
+                .map(item),
+            moved: b.nodes
+                .filter((n) => {
+                const was = an.get(n.id);
+                return was && withoutAt(was) === withoutAt(n) && json(was.at) !== json(n.at);
+            })
+                .map(item),
+            edgesAdded: b.edges.filter((e) => !ae.has(edgeId(e))).map((e) => edge(b, e)),
+            edgesRemoved: a.edges.filter((e) => !be.has(edgeId(e))).map((e) => edge(a, e)),
+            edgesChanged: b.edges
+                .filter((e) => ae.has(edgeId(e)) && json(ae.get(edgeId(e))) !== json(e))
+                .map((e) => edge(b, e)),
+        };
+        const { flow: _flow, ...lists } = d;
+        if (Object.values(lists).some((l) => l.length))
+            flows.push(d);
+    }
+    const same = !details.length &&
+        !flowsAdded.length &&
+        !flowsRemoved.length &&
+        !shapeChanged &&
+        flows.every((f) => !f.nodesAdded.length &&
+            !f.nodesRemoved.length &&
+            !f.nodesChanged.length &&
+            !f.edgesAdded.length &&
+            !f.edgesRemoved.length &&
+            !f.edgesChanged.length);
+    return { details, flowsAdded, flowsRemoved, flows, same };
+}
+/**
+ * Whether two definitions are the same document. With `positions: false`,
+ * whether they run the same (a moved node does not count).
+ */
+export function sameDefinition(a, b, options = {}) {
+    if (!a || !b)
+        return a === b;
+    const d = diffDefinitions(a, b);
+    return d.same && (options.positions === false || d.flows.every((f) => !f.moved.length));
+}
+// ---------------------------------------------------------------- packages
+export const WORKFLOW_PACKAGE_FORMAT = "calliope.workflow-package";
+export const WORKFLOW_PACKAGE_VERSION = 1;
+/** What a definition needs, against the registry it was written for. */
+export function requirementsOf(definition, registry) {
+    const nodes = Object.values(definition.flows).flatMap((f) => f.nodes);
+    const edges = Object.values(definition.flows).flatMap((f) => f.edges);
+    const presets = new Map();
+    const modules = new Map();
+    const capabilities = new Set();
+    const gateKinds = new Set();
+    const facts = new Set();
+    const operators = new Set();
+    if (definition.module) {
+        const m = registry.modules.find((x) => x.id === definition.module);
+        modules.set(definition.module, clean({ id: definition.module, label: m?.label ?? definition.module, version: m?.version }));
+    }
+    const conditions = edges.flatMap((e) => (e.until ? [e.until] : []));
+    for (const n of nodes) {
+        if ((n.kind === "step" || n.kind === "variants") && n.preset) {
+            const m = registry.modules.find((x) => x.id === n.preset?.module);
+            const p = m?.presets.find((x) => x.id === n.preset?.id);
+            modules.set(n.preset.module, clean({ id: n.preset.module, label: m?.label ?? n.preset.module, version: m?.version }));
+            presets.set(`${n.preset.module}/${n.preset.id}`, {
+                ...n.preset,
+                label: p?.label ?? n.preset.id,
+            });
+            for (const c of p?.capabilities ?? [])
+                capabilities.add(c);
+        }
+        if (n.kind === "gate") {
+            gateKinds.add(n.gate);
+            for (const c of findGateKind(registry, n.gate)?.capabilities ?? [])
+                capabilities.add(c);
+        }
+        if (n.kind === "condition")
+            conditions.push(...n.cases.map((c) => c.when));
+    }
+    for (const c of conditions) {
+        facts.add(c.fact);
+        operators.add(c.op);
+    }
+    return {
+        modules: [...modules.values()],
+        presets: [...presets.values()],
+        capabilities: [...capabilities],
+        gateKinds: [...gateKinds],
+        facts: [...facts],
+        operators: [...operators],
+        nodeKinds: WORKFLOW_NODE_KINDS.filter((k) => nodes.some((n) => n.kind === k)),
+    };
+}
+/** Gates keep their roles and quorum; named members are this organization's, not the package's. */
+function withoutMembers(definition) {
+    const flows = {};
+    for (const [name, f] of Object.entries(definition.flows))
+        flows[name] = {
+            ...f,
+            nodes: f.nodes.map((n) => {
+                if (n.kind !== "gate" || !n.policy?.members)
+                    return n;
+                const { members: _members, ...policy } = n.policy;
+                return { ...n, policy };
+            }),
+        };
+    return { ...definition, flows };
+}
+/** A package of a definition, for the host to write out. */
+export function exportWorkflowPackage(definition, registry, source) {
+    const read = readWorkflowDefinition(JSON.stringify(definition));
+    if (!read.ok)
+        throw new Error("exportWorkflowPackage: the definition does not read back");
+    const portable = withoutMembers(read.value);
+    return {
+        format: WORKFLOW_PACKAGE_FORMAT,
+        version: WORKFLOW_PACKAGE_VERSION,
+        definition: portable,
+        requires: requirementsOf(portable, registry),
+        ...(source ? { source } : {}),
+    };
+}
+function readRequirements(raw) {
+    const o = isObj(raw) ? raw : {};
+    const list = (v) => arr(v).filter(isObj);
+    return {
+        modules: list(o.modules).flatMap((m) => str(m.id)
+            ? [
+                clean({
+                    id: str(m.id),
+                    label: str(m.label) ?? m.id,
+                    version: str(m.version),
+                }),
+            ]
+            : []),
+        presets: list(o.presets).flatMap((p) => str(p.module) && str(p.id)
+            ? [
+                {
+                    module: p.module,
+                    id: p.id,
+                    label: str(p.label) ?? p.id,
+                },
+            ]
+            : []),
+        capabilities: strs(o.capabilities),
+        gateKinds: strs(o.gateKinds),
+        facts: strs(o.facts),
+        operators: strs(o.operators),
+        nodeKinds: strs(o.nodeKinds).filter((k) => WORKFLOW_NODE_KINDS.includes(k)),
+    };
+}
+/** Reads a package from parsed JSON or a JSON string, checking its format and version. */
+export function readWorkflowPackage(raw) {
+    if (typeof raw === "string") {
+        try {
+            raw = JSON.parse(raw);
+        }
+        catch {
+            return { ok: false, error: { code: "not-json" } };
+        }
+    }
+    if (!isObj(raw) || raw.format !== WORKFLOW_PACKAGE_FORMAT)
+        return { ok: false, error: { code: "not-a-package" } };
+    if (raw.version !== WORKFLOW_PACKAGE_VERSION)
+        return { ok: false, error: { code: "unsupported-version", version: raw.version } };
+    const definition = readWorkflowDefinition(raw.definition);
+    if (!definition.ok)
+        return definition;
+    const s = isObj(raw.source) ? raw.source : undefined;
+    return {
+        ok: true,
+        value: {
+            format: WORKFLOW_PACKAGE_FORMAT,
+            version: WORKFLOW_PACKAGE_VERSION,
+            definition: withoutMembers(definition.value),
+            requires: readRequirements(raw.requires),
+            ...(s
+                ? {
+                    source: clean({
+                        factory: str(s.factory),
+                        revision: str(s.revision),
+                        exportedAt: str(s.exportedAt),
+                    }),
+                }
+                : {}),
+        },
+    };
+}
+/**
+ * What importing a package would do at a destination: the module and
+ * capability gaps, the vocabulary it does not know, the nodes that would be
+ * disabled, the problems there, and, when it replaces a definition, the diff.
+ */
+export function previewWorkflowImport(pkg, destination, replacing) {
+    const { definition, requires } = pkg;
+    const modules = requires.modules.map((m) => {
+        const here = destination.modules.find((x) => x.id === m.id);
+        const base = clean({ id: m.id, label: m.label, version: m.version });
+        if (!here)
+            return { ...base, status: "missing" };
+        const installed = here.version ? { installed: here.version } : {};
+        if (here.availability && here.availability.status !== "available")
+            return { ...base, ...installed, status: "unavailable", availability: here.availability };
+        if (m.version && here.version && m.version !== here.version)
+            return { ...base, ...installed, status: "version" };
+        return { ...base, ...installed, status: "available" };
+    });
+    const missingCapabilities = destination.capabilities
+        ? requires.capabilities.filter((c) => !destination.capabilities?.includes(c))
+        : [];
+    const disabled = [];
+    const gatesNeedingApprovers = [];
+    for (const [flow, f] of Object.entries(definition.flows))
+        for (const n of f.nodes) {
+            const availability = nodeAvailability(n, destination);
+            if (availability.status !== "available")
+                disabled.push({ flow, id: n.id, label: n.label, availability });
+            if (n.kind === "gate" &&
+                findGateKind(destination, n.gate)?.fields.includes("approvers") &&
+                !n.policy?.roles?.length)
+                gatesNeedingApprovers.push({ id: n.id, label: n.label });
+        }
+    return {
+        definition,
+        availability: definitionAvailability(definition, destination),
+        modules,
+        missingCapabilities,
+        unknownGateKinds: requires.gateKinds.filter((g) => !findGateKind(destination, g)),
+        unknownFacts: requires.facts.filter((f) => !destination.facts.some((x) => x.id === f)),
+        unknownOperators: requires.operators.filter((o) => !destination.operators.some((x) => x.id === o)),
+        disabled,
+        gatesNeedingApprovers,
+        problems: checkDefinition(definition, destination),
+        ...(replacing ? { diff: diffDefinitions(replacing, definition) } : {}),
+    };
+}

package/dist/workflow/problems.d.ts

@@ -0,0 +1,38 @@
+/**
+ * What is wrong with a workflow definition, at three levels, and whether this
+ * destination can run each node. `blocking` problems stop a publish,
+ * `warning`s do not, and `not-run` marks a node this destination does not run
+ * (yet): its module, a capability or its kind is missing here. Problems carry
+ * a code and values, never English; the editor's copy names them. Pure.
+ */
+import { type WorkflowDefinition, type WorkflowNode, type WorkflowRegistry } from "./definition.js";
+import type { WorkflowAvailability } from "./model.js";
+export type WorkflowProblemLevel = "blocking" | "warning" | "not-run";
+export declare const WORKFLOW_PROBLEM_CODES: readonly ["no-main", "flow-empty", "duplicate-id", "unreachable", "dangling-edge", "missing-exit", "cycle", "loop-no-until", "loop-no-max", "loop-not-back", "exit-unwired", "input-unbound", "data-port-missing", "data-type", "data-order", "unknown-preset", "unknown-model", "unknown-harness", "unknown-effort", "subflow-none", "subflow-missing", "subflow-recursive", "unknown-gate-kind", "gate-no-approver", "gate-quorum", "gate-no-threshold", "gate-no-rule", "gate-no-timeout-action", "no-cases", "unknown-fact", "unknown-operator", "operator-mismatch", "value-missing", "value-type", "fact-node-missing", "goto-no-target", "goto-missing-target", "goto-no-max", "fanout-few", "join-few", "join-no-n", "variants-few", "variants-no-select", "variants-no-evaluator", "rubric-short", "no-threshold", "no-question", "options-few", "option-duplicate", "not-runnable"];
+export type WorkflowProblemCode = (typeof WORKFLOW_PROBLEM_CODES)[number];
+export interface WorkflowProblem {
+    level: WorkflowProblemLevel;
+    code: WorkflowProblemCode;
+    /** The flow it is in. */
+    flow?: string;
+    /** What it points at: a node id, an edge id (`edgeId`). Neither: the flow or the definition. */
+    node?: string;
+    edge?: string;
+    /** What the copy names: labels, exits, types, counts. */
+    values: Record<string, string | number>;
+    /** For `not-runnable`: what this destination says about the node. */
+    availability?: WorkflowAvailability;
+}
+/**
+ * Whether this destination can run a node, reusing the gallery's
+ * availability: `unsupported` when its kind, module, preset or gate kind is
+ * not here, `missing-capabilities` with the names when the module is but a
+ * capability it needs is not.
+ */
+export declare function nodeAvailability(node: WorkflowNode, registry: WorkflowRegistry): WorkflowAvailability;
+/** Whether this destination can run the whole definition: every node of every flow. */
+export declare function definitionAvailability(definition: WorkflowDefinition, registry: WorkflowRegistry): WorkflowAvailability;
+/** Every problem in a definition, against what this destination's registry says. */
+export declare function checkDefinition(definition: WorkflowDefinition, registry: WorkflowRegistry): WorkflowProblem[];
+/** The problems that stop a publish. */
+export declare const blockingProblems: (problems: readonly WorkflowProblem[]) => WorkflowProblem[];