@foresthubai/workflow-builder 0.4.3 → 0.4.5

package/src/utils/migrateFunctionNodes.ts

@@ -1,107 +1,111 @@
-import type { OutputBinding, FunctionCallNode } from "@foresthubai/workflow-core/node";
-import type { Expression } from "@foresthubai/workflow-core";
-import { toast } from "../hooks/use-toast";
-import i18n from "../i18n";
-import { getAllCanvasStores } from "../stores/canvasStore";
-import { useEditorStore } from "../stores/editorStore";
-import { toFunctionInfo, type FunctionInfo } from "@foresthubai/workflow-core/function";
-import { paramKey } from "@foresthubai/workflow-core/variable";
-import { updateNodeInStore } from "./graphOperations";
-
-// ============================================================================
-// Single-Node Migration — builds the update payload for updateNodeInStore
-// ============================================================================
-
-function buildMigrationUpdate(
-  node: FunctionCallNode,
-  latest: FunctionInfo,
-): { arguments: Record<string, unknown>; functionInfo: FunctionInfo } {
-  const oldArgs = node.arguments;
-  const newArgs: Record<string, Expression | OutputBinding> = {};
-
-  // Preserve existing input expressions where uid matches; default empty otherwise.
-  // Always update dataType to match the latest function definition.
-  for (const arg of latest.arguments) {
-    const key = paramKey(arg);
-    const existing = oldArgs[key] as Expression | undefined;
-    newArgs[key] = existing ? { ...existing, dataType: arg.dataType } : { expression: "", references: [], dataType: arg.dataType };
-  }
-
-  // Preserve existing output bindings where uid matches; default emit for new returns.
-  for (const ret of latest.returns) {
-    const key = paramKey(ret);
-    const existing = oldArgs[key] as OutputBinding | undefined;
-    newArgs[key] = existing ?? { active: true, mode: "emit", name: ret.name };
-  }
-
-  return {
-    functionInfo: { ...latest },
-    arguments: newArgs,
-  };
-}
-
-// ============================================================================
-// All-Canvas Migration
-// ============================================================================
-
-/**
- * Iterate all canvas stores and migrate any stale FunctionCallNodes
- * to match the latest function definitions.
- *
- * Does NOT create undo history entries — migration is automatic and transparent.
- * Uses updateNodeInStore for proper store reactivity.
- */
-export function migrateFunctionCallNodes(): void {
-  const allStores = getAllCanvasStores();
-
-  // Latest call-site signatures come from the project-scoped declarations, projected
-  // to the flat snapshot form a FunctionCall stores (expressions dropped).
-  const latestFunctions: Record<string, FunctionInfo> = {};
-  for (const [id, def] of Object.entries(useEditorStore.getState().functions)) {
-    latestFunctions[id] = toFunctionInfo(def);
-  }
-
-  // Iterate all canvases and migrate stale FunctionCallNodes
-  let totalMigrated = 0;
-
-  for (const [, store] of Object.entries(allStores)) {
-    const nodes = store.getState().nodes;
-
-    for (const node of nodes) {
-      if (node.data.type !== "FunctionCall") continue;
-
-      const fnNode = node.data as FunctionCallNode;
-      const latest = latestFunctions[fnNode.functionInfo.id];
-      if (!latest) continue;
-
-      // Check if migration is needed (version or name change)
-      if (fnNode.functionInfo.version === latest.version && fnNode.functionInfo.name === latest.name) {
-        continue;
-      }
-
-      updateNodeInStore(store, node.id, buildMigrationUpdate(fnNode, latest));
-      totalMigrated++;
-    }
-  }
-
-  if (totalMigrated > 0) {
-    toast({
-      title: i18n.t("functionCallNodesMigrated"),
-      description: i18n.t("functionCallNodesMigratedDesc", { count: totalMigrated }),
-    });
-  }
-}
-
-// ============================================================================
-// Module-Level Subscription
-// ============================================================================
-
-// Automatically migrate FunctionCallNodes whenever a function declaration changes.
-// Declarations are non-undo-tracked editorStore edits, so this is a forward-only
-// reconcile — no undo can revert a definition out from under its call sites.
-let prevFunctions = useEditorStore.getState().functions;
-useEditorStore.subscribe((state) => {
-  if (state.functions === prevFunctions) return;
-  prevFunctions = state.functions;
-  migrateFunctionCallNodes();
-});
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 ForestHub. All rights reserved.
+// For commercial licensing, contact root@foresthub.ai
+
+import type { OutputBinding, FunctionCallNode } from "@foresthubai/workflow-core/node";
+import type { Expression } from "@foresthubai/workflow-core";
+import { toast } from "../hooks/use-toast";
+import i18n from "../i18n";
+import { getAllCanvasStores } from "../stores/canvasStore";
+import { useEditorStore } from "../stores/editorStore";
+import { toFunctionInfo, type FunctionInfo } from "@foresthubai/workflow-core/function";
+import { paramKey } from "@foresthubai/workflow-core/variable";
+import { updateNodeInStore } from "./graphOperations";
+
+// ============================================================================
+// Single-Node Migration — builds the update payload for updateNodeInStore
+// ============================================================================
+
+function buildMigrationUpdate(
+  node: FunctionCallNode,
+  latest: FunctionInfo,
+): { arguments: Record<string, unknown>; functionInfo: FunctionInfo } {
+  const oldArgs = node.arguments;
+  const newArgs: Record<string, Expression | OutputBinding> = {};
+
+  // Preserve existing input expressions where uid matches; default empty otherwise.
+  // Always update dataType to match the latest function definition.
+  for (const arg of latest.arguments) {
+    const key = paramKey(arg);
+    const existing = oldArgs[key] as Expression | undefined;
+    newArgs[key] = existing ? { ...existing, dataType: arg.dataType } : { expression: "", references: [], dataType: arg.dataType };
+  }
+
+  // Preserve existing output bindings where uid matches; default emit for new returns.
+  for (const ret of latest.returns) {
+    const key = paramKey(ret);
+    const existing = oldArgs[key] as OutputBinding | undefined;
+    newArgs[key] = existing ?? { active: true, mode: "emit", name: ret.name };
+  }
+
+  return {
+    functionInfo: { ...latest },
+    arguments: newArgs,
+  };
+}
+
+// ============================================================================
+// All-Canvas Migration
+// ============================================================================
+
+/**
+ * Iterate all canvas stores and migrate any stale FunctionCallNodes
+ * to match the latest function definitions.
+ *
+ * Does NOT create undo history entries — migration is automatic and transparent.
+ * Uses updateNodeInStore for proper store reactivity.
+ */
+export function migrateFunctionCallNodes(): void {
+  const allStores = getAllCanvasStores();
+
+  // Latest call-site signatures come from the project-scoped declarations, projected
+  // to the flat snapshot form a FunctionCall stores (expressions dropped).
+  const latestFunctions: Record<string, FunctionInfo> = {};
+  for (const [id, def] of Object.entries(useEditorStore.getState().functions)) {
+    latestFunctions[id] = toFunctionInfo(def);
+  }
+
+  // Iterate all canvases and migrate stale FunctionCallNodes
+  let totalMigrated = 0;
+
+  for (const [, store] of Object.entries(allStores)) {
+    const nodes = store.getState().nodes;
+
+    for (const node of nodes) {
+      if (node.data.type !== "FunctionCall") continue;
+
+      const fnNode = node.data as FunctionCallNode;
+      const latest = latestFunctions[fnNode.functionInfo.id];
+      if (!latest) continue;
+
+      // Check if migration is needed (version or name change)
+      if (fnNode.functionInfo.version === latest.version && fnNode.functionInfo.name === latest.name) {
+        continue;
+      }
+
+      updateNodeInStore(store, node.id, buildMigrationUpdate(fnNode, latest));
+      totalMigrated++;
+    }
+  }
+
+  if (totalMigrated > 0) {
+    toast({
+      title: i18n.t("functionCallNodesMigrated"),
+      description: i18n.t("functionCallNodesMigratedDesc", { count: totalMigrated }),
+    });
+  }
+}
+
+// ============================================================================
+// Module-Level Subscription
+// ============================================================================
+
+// Automatically migrate FunctionCallNodes whenever a function declaration changes.
+// Declarations are non-undo-tracked editorStore edits, so this is a forward-only
+// reconcile — no undo can revert a definition out from under its call sites.
+let prevFunctions = useEditorStore.getState().functions;
+useEditorStore.subscribe((state) => {
+  if (state.functions === prevFunctions) return;
+  prevFunctions = state.functions;
+  migrateFunctionCallNodes();
+});

