@foresthubai/workflow-core 0.3.0

package/src/channel/ChannelDefinition.ts

@@ -0,0 +1,76 @@
+import type { Parameter } from "../parameter";
+import { ALL_CHANNEL_TYPES } from "./Channel";
+
+/**
+ * Single union definition for all Channel variants — deliberately NOT the
+ * per-type registry pattern used by Node/Memory/Model (`*Definition` +
+ * `*Registry`, one definition object per type).
+ *
+ * The reason is in-place `type` switching that preserves shared parameter state.
+ * Because `type` is a parameter and all variants share one `arguments` bag,
+ * changing a channel's type keeps the same instance (id, label) and retains any
+ * entered values that are still valid for the new type: the parameter +
+ * `activationRules` machinery just re-gates which fields show, and `serialize`
+ * (via `pruneArguments`) drops the now-inactive ones. A per-type registry
+ * would make each variant its own definition, so switching type would mean
+ * delete-and-recreate — losing id/label and every shared value the user entered.
+ * (It also lets channels add from one "Add Channel" button with type as a field,
+ * rather than an add-button per type. Node/Memory/Model instead treat `type` as
+ * an immutable registry key chosen at creation.)
+ *
+ * The same could be achieved with a UI-layer "type selector" over a
+ * ChannelRegistry; this union trades cross-family consistency for that
+ * shared-state-preserving switch.
+ */
+export interface ChannelDefinition {
+  parameters: Parameter[];
+}
+
+export const CHANNEL_DEFINITION: ChannelDefinition = {
+  parameters: [
+    {
+      id: "type",
+      label: "Type",
+      description: "Channel type",
+      type: "selection",
+      default: "GPIOIN",
+      options: ALL_CHANNEL_TYPES.map((t) => ({ value: t, label: t })),
+    },
+    {
+      id: "bias",
+      label: "Bias",
+      description: "Pin bias configuration",
+      type: "selection",
+      default: "none",
+      options: [
+        { value: "none", label: "None" },
+        { value: "pullup", label: "Pull-up" },
+        { value: "pulldown", label: "Pull-down" },
+      ],
+      activationRules: [{ type: "parameterIn", parameterId: "type", values: ["GPIOIN"] }],
+    },
+    {
+      id: "debounceMs",
+      label: "Debounce (ms)",
+      description: "Debounce window in milliseconds",
+      type: "int",
+      default: 50,
+      activationRules: [{ type: "parameterIn", parameterId: "type", values: ["GPIOIN"] }],
+    },
+    {
+      id: "frequency",
+      label: "Frequency (Hz)",
+      description: "PWM frequency in Hz",
+      type: "int",
+      default: 1000,
+      activationRules: [{ type: "parameterIn", parameterId: "type", values: ["PWM"] }],
+    },
+    {
+      id: "topic",
+      label: "Topic",
+      description: "MQTT topic this channel publishes to / subscribes on (e.g. sensors/temperature)",
+      type: "string",
+      activationRules: [{ type: "parameterIn", parameterId: "type", values: ["MQTT"] }],
+    },
+  ],
+};

package/src/channel/index.ts

@@ -0,0 +1,6 @@
+export type { ChannelType, Channel } from "./Channel";
+export { ALL_CHANNEL_TYPES } from "./Channel";
+export type { ChannelDefinition } from "./ChannelDefinition";
+export { CHANNEL_DEFINITION } from "./ChannelDefinition";
+export { serialize, deserialize } from "./serialization";
+export type { ApiChannel } from "./serialization";

package/src/channel/serialization.ts

