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

package/tests/keepAliveLifecycle.test.ts

@@ -0,0 +1,167 @@
+import { describe, it, expect } from 'vitest';
+import {
+  Engine,
+  ManualLifecycleEventEmitter,
+  makeEventNodeDefinition,
+  makeFlowNodeDefinition,
+  readGraphFromJSON,
+  registerCoreProfile,
+  NodeCategory,
+  type GraphJSON
+} from '@kiberon-labs/behave-graph';
+import {
+  executeGraphLifecycle,
+  type ActiveRun,
+  type MessageContext
+} from '../src/plugin/graphrunner-local/execution-utils.js';
+
+/**
+ * A minimal external event source standing in for the AI conversation runtime:
+ * the event node subscribes on init, and `fire()` commits a flow the way
+ * ai/onToolCall does when the model requests a tool.
+ */
+const makeExternalSource = () => {
+  const listeners = new Set<() => void>();
+  return {
+    subscribe(listener: () => void) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    fire() {
+      listeners.forEach((listener) => listener());
+    },
+    get listenerCount() {
+      return listeners.size;
+    }
+  };
+};
+
+const buildRun = (handled: string[]) => {
+  const source = makeExternalSource();
+
+  const onExternal = makeEventNodeDefinition({
+    typeName: 'test/onExternal',
+    category: NodeCategory.Event,
+    in: {},
+    out: { flow: 'flow' },
+    initialState: { unsubscribe: undefined as undefined | (() => void) },
+    init: ({ commit }) => ({
+      unsubscribe: source.subscribe(() => commit('flow'))
+    }),
+    dispose: ({ state }) => {
+      state.unsubscribe?.();
+      return { unsubscribe: undefined };
+    }
+  });
+
+  const handle = makeFlowNodeDefinition({
+    typeName: 'test/handle',
+    category: NodeCategory.Action,
+    in: { flow: 'flow' },
+    out: {},
+    initialState: undefined,
+    triggered: () => {
+      handled.push('handled');
+    }
+  });
+
+  const registry = registerCoreProfile({
+    nodes: {},
+    values: {},
+    dependencies: {
+      ILifecycleEventEmitter: new ManualLifecycleEventEmitter()
+    }
+  });
+  registry.nodes['test/onExternal'] = onExternal;
+  registry.nodes['test/handle'] = handle;
+
+  const graphJson: GraphJSON = {
+    name: 'keep-alive test',
+    nodes: [
+      {
+        id: 'listener',
+        type: 'test/onExternal',
+        flows: { flow: { nodeId: 'handler', socket: 'flow' } }
+      },
+      { id: 'handler', type: 'test/handle' }
+    ],
+    variables: [],
+    customEvents: []
+  };
+
+  const graphInstance = readGraphFromJSON({ graphJson, registry });
+  const engine = new Engine(graphInstance, registry);
+
+  const run: ActiveRun = {
+    runId: 'run-1',
+    graphId: 'graph-1',
+    engine,
+    graphInstance,
+    registry,
+    status: 'running',
+    startedAt: Date.now(),
+    performance: { nodesExecuted: 0, eventsEmitted: 0, variableChanges: 0 },
+    isPaused: false,
+    executionPhase: 'start',
+    currentTick: 0
+  };
+
+  return { run, source };
+};
+
+const collectMessages = () => {
+  const messages: Array<{ type: string }> = [];
+  const ctx: MessageContext = {
+    sendMessage: (message) => messages.push(message),
+    sendError: () => {}
+  };
+  return { messages, ctx };
+};
+
+describe('graph run lifecycle', () => {
+  it('autoEnd: true finalizes when flows drain and unsubscribes event nodes', async () => {
+    const handled: string[] = [];
+    const { run, source } = buildRun(handled);
+    const { messages, ctx } = collectMessages();
+
+    // The engine constructor fires event-node init without awaiting it; let
+    // its state (the unsubscribe handle) settle before the lifecycle disposes.
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    await executeGraphLifecycle(run, 'graph-1', ctx, { autoEnd: true });
+
+    expect(run.status).toBe('completed');
+    expect(messages.some((m) => m.type === 'completed')).toBe(true);
+    // Dispose tore the subscription down; a late event finds no listener.
+    expect(source.listenerCount).toBe(0);
+  });
+
+  it('stays alive by default and services events fired after the flows drain', async () => {
+    const handled: string[] = [];
+    const { run, source } = buildRun(handled);
+    const { messages, ctx } = collectMessages();
+
+    const lifecycle = executeGraphLifecycle(run, 'graph-1', ctx, {
+      tickInterval: 1
+    });
+
+    // Give the lifecycle time to drain the (empty) start flow. With autoEnd
+    // it would have completed here.
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(run.status).toBe('running');
+    expect(source.listenerCount).toBe(1);
+
+    // The out-of-band event (the "tool call") arrives after the start flow
+    // ended; the idle loop must still drain the fiber it commits.
+    source.fire();
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(handled).toEqual(['handled']);
+
+    // Stopping ends the idle loop; no `completed` message is emitted.
+    run.status = 'stopped';
+    await lifecycle;
+    expect(messages.some((m) => m.type === 'completed')).toBe(false);
+
+    run.engine.dispose();
+  });
+});

