@smithers-orchestrator/devtools 0.16.0

package/src/SmithersDevToolsCore.js

@@ -0,0 +1,146 @@
+import { buildSnapshot } from "./buildSnapshot.js";
+import { collectTasks } from "./collectTasks.js";
+import { DevToolsRunStore } from "./DevToolsRunStore.js";
+import { findNodeById } from "./findNodeById.js";
+import { printTree } from "./printTree.js";
+
+/** @typedef {import("./DevToolsEngineEvent.ts").DevToolsEngineEvent} DevToolsEngineEvent */
+/** @typedef {import("./DevToolsEventBus.ts").DevToolsEventBus} DevToolsEventBus */
+/** @typedef {import("./DevToolsNode.ts").DevToolsNode} DevToolsNode */
+/** @typedef {import("./DevToolsSnapshot.ts").DevToolsSnapshot} DevToolsSnapshot */
+/** @typedef {import("./RunExecutionState.ts").RunExecutionState} RunExecutionState */
+/** @typedef {import("./SmithersDevToolsOptions.ts").SmithersDevToolsOptions} SmithersDevToolsOptions */
+/** @typedef {import("./TaskExecutionState.ts").TaskExecutionState} TaskExecutionState */
+
+export class SmithersDevToolsCore {
+    /** @type {SmithersDevToolsOptions} */
+    options;
+    /** @type {DevToolsSnapshot | null} */
+    _lastSnapshot = null;
+    /** @type {DevToolsRunStore} */
+    _runStore;
+    /**
+     * @param {SmithersDevToolsOptions} [options]
+     */
+    constructor(options = {}) {
+        this.options = options;
+        this._runStore = new DevToolsRunStore(options);
+    }
+    /**
+     * @param {DevToolsNode | null} tree
+     * @returns {DevToolsSnapshot}
+     */
+    captureSnapshot(tree) {
+        const snapshot = buildSnapshot(tree);
+        this._lastSnapshot = snapshot;
+        return snapshot;
+    }
+    /**
+     * @param {DevToolsSnapshot} [snapshot]
+     * @returns {DevToolsSnapshot}
+     */
+    emitCommit(snapshot = this._lastSnapshot ?? buildSnapshot(null)) {
+        this.options.onCommit?.("commit", snapshot);
+        return snapshot;
+    }
+    /**
+     * @param {DevToolsNode | null} tree
+     * @returns {DevToolsSnapshot}
+     */
+    captureCommit(tree) {
+        const snapshot = this.captureSnapshot(tree);
+        this.emitCommit(snapshot);
+        return snapshot;
+    }
+    /**
+     * @param {DevToolsSnapshot} [snapshot]
+     * @returns {DevToolsSnapshot}
+     */
+    emitUnmount(snapshot = this._lastSnapshot ?? buildSnapshot(null)) {
+        this.options.onCommit?.("unmount", snapshot);
+        return snapshot;
+    }
+    /**
+     * @param {DevToolsEventBus} bus
+     * @returns {this}
+     */
+    attachEventBus(bus) {
+        this._runStore.attachEventBus(bus);
+        return this;
+    }
+    /** @returns {void} */
+    detachEventBuses() {
+        this._runStore.detachEventBuses();
+    }
+    /**
+     * @param {DevToolsEngineEvent} event
+     * @returns {void}
+     */
+    processEngineEvent(event) {
+        this._runStore.processEngineEvent(event);
+    }
+    /**
+     * @param {string} runId
+     * @returns {RunExecutionState | undefined}
+     */
+    getRun(runId) {
+        return this._runStore.getRun(runId);
+    }
+    /**
+     * @returns {Map<string, RunExecutionState>}
+     */
+    get runs() {
+        return this._runStore.runs;
+    }
+    /**
+     * @param {string} runId
+     * @param {string} nodeId
+     * @param {number} [iteration]
+     * @returns {TaskExecutionState | undefined}
+     */
+    getTaskState(runId, nodeId, iteration) {
+        return this._runStore.getTaskState(runId, nodeId, iteration);
+    }
+    /**
+     * Get the last captured snapshot.
+     * @returns {DevToolsSnapshot | null}
+     */
+    get snapshot() {
+        return this._lastSnapshot;
+    }
+    /**
+     * Get the current tree (shorthand).
+     * @returns {DevToolsNode | null}
+     */
+    get tree() {
+        return this._lastSnapshot?.tree ?? null;
+    }
+    /**
+     * Pretty-print the current tree to a string.
+     * @returns {string}
+     */
+    printTree() {
+        if (!this._lastSnapshot?.tree)
+            return "(no tree captured yet)";
+        return printTree(this._lastSnapshot.tree);
+    }
+    /**
+     * Find a node by task nodeId.
+     * @param {string} nodeId
+     * @returns {DevToolsNode | null}
+     */
+    findTask(nodeId) {
+        if (!this._lastSnapshot?.tree)
+            return null;
+        return findNodeById(this._lastSnapshot.tree, nodeId);
+    }
+    /**
+     * List all tasks in the current tree.
+     * @returns {DevToolsNode[]}
+     */
+    listTasks() {
+        if (!this._lastSnapshot?.tree)
+            return [];
+        return collectTasks(this._lastSnapshot.tree);
+    }
+}

