@kiberon-labs/behave-graph-flow 1.0.0 → 3.0.0

package/tests/autoConvert.test.ts

@@ -0,0 +1,329 @@
+import { describe, it, expect } from 'vitest';
+import type { Node, Connection } from 'reactflow';
+import type { NodeSpecJSON } from '@kiberon-labs/behave-graph';
+import {
+  findConverterSpec,
+  resolveConverter,
+  buildConverterInsertion
+} from '../src/util/autoConvert.js';
+
+const specs = [
+  {
+    type: 'src',
+    label: '',
+    category: '',
+    inputs: [],
+    outputs: [{ name: 'out', valueType: 'integer' }]
+  },
+  {
+    type: 'dst',
+    label: '',
+    category: '',
+    inputs: [{ name: 'in', valueType: 'string' }],
+    outputs: []
+  },
+  {
+    type: 'math/toString/integer',
+    label: 'To String',
+    category: 'Logic',
+    inputs: [{ name: 'a', valueType: 'integer' }],
+    outputs: [{ name: 'result', valueType: 'string' }]
+  }
+] as unknown as NodeSpecJSON[];
+
+const node = (id: string, type: string, x: number): Node => ({
+  id,
+  type: 'behaveNode',
+  position: { x, y: 0 },
+  data: { type, configuration: {}, ports: {} } as any
+});
+
+const conn = (
+  source: string,
+  sourceHandle: string,
+  target: string,
+  targetHandle: string
+): Connection => ({ source, sourceHandle, target, targetHandle });
+
+describe('findConverterSpec', () => {
+  it('finds a single-in/single-out converter for the type pair', () => {
+    expect(findConverterSpec(specs, 'integer', 'string')?.type).toBe(
+      'math/toString/integer'
+    );
+  });
+
+  it('ignores nodes that have flow sockets', () => {
+    const flowNode = [
+      {
+        type: 'fn',
+        inputs: [
+          { name: 'flow', valueType: 'flow' },
+          { name: 'a', valueType: 'integer' }
+        ],
+        outputs: [{ name: 'result', valueType: 'string' }]
+      }
+    ] as unknown as NodeSpecJSON[];
+    expect(findConverterSpec(flowNode, 'integer', 'string')).toBeUndefined();
+  });
+
+  it('returns undefined when no converter exists', () => {
+    expect(findConverterSpec(specs, 'string', 'boolean')).toBeUndefined();
+  });
+});
+
+describe('resolveConverter (configurable rules)', () => {
+  const customSpecs = [
+    ...specs,
+    {
+      type: 'custom/intToStr',
+      inputs: [{ name: 'x', valueType: 'integer' }],
+      outputs: [{ name: 'y', valueType: 'string' }]
+    }
+  ] as unknown as NodeSpecJSON[];
+
+  it('prefers a registered custom rule over the spec heuristic', () => {
+    const rules = [
+      { from: 'integer', to: 'string', nodeType: 'custom/intToStr' }
+    ];
+    expect(resolveConverter(customSpecs, 'integer', 'string', rules)).toEqual({
+      nodeType: 'custom/intToStr',
+      inputName: 'x',
+      outputName: 'y'
+    });
+  });
+
+  it('falls back to the spec heuristic when no rule matches', () => {
+    expect(resolveConverter(specs, 'integer', 'string', [])?.nodeType).toBe(
+      'math/toString/integer'
+    );
+  });
+
+  it('honours explicit inputKey/outputKey from the rule', () => {
+    const rules = [
+      {
+        from: 'integer',
+        to: 'string',
+        nodeType: 'whatever',
+        inputKey: 'in',
+        outputKey: 'out'
+      }
+    ];
+    expect(resolveConverter([], 'integer', 'string', rules)).toEqual({
+      nodeType: 'whatever',
+      inputName: 'in',
+      outputName: 'out'
+    });
+  });
+
+  // A converter node with several inputs/outputs (e.g. value + config ports).
+  const multiPortSpecs = [
+    {
+      type: 'multi',
+      inputs: [
+        { name: 'flow', valueType: 'flow' },
+        { name: 'label', valueType: 'string' }, // first non-flow, wrong type
+        { name: 'n', valueType: 'integer' } // the actual source port
+      ],
+      outputs: [
+        { name: 'flag', valueType: 'boolean' }, // first non-flow, wrong type
+        { name: 'text', valueType: 'string' } // the actual target port
+      ]
+    }
+  ] as unknown as NodeSpecJSON[];
+
+  it('resolves a multi-port converter by type when keys are omitted', () => {
+    const rules = [{ from: 'integer', to: 'string', nodeType: 'multi' }];
+    expect(
+      resolveConverter(multiPortSpecs, 'integer', 'string', rules)
+    ).toEqual({ nodeType: 'multi', inputName: 'n', outputName: 'text' });
+  });
+
+  it('honours explicit keys to pick a specific port among several of a type', () => {
+    const twoEachSpecs = [
+      {
+        type: 'multi2',
+        inputs: [
+          { name: 'a', valueType: 'integer' },
+          { name: 'b', valueType: 'integer' }
+        ],
+        outputs: [
+          { name: 'x', valueType: 'string' },
+          { name: 'y', valueType: 'string' }
+        ]
+      }
+    ] as unknown as NodeSpecJSON[];
+    const rules = [
+      {
+        from: 'integer',
+        to: 'string',
+        nodeType: 'multi2',
+        inputKey: 'b',
+        outputKey: 'y'
+      }
+    ];
+    expect(resolveConverter(twoEachSpecs, 'integer', 'string', rules)).toEqual({
+      nodeType: 'multi2',
+      inputName: 'b',
+      outputName: 'y'
+    });
+  });
+});
+
+describe('buildConverterInsertion', () => {
+  const nodes = [node('s', 'src', 0), node('t', 'dst', 100)];
+
+  it('uses a custom conversion rule when provided', () => {
+    const customSpecs = [
+      ...specs,
+      {
+        type: 'custom/intToStr',
+        inputs: [{ name: 'x', valueType: 'integer' }],
+        outputs: [{ name: 'y', valueType: 'string' }]
+      }
+    ] as unknown as NodeSpecJSON[];
+    const insertion = buildConverterInsertion(
+      conn('s', 'out', 't', 'in'),
+      nodes,
+      customSpecs,
+      [{ from: 'integer', to: 'string', nodeType: 'custom/intToStr' }]
+    );
+    expect(insertion!.node.data.type).toBe('custom/intToStr');
+    expect(insertion!.edges[0]!.targetHandle).toBe('x');
+    expect(insertion!.edges[1]!.sourceHandle).toBe('y');
+  });
+
+  it('splices a converter between mismatched-but-convertible sockets', () => {
+    const insertion = buildConverterInsertion(
+      conn('s', 'out', 't', 'in'),
+      nodes,
+      specs
+    );
+    expect(insertion).not.toBeNull();
+    expect(insertion!.node.data.type).toBe('math/toString/integer');
+    expect(insertion!.node.position).toEqual({ x: 50, y: 0 });
+    expect(insertion!.edges).toHaveLength(2);
+    expect(insertion!.edges[0]).toMatchObject({
+      source: 's',
+      sourceHandle: 'out',
+      target: insertion!.node.id,
+      targetHandle: 'a'
+    });
+    expect(insertion!.edges[1]).toMatchObject({
+      source: insertion!.node.id,
+      sourceHandle: 'result',
+      target: 't',
+      targetHandle: 'in'
+    });
+  });
+
+  it('wires the type-matched output port of a multi-output converter', () => {
+    // Converter emits both a boolean and a string; from→to is integer→string,
+    // so the splice must use the `string` output (`text`), not the first output.
+    const multiOutSpecs = [
+      {
+        type: 'src',
+        inputs: [],
+        outputs: [{ name: 'out', valueType: 'integer' }]
+      },
+      {
+        type: 'dst',
+        inputs: [{ name: 'in', valueType: 'string' }],
+        outputs: []
+      },
+      {
+        type: 'multiOut',
+        inputs: [{ name: 'a', valueType: 'integer' }],
+        outputs: [
+          { name: 'flag', valueType: 'boolean' },
+          { name: 'text', valueType: 'string' }
+        ]
+      }
+    ] as unknown as NodeSpecJSON[];
+    const insertion = buildConverterInsertion(
+      conn('s', 'out', 't', 'in'),
+      nodes,
+      multiOutSpecs,
+      [{ from: 'integer', to: 'string', nodeType: 'multiOut' }]
+    );
+    expect(insertion!.node.data.type).toBe('multiOut');
+    expect(insertion!.edges[0]!.targetHandle).toBe('a');
+    // The converter→target edge leaves the string output, not the boolean one.
+    expect(insertion!.edges[1]!.sourceHandle).toBe('text');
+  });
+
+  it('honours an explicit outputKey to pin a specific output port', () => {
+    const twoStrOutSpecs = [
+      {
+        type: 'src',
+        inputs: [],
+        outputs: [{ name: 'out', valueType: 'integer' }]
+      },
+      {
+        type: 'dst',
+        inputs: [{ name: 'in', valueType: 'string' }],
+        outputs: []
+      },
+      {
+        type: 'twoOut',
+        inputs: [{ name: 'a', valueType: 'integer' }],
+        outputs: [
+          { name: 'x', valueType: 'string' },
+          { name: 'y', valueType: 'string' }
+        ]
+      }
+    ] as unknown as NodeSpecJSON[];
+    const insertion = buildConverterInsertion(
+      conn('s', 'out', 't', 'in'),
+      nodes,
+      twoStrOutSpecs,
+      [
+        {
+          from: 'integer',
+          to: 'string',
+          nodeType: 'twoOut',
+          inputKey: 'a',
+          outputKey: 'y'
+        }
+      ]
+    );
+    expect(insertion!.edges[1]!.sourceHandle).toBe('y');
+  });
+
+  it('returns null for same-type connections', () => {
+    const sameSpecs = [
+      {
+        type: 'src',
+        inputs: [],
+        outputs: [{ name: 'out', valueType: 'integer' }]
+      },
+      {
+        type: 'dstI',
+        inputs: [{ name: 'in', valueType: 'integer' }],
+        outputs: []
+      }
+    ] as unknown as NodeSpecJSON[];
+    const ns = [node('s', 'src', 0), node('t', 'dstI', 100)];
+    expect(
+      buildConverterInsertion(conn('s', 'out', 't', 'in'), ns, sameSpecs)
+    ).toBeNull();
+  });
+
+  it('returns null when no converter is available', () => {
+    const noConv = [
+      {
+        type: 'src',
+        inputs: [],
+        outputs: [{ name: 'out', valueType: 'integer' }]
+      },
+      {
+        type: 'dstB',
+        inputs: [{ name: 'in', valueType: 'boolean' }],
+        outputs: []
+      }
+    ] as unknown as NodeSpecJSON[];
+    const ns = [node('s', 'src', 0), node('t', 'dstB', 100)];
+    expect(
+      buildConverterInsertion(conn('s', 'out', 't', 'in'), ns, noConv)
+    ).toBeNull();
+  });
+});