package/tests/loadManifest.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, vi } from 'vitest';
+import type {
+  ManifestJSON,
+  PackageRequirement
+} from '@kiberon-labs/behave-graph';
+import { System } from '../src/system/system.js';
+import { loadManifest } from '../src/manifest/loadManifest.js';
+
+const Vec2Control = () => null;
+const conversionRule = {
+  from: 'vec2',
+  to: 'object',
+  nodeType: 'convert/vec2ToObject'
+};
+
+const manifest: ManifestJSON = {
+  manifestVersion: 1,
+  package: { name: '@test/pkg', version: '1.0.0' },
+  values: [{ name: 'vec2', defaultJSON: { x: 0, y: 0 } }],
+  nodes: [
+    {
+      type: 'test/node',
+      category: 'Logic',
+      label: 'Test Node',
+      inputs: [],
+      outputs: [],
+      configuration: []
+    }
+  ],
+  contributions: [
+    {
+      id: 'vec2-ctrl',
+      kind: 'control',
+      export: './ui.js#Vec2Control',
+      bind: { controlName: 'vec2' }
+    },
+    { id: 'vec2-conv', kind: 'conversion', export: './ui.js#rule' }
+  ],
+  requirements: [
+    { kind: 'backendService', entry: './server.js', persistent: true }
+  ]
+};
+
+const resolve = (c: { id: string }) => {
+  if (c.id === 'vec2-ctrl') return Vec2Control;
+  if (c.id === 'vec2-conv') return conversionRule;
+  return undefined;
+};
+
+describe('loadManifest', () => {
+  it('loads nodes + pass-through value types without trust (no code exec)', async () => {
+    const system = new System();
+    await loadManifest(system, manifest);
+
+    const reg = system.registry.getState();
+    expect(reg.specs.some((s) => s.type === 'test/node')).toBe(true);
+
+    const vec2 = reg.values['vec2'];
+    expect(vec2).toBeDefined();
+    // Pass-through creator returns a *clone* of the declared default.
+    const created = vec2.creator();
+    expect(created).toEqual({ x: 0, y: 0 });
+    expect(created).not.toBe(manifest.values[0].defaultJSON);
+    // Identity (de)serialize keeps existing UI call sites working.
+    expect(vec2.serialize?.(created)).toEqual({ x: 0, y: 0 });
+
+    // No contributions applied without trust.
+    expect(system.controlStore.getState().controls['vec2']).toBeUndefined();
+  });
+
+  it('surfaces host requirements via onRequirement', async () => {
+    const system = new System();
+    const seen: PackageRequirement[] = [];
+    await loadManifest(system, manifest, {
+      onRequirement: (req) => seen.push(req)
+    });
+    expect(seen).toHaveLength(1);
+    expect(seen[0].kind).toBe('backendService');
+  });
+
+  it('applies code contributions only under trust + resolve', async () => {
+    const system = new System();
+    await loadManifest(system, manifest, { trust: true, resolve });
+
+    expect(system.controlStore.getState().controls['vec2']).toBe(Vec2Control);
+    expect(
+      system.conversionStore.getState().findConversion('vec2', 'object')
+    ).toEqual(conversionRule);
+  });
+
+  it('skips contributions when trusted but no resolver is given', async () => {
+    const system = new System();
+    await loadManifest(system, manifest, { trust: true });
+    expect(system.controlStore.getState().controls['vec2']).toBeUndefined();
+  });
+
+  it('does not let one failing contribution abort the rest', async () => {
+    const system = new System();
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    await loadManifest(system, manifest, {
+      trust: true,
+      resolve: (c) => {
+        if (c.id === 'vec2-ctrl') throw new Error('boom');
+        return resolve(c);
+      }
+    });
+    // The conversion still registered despite the control throwing.
+    expect(
+      system.conversionStore.getState().findConversion('vec2', 'object')
+    ).toEqual(conversionRule);
+    spy.mockRestore();
+  });
+});