package/src/utils/modelOperations.ts

@@ -1,55 +1,59 @@
-import { ModelRegistry, type ModelType, type Model } from "@foresthubai/workflow-core/model";
-import { useEditorStore } from "../stores/editorStore";
-import { generateId } from "@foresthubai/workflow-core/id";
-import { seedDefaultArguments, uniqueName } from "./resourceHelpers";
-
-/** Default label prefix per model type. */
-const LABEL_PREFIX: Record<ModelType, string> = {
-  LLMModel: "model",
-};
-
-/** Create a new declared (custom) model of the given type. Returns the new instance. */
-export function addModel(type: ModelType): Model {
-  const id = generateId();
-  const existing = Object.values(useEditorStore.getState().models).map((m) => m.label);
-  const instance: Model = {
-    id,
-    label: uniqueName(LABEL_PREFIX[type], existing),
-    type,
-    arguments: seedDefaultArguments(ModelRegistry.getByType(type)?.parameters ?? []),
-  };
-  useEditorStore.getState().setModels((models) => ({ ...models, [id]: instance }));
-  return instance;
-}
-
-/**
- * Apply a partial patch to a declared model. Top-level `label` and the
- * `arguments` record merge separately. `type` is fixed at creation.
- */
-export function updateModel(id: string, patch: { label?: string; arguments?: Record<string, unknown> }): void {
-  const key = id;
-  useEditorStore.getState().setModels((models) => {
-    const existing = models[key];
-    if (!existing) return models;
-    return {
-      ...models,
-      [key]: {
-        ...existing,
-        ...(patch.label !== undefined ? { label: patch.label } : {}),
-        ...(patch.arguments ? { arguments: { ...existing.arguments, ...patch.arguments } } : {}),
-      },
-    };
-  });
-}
-
-export function deleteModel(id: string): void {
-  const key = id;
-  useEditorStore.getState().setModels((models) => {
-    const { [key]: _drop, ...rest } = models;
-    return rest;
-  });
-  const sel = useEditorStore.getState().selection;
-  if (sel.kind === "model" && sel.id === id) {
-    useEditorStore.getState().clearSelection();
-  }
-}
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 ForestHub. All rights reserved.
+// For commercial licensing, contact root@foresthub.ai
+
+import { ModelRegistry, type ModelType, type Model } from "@foresthubai/workflow-core/model";
+import { useEditorStore } from "../stores/editorStore";
+import { generateId } from "@foresthubai/workflow-core/id";
+import { seedDefaultArguments, uniqueName } from "./resourceHelpers";
+
+/** Default label prefix per model type. */
+const LABEL_PREFIX: Record<ModelType, string> = {
+  LLMModel: "model",
+};
+
+/** Create a new declared (custom) model of the given type. Returns the new instance. */
+export function addModel(type: ModelType): Model {
+  const id = generateId();
+  const existing = Object.values(useEditorStore.getState().models).map((m) => m.label);
+  const instance: Model = {
+    id,
+    label: uniqueName(LABEL_PREFIX[type], existing),
+    type,
+    arguments: seedDefaultArguments(ModelRegistry.getByType(type)?.parameters ?? []),
+  };
+  useEditorStore.getState().setModels((models) => ({ ...models, [id]: instance }));
+  return instance;
+}
+
+/**
+ * Apply a partial patch to a declared model. Top-level `label` and the
+ * `arguments` record merge separately. `type` is fixed at creation.
+ */
+export function updateModel(id: string, patch: { label?: string; arguments?: Record<string, unknown> }): void {
+  const key = id;
+  useEditorStore.getState().setModels((models) => {
+    const existing = models[key];
+    if (!existing) return models;
+    return {
+      ...models,
+      [key]: {
+        ...existing,
+        ...(patch.label !== undefined ? { label: patch.label } : {}),
+        ...(patch.arguments ? { arguments: { ...existing.arguments, ...patch.arguments } } : {}),
+      },
+    };
+  });
+}
+
+export function deleteModel(id: string): void {
+  const key = id;
+  useEditorStore.getState().setModels((models) => {
+    const { [key]: _drop, ...rest } = models;
+    return rest;
+  });
+  const sel = useEditorStore.getState().selection;
+  if (sel.kind === "model" && sel.id === id) {
+    useEditorStore.getState().clearSelection();
+  }
+}