@@ -0,0 +1,68 @@
+import type { Schemas } from "../api";
+import { pruneArguments } from "../parameter";
+import { CHANNEL_DEFINITION } from "./ChannelDefinition";
+import type { Channel } from "./Channel";
+
+export type ApiChannel = Schemas["Channel"];
+
+/**
+ * Serialize a domain Channel to the API discriminated-union shape.
+ *
+ * The domain store retains inactive parameters (non-destructive type switching),
+ * so this is the boundary that drops them. The `type` discriminator must be in
+ * the args record so `parameterIn` rules can evaluate — otherwise every gated
+ * field (bias/debounceMs/frequency) is stripped as "inactive". Physical
+ * addressing (GPIO line, ADC/PWM/DAC channel) is not here — it's a deploy
+ * binding, not workflow state.
+ */
+export function serialize(ch: Channel): ApiChannel {
+  const { id, label, type } = ch;
+  const args: Record<string, unknown> = { ...ch.arguments, type };
+  pruneArguments(args, CHANNEL_DEFINITION.parameters);
+  switch (type) {
+    case "GPIOIN":
+      return {
+        type,
+        id,
+        label,
+        bias: args.bias as Schemas["GPIOINChannel"]["bias"],
+        debounceMs: args.debounceMs as number,
+      };
+    case "GPIOOUT":
+      return { type, id, label };
+    case "ADC":
+      return { type, id, label };
+    case "PWM":
+      return { type, id, label, frequency: args.frequency as number };
+    case "DAC":
+      return { type, id, label };
+    case "UART":
+      return { type, id, label };
+    case "MQTT":
+      return { type, id, label, topic: args.topic as string };
+  }
+}
+
+/** Convert an API Channel into a domain Channel. */
+export function deserialize(api: ApiChannel): Channel {
+  const { id, label, type } = api;
+  const args: Record<string, unknown> = {};
+  switch (type) {
+    case "GPIOIN":
+      args.bias = api.bias;
+      args.debounceMs = api.debounceMs;
+      break;
+    case "PWM":
+      args.frequency = api.frequency;
+      break;
+    case "MQTT":
+      args.topic = api.topic;
+      break;
+    case "GPIOOUT":
+    case "ADC":
+    case "DAC":
+    case "UART":
+      break;
+  }
+  return { id, label, type, arguments: args };
+}

package/src/deploy/index.ts

@@ -0,0 +1 @@
+export { getReferencedCatalogModelIds } from "./requirements";

package/src/deploy/requirements.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+import { getReferencedCatalogModelIds } from "./requirements";
+import { MAIN_CANVAS_ID, type Workflow, type Canvas } from "../workflow";
+import type { Node } from "../node";
+import type { Model } from "../model";
+
+// Minimal Agent node referencing `model`. Cast through the union — only id/type/
+// arguments.model matter to the walk.
+function agent(id: string, model: string): Node {
+  return {
+    id,
+    type: "Agent",
+    position: { x: 0, y: 0 },
+    arguments: {
+      name: id,
+      model,
+      instructions: "",
+      outputDeclarations: [],
+      memoryRefs: [],
+      answer: { active: true, mode: "emit", name: "answer" },
+    },
+  } as Node;
+}
+
+function canvas(nodes: Node[]): Canvas {
+  return { nodes, edges: [], variables: {} };
+}
+
+const customModel: Model = { id: "custom-llm", label: "Custom", type: "LLMModel", arguments: {} };
+
+function workflow(canvases: Workflow["canvases"], models: Record<string, Model> = {}): Workflow {
+  return { canvases, functions: {}, channels: {}, memory: {}, models };
+}
+
+describe("getReferencedCatalogModelIds", () => {
+  it("returns catalog ids (referenced but not declared), excluding declared customs", () => {
+    const wf = workflow(
+      { [MAIN_CANVAS_ID]: canvas([agent("n1", "claude-opus-4-7"), agent("n2", "custom-llm")]) },
+      { "custom-llm": customModel },
+    );
+    expect(getReferencedCatalogModelIds(wf)).toEqual(["claude-opus-4-7"]);
+  });
+
+  it("ignores unset model references", () => {
+    const wf = workflow({ [MAIN_CANVAS_ID]: canvas([agent("n1", "")]) });
+    expect(getReferencedCatalogModelIds(wf)).toEqual([]);
+  });
+
+  it("dedupes across nodes and walks every canvas (main + function bodies)", () => {
+    const wf = workflow({
+      [MAIN_CANVAS_ID]: canvas([agent("n1", "claude-opus-4-7"), agent("n2", "claude-opus-4-7")]),
+      fnBody: canvas([agent("n3", "gemini-2")]),
+    });
+    expect(getReferencedCatalogModelIds(wf).sort()).toEqual(["claude-opus-4-7", "gemini-2"]);
+  });
+
+  it("returns nothing when every referenced model is declared", () => {
+    const wf = workflow({ [MAIN_CANVAS_ID]: canvas([agent("n1", "custom-llm")]) }, { "custom-llm": customModel });
+    expect(getReferencedCatalogModelIds(wf)).toEqual([]);
+  });
+});

