@calliopelabs/ui 0.7.0 → 0.11.0

package/dist/workflow/portable.d.ts

@@ -0,0 +1,162 @@
+/**
+ * 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 { type WorkflowDefinition, type WorkflowEdge, type WorkflowNodeKind, type WorkflowRegistry } from "./definition.js";
+import type { WorkflowAvailability } from "./model.js";
+import { type WorkflowProblem } from "./problems.js";
+/** Why a definition or package could not be read. */
+export type WorkflowReadError = {
+    code: "not-json";
+} | {
+    code: "not-a-definition";
+    path: string;
+} | {
+    code: "not-a-package";
+} | {
+    code: "unsupported-version";
+    version: unknown;
+};
+export type WorkflowReadResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: WorkflowReadError;
+};
+/**
+ * Reads a definition from parsed JSON or a JSON string. Keeps only the fields
+ * the format knows; anything else is dropped, never carried.
+ */
+export declare function readWorkflowDefinition(raw: unknown): WorkflowReadResult<WorkflowDefinition>;
+export interface WorkflowDiffItem {
+    id: string;
+    label: string;
+}
+export interface WorkflowFlowDiff {
+    flow: string;
+    nodesAdded: WorkflowDiffItem[];
+    nodesRemoved: WorkflowDiffItem[];
+    nodesChanged: WorkflowDiffItem[];
+    /** Edges, labelled by their ends ("Draft", "Review"). */
+    edgesAdded: WorkflowDiffEdge[];
+    edgesRemoved: WorkflowDiffEdge[];
+    edgesChanged: WorkflowDiffEdge[];
+    /** Only positions moved; does not change what runs. */
+    moved: WorkflowDiffItem[];
+}
+export interface WorkflowDiffEdge {
+    id: string;
+    kind: WorkflowEdge["kind"];
+    from: string;
+    to: string;
+}
+export interface WorkflowDefinitionDiff {
+    /** Name, description, module or main flow changed. */
+    details: ("name" | "description" | "module" | "main")[];
+    flowsAdded: string[];
+    flowsRemoved: string[];
+    flows: WorkflowFlowDiff[];
+    /** Nothing that runs changes (positions may have). */
+    same: boolean;
+}
+/** What changing `before` into `after` does to what runs. Positions are reported apart, as `moved`. */
+export declare function diffDefinitions(before: WorkflowDefinition, after: WorkflowDefinition): WorkflowDefinitionDiff;
+/**
+ * Whether two definitions are the same document. With `positions: false`,
+ * whether they run the same (a moved node does not count).
+ */
+export declare function sameDefinition(a: WorkflowDefinition | null | undefined, b: WorkflowDefinition | null | undefined, options?: {
+    positions?: boolean;
+}): boolean;
+export declare const WORKFLOW_PACKAGE_FORMAT = "calliope.workflow-package";
+export declare const WORKFLOW_PACKAGE_VERSION = 1;
+/** What a definition needs from a destination, listed so a preview can read it without a registry. */
+export interface WorkflowRequirements {
+    modules: {
+        id: string;
+        label: string;
+        version?: string;
+    }[];
+    presets: {
+        module: string;
+        id: string;
+        label: string;
+    }[];
+    capabilities: string[];
+    gateKinds: string[];
+    facts: string[];
+    operators: string[];
+    nodeKinds: WorkflowNodeKind[];
+}
+/**
+ * A portable workflow: the definition and what it needs. It never carries
+ * credentials, grants or named people: the definition is re-read through the
+ * format (unknown fields dropped) and gates lose their named members.
+ */
+export interface WorkflowPackage {
+    format: typeof WORKFLOW_PACKAGE_FORMAT;
+    version: typeof WORKFLOW_PACKAGE_VERSION;
+    definition: WorkflowDefinition;
+    requires: WorkflowRequirements;
+    /** Where it came from, as the host labels it. */
+    source?: {
+        factory?: string;
+        revision?: string;
+        exportedAt?: string;
+    };
+}
+/** What a definition needs, against the registry it was written for. */
+export declare function requirementsOf(definition: WorkflowDefinition, registry: WorkflowRegistry): WorkflowRequirements;
+/** A package of a definition, for the host to write out. */
+export declare function exportWorkflowPackage(definition: WorkflowDefinition, registry: WorkflowRegistry, source?: WorkflowPackage["source"]): WorkflowPackage;
+/** Reads a package from parsed JSON or a JSON string, checking its format and version. */
+export declare function readWorkflowPackage(raw: unknown): WorkflowReadResult<WorkflowPackage>;
+/** One module the package needs, as the destination has it. */
+export interface WorkflowModuleGap {
+    id: string;
+    label: string;
+    /** The version the package was written against. */
+    version?: string;
+    /** `missing`: not installed here. `version`: installed at another version. */
+    status: "available" | "missing" | "version" | "unavailable";
+    /** The destination's version, when it has the module. */
+    installed?: string;
+    availability?: WorkflowAvailability;
+}
+/** A node importing would leave disabled, and why. */
+export interface WorkflowDisabledNode {
+    flow: string;
+    id: string;
+    label: string;
+    availability: WorkflowAvailability;
+}
+export interface WorkflowImportSummary {
+    definition: WorkflowDefinition;
+    /** Whether the destination could run it as imported. */
+    availability: WorkflowAvailability;
+    modules: WorkflowModuleGap[];
+    /** Capabilities the package needs that the destination lacks. */
+    missingCapabilities: string[];
+    /** Vocabulary the destination's runtime does not know. */
+    unknownGateKinds: string[];
+    unknownFacts: string[];
+    unknownOperators: string[];
+    /** Nodes that would be disabled here. */
+    disabled: WorkflowDisabledNode[];
+    /** Gates that came without named approvers and need a role here. */
+    gatesNeedingApprovers: WorkflowDiffItem[];
+    /** Problems at the destination. */
+    problems: WorkflowProblem[];
+    /** Against the definition it would replace, when the host names one. */
+    diff?: WorkflowDefinitionDiff;
+}
+/**
+ * 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 declare function previewWorkflowImport(pkg: WorkflowPackage, destination: WorkflowRegistry, replacing?: WorkflowDefinition): WorkflowImportSummary;