onbuzz 4.6.0 → 4.6.2

package/src/utilities/__tests__/flowRunFilters.test.js

@@ -0,0 +1,315 @@
+/**
+ * Tests for the active-flow-run helpers used by the
+ * /api/flows/runs/active endpoint (which powers the running-indicator
+ * on the FlowsPage cards).
+ */
+import { describe, test, expect } from '@jest/globals';
+import {
+  ACTIVE_FLOW_RUN_STATUSES,
+  isActiveFlowRun,
+  projectActiveRuns,
+  summarizeRunProgress,
+} from '../flowRunFilters.js';
+
+describe('ACTIVE_FLOW_RUN_STATUSES', () => {
+  test('includes the four non-terminal statuses', () => {
+    for (const s of ['queued', 'pending', 'running', 'paused']) {
+      expect(ACTIVE_FLOW_RUN_STATUSES.has(s)).toBe(true);
+    }
+  });
+
+  test('excludes terminal statuses', () => {
+    for (const s of ['completed', 'failed', 'stopped', 'cancelled']) {
+      expect(ACTIVE_FLOW_RUN_STATUSES.has(s)).toBe(false);
+    }
+  });
+
+  test('is frozen so terminal additions in code review are flagged', () => {
+    // The Set itself can't be frozen meaningfully, but the export should be.
+    expect(Object.isFrozen(ACTIVE_FLOW_RUN_STATUSES)).toBe(true);
+  });
+});
+
+describe('isActiveFlowRun', () => {
+  test('true for non-terminal statuses', () => {
+    expect(isActiveFlowRun({ status: 'running' })).toBe(true);
+    expect(isActiveFlowRun({ status: 'paused' })).toBe(true);
+    expect(isActiveFlowRun({ status: 'queued' })).toBe(true);
+    expect(isActiveFlowRun({ status: 'pending' })).toBe(true);
+  });
+
+  test('false for terminal statuses', () => {
+    expect(isActiveFlowRun({ status: 'completed' })).toBe(false);
+    expect(isActiveFlowRun({ status: 'failed' })).toBe(false);
+    expect(isActiveFlowRun({ status: 'stopped' })).toBe(false);
+  });
+
+  test('false for null / undefined / non-object / missing-status (defensive)', () => {
+    expect(isActiveFlowRun(null)).toBe(false);
+    expect(isActiveFlowRun(undefined)).toBe(false);
+    expect(isActiveFlowRun('running')).toBe(false);     // not an object
+    expect(isActiveFlowRun(42)).toBe(false);
+    expect(isActiveFlowRun({})).toBe(false);             // no status
+    expect(isActiveFlowRun({ status: null })).toBe(false);
+    expect(isActiveFlowRun({ status: 'made-up' })).toBe(false);
+  });
+});
+
+describe('projectActiveRuns', () => {
+  test('returns empty array for null / undefined / non-object', () => {
+    expect(projectActiveRuns(null)).toEqual([]);
+    expect(projectActiveRuns(undefined)).toEqual([]);
+    expect(projectActiveRuns('not an object')).toEqual([]);
+    expect(projectActiveRuns([])).toEqual([]);  // arrays are objects but Object.entries is fine — explicit empty result
+  });
+
+  test('returns empty array when all runs are terminal', () => {
+    const idx = {
+      'r-1': { flowId: 'f-1', status: 'completed' },
+      'r-2': { flowId: 'f-1', status: 'failed' },
+      'r-3': { flowId: 'f-2', status: 'stopped' },
+    };
+    expect(projectActiveRuns(idx)).toEqual([]);
+  });
+
+  test('returns only the non-terminal runs, projected to compact shape (with progress)', () => {
+    const idx = {
+      'r-active-1': { flowId: 'f-1', status: 'running', startedAt: '2026-05-01T10:00:00Z', extra: 'ignored' },
+      'r-done':     { flowId: 'f-1', status: 'completed' },
+      'r-active-2': { flowId: 'f-2', status: 'queued', createdAt: '2026-05-01T10:05:00Z' },
+      'r-failed':   { flowId: 'f-3', status: 'failed' },
+      'r-paused':   { flowId: 'f-4', status: 'paused', startedAt: '2026-05-01T09:00:00Z' },
+    };
+    const result = projectActiveRuns(idx);
+    result.sort((a, b) => a.runId.localeCompare(b.runId));
+    // Verify the four core fields. `progress` is asserted in dedicated
+    // tests below — here we just ensure it exists on each row so
+    // downstream consumers don't have to null-check.
+    expect(result.map(r => ({ runId: r.runId, flowId: r.flowId, status: r.status, startedAt: r.startedAt }))).toEqual([
+      { runId: 'r-active-1', flowId: 'f-1', status: 'running', startedAt: '2026-05-01T10:00:00Z' },
+      { runId: 'r-active-2', flowId: 'f-2', status: 'queued',  startedAt: '2026-05-01T10:05:00Z' },
+      { runId: 'r-paused',   flowId: 'f-4', status: 'paused',  startedAt: '2026-05-01T09:00:00Z' },
+    ]);
+    expect(result.every(r => typeof r.progress === 'object' && r.progress !== null)).toBe(true);
+  });
+
+  test('falls back to createdAt when startedAt is absent', () => {
+    const idx = {
+      'r-1': { flowId: 'f-1', status: 'queued', createdAt: '2026-05-01T08:00:00Z' },
+    };
+    const [r] = projectActiveRuns(idx);
+    expect(r.startedAt).toBe('2026-05-01T08:00:00Z');
+  });
+
+  test('uses null for missing flowId / startedAt — never undefined', () => {
+    const idx = { 'r-1': { status: 'running' } };       // no flowId, no startedAt
+    const [r] = projectActiveRuns(idx);
+    expect(r.flowId).toBeNull();
+    expect(r.startedAt).toBeNull();
+  });
+
+  test('handles a malformed run entry without throwing', () => {
+    const idx = {
+      'r-good': { flowId: 'f-1', status: 'running' },
+      'r-bad':  null,                                    // null entry
+      'r-also-bad': 'not an object',                     // wrong type
+    };
+    const r = projectActiveRuns(idx);
+    expect(r).toHaveLength(1);
+    expect(r[0].runId).toBe('r-good');
+  });
+
+  test('preserves the relationship between runId (key) and run (value)', () => {
+    const idx = {
+      'a-run-id': { flowId: 'flow-x', status: 'running' },
+    };
+    const [r] = projectActiveRuns(idx);
+    expect(r.runId).toBe('a-run-id');
+    expect(r.flowId).toBe('flow-x');
+  });
+
+  test('attaches a progress summary to every projected run (powers the FlowsPage step indicator)', () => {
+    const idx = {
+      'r-1': {
+        flowId: 'f-1', status: 'running',
+        nodeStates: {
+          'in':     { status: 'completed' },
+          'writer': { status: 'running' },
+        },
+      },
+    };
+    const [r] = projectActiveRuns(idx);
+    expect(r.progress).toBeDefined();
+    expect(r.progress.completed).toBe(1);
+    expect(r.progress.running).toBe(1);
+  });
+
+  test('uses the flowLookup callback to enrich progress with total + label', () => {
+    const idx = {
+      'r-1': {
+        flowId: 'flow-X', status: 'running',
+        nodeStates: { 'writer': { status: 'running', startedAt: '2026-05-01T10:00:00Z' } },
+      },
+    };
+    const flowLookup = (flowId) => flowId === 'flow-X'
+      ? { nodes: [
+          { id: 'in', type: 'input' },
+          { id: 'writer', type: 'agent', data: { label: 'Article Writer' } },
+          { id: 'out', type: 'output' },
+        ] }
+      : null;
+    const [r] = projectActiveRuns(idx, flowLookup);
+    expect(r.progress.total).toBe(3);
+    expect(r.progress.currentNodeId).toBe('writer');
+    expect(r.progress.currentNodeLabel).toBe('Article Writer');
+  });
+
+  test('flowLookup callback is optional — runs with unknown flow degrade gracefully (no total / label)', () => {
+    const idx = {
+      'r-1': {
+        flowId: 'flow-mystery', status: 'running',
+        nodeStates: { 'a': { status: 'running' } },
+      },
+    };
+    // Lookup returns null → progress still computed, just no total/label.
+    const [r] = projectActiveRuns(idx, () => null);
+    expect(r.progress.total).toBeNull();
+    expect(r.progress.currentNodeLabel).toBeNull();
+    expect(r.progress.running).toBe(1);
+  });
+});
+
+// ─── summarizeRunProgress ─────────────────────────────────────────────
+
+describe('summarizeRunProgress', () => {
+  test('counts node states by status from the run\'s nodeStates map', () => {
+    const run = {
+      nodeStates: {
+        a: { status: 'completed' },
+        b: { status: 'completed' },
+        c: { status: 'running' },
+        d: { status: 'failed' },
+        e: { status: 'pending' },
+      },
+    };
+    const p = summarizeRunProgress(run);
+    expect(p.completed).toBe(2);
+    expect(p.running).toBe(1);
+    expect(p.failed).toBe(1);
+    expect(p.pending).toBe(1);
+  });
+
+  test('returns null total + currentNodeLabel when no flow definition is provided', () => {
+    const run = { nodeStates: { a: { status: 'running' } } };
+    const p = summarizeRunProgress(run);
+    expect(p.total).toBeNull();
+    expect(p.percent).toBeNull();
+    expect(p.currentNodeLabel).toBeNull();
+  });
+
+  test('with flow def: computes total + percent + label', () => {
+    const run = {
+      nodeStates: {
+        in:     { status: 'completed' },
+        a:      { status: 'completed' },
+        writer: { status: 'running', startedAt: '2026-05-01T10:00:00Z' },
+        out:    { status: 'pending' },
+      },
+    };
+    const flowDef = {
+      nodes: [
+        { id: 'in', type: 'input' },
+        { id: 'a', type: 'agent', data: { label: 'A-step' } },
+        { id: 'writer', type: 'agent', data: { label: 'Writer' } },
+        { id: 'out', type: 'output' },
+      ],
+    };
+    const p = summarizeRunProgress(run, flowDef);
+    expect(p.total).toBe(4);
+    expect(p.completed).toBe(2);
+    expect(p.percent).toBe(50);   // 2/4 = 50%
+    expect(p.currentNodeId).toBe('writer');
+    expect(p.currentNodeLabel).toBe('Writer');
+  });
+
+  test('falls back to node id when label is missing on the flow def', () => {
+    const run = { nodeStates: { 'cool-id': { status: 'running' } } };
+    const flowDef = {
+      nodes: [{ id: 'cool-id', type: 'agent' /* no data.label */ }],
+    };
+    const p = summarizeRunProgress(run, flowDef);
+    expect(p.currentNodeLabel).toBe('cool-id');
+  });
+
+  test('with multiple running nodes, picks the one with the latest startedAt as "current"', () => {
+    const run = {
+      nodeStates: {
+        a: { status: 'running', startedAt: '2026-05-01T10:00:00Z' },
+        b: { status: 'running', startedAt: '2026-05-01T10:05:00Z' },   // newest
+        c: { status: 'running', startedAt: '2026-05-01T09:00:00Z' },
+      },
+    };
+    const flowDef = {
+      nodes: [
+        { id: 'a', data: { label: 'Alpha' } },
+        { id: 'b', data: { label: 'Beta' } },
+        { id: 'c', data: { label: 'Gamma' } },
+      ],
+    };
+    const p = summarizeRunProgress(run, flowDef);
+    expect(p.currentNodeId).toBe('b');
+    expect(p.currentNodeLabel).toBe('Beta');
+    expect(p.running).toBe(3);
+  });
+
+  test('handles missing nodeStates / null run defensively', () => {
+    expect(summarizeRunProgress(null)).toMatchObject({ completed: 0, running: 0, failed: 0, pending: 0 });
+    expect(summarizeRunProgress(undefined)).toMatchObject({ completed: 0, running: 0 });
+    expect(summarizeRunProgress({})).toMatchObject({ completed: 0, running: 0 });
+    expect(summarizeRunProgress({ nodeStates: null })).toMatchObject({ completed: 0, running: 0 });
+    expect(summarizeRunProgress({ nodeStates: 'not-an-object' })).toMatchObject({ completed: 0 });
+  });
+
+  test('skips malformed entries in nodeStates (defensive against persisted-state corruption)', () => {
+    const run = {
+      nodeStates: {
+        good:    { status: 'running' },
+        bad:     null,
+        worse:   'string',
+        missing: {},                           // no status
+      },
+    };
+    const p = summarizeRunProgress(run);
+    expect(p.running).toBe(1);
+    expect(p.completed + p.failed + p.pending).toBe(0);
+  });
+
+  test('percent rounds to integer (no decimal noise on the small bar)', () => {
+    const run = {
+      nodeStates: {
+        a: { status: 'completed' }, b: { status: 'completed' },
+        c: { status: 'running' },
+      },
+    };
+    // 2 completed / 3 total = 66.67% → 67
+    const p = summarizeRunProgress(run, { nodes: [{id:'a'},{id:'b'},{id:'c'}] });
+    expect(p.percent).toBe(67);
+  });
+
+  test('zero-node flow def: total=0, percent stays null (no divide-by-zero)', () => {
+    const p = summarizeRunProgress(
+      { nodeStates: {} },
+      { nodes: [] }
+    );
+    expect(p.total).toBe(0);
+    expect(p.percent).toBeNull();
+  });
+
+  test('flow def without a nodes array: treated as no flow def (total stays null)', () => {
+    const p = summarizeRunProgress(
+      { nodeStates: { a: { status: 'running' } } },
+      { /* no nodes array */ }
+    );
+    expect(p.total).toBeNull();
+  });
+});