package/src/deploy/requirements.ts

@@ -0,0 +1,41 @@
+import type { Workflow } from "../workflow";
+import { NodeRegistry, isNodeUsedAsTool } from "../node";
+import { isParameterActive } from "../parameter";
+
+/**
+ * Model ids that nodes reference but the workflow does not declare in `models`.
+ * A `modelSelect` accepts exactly two sources — declared custom models and the
+ * static catalog — so any referenced id that isn't a declared model is a catalog
+ * model: it carries no declared config, yet still needs a provider/credential
+ * supplied at deploy.
+ *
+ * This is the one deploy demand the workflow's resource arrays can't express:
+ * channels/memory/declared-models are enumerable directly from
+ * `workflow.{channels,memory,models}`, but catalog model ids live only on the
+ * nodes that pick them — hence the walk. Spans every canvas (main + function
+ * bodies) and honors parameter activation, so a model behind an inactive
+ * `modelSelect` (pruned on serialize, never deployed) is not counted.
+ */
+export function getReferencedCatalogModelIds(workflow: Workflow): string[] {
+  const declaredModel = new Set(Object.keys(workflow.models));
+  const catalogIds = new Set<string>();
+
+  for (const canvas of Object.values(workflow.canvases)) {
+    for (const node of canvas.nodes) {
+      const def = NodeRegistry.getByType(node.type);
+      if (!def) continue;
+      const args = node.arguments as Record<string, unknown>;
+      const isToolInput = isNodeUsedAsTool(node.id, node, canvas.edges);
+      for (const param of def.parameters) {
+        if (param.type !== "modelSelect") continue;
+        if (!isParameterActive(param, args, isToolInput)) continue;
+        const id = args[param.id];
+        if (typeof id === "string" && id !== "" && !declaredModel.has(id)) {
+          catalogIds.add(id);
+        }
+      }
+    }
+  }
+
+  return [...catalogIds];
+}

package/src/diagnostics/__fixtures__/diagnosticFixtures.ts