package/tests/autosavePlugin.test.ts

@@ -0,0 +1,204 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  registerCoreProfile,
+  writeNodeSpecsToJSON
+} from '@kiberon-labs/behave-graph';
+import { System } from '../src/system/system.js';
+import type { GraphSession } from '../src/system/graphSession.js';
+import {
+  autosavePlugin,
+  BackupStorage,
+  AUTOSAVE_ENABLED,
+  AUTOSAVE_INTERVAL_SECONDS,
+  AUTOSAVE_MAX_COPIES
+} from '../src/plugin/autosave/index.js';
+import type { BackupController } from '../src/plugin/autosave/index.js';
+
+/** In-memory get/set storage so backups never touch real localStorage. */
+const makeStorage = () => {
+  const backing: Record<string, string> = {};
+  return {
+    backing,
+    adapter: {
+      getItem: (k: string) => backing[k] ?? null,
+      setItem: (k: string, v: string) => {
+        backing[k] = v;
+      }
+    }
+  };
+};
+
+const NODE = (id: string, x = 0, y = 0) => ({
+  id,
+  type: 'behaveNode',
+  position: { x, y },
+  data: {
+    type: 'lifecycle/onStart',
+    configuration: {},
+    ports: {},
+    annotations: {}
+  }
+});
+
+describe('autosave plugin', () => {
+  let system: System;
+  let session: GraphSession;
+  let controller: BackupController;
+  let storage: ReturnType<typeof makeStorage>;
+
+  beforeEach(async () => {
+    vi.useFakeTimers();
+
+    const coreRegistry = registerCoreProfile({
+      nodes: {},
+      values: {},
+      dependencies: {}
+    });
+    const registry = {
+      values: coreRegistry.values,
+      specs: writeNodeSpecsToJSON(coreRegistry)
+    };
+
+    storage = makeStorage();
+    system = new System(registry);
+    await system.registerPlugin(autosavePlugin, {
+      storage: storage.adapter,
+      addMenuItem: false
+    });
+    controller = system.backups as BackupController;
+    session = system.createSession('graph');
+  });
+
+  afterEach(() => {
+    controller.dispose();
+    vi.useRealTimers();
+  });
+
+  const dirty = (nodes = [NODE('a')], edges: any[] = []) => {
+    session.nodeStore.getState().setNodes(nodes);
+    session.edgeStore.getState().setEdges(edges);
+  };
+
+  it('registers the autosave settings and seeds defaults', () => {
+    const keys = system.settingsSchema.getState().settings.map((s) => s.key);
+    expect(keys).toContain(AUTOSAVE_ENABLED);
+    expect(keys).toContain(AUTOSAVE_INTERVAL_SECONDS);
+    expect(keys).toContain(AUTOSAVE_MAX_COPIES);
+    expect(system.getSetting(AUTOSAVE_ENABLED)).toBe(false);
+  });
+
+  it('installs the controller on the system', () => {
+    expect(system.backups).toBeInstanceOf(Object);
+    expect(typeof controller.backupNow).toBe('function');
+  });
+
+  it('captures a forced snapshot of the focused graph', () => {
+    dirty([NODE('a'), NODE('b')]);
+    const snap = controller.backupNow();
+    expect(snap).not.toBeNull();
+    expect(snap?.nodeCount).toBe(2);
+    expect(controller.store.getState().snapshots).toHaveLength(1);
+    // Persisted to storage.
+    expect(new BackupStorage(storage.adapter).listAll()).toHaveLength(1);
+  });
+
+  it('does not capture an empty graph', () => {
+    expect(controller.backupNow()).toBeNull();
+    expect(controller.store.getState().snapshots).toHaveLength(0);
+  });
+
+  it('does not capture an inconsistent graph (edge to missing node)', () => {
+    dirty(
+      [NODE('a')],
+      [
+        {
+          id: 'e',
+          source: 'a',
+          target: 'ghost',
+          sourceHandle: 'f',
+          targetHandle: 'f'
+        }
+      ]
+    );
+    expect(controller.backupNow()).toBeNull();
+    expect(controller.store.getState().snapshots).toHaveLength(0);
+  });
+
+  it('skips a forced capture that duplicates the previous one', () => {
+    dirty([NODE('a')]);
+    expect(controller.backupNow()).not.toBeNull();
+    // No change since the last capture: identical, so skipped.
+    expect(controller.backupNow()).toBeNull();
+    expect(controller.store.getState().snapshots).toHaveLength(1);
+  });
+
+  it('does not capture while suspended', () => {
+    dirty([NODE('a')]);
+    controller.suspend();
+    expect(controller.backupNow()).toBeNull();
+    controller.resume();
+    expect(controller.backupNow()).not.toBeNull();
+  });
+
+  it('runExclusive brackets a region with no capture', () => {
+    dirty([NODE('a')]);
+    const inside = controller.runExclusive(() => controller.backupNow());
+    expect(inside).toBeNull();
+    expect(controller.store.getState().snapshots).toHaveLength(0);
+  });
+
+  it('trims each graph to the max-copies ring', () => {
+    system.setSetting(AUTOSAVE_MAX_COPIES, 3);
+    for (let i = 0; i < 5; i++) {
+      dirty([NODE('a', i, 0)]); // move node so each snapshot differs
+      controller.backupNow();
+    }
+    expect(controller.store.getState().snapshots).toHaveLength(3);
+  });
+
+  it('restores a snapshot into a new tab without touching the source graph', () => {
+    dirty([NODE('a'), NODE('b')]);
+    const snap = controller.backupNow()!;
+    const sessionsBefore = Object.keys(
+      system.activeGraph.getState().sessions
+    ).length;
+
+    const restored = controller.restore(snap.id);
+    expect(restored).toBeDefined();
+    expect(restored!.id).not.toBe(session.id);
+    expect(restored!.nodeStore.getState().nodes).toHaveLength(2);
+    expect(Object.keys(system.activeGraph.getState().sessions).length).toBe(
+      sessionsBefore + 1
+    );
+    // Source graph untouched.
+    expect(session.nodeStore.getState().nodes).toHaveLength(2);
+  });
+
+  it('runs the timer only while enabled and captures dirty, settled graphs', () => {
+    system.setSetting(AUTOSAVE_INTERVAL_SECONDS, 5);
+    system.setSetting(AUTOSAVE_ENABLED, true);
+    expect(controller.store.getState().running).toBe(true);
+
+    dirty([NODE('a')]);
+    // Advance past the interval AND the quiescence window.
+    vi.advanceTimersByTime(6000);
+    expect(controller.store.getState().snapshots).toHaveLength(1);
+
+    system.setSetting(AUTOSAVE_ENABLED, false);
+    expect(controller.store.getState().running).toBe(false);
+  });
+
+  it('deletes a single snapshot and clears all', () => {
+    dirty([NODE('a')]);
+    const snap = controller.backupNow()!;
+    dirty([NODE('a'), NODE('b')]);
+    controller.backupNow();
+    expect(controller.store.getState().snapshots).toHaveLength(2);
+
+    controller.deleteSnapshot(snap.id);
+    expect(controller.store.getState().snapshots).toHaveLength(1);
+
+    controller.clearAll();
+    expect(controller.store.getState().snapshots).toHaveLength(0);
+  });
+});