package/src/utils/paramDisplay.ts

@@ -1,71 +1,75 @@
-// Presentation-only formatters for inline node display. These render domain
-// values to human-readable text; they live in the builder (not headless
-// workflow-core) because formatting for display is an editor concern.
-import type { Parameter } from "@foresthubai/workflow-core/parameter";
-import type { Reference } from "@foresthubai/workflow-core";
-import { refToLookupKey, type Variable } from "@foresthubai/workflow-core/variable";
-import type { ResolvedExpr } from "@foresthubai/workflow-core/expression";
-
-export interface ParamDisplayResult {
-  text: string;
-  isInvalid?: boolean;
-}
-
-/** Format a non-expression parameter value for inline display on the node. */
-export function formatParamDisplay(
-  param: Parameter,
-  value: unknown,
-  variables: Record<string, Variable>,
-  channelLabels?: Record<string, string>,
-  memoryLabels?: Record<string, string>,
-  modelLabels?: Record<string, string>,
-): ParamDisplayResult {
-  switch (param.type) {
-    case "variableSelect": {
-      const ref = value as Reference | undefined;
-      if (!ref?.varId) return { text: "" };
-      const v = variables[refToLookupKey(ref)];
-      return v ? { text: v.name } : { text: "unknown", isInvalid: true };
-    }
-    case "bool":
-      return { text: (value as boolean) ? "true" : "false" };
-    case "weekdays": {
-      const days = value as string[] | undefined;
-      return { text: !days?.length ? "every day" : days.join(", ") };
-    }
-    case "selection": {
-      const option = param.options.find((o) => o.value === value);
-      return { text: option?.label ?? String(value ?? "") };
-    }
-    case "memorySelect": {
-      const memoryId = value as string | undefined;
-      if (!memoryId) return { text: "" };
-      return memoryLabels?.[memoryId] ? { text: memoryLabels[memoryId] } : { text: "unknown", isInvalid: true };
-    }
-    case "channelSelect": {
-      const channelId = value as string | undefined;
-      if (!channelId) return { text: "" };
-      return channelLabels?.[channelId] ? { text: channelLabels[channelId] } : { text: "unknown", isInvalid: true };
-    }
-    case "modelSelect": {
-      // A ModelID is human-meaningful (e.g. "claude-opus-4-7"); show the catalog/
-      // custom label when known, otherwise the id itself. Staleness is surfaced
-      // by diagnostics, not inline, since the catalog isn't available headlessly.
-      const modelId = value as string | undefined;
-      if (!modelId) return { text: "" };
-      return { text: modelLabels?.[modelId] ?? modelId };
-    }
-    default:
-      return { text: String(value ?? "") };
-  }
-}
-
-/** Format an expression for display by replacing variable-reference placeholders with their names. */
-export function displayValue(expr: ResolvedExpr): string {
-  let result = expr.expression;
-  // Replace each variable reference placeholder with its name
-  expr.variables.forEach((variable) => {
-    result = result.replace(/\$\{\}/, variable?.name || "unknown");
-  });
-  return result;
-}
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 ForestHub. All rights reserved.
+// For commercial licensing, contact root@foresthub.ai
+
+// Presentation-only formatters for inline node display. These render domain
+// values to human-readable text; they live in the builder (not headless
+// workflow-core) because formatting for display is an editor concern.
+import type { Parameter } from "@foresthubai/workflow-core/parameter";
+import type { Reference } from "@foresthubai/workflow-core";
+import { refToLookupKey, type Variable } from "@foresthubai/workflow-core/variable";
+import type { ResolvedExpr } from "@foresthubai/workflow-core/expression";
+
+export interface ParamDisplayResult {
+  text: string;
+  isInvalid?: boolean;
+}
+
+/** Format a non-expression parameter value for inline display on the node. */
+export function formatParamDisplay(
+  param: Parameter,
+  value: unknown,
+  variables: Record<string, Variable>,
+  channelLabels?: Record<string, string>,
+  memoryLabels?: Record<string, string>,
+  modelLabels?: Record<string, string>,
+): ParamDisplayResult {
+  switch (param.type) {
+    case "variableSelect": {
+      const ref = value as Reference | undefined;
+      if (!ref?.varId) return { text: "" };
+      const v = variables[refToLookupKey(ref)];
+      return v ? { text: v.name } : { text: "unknown", isInvalid: true };
+    }
+    case "bool":
+      return { text: (value as boolean) ? "true" : "false" };
+    case "weekdays": {
+      const days = value as string[] | undefined;
+      return { text: !days?.length ? "every day" : days.join(", ") };
+    }
+    case "selection": {
+      const option = param.options.find((o) => o.value === value);
+      return { text: option?.label ?? String(value ?? "") };
+    }
+    case "memorySelect": {
+      const memoryId = value as string | undefined;
+      if (!memoryId) return { text: "" };
+      return memoryLabels?.[memoryId] ? { text: memoryLabels[memoryId] } : { text: "unknown", isInvalid: true };
+    }
+    case "channelSelect": {
+      const channelId = value as string | undefined;
+      if (!channelId) return { text: "" };
+      return channelLabels?.[channelId] ? { text: channelLabels[channelId] } : { text: "unknown", isInvalid: true };
+    }
+    case "modelSelect": {
+      // A ModelID is human-meaningful (e.g. "claude-opus-4-7"); show the catalog/
+      // custom label when known, otherwise the id itself. Staleness is surfaced
+      // by diagnostics, not inline, since the catalog isn't available headlessly.
+      const modelId = value as string | undefined;
+      if (!modelId) return { text: "" };
+      return { text: modelLabels?.[modelId] ?? modelId };
+    }
+    default:
+      return { text: String(value ?? "") };
+  }
+}
+
+/** Format an expression for display by replacing variable-reference placeholders with their names. */
+export function displayValue(expr: ResolvedExpr): string {
+  let result = expr.expression;
+  // Replace each variable reference placeholder with its name
+  expr.variables.forEach((variable) => {
+    result = result.replace(/\$\{\}/, variable?.name || "unknown");
+  });
+  return result;
+}