package/tests/noteMarkdown.test.ts

@@ -0,0 +1,65 @@
+// @vitest-environment happy-dom
+// @vitest-environment-options { "settings": { "disableIframePageLoading": true } }
+// (embedded youtube iframes must not trigger real network requests in tests)
+
+import { describe, it, expect } from 'vitest';
+import { Editor } from '@tiptap/react';
+import StarterKit from '@tiptap/starter-kit';
+import Youtube from '@tiptap/extension-youtube';
+import { Markdown } from 'tiptap-markdown';
+
+const makeEditor = (content: string) =>
+  new Editor({
+    element: document.createElement('div'),
+    extensions: [StarterKit, Markdown, Youtube.configure({ nocookie: true })],
+    content
+  });
+
+const getMarkdown = (editor: Editor): string =>
+  (
+    editor.storage as unknown as { markdown: { getMarkdown(): string } }
+  ).markdown.getMarkdown();
+
+describe('note markdown serialization', () => {
+  it('round-trips formatted text', () => {
+    const editor = makeEditor('# Title\n\nSome **bold** and `code`.');
+    const md = getMarkdown(editor);
+    expect(md).toContain('# Title');
+    expect(md).toContain('**bold**');
+    expect(md).toContain('`code`');
+    editor.destroy();
+  });
+
+  it('embeds a youtube video and round-trips it through markdown', () => {
+    const editor = makeEditor('');
+    const inserted = editor
+      .chain()
+      .setYoutubeVideo({ src: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ' })
+      .run();
+    expect(inserted).toBe(true);
+
+    // The video serializes as an HTML block inside the markdown text.
+    const md = getMarkdown(editor);
+    expect(md).toContain('data-youtube-video');
+    expect(md).toContain('dQw4w9WgXcQ');
+    editor.destroy();
+
+    // Loading that markdown back (what NoteNodeImpl does with data.text)
+    // restores the embed.
+    const reloaded = makeEditor(md);
+    expect(reloaded.getHTML()).toContain('data-youtube-video');
+    expect(reloaded.getHTML()).toContain('dQw4w9WgXcQ');
+    reloaded.destroy();
+  });
+
+  it('rejects non-youtube urls', () => {
+    const editor = makeEditor('');
+    const inserted = editor
+      .chain()
+      .setYoutubeVideo({ src: 'https://example.com/video.mp4' })
+      .run();
+    expect(inserted).toBe(false);
+    expect(getMarkdown(editor)).not.toContain('example.com');
+    editor.destroy();
+  });
+});

package/tests/notesPlugin.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { System } from '../src/system/system.js';
+import type { GraphSession } from '../src/system/graphSession.js';
+import {
+  notesPlugin,
+  NOTE_NODE_TYPE,
+  LEGACY_COMMENT_NODE_TYPE
+} from '../src/plugin/notes/index.js';
+
+describe('notes plugin', () => {
+  let system: System;
+  let session: GraphSession;
+
+  const addNote = (position = { x: 10, y: 20 }) =>
+    system.commandStore.getState().run('notes.addNote', {
+      editor: system,
+      session,
+      position
+    });
+
+  const nodes = () => session.nodeStore.getState().nodes;
+
+  beforeEach(async () => {
+    system = new System();
+    await system.registerPlugin(notesPlugin);
+    session = system.createSession('graph');
+  });
+
+  it('does not register note node types without the plugin', () => {
+    const bare = new System();
+    const bareSession = bare.createSession('graph');
+    expect(bareSession.flowStore.getState().nodeTypes[NOTE_NODE_TYPE]).toBe(
+      undefined
+    );
+  });
+
+  it('registers the note component (and legacy alias) on new sessions', () => {
+    const { nodeTypes } = session.flowStore.getState();
+    expect(nodeTypes[NOTE_NODE_TYPE]).toBeDefined();
+    expect(nodeTypes[LEGACY_COMMENT_NODE_TYPE]).toBe(nodeTypes[NOTE_NODE_TYPE]);
+  });
+
+  it('adds a toolbar group with the Add Note button', () => {
+    const group = system.toolbarStore
+      .getState()
+      .groups.find((g) => g.id === 'notes');
+    expect(group).toBeDefined();
+    expect(group?.buttons).toHaveLength(1);
+  });
+
+  it('notes.addNote creates a selected, header-draggable note (undoable)', () => {
+    void addNote();
+
+    expect(nodes()).toHaveLength(1);
+    const note = nodes()[0];
+    expect(note?.type).toBe(NOTE_NODE_TYPE);
+    expect(note?.position).toEqual({ x: 10, y: 20 });
+    expect(note?.selected).toBe(true);
+    expect(note?.dragHandle).toBe('.notes-node__header');
+    expect(note?.data).toEqual({ text: '' });
+
+    session.undoManager.undo();
+    expect(nodes()).toHaveLength(0);
+    session.undoManager.redo();
+    expect(nodes()).toHaveLength(1);
+  });
+
+  it('note nodes are ignored by the behave graph transform', () => {
+    void addNote();
+    const graph = session.flowStore.getState().getGraph();
+    expect(graph.nodes ?? []).toHaveLength(0);
+  });
+
+  it('note.duplicate clones the note with an offset', () => {
+    void addNote();
+    const original = nodes()[0]!;
+
+    void system.commandStore.getState().run('note.duplicate', {
+      editor: system,
+      session,
+      nodeId: original.id
+    });
+
+    expect(nodes()).toHaveLength(2);
+    const copy = nodes()[1]!;
+    expect(copy.id).not.toBe(original.id);
+    expect(copy.position).toEqual({
+      x: original.position.x + 24,
+      y: original.position.y + 24
+    });
+
+    session.undoManager.undo();
+    expect(nodes()).toHaveLength(1);
+  });
+
+  it('note.delete removes the note and undo restores it', () => {
+    void addNote();
+    const note = nodes()[0]!;
+
+    void system.commandStore.getState().run('note.delete', {
+      editor: system,
+      session,
+      nodeId: note.id
+    });
+    expect(nodes()).toHaveLength(0);
+
+    session.undoManager.undo();
+    expect(nodes()).toHaveLength(1);
+    expect(nodes()[0]?.id).toBe(note.id);
+  });
+
+  it('bring to front / send to back reorder within the nodes array', () => {
+    void addNote({ x: 0, y: 0 });
+    void addNote({ x: 5, y: 5 });
+    const [first, second] = nodes();
+
+    void system.commandStore.getState().run('note.bringToFront', {
+      editor: system,
+      session,
+      nodeId: first!.id
+    });
+    expect(nodes().map((n) => n.id)).toEqual([second!.id, first!.id]);
+
+    void system.commandStore.getState().run('note.sendToBack', {
+      editor: system,
+      session,
+      nodeId: first!.id
+    });
+    expect(nodes().map((n) => n.id)).toEqual([first!.id, second!.id]);
+  });
+
+  it('behave-only context menu items are hidden on notes, note items shown', () => {
+    void addNote();
+    const note = nodes()[0]!;
+    const ctx = { editor: system, session, nodeId: note.id };
+
+    const visible = system.contextMenuStore
+      .getState()
+      .getItems('node')
+      .filter((i) => !i.when || i.when(ctx))
+      .map((i) => i.id);
+
+    expect(visible).toContain('note.duplicate');
+    expect(visible).toContain('note.delete');
+    expect(visible).not.toContain('node.traceUpstream');
+    expect(visible).not.toContain('node.togglePinned');
+  });
+
+  it('note commands no-op for behave nodes', () => {
+    session.actionStore
+      .getState()
+      .actions.addBehaveNode('debug/log', { x: 0, y: 0 });
+    const behave = nodes()[0]!;
+
+    void system.commandStore.getState().run('note.delete', {
+      editor: system,
+      session,
+      nodeId: behave.id
+    });
+    expect(nodes()).toHaveLength(1);
+  });
+});

package/tests/persistence.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { System } from '../src/system/system.js';
+import type { UIGraphJSON } from '../src/types/graph.js';
+
+const fakeUIGraph = (): UIGraphJSON =>
+  ({ flow: { nodes: [] } }) as unknown as UIGraphJSON;
+
+describe('default graph/layout persistence', () => {
+  let system: System;
+
+  beforeEach(() => {
+    system = new System();
+  });
+
+  it('subscribes save handlers by default (no per-host wiring)', () => {
+    // The three save topics each have exactly one default subscriber.
+    expect(system.pubsub.countSubscriptions('graph:saved')).toBe(1);
+    expect(system.pubsub.countSubscriptions('graph:inner:saved')).toBe(1);
+    expect(system.pubsub.countSubscriptions('layout:saved')).toBe(1);
+  });
+
+  it('routes a custom adapter and keeps defaults for omitted topics', () => {
+    const saveGraph = vi.fn();
+    system.enablePersistence({ saveGraph });
+
+    // Replacing does not stack subscriptions.
+    expect(system.pubsub.countSubscriptions('graph:saved')).toBe(1);
+
+    const graph = fakeUIGraph();
+    system.pubsub.publishSync('graph:saved', graph);
+    expect(saveGraph).toHaveBeenCalledWith(graph);
+  });
+
+  it('disablePersistence removes all save handlers', () => {
+    system.disablePersistence();
+    expect(system.pubsub.countSubscriptions('graph:saved')).toBe(0);
+    expect(system.pubsub.countSubscriptions('graph:inner:saved')).toBe(0);
+    expect(system.pubsub.countSubscriptions('layout:saved')).toBe(0);
+
+    // Publishing after disabling is a no-op (no subscriber throws).
+    expect(() =>
+      system.pubsub.publishSync('graph:saved', fakeUIGraph())
+    ).not.toThrow();
+  });
+
+  it('does not throw when the default (download) sink runs without a DOM', () => {
+    const graph = fakeUIGraph();
+    // jsdom provides document/URL, but the guard makes this safe either way.
+    expect(() => system.pubsub.publishSync('graph:saved', graph)).not.toThrow();
+  });
+});

package/tests/saveLoad.test.ts

@@ -24,6 +24,7 @@ describe('Save and Load Graph', () => {
     };
 
     system = new System(registry);
+    system.createSession('graph');
   });
 
   it('should save and load a graph with node positions', () => {
@@ -67,7 +68,7 @@ describe('Save and Load Graph', () => {
     system.edgeStore.getState().setEdges(initialEdges);
 
     // Save the graph
-    const savedGraph = buildUIGraphJSON(system);
+    const savedGraph = buildUIGraphJSON(system.session!);
 
     // Verify saved graph has nodes with positions
     expect(savedGraph.nodes).toHaveLength(2);
@@ -115,7 +116,7 @@ describe('Save and Load Graph', () => {
     system.nodeStore.getState().setNodes(initialNodes);
 
     // Save the graph
-    const savedGraph = buildUIGraphJSON(system);
+    const savedGraph = buildUIGraphJSON(system.session!);
 
     // Verify viewport is saved
     expect(savedGraph.user?.viewport).toEqual({ x: 50, y: 100, zoom: 1.5 });
@@ -151,7 +152,7 @@ describe('Save and Load Graph', () => {
     system.nodeStore.getState().setNodes(nodes);
 
     // Save the graph
-    const savedGraph = buildUIGraphJSON(system);
+    const savedGraph = buildUIGraphJSON(system.session!);
 
     // Verify variables are in the flow
     expect(savedGraph.flow.variables).toBeDefined();
@@ -200,7 +201,7 @@ describe('Save and Load Graph', () => {
     system.nodeStore.getState().setNodes(nodes);
 
     // Save the graph
-    const savedGraph = buildUIGraphJSON(system);
+    const savedGraph = buildUIGraphJSON(system.session!);
 
     // Verify custom events are in the flow
     expect(savedGraph.flow.customEvents).toEqual(customEvents);
@@ -236,7 +237,7 @@ describe('Save and Load Graph', () => {
     system.nodeStore.getState().setNodes(nodesWithPositions);
 
     // Save the graph
-    const savedGraph = buildUIGraphJSON(system);
+    const savedGraph = buildUIGraphJSON(system.session!);
 
     // Modify the node position
     system.nodeStore.getState().setNodes([
@@ -340,7 +341,7 @@ describe('Save and Load Graph', () => {
     system.variableStore.getState().setVariables(variables);
 
     // Save
-    const saved = buildUIGraphJSON(system);
+    const saved = buildUIGraphJSON(system.session!);
 
     // Clear
     system.nodeStore.getState().setNodes([]);