package/tests/callSubgraphSync.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect } from 'vitest';
+import type { Node } from 'reactflow';
+import {
+  registerCoreProfile,
+  writeNodeSpecsToJSON
+} from '@kiberon-labs/behave-graph';
+import { System } from '../src/system/system.js';
+import { setupCallSubgraphSync } from '../src/generators/callSubgraphSync.js';
+
+const buildSystem = () => {
+  const registry = registerCoreProfile({
+    nodes: {},
+    values: {},
+    dependencies: {} as any
+  });
+  const specs = writeNodeSpecsToJSON(registry);
+  return new System({ values: registry.values, specs });
+};
+
+const outputBoundary = (
+  id: string,
+  params: Array<{ id?: string; name: string; valueTypeName: string }>
+): Node => ({
+  id,
+  type: 'behaveNode',
+  position: { x: 0, y: 0 },
+  data: {
+    type: 'graph/output',
+    configuration: { parameters: params },
+    ports: {}
+  }
+});
+
+const callNode = (id: string, subgraphId: string): Node => ({
+  id,
+  type: 'behaveNode',
+  position: { x: 0, y: 0 },
+  data: { type: 'flow/callSubgraph', configuration: { subgraphId }, ports: {} }
+});
+
+const getNode = (session: { nodeStore: any }, id: string): Node =>
+  session.nodeStore.getState().nodes.find((n: Node) => n.id === id);
+
+describe('call subgraph contract sync', () => {
+  it('updates a call node when the referenced subgraph contract changes after creation', () => {
+    const system = buildSystem();
+    const caller = system.createSession('caller');
+    const dispose = setupCallSubgraphSync(system);
+
+    // `sub` is created AFTER the sync is registered , exercises the session
+    // extension applying to future graphs, not just existing ones.
+    const sub = system.createSession('sub');
+
+    // A call node referencing `sub`, created while `sub` has no outputs yet.
+    caller.nodeStore.getState().setNodes(() => [callNode('call1', sub.id)]);
+    expect(getNode(caller, 'call1').data.configuration.outputs ?? []).toEqual(
+      []
+    );
+
+    // Now author the subgraph's output contract.
+    sub.nodeStore
+      .getState()
+      .setNodes(() => [
+        outputBoundary('out', [
+          { id: 'o1', name: 'result', valueTypeName: 'float' }
+        ])
+      ]);
+
+    // The call node should have picked up the new contract reactively , no
+    // re-selection required.
+    const synced = getNode(caller, 'call1');
+    expect(synced.data.configuration.outputs).toEqual([
+      { id: 'o1', name: 'result', valueTypeName: 'float' }
+    ]);
+    expect(synced.data.dynamicPorts.outputs).toEqual([
+      { name: 'o1', key: 'o1', label: 'result', valueType: 'float' }
+    ]);
+
+    // Rename the param: the call node tracks the change (stable id, new label).
+    sub.nodeStore
+      .getState()
+      .setNodes(() => [
+        outputBoundary('out', [
+          { id: 'o1', name: 'renamed', valueTypeName: 'float' }
+        ])
+      ]);
+    expect(getNode(caller, 'call1').data.configuration.outputs).toEqual([
+      { id: 'o1', name: 'renamed', valueTypeName: 'float' }
+    ]);
+
+    dispose();
+  });
+
+  it('does not rewrite call nodes on non-contract edits (e.g. dragging)', () => {
+    const system = buildSystem();
+    const caller = system.createSession('caller');
+    const sub = system.createSession('sub');
+    const dispose = setupCallSubgraphSync(system);
+
+    sub.nodeStore
+      .getState()
+      .setNodes(() => [
+        outputBoundary('out', [
+          { id: 'o1', name: 'result', valueTypeName: 'float' }
+        ])
+      ]);
+    caller.nodeStore.getState().setNodes(() => [callNode('call1', sub.id)]);
+
+    const before = getNode(caller, 'call1');
+    // A position-only change to the subgraph must not churn the call node.
+    sub.nodeStore
+      .getState()
+      .setNodes((prev: Node[]) =>
+        prev.map((n) =>
+          n.id === 'out' ? { ...n, position: { x: 50, y: 50 } } : n
+        )
+      );
+    const after = getNode(caller, 'call1');
+
+    // Same object identity ⇒ the call node was not rewritten.
+    expect(after).toBe(before);
+
+    dispose();
+  });
+
+  it('stops syncing after dispose', () => {
+    const system = buildSystem();
+    const caller = system.createSession('caller');
+    const sub = system.createSession('sub');
+    const dispose = setupCallSubgraphSync(system);
+
+    caller.nodeStore.getState().setNodes(() => [callNode('call1', sub.id)]);
+    dispose();
+
+    sub.nodeStore
+      .getState()
+      .setNodes(() => [
+        outputBoundary('out', [
+          { id: 'o1', name: 'result', valueTypeName: 'float' }
+        ])
+      ]);
+
+    // No sync after dispose ⇒ contract not propagated.
+    expect(getNode(caller, 'call1').data.configuration.outputs ?? []).toEqual(
+      []
+    );
+  });
+});