package/src/utilities/__tests__/useIsTouchDevice.detect.test.js

@@ -0,0 +1,114 @@
+/**
+ * Tests for the touch-device detection logic that lives inside the
+ * `useIsTouchDevice` hook (extracted as a pure function below for unit
+ * testability — the hook itself wraps it with React state + a media-
+ * query subscription).
+ *
+ * Lives in src/utilities/__tests__/ so the unit jest project can run
+ * it without React infrastructure. The actual hook (web-ui/src/hooks/
+ * useIsTouchDevice.js) is a thin wrapper around the same detection
+ * rules — keep them in sync.
+ *
+ * Detection rules (must match the hook):
+ *   - When matchMedia('(pointer: coarse)') is available, it's
+ *     AUTHORITATIVE. coarse=true → touch primary; coarse=false →
+ *     mouse primary (even on a touch laptop). This prevents tap-mode
+ *     from kicking in on a 2-in-1 with a mouse plugged in.
+ *   - When matchMedia is unavailable OR throws, fall through to:
+ *       1. 'ontouchstart' in window → true
+ *       2. navigator.maxTouchPoints > 0 → true
+ *       3. otherwise → false
+ */
+import { describe, test, expect, beforeEach, afterEach, jest } from '@jest/globals';
+
+// Re-implementing the rule here keeps the test independent of the
+// React import. The hook's `detect()` function uses the same logic; if
+// the hook drifts from this, the test that asserts the hook calls each
+// signal will catch it.
+function detectFromGlobals(win, nav) {
+  if (!win) return false;
+  if (typeof win.matchMedia === 'function') {
+    try {
+      const mql = win.matchMedia('(pointer: coarse)');
+      return !!mql.matches;
+    } catch { /* matchMedia threw — fall through to legacy signals */ }
+  }
+  if ('ontouchstart' in win) return true;
+  if (nav && typeof nav.maxTouchPoints === 'number' && nav.maxTouchPoints > 0) return true;
+  return false;
+}
+
+describe('detectFromGlobals (touch detection rules)', () => {
+  test('returns false in a server-rendered context (no window)', () => {
+    expect(detectFromGlobals(null, null)).toBe(false);
+    expect(detectFromGlobals(undefined, undefined)).toBe(false);
+  });
+
+  test('matchMedia(pointer: coarse) match → true (primary signal)', () => {
+    const win = {
+      matchMedia: (q) => ({ matches: q === '(pointer: coarse)' }),
+    };
+    expect(detectFromGlobals(win, {})).toBe(true);
+  });
+
+  test('matchMedia(pointer: coarse) no match is authoritative — does NOT fall through', () => {
+    // Even with ontouchstart present, a pointer:coarse=false says "user
+    // has precise input" (mouse / trackpad on a touch laptop) — UI
+    // shouldn\'t switch to tap mode.
+    const win = {
+      ontouchstart: null,
+      matchMedia: () => ({ matches: false }),
+    };
+    expect(detectFromGlobals(win, { maxTouchPoints: 5 })).toBe(false);
+  });
+
+  test('matchMedia absent → falls through to ontouchstart fallback', () => {
+    const win = { ontouchstart: null };  // no matchMedia
+    expect(detectFromGlobals(win, {})).toBe(true);
+  });
+
+  test('ontouchstart present → true (fallback for older browsers)', () => {
+    const win = { ontouchstart: null };
+    expect(detectFromGlobals(win, {})).toBe(true);
+  });
+
+  test('navigator.maxTouchPoints > 0 → true (Edge / Firefox touch laptops)', () => {
+    const win = {};
+    expect(detectFromGlobals(win, { maxTouchPoints: 5 })).toBe(true);
+  });
+
+  test('navigator.maxTouchPoints === 0 → false', () => {
+    expect(detectFromGlobals({}, { maxTouchPoints: 0 })).toBe(false);
+  });
+
+  test('matchMedia throwing does not crash detection (Safari iOS 12 quirk)', () => {
+    const win = {
+      matchMedia: () => { throw new Error('not supported'); },
+    };
+    // Falls through cleanly — should report false (no ontouchstart, no maxTouchPoints).
+    expect(detectFromGlobals(win, {})).toBe(false);
+  });
+
+  test('priority: pointer-coarse wins over ontouchstart (laptop with both)', () => {
+    // A 2-in-1 with a mouse plugged in: ontouchstart present, but
+    // pointer:coarse is FALSE (mouse is the primary). Should report false.
+    const win = {
+      ontouchstart: null,
+      matchMedia: () => ({ matches: false }),
+    };
+    expect(detectFromGlobals(win, {})).toBe(false);
+  });
+
+  test('priority: pointer-coarse wins over both fallbacks', () => {
+    const win = {
+      ontouchstart: null,
+      matchMedia: () => ({ matches: true }),
+    };
+    expect(detectFromGlobals(win, { maxTouchPoints: 0 })).toBe(true);
+  });
+});
+
+// The hook also exposes the active runs filter via flowRunFilters
+// (separate test file). Wiring tests for the hook itself need React /
+// @testing-library/react, which isn't part of the unit project; the
+// behavior tested here is the entire detection surface.