package/src/utils/resourceHelpers.ts

@@ -1,32 +1,36 @@
-import type { Parameter } from "@foresthubai/workflow-core/parameter";
-
-/**
- * Build the initial `arguments` record for a new resource instance: each
- * parameter that declares a `default` gets seeded. Defaults are `structuredClone`d
- * so two instances never share a mutable reference (objects/arrays).
- *
- * Shared by the registry-backed project primitives (memory, model). Channels
- * have conditional, activation-rule parameters and seed inside `channelOperations`
- * instead.
- */
-export function seedDefaultArguments(params: Parameter[]): Record<string, unknown> {
-  const args: Record<string, unknown> = {};
-  for (const param of params) {
-    if ("default" in param && param.default !== undefined) {
-      args[param.id] = structuredClone(param.default);
-    }
-  }
-  return args;
-}
-
-/**
- * Return `desired` if it's free, otherwise append 2, 3, 4… until the result
- * doesn't collide with `existing`.
- */
-export function uniqueName(desired: string, existing: Iterable<string>): string {
-  const taken = existing instanceof Set ? existing : new Set(existing);
-  if (!taken.has(desired)) return desired;
-  let i = 2;
-  while (taken.has(`${desired}${i}`)) i++;
-  return `${desired}${i}`;
-}
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 ForestHub. All rights reserved.
+// For commercial licensing, contact root@foresthub.ai
+
+import type { Parameter } from "@foresthubai/workflow-core/parameter";
+
+/**
+ * Build the initial `arguments` record for a new resource instance: each
+ * parameter that declares a `default` gets seeded. Defaults are `structuredClone`d
+ * so two instances never share a mutable reference (objects/arrays).
+ *
+ * Shared by the registry-backed project primitives (memory, model). Channels
+ * have conditional, activation-rule parameters and seed inside `channelOperations`
+ * instead.
+ */
+export function seedDefaultArguments(params: Parameter[]): Record<string, unknown> {
+  const args: Record<string, unknown> = {};
+  for (const param of params) {
+    if ("default" in param && param.default !== undefined) {
+      args[param.id] = structuredClone(param.default);
+    }
+  }
+  return args;
+}
+
+/**
+ * Return `desired` if it's free, otherwise append 2, 3, 4… until the result
+ * doesn't collide with `existing`.
+ */
+export function uniqueName(desired: string, existing: Iterable<string>): string {
+  const taken = existing instanceof Set ? existing : new Set(existing);
+  if (!taken.has(desired)) return desired;
+  let i = 2;
+  while (taken.has(`${desired}${i}`)) i++;
+  return `${desired}${i}`;
+}

