@foresthubai/workflow-core 0.3.0 → 0.4.0

package/src/channel/Channel.ts

@@ -1,11 +1,11 @@
-export type ChannelType = "GPIOIN" | "GPIOOUT" | "ADC" | "PWM" | "DAC" | "UART" | "MQTT";
-
-export const ALL_CHANNEL_TYPES: ChannelType[] = ["GPIOIN", "GPIOOUT", "ADC", "PWM", "DAC", "UART", "MQTT"];
-
-/** Interface for a channel instance in the workflow */
-export interface Channel {
-  id: string;
-  label: string;
-  type: ChannelType;
-  arguments: Record<string, unknown>;
-}
+export type ChannelType = "GPIOIN" | "GPIOOUT" | "ADC" | "PWM" | "DAC" | "UART" | "MQTT";
+
+export const ALL_CHANNEL_TYPES: ChannelType[] = ["GPIOIN", "GPIOOUT", "ADC", "PWM", "DAC", "UART", "MQTT"];
+
+/** Interface for a channel instance in the workflow */
+export interface Channel {
+  id: string;
+  label: string;
+  type: ChannelType;
+  arguments: Record<string, unknown>;
+}

package/src/channel/ChannelDefinition.ts

@@ -1,76 +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"] }],
-    },
-  ],
-};
+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

@@ -1,6 +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";
+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

@@ -1,68 +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 };
-}
+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

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

package/src/deploy/requirements.test.ts

@@ -1,61 +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([]);
-  });
-});
+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

@@ -1,41 +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];
-}
+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];
+}