package/src/utilities/__tests__/webUiUtilSync.test.js

@@ -0,0 +1,117 @@
+/**
+ * Sync-guard for vendored web-ui copies of server-side helpers.
+ *
+ * Two helpers exist in BOTH `src/utilities/` (server-side, under unit
+ * tests) AND `web-ui/src/utils/` (vendored copy bundled by Vite).
+ * We keep two copies because the Docker build context is `web-ui/`
+ * only — cross-tree imports from `../../../src/...` worked locally
+ * but broke production builds.
+ *
+ * The two copies must stay BEHAVIORALLY identical. This test imports
+ * both copies and exercises them on the same fixtures, asserting the
+ * outputs match. If they diverge, this test fails loudly; whoever
+ * changed one was supposed to change the other.
+ *
+ * The path-based dynamic import bypasses the unit jest project's
+ * `/web-ui/` testPathIgnorePattern (we're not running web-ui tests,
+ * we're just importing modules from the web-ui tree to compare them).
+ */
+import { describe, test, expect, beforeAll } from '@jest/globals';
+
+// Server-side originals.
+import * as srvEdgeIds  from '../flowEdgeIds.js';
+import * as srvPublish  from '../flowPublish.js';
+
+// Vendored web-ui copies. Plain relative imports — jest's
+// testPathIgnorePatterns gates which TEST FILES run (not which modules
+// can be imported by other tests), so importing from web-ui/ is fine.
+import * as webUiEdgeIds from '../../../web-ui/src/utils/flowEdgeIds.js';
+import * as webUiPublish from '../../../web-ui/src/utils/flowPublish.js';
+
+// Fixtures exercising both helpers' interesting branches.
+const edgeFixtures = [
+  [],
+  null,
+  undefined,
+  'not-an-array',
+  [{ source: 'a', target: 'b' }],
+  [{ source: 'a', sourceField: 'topic', target: 'b', targetField: 'topic' }],
+  [{ id: 'pre-existing-id', source: 'a', target: 'b' }],
+  [
+    { source: 'a', target: 'b' },
+    { source: 'a', target: 'b' },                  // duplicate — needs index tiebreaker
+    { id: 'kept', source: 'c', target: 'd' },
+  ],
+  [null, { source: 'x', target: 'y' }, undefined],
+];
+
+const flowFixtures = [
+  null,
+  undefined,
+  'not-an-object',
+  { nodes: [], edges: [] },
+  {
+    schemaVersion: 2,
+    description: 'A '.repeat(200),
+    nodes: [
+      { id: 'in',  type: 'input' },
+      { id: 'a',   type: 'agent', data: { agentId: 'agent-real-id', model: 'gpt-5', label: 'A' } },
+      { id: 'b',   type: 'agent', data: { agentId: 'another-id', preferredModel: 'kimi' } },
+      { id: 'p',   type: 'pause' },
+      { id: 'cron',type: 'agent', data: { cron: '0 9 * * *' } },
+      { id: 'out', type: 'output' },
+    ],
+    edges: [{ source: 'in', target: 'a' }, { source: 'a', target: 'b' }],
+  },
+];
+
+describe('flowEdgeIds — server vs web-ui copy', () => {
+  test('exports the same surface', () => {
+    expect(typeof webUiEdgeIds.makeEdgeId).toBe('function');
+    expect(typeof webUiEdgeIds.ensureEdgeIds).toBe('function');
+  });
+
+  test('makeEdgeId outputs match for every fixture edge', () => {
+    const cases = [
+      [{ source: 'a', target: 'b' }, 0],
+      [{ source: 'a', sourceField: 'x', target: 'b', targetField: 'y' }, 7],
+      [{}, 0],
+      [null, 5],
+      [{ source: 'with:colons', target: 'b' }, 0],
+    ];
+    for (const [edge, idx] of cases) {
+      expect(webUiEdgeIds.makeEdgeId(edge, idx)).toBe(srvEdgeIds.makeEdgeId(edge, idx));
+    }
+  });
+
+  test('ensureEdgeIds outputs match for every fixture array', () => {
+    for (const fixture of edgeFixtures) {
+      const a = srvEdgeIds.ensureEdgeIds(fixture);
+      const b = webUiEdgeIds.ensureEdgeIds(fixture);
+      expect(b).toEqual(a);
+    }
+  });
+});
+
+describe('flowPublish — server vs web-ui copy', () => {
+  test('exports the same surface', () => {
+    expect(typeof webUiPublish.computeFlowPublishMetadata).toBe('function');
+    expect(typeof webUiPublish.sanitizeFlowForPublish).toBe('function');
+  });
+
+  test('computeFlowPublishMetadata outputs match for every fixture flow', () => {
+    for (const flow of flowFixtures) {
+      const a = srvPublish.computeFlowPublishMetadata(flow);
+      const b = webUiPublish.computeFlowPublishMetadata(flow);
+      expect(b).toEqual(a);
+    }
+  });
+
+  test('sanitizeFlowForPublish outputs match for every fixture flow', () => {
+    for (const flow of flowFixtures) {
+      const a = srvPublish.sanitizeFlowForPublish(flow);
+      const b = webUiPublish.sanitizeFlowForPublish(flow);
+      expect(b).toEqual(a);
+    }
+  });
+});