package/src/SmithersDevToolsOptions.ts

@@ -0,0 +1,11 @@
+import type { DevToolsEngineEvent } from "./DevToolsEngineEvent.ts";
+import type { DevToolsEventHandler } from "./DevToolsEventHandler.ts";
+
+export type SmithersDevToolsOptions = {
+  /** Called on every renderer commit that touches the Smithers tree */
+  onCommit?: DevToolsEventHandler;
+  /** Called on every SmithersEvent from an attached EventBus */
+  onEngineEvent?: (event: DevToolsEngineEvent) => void;
+  /** Enable verbose console logging */
+  verbose?: boolean;
+};

package/src/SmithersNodeType.ts

@@ -0,0 +1,17 @@
+export type SmithersNodeType =
+  | "workflow"
+  | "task"
+  | "sequence"
+  | "parallel"
+  | "merge-queue"
+  | "branch"
+  | "loop"
+  | "worktree"
+  | "approval"
+  | "timer"
+  | "subflow"
+  | "wait-for-event"
+  | "saga"
+  | "try-catch"
+  | "fragment"
+  | "unknown";

package/src/SnapshotSerializerOptions.ts

@@ -0,0 +1,7 @@
+import type { SnapshotSerializerWarning } from "./SnapshotSerializerWarning.ts";
+
+export type SnapshotSerializerOptions = {
+  maxDepth?: number;
+  maxEntries?: number;
+  onWarning?: (warning: SnapshotSerializerWarning) => void;
+};

package/src/SnapshotSerializerWarning.ts

@@ -0,0 +1,9 @@
+export type SnapshotSerializerWarning = {
+  code:
+    | "CircularReference"
+    | "MaxDepthExceeded"
+    | "MaxEntriesExceeded"
+    | "UnsupportedType";
+  path: string;
+  detail?: string;
+};

package/src/TaskExecutionState.ts

@@ -0,0 +1,21 @@
+/** Execution state for a task, derived from SmithersEvent stream */
+export type TaskExecutionState = {
+  nodeId: string;
+  iteration: number;
+  status:
+    | "pending"
+    | "started"
+    | "finished"
+    | "failed"
+    | "cancelled"
+    | "skipped"
+    | "waiting-approval"
+    | "waiting-event"
+    | "waiting-timer"
+    | "retrying";
+  attempt: number;
+  startedAt?: number;
+  finishedAt?: number;
+  error?: unknown;
+  toolCalls: Array<{ name: string; seq: number; status?: "success" | "error" }>;
+};

package/src/applyDelta.js