@@ -0,0 +1,158 @@
+import type { Edge } from "../../edge";
+import type { NodeDefinition, NodeData } from "../../node";
+import type { DataType, Expression, Reference } from "../../api";
+import type { Channel } from "../../channel";
+import type { Memory } from "../../memory";
+import { NodeCategory } from "../../node";
+import type { Variable, DeclaredVariable, NodeOutputVariable } from "../../variable";
+import type { Diagnostic, DiagnosticCategory } from "../diagnostics";
+
+// ============================================================================
+// Variable builders
+// ============================================================================
+
+export function makeDeclaredVar(overrides: Partial<DeclaredVariable> = {}): Variable {
+  return {
+    kind: "declared",
+    uid: "v1",
+    name: "count",
+    dataType: "int" as DataType,
+    ...overrides,
+  };
+}
+
+export function makeNodeOutputVar(overrides: Partial<NodeOutputVariable> = {}): Variable {
+  return {
+    kind: "node",
+    nodeId: "n1",
+    outputId: "output",
+    name: "result",
+    dataType: "int" as DataType,
+    ...overrides,
+  };
+}
+
+/** Build an `availableVariables` map from a list of `AvailableVariable` entries. */
+export function makeAvailableVars(vars: Variable[]): Record<string, Variable> {
+  const map: Record<string, Variable> = {};
+  for (const v of vars) {
+    const key = v.kind === "declared" ? `declared:${v.uid}` : v.kind === "fnarg" ? `fnarg:${v.uid}` : `${v.nodeId}:${v.outputId}`;
+    map[key] = v;
+  }
+  return map;
+}
+
+// ============================================================================
+// Expression / Reference builders
+// ============================================================================
+
+export function makeExpression(expression: string, dataType: DataType = "int", references: Reference[] = []): Expression {
+  return { expression, references, dataType };
+}
+
+export function makeDeclaredRef(uid: string): Reference {
+  return { srcId: "declared", varId: uid };
+}
+
+// ============================================================================
+// Edge builder
+// ============================================================================
+
+export function makeEdge(
+  id: string,
+  source: string,
+  sourceHandle: string,
+  target: string,
+  targetHandle: string,
+  overrides: Partial<Edge> = {},
+): Edge {
+  return {
+    id,
+    source,
+    sourceHandle,
+    target,
+    targetHandle,
+    type: "control",
+    ...overrides,
+  };
+}
+
+// ============================================================================
+// Channel builders
+// ============================================================================
+
+export function makeChannel(overrides: Partial<Channel> = {}): Channel {
+  return {
+    id: "ch1",
+    label: "GPIO 4",
+    type: "GPIOIN",
+    arguments: {},
+    ...overrides,
+  };
+}
+
+export function makeChannels(channels: Channel[]): Record<string, Channel> {
+  const map: Record<string, Channel> = {};
+  for (const v of channels) map[v.id] = v;
+  return map;
+}
+
+// ============================================================================
+// Memory builders
+// ============================================================================
+
+export function makeMemory(overrides: Partial<Memory> = {}): Memory {
+  return {
+    id: "mem1",
+    label: "memory1",
+    type: "MemoryFile",
+    arguments: {},
+    ...overrides,
+  };
+}
+
+export function makeMemories(memories: Memory[]): Record<string, Memory> {
+  const map: Record<string, Memory> = {};
+  for (const m of memories) map[m.id] = m;
+  return map;
+}
+
+// ============================================================================
+// Node instance builder — untyped escape hatch
+// ============================================================================
+
+/**
+ * Build a minimal NodeData. Tests assert against the shape `computeNodeDiagnostics`
+ * sees (arguments record + type discriminator), not against the strict per-type shapes,
+ * so we widen to `NodeData` via unknown at the boundary.
+ */
+export function makeNode(type: string, args: Record<string, unknown>, overrides: Record<string, unknown> = {}): NodeData {
+  return { id: "n1", type, arguments: args, ...overrides } as unknown as NodeData;
+}
+
+// ============================================================================
+// Synthetic NodeDefinition builder
+// ============================================================================
+
+export function makeNodeDef(overrides: Partial<NodeDefinition> = {}): NodeDefinition {
+  return {
+    type: "Synthetic" as NodeDefinition["type"],
+    label: "Synthetic Node",
+    category: NodeCategory.Input,
+    description: "Synthetic node used only in tests",
+    parameters: [],
+    ...overrides,
+  };
+}
+
+// ============================================================================
+// Diagnostic assertion helpers
+// ============================================================================
+
+export function diagsOfCategory(diags: Diagnostic[], category: DiagnosticCategory): Diagnostic[] {
+  return diags.filter((d) => d.category === category);
+}
+
+export function hasDiag(diags: Diagnostic[], predicate: (d: Diagnostic) => boolean): boolean {
+  return diags.some(predicate);
+}