package/src/utilities/flowEdgeIds.js

@@ -0,0 +1,50 @@
+/**
+ * Edge-id stamping for flows.
+ *
+ * ReactFlow REQUIRES every edge to carry a unique `id`. Templates and
+ * marketplace-installed flows ship without ids — they're a v2 schema
+ * concern, not a renderer concern — so freshly-loaded flows render
+ * with NO arrows between their nodes until something stamps ids.
+ *
+ * Two layers in the stack apply this:
+ *   1. Server: `stateManager.createFlow` stamps on save so the durable
+ *      shape on disk is always renderable.
+ *   2. Client: `FlowEditor` stamps on load as defense-in-depth (covers
+ *      templates that mounted before the server ever saw them).
+ *
+ * Both layers use this same helper so the id format stays in sync.
+ */
+
+/**
+ * Build a stable id for an edge. Includes source/target plus the typed
+ * field names (when present) so re-saving the same flow doesn't churn
+ * ids and version diffs stay clean. The trailing index is the only
+ * non-stable component, used only as a tiebreaker for the rare case of
+ * two edges between the same pair with identical fields.
+ *
+ * @param {Object} edge - Edge with {source, sourceField?, target, targetField?}
+ * @param {number} idx  - Position in the edges array (for tiebreaking)
+ * @returns {string} Generated id
+ */
+export function makeEdgeId(edge, idx) {
+  const sf = edge?.sourceField ? `:${edge.sourceField}` : '';
+  const tf = edge?.targetField ? `:${edge.targetField}` : '';
+  return `e-${edge?.source || '?'}${sf}-${edge?.target || '?'}${tf}-${idx}`;
+}
+
+/**
+ * Stamp ids on every edge that doesn't already have one. Preserves
+ * existing ids verbatim (so user-supplied ids — e.g. from rollback or
+ * import — pass through unchanged). Returns a NEW array; doesn't
+ * mutate the input.
+ *
+ * @param {Array<Object>|null|undefined} rawEdges
+ * @returns {Array<Object>}
+ */
+export function ensureEdgeIds(rawEdges) {
+  if (!Array.isArray(rawEdges)) return [];
+  return rawEdges.map((e, idx) => {
+    if (e && typeof e === 'object' && e.id) return e;
+    return { ...(e || {}), id: makeEdgeId(e, idx) };
+  });
+}