package/src/utils/translation.ts

@@ -1,28 +1,32 @@
-import type { TFunction } from "i18next";
-import type { NodeDefinition } from "@foresthubai/workflow-core/node";
-import type { Parameter } from "@foresthubai/workflow-core/parameter";
-
-/**
- * Convention-based i18n helpers for description strings only.
- *
- * Keys follow the pattern:
- *   nodes.<NodeType>.description
- *   edges.<EdgeType>.description
- *   <prefix>.params.<paramId>.description
- *
- * Labels, categories, port names, and option labels stay as raw English code values.
- * Only natural-language descriptions are translated.
- */
-
-export function getNodeDescription(t: TFunction, def: NodeDefinition): string {
-  return t(`nodes.${def.type}.description`, { defaultValue: def.description });
-}
-
-export function getParamDescription(t: TFunction, translationPrefix: string, param: Parameter): string {
-  if (!param.description) return "";
-  return t(`${translationPrefix}.params.${param.id}.description`, { defaultValue: param.description });
-}
-
-export function getEdgeDescription(t: TFunction, def: { description: string }, portType: string): string {
-  return t(`edges.${portType}.description`, { defaultValue: def.description });
-}
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 ForestHub. All rights reserved.
+// For commercial licensing, contact root@foresthub.ai
+
+import type { TFunction } from "i18next";
+import type { NodeDefinition } from "@foresthubai/workflow-core/node";
+import type { Parameter } from "@foresthubai/workflow-core/parameter";
+
+/**
+ * Convention-based i18n helpers for description strings only.
+ *
+ * Keys follow the pattern:
+ *   nodes.<NodeType>.description
+ *   edges.<EdgeType>.description
+ *   <prefix>.params.<paramId>.description
+ *
+ * Labels, categories, port names, and option labels stay as raw English code values.
+ * Only natural-language descriptions are translated.
+ */
+
+export function getNodeDescription(t: TFunction, def: NodeDefinition): string {
+  return t(`nodes.${def.type}.description`, { defaultValue: def.description });
+}
+
+export function getParamDescription(t: TFunction, translationPrefix: string, param: Parameter): string {
+  if (!param.description) return "";
+  return t(`${translationPrefix}.params.${param.id}.description`, { defaultValue: param.description });
+}
+
+export function getEdgeDescription(t: TFunction, def: { description: string }, portType: string): string {
+  return t(`edges.${portType}.description`, { defaultValue: def.description });
+}