@@ -0,0 +1,115 @@
+/** @typedef {import("./DevToolsNode.ts").DevToolsNode} DevToolsNode */
+/** @typedef {import("./DevToolsDelta.ts").DevToolsDelta} DevToolsDelta */
+/** @typedef {import("./DevToolsSnapshotV1.ts").DevToolsSnapshotV1} DevToolsSnapshotV1 */
+
+import { InvalidDeltaError } from "./InvalidDeltaError.js";
+
+/**
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+function cloneValue(value) {
+    if (typeof structuredClone === "function") {
+        return structuredClone(value);
+    }
+    return JSON.parse(JSON.stringify(value));
+}
+
+/**
+ * @param {DevToolsNode} root
+ * @param {number} id
+ * @returns {{ node: DevToolsNode; parent: DevToolsNode | null; index: number } | null}
+ */
+function findNode(root, id) {
+    /** @type {Array<{ node: DevToolsNode; parent: DevToolsNode | null; index: number }>} */
+    const stack = [{ node: root, parent: null, index: -1 }];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current) {
+            continue;
+        }
+        if (current.node.id === id) {
+            return current;
+        }
+        for (let index = current.node.children.length - 1; index >= 0; index -= 1) {
+            const child = current.node.children[index];
+            stack.push({ node: child, parent: current.node, index });
+        }
+    }
+    return null;
+}
+
+/**
+ * Apply a delta to a snapshot. Throws `InvalidDeltaError` for malformed ops.
+ *
+ * @param {DevToolsSnapshotV1} snapshot
+ * @param {DevToolsDelta} delta
+ * @returns {DevToolsSnapshotV1}
+ */
+export function applyDelta(snapshot, delta) {
+    if (delta.version !== 1) {
+        throw new InvalidDeltaError(`Unsupported delta version: ${String(delta.version)}`);
+    }
+    if (delta.baseSeq !== snapshot.seq) {
+        throw new InvalidDeltaError(`Delta base seq ${delta.baseSeq} does not match snapshot seq ${snapshot.seq}.`);
+    }
+    /** @type {DevToolsSnapshotV1} */
+    const next = {
+        ...snapshot,
+        frameNo: delta.seq,
+        seq: delta.seq,
+        root: /** @type {DevToolsNode} */ (cloneValue(snapshot.root)),
+    };
+    for (const op of delta.ops) {
+        if (op.op === "replaceRoot") {
+            if (!op.node || typeof op.node !== "object") {
+                throw new InvalidDeltaError("replaceRoot requires a node.");
+            }
+            next.root = /** @type {DevToolsNode} */ (cloneValue(op.node));
+            continue;
+        }
+        if (op.op === "removeNode") {
+            if (op.id === next.root.id) {
+                throw new InvalidDeltaError("Cannot remove the root node.");
+            }
+            const target = findNode(next.root, op.id);
+            if (!target || !target.parent) {
+                throw new InvalidDeltaError(`Unknown node id: ${op.id}`);
+            }
+            target.parent.children.splice(target.index, 1);
+            continue;
+        }
+        if (op.op === "addNode") {
+            const parent = findNode(next.root, op.parentId);
+            if (!parent) {
+                throw new InvalidDeltaError(`Unknown parent id: ${op.parentId}`);
+            }
+            const index = Math.max(0, Math.min(op.index, parent.node.children.length));
+            parent.node.children.splice(index, 0, /** @type {DevToolsNode} */ (cloneValue(op.node)));
+            continue;
+        }
+        if (op.op === "updateProps") {
+            const target = findNode(next.root, op.id);
+            if (!target) {
+                throw new InvalidDeltaError(`Unknown node id: ${op.id}`);
+            }
+            target.node.props = /** @type {Record<string, unknown>} */ (cloneValue(op.props));
+            continue;
+        }
+        if (op.op === "updateTask") {
+            const target = findNode(next.root, op.id);
+            if (!target) {
+                throw new InvalidDeltaError(`Unknown node id: ${op.id}`);
+            }
+            if (op.task === undefined) {
+                delete target.node.task;
+            }
+            else {
+                target.node.task = /** @type {DevToolsNode["task"]} */ (cloneValue(op.task));
+            }
+            continue;
+        }
+        throw new InvalidDeltaError(`Unknown op: ${String(op?.op)}`);
+    }
+    return next;
+}

package/src/buildSnapshot.js

@@ -0,0 +1,15 @@
+import { countNodes } from "./countNodes.js";
+/** @typedef {import("./DevToolsNode.ts").DevToolsNode} DevToolsNode */
+/** @typedef {import("./DevToolsSnapshot.ts").DevToolsSnapshot} DevToolsSnapshot */
+
+/**
+ * @param {DevToolsNode | null} root
+ * @returns {DevToolsSnapshot}
+ */
+export function buildSnapshot(root) {
+    if (!root) {
+        return { tree: null, nodeCount: 0, taskCount: 0, timestamp: Date.now() };
+    }
+    const { nodes, tasks } = countNodes(root);
+    return { tree: root, nodeCount: nodes, taskCount: tasks, timestamp: Date.now() };
+}

package/src/collectTasks.js

@@ -0,0 +1,15 @@
+
+/** @typedef {import("./DevToolsNode.ts").DevToolsNode} DevToolsNode */
+/**
+ * @param {DevToolsNode} node
+ * @param {DevToolsNode[]} [out]
+ * @returns {DevToolsNode[]}
+ */
+export function collectTasks(node, out = []) {
+    if (node.type === "task")
+        out.push(node);
+    for (const child of node.children) {
+        collectTasks(child, out);
+    }
+    return out;
+}

package/src/countNodes.js

@@ -0,0 +1,16 @@
+
+/** @typedef {import("./DevToolsNode.ts").DevToolsNode} DevToolsNode */
+/**
+ * @param {DevToolsNode} node
+ * @returns {{ nodes: number; tasks: number }}
+ */
+export function countNodes(node) {
+    let nodes = 1;
+    let tasks = node.type === "task" ? 1 : 0;
+    for (const child of node.children) {
+        const c = countNodes(child);
+        nodes += c.nodes;
+        tasks += c.tasks;
+    }
+    return { nodes, tasks };
+}

package/src/diffSnapshots.js

@@ -0,0 +1,211 @@
+/** @typedef {import("./DevToolsNode.ts").DevToolsNode} DevToolsNode */
+/** @typedef {import("./DevToolsDelta.ts").DevToolsDelta} DevToolsDelta */
+/** @typedef {import("./DevToolsDeltaOp.ts").DevToolsDeltaOp} DevToolsDeltaOp */
+/** @typedef {import("./DevToolsSnapshotV1.ts").DevToolsSnapshotV1} DevToolsSnapshotV1 */
+
+/**
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+function cloneValue(value) {
+    if (typeof structuredClone === "function") {
+        return structuredClone(value);
+    }
+    return JSON.parse(JSON.stringify(value));
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * @param {unknown} left
+ * @param {unknown} right
+ * @returns {boolean}
+ */
+function deepEqual(left, right) {
+    if (Object.is(left, right)) {
+        return true;
+    }
+    if (typeof left !== typeof right) {
+        return false;
+    }
+    if (left === null || right === null) {
+        return left === right;
+    }
+    if (Array.isArray(left) && Array.isArray(right)) {
+        if (left.length !== right.length) {
+            return false;
+        }
+        for (let index = 0; index < left.length; index += 1) {
+            if (!deepEqual(left[index], right[index])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    if (isRecord(left) && isRecord(right)) {
+        const leftKeys = Object.keys(left);
+        const rightKeys = Object.keys(right);
+        if (leftKeys.length !== rightKeys.length) {
+            return false;
+        }
+        leftKeys.sort();
+        rightKeys.sort();
+        for (let index = 0; index < leftKeys.length; index += 1) {
+            if (leftKeys[index] !== rightKeys[index]) {
+                return false;
+            }
+        }
+        for (const key of leftKeys) {
+            if (!deepEqual(left[key], right[key])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    return false;
+}
+
+/**
+ * @param {DevToolsNode} root
+ * @returns {Map<number, { node: DevToolsNode; parentId: number | null; index: number }>}
+ */
+function indexTree(root) {
+    /** @type {Map<number, { node: DevToolsNode; parentId: number | null; index: number }>} */
+    const indexed = new Map();
+    /** @type {Array<{ node: DevToolsNode; parentId: number | null; index: number }>} */
+    const stack = [{ node: root, parentId: null, index: 0 }];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current) {
+            continue;
+        }
+        indexed.set(current.node.id, current);
+        for (let childIndex = current.node.children.length - 1; childIndex >= 0; childIndex -= 1) {
+            const child = current.node.children[childIndex];
+            stack.push({
+                node: child,
+                parentId: current.node.id,
+                index: childIndex,
+            });
+        }
+    }
+    return indexed;
+}
+
+/**
+ * @param {DevToolsNode} left
+ * @param {DevToolsNode} right
+ * @returns {boolean}
+ */
+function sameNodeShape(left, right) {
+    return left.type === right.type &&
+        left.name === right.name &&
+        left.depth === right.depth;
+}
+
+/**
+ * Compute a delta from snapshot `a` to snapshot `b`.
+ *
+ * @param {DevToolsSnapshotV1} a
+ * @param {DevToolsSnapshotV1} b
+ * @returns {DevToolsDelta}
+ */
+export function diffSnapshots(a, b) {
+    if (a.runId !== b.runId) {
+        throw new Error("Cannot diff snapshots from different runs.");
+    }
+    // Root replacement: if the root's identity (id) changed, or its shape
+    // changed, emit a single replaceRoot op rather than trying to remove + add
+    // the root in place (the root cannot be removed).
+    if (a.root.id !== b.root.id || !sameNodeShape(a.root, b.root)) {
+        return {
+            version: 1,
+            baseSeq: a.seq,
+            seq: b.seq,
+            ops: [{
+                    op: "replaceRoot",
+                    node: /** @type {DevToolsNode} */ (cloneValue(b.root)),
+                }],
+        };
+    }
+    const from = indexTree(a.root);
+    const to = indexTree(b.root);
+    /** @type {Set<number>} */
+    const removeSet = new Set();
+    /** @type {Set<number>} */
+    const addSet = new Set();
+    /** @type {DevToolsDeltaOp[]} */
+    const updateOps = [];
+    for (const [id, fromEntry] of from.entries()) {
+        const toEntry = to.get(id);
+        if (!toEntry) {
+            removeSet.add(id);
+            continue;
+        }
+        const moved = fromEntry.parentId !== toEntry.parentId || fromEntry.index !== toEntry.index;
+        const replaced = !sameNodeShape(fromEntry.node, toEntry.node);
+        if (moved || replaced) {
+            removeSet.add(id);
+            addSet.add(id);
+            continue;
+        }
+        if (!deepEqual(fromEntry.node.props, toEntry.node.props)) {
+            updateOps.push({
+                op: "updateProps",
+                id,
+                props: /** @type {Record<string, unknown>} */ (cloneValue(toEntry.node.props)),
+            });
+        }
+        if (!deepEqual(fromEntry.node.task, toEntry.node.task)) {
+            updateOps.push({
+                op: "updateTask",
+                id,
+                task: /** @type {DevToolsNode["task"]} */ (cloneValue(toEntry.node.task)),
+            });
+        }
+    }
+    for (const [id] of to.entries()) {
+        if (!from.has(id)) {
+            addSet.add(id);
+        }
+    }
+    /** @type {DevToolsDeltaOp[]} */
+    const removeOps = [...removeSet]
+        .sort((leftId, rightId) => (from.get(rightId)?.node.depth ?? 0) - (from.get(leftId)?.node.depth ?? 0))
+        .map((id) => ({ op: "removeNode", id }));
+    const topLevelAddIds = [...addSet].filter((id) => {
+        const parentId = to.get(id)?.parentId;
+        return parentId === null || !addSet.has(parentId);
+    });
+    /** @type {DevToolsDeltaOp[]} */
+    const addOps = topLevelAddIds
+        .sort((leftId, rightId) => (to.get(leftId)?.node.depth ?? 0) - (to.get(rightId)?.node.depth ?? 0))
+        .map((id) => {
+        const entry = to.get(id);
+        if (!entry || entry.parentId === null) {
+            return /** @type {DevToolsDeltaOp} */ ({
+                op: "updateProps",
+                id,
+                props: /** @type {Record<string, unknown>} */ (cloneValue(entry?.node.props ?? {})),
+            });
+        }
+        return /** @type {DevToolsDeltaOp} */ ({
+            op: "addNode",
+            parentId: entry.parentId,
+            index: entry.index,
+            node: /** @type {DevToolsNode} */ (cloneValue(entry.node)),
+        });
+    });
+    return {
+        version: 1,
+        baseSeq: a.seq,
+        seq: b.seq,
+        ops: [...removeOps, ...addOps, ...updateOps],
+    };
+}

package/src/findNodeById.js

@@ -0,0 +1,17 @@
+
+/** @typedef {import("./DevToolsNode.ts").DevToolsNode} DevToolsNode */
+/**
+ * @param {DevToolsNode} node
+ * @param {string} nodeId
+ * @returns {DevToolsNode | null}
+ */
+export function findNodeById(node, nodeId) {
+    if (node.task?.nodeId === nodeId)
+        return node;
+    for (const child of node.children) {
+        const found = findNodeById(child, nodeId);
+        if (found)
+            return found;
+    }
+    return null;
+}