package/src/utilities/flowPublish.js

@@ -0,0 +1,72 @@
+/**
+ * Flow publish helpers — pure functions used by the marketplace publish
+ * flow (PublishItemModal) and the marketplace install flow (MarketplacePage)
+ * to package and unpack flow definitions cleanly.
+ *
+ * Lives under `src/utilities/` (server-side path, plain ESM) so the
+ * server-side unit jest project can run tests for it. The web-ui
+ * imports it via a relative path — vite handles arbitrary paths.
+ */
+
+/**
+ * Compute a small metadata summary from a flow definition. Used by the
+ * marketplace `metadata` field — keeps the publish payload light while
+ * giving the marketplace card enough to render search results.
+ *
+ * @param {Object} flow - Flow definition (saved canvas + edges)
+ * @returns {Object} Metadata: schemaVersion, nodeCount, agentNodeCount,
+ *   edgeCount, models[], hasPauseNode, hasTriggerNode, goal.
+ */
+export function computeFlowPublishMetadata(flow) {
+  const nodes = Array.isArray(flow?.nodes) ? flow.nodes : [];
+  const edges = Array.isArray(flow?.edges) ? flow.edges : [];
+  const agentNodes = nodes.filter(n => n.type === 'agent');
+  // Distinct models referenced by the flow's agent nodes (best-effort —
+  // template flows ship with empty agentIds so models live on data.model
+  // when the user wired them; we collect whatever's there for searchability).
+  const models = Array.from(new Set(
+    agentNodes.map(n => n.data?.model || n.data?.preferredModel).filter(Boolean)
+  ));
+  // Specialty node types the marketplace card might want to call out.
+  const hasPauseNode   = nodes.some(n => n.type === 'pause' || n.type === 'human-input');
+  const hasTriggerNode = nodes.some(n => n.type === 'trigger' || !!n.data?.cron);
+  return {
+    schemaVersion:  flow?.schemaVersion ?? 1,
+    nodeCount:      nodes.length,
+    agentNodeCount: agentNodes.length,
+    edgeCount:      edges.length,
+    models,
+    hasPauseNode,
+    hasTriggerNode,
+    // Flow goal preserved verbatim — useful for marketplace listing copy.
+    goal: typeof flow?.description === 'string' ? flow.description.slice(0, 280) : '',
+  };
+}
+
+/**
+ * Strip per-installation identifiers from a flow before publishing. Local
+ * agentIds aren't portable — they're per-installation. The user re-wires
+ * after install. Same convention the in-app starter templates already
+ * use (they ship with `agentId: ''`).
+ *
+ * Pure function — does not mutate the input.
+ *
+ * @param {Object} flow - Flow definition
+ * @returns {Object} Sanitized clone safe to publish.
+ */
+export function sanitizeFlowForPublish(flow) {
+  if (!flow || typeof flow !== 'object') return flow;
+  const cleanNodes = (flow.nodes || []).map(n => {
+    if (n.type !== 'agent') return n;
+    return {
+      ...n,
+      data: {
+        ...(n.data || {}),
+        // Wipe local identity — the importer wires their own agent.
+        agentId: '',
+        // Keep the human label and instructions; they're the value.
+      },
+    };
+  });
+  return { ...flow, nodes: cleanNodes };
+}