@lumenflow/core 1.0.0

package/dist/spawn-registry-store.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Spawn Registry Store (WU-1944)
+ *
+ * Event-sourced state store for tracking sub-agent spawns.
+ * Stores events in .beacon/state/spawn-registry.jsonl (append-only, git-friendly).
+ *
+ * Features:
+ * - Event sourcing with replay for current state
+ * - Atomic append operations
+ * - O(1) queries by parent WU, target WU, and status
+ *
+ * @see {@link tools/lib/__tests__/spawn-registry-store.test.mjs} - Tests
+ * @see {@link tools/lib/spawn-registry-schema.mjs} - Schema definitions
+ */
+import { type SpawnEvent } from './spawn-registry-schema.js';
+/**
+ * Spawn registry file name constant
+ */
+export declare const SPAWN_REGISTRY_FILE_NAME = "spawn-registry.jsonl";
+/**
+ * Spawn Registry Store class
+ *
+ * Manages spawn registry state via event sourcing pattern.
+ * Events are appended to JSONL file, state is rebuilt by replaying events.
+ */
+export declare class SpawnRegistryStore {
+    private readonly baseDir;
+    private readonly registryFilePath;
+    private readonly spawns;
+    private readonly byParent;
+    private readonly byTarget;
+    /**
+     * @param {string} baseDir - Directory containing .beacon/state/
+     */
+    constructor(baseDir: string);
+    /**
+     * Loads and replays events from JSONL file into current state.
+     *
+     * Handles:
+     * - Missing file: returns empty state
+     * - Empty file: returns empty state
+     * - Empty lines: skipped gracefully
+     * - Malformed JSON: throws error with line info
+     * - Invalid events: throws validation error
+     *
+     * @returns {Promise<void>}
+     * @throws {Error} If file contains malformed JSON or invalid events
+     *
+     * @example
+     * const store = new SpawnRegistryStore('/path/to/project');
+     * await store.load();
+     * const pending = store.getPending();
+     */
+    load(): Promise<void>;
+    /**
+     * Applies an event to the in-memory state.
+     * If event for same spawn ID exists, updates it (latest wins).
+     *
+     * @private
+     */
+    private _applyEvent;
+    /**
+     * Appends an event to the registry file.
+     *
+     * Uses append mode to avoid full file rewrite.
+     * Creates file and parent directories if they don't exist.
+     * Validates event before appending.
+     *
+     * @private
+     * @throws {Error} If event fails validation
+     */
+    private _appendEvent;
+    /**
+     * Records a new spawn event with pending status.
+     *
+     * @param {string} parentWuId - Parent WU ID (orchestrator)
+     * @param {string} targetWuId - Target WU ID (spawned work)
+     * @param {string} lane - Lane for the spawned work
+     * @returns {Promise<string>} The generated spawn ID
+     * @throws {Error} If validation fails
+     *
+     * @example
+     * const spawnId = await store.record('WU-1000', 'WU-1001', 'Operations: Tooling');
+     */
+    record(parentWuId: string, targetWuId: string, lane: string): Promise<string>;
+    /**
+     * Updates the status of a spawn.
+     *
+     * @param {string} spawnId - Spawn ID to update
+     * @param {string} status - New status
+     * @returns {Promise<void>}
+     * @throws {Error} If spawn ID not found
+     *
+     * @example
+     * await store.updateStatus('spawn-a1b2', 'completed');
+     */
+    updateStatus(spawnId: string, status: string): Promise<void>;
+    /**
+     * Gets all spawns for a parent WU.
+     *
+     * @param {string} parentWuId - Parent WU ID
+     * @returns {SpawnEvent[]} Array of spawn events
+     *
+     * @example
+     * const spawns = store.getByParent('WU-1000');
+     */
+    getByParent(parentWuId: string): SpawnEvent[];
+    /**
+     * Gets spawn for a target WU.
+     *
+     * @param {string} targetWuId - Target WU ID
+     * @returns {SpawnEvent | null} Spawn event or null
+     *
+     * @example
+     * const spawn = store.getByTarget('WU-1001');
+     */
+    getByTarget(targetWuId: string): SpawnEvent | null;
+    /**
+     * Gets all pending spawns.
+     *
+     * @returns {SpawnEvent[]} Array of pending spawn events
+     *
+     * @example
+     * const pending = store.getPending();
+     */
+    getPending(): SpawnEvent[];
+    /**
+     * Gets all spawns as an array.
+     *
+     * @returns {SpawnEvent[]} Array of all spawn events
+     *
+     * @example
+     * const allSpawns = store.getAllSpawns();
+     */
+    getAllSpawns(): SpawnEvent[];
+    /**
+     * Gets spawn by ID.
+     *
+     * @param {string} spawnId - Spawn ID
+     * @returns {SpawnEvent | null} Spawn event or null
+     *
+     * @example
+     * const spawn = store.getById('spawn-a1b2');
+     */
+    getById(spawnId: string): SpawnEvent | null;
+}

package/dist/spawn-registry-store.js

@@ -0,0 +1,273 @@
+/**
+ * Spawn Registry Store (WU-1944)
+ *
+ * Event-sourced state store for tracking sub-agent spawns.
+ * Stores events in .beacon/state/spawn-registry.jsonl (append-only, git-friendly).
+ *
+ * Features:
+ * - Event sourcing with replay for current state
+ * - Atomic append operations
+ * - O(1) queries by parent WU, target WU, and status
+ *
+ * @see {@link tools/lib/__tests__/spawn-registry-store.test.mjs} - Tests
+ * @see {@link tools/lib/spawn-registry-schema.mjs} - Schema definitions
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { validateSpawnEvent, generateSpawnId, SpawnStatus, } from './spawn-registry-schema.js';
+/**
+ * Spawn registry file name constant
+ */
+export const SPAWN_REGISTRY_FILE_NAME = 'spawn-registry.jsonl';
+/**
+ * Spawn Registry Store class
+ *
+ * Manages spawn registry state via event sourcing pattern.
+ * Events are appended to JSONL file, state is rebuilt by replaying events.
+ */
+export class SpawnRegistryStore {
+    baseDir;
+    registryFilePath;
+    spawns;
+    byParent;
+    byTarget;
+    /**
+     * @param {string} baseDir - Directory containing .beacon/state/
+     */
+    constructor(baseDir) {
+        this.baseDir = baseDir;
+        this.registryFilePath = path.join(baseDir, SPAWN_REGISTRY_FILE_NAME);
+        // In-memory state (rebuilt from events)
+        this.spawns = new Map();
+        // Index: parentWuId -> spawnIds[]
+        this.byParent = new Map();
+        // Index: targetWuId -> spawnId
+        this.byTarget = new Map();
+    }
+    /**
+     * Loads and replays events from JSONL file into current state.
+     *
+     * Handles:
+     * - Missing file: returns empty state
+     * - Empty file: returns empty state
+     * - Empty lines: skipped gracefully
+     * - Malformed JSON: throws error with line info
+     * - Invalid events: throws validation error
+     *
+     * @returns {Promise<void>}
+     * @throws {Error} If file contains malformed JSON or invalid events
+     *
+     * @example
+     * const store = new SpawnRegistryStore('/path/to/project');
+     * await store.load();
+     * const pending = store.getPending();
+     */
+    async load() {
+        // Reset state
+        this.spawns.clear();
+        this.byParent.clear();
+        this.byTarget.clear();
+        // Check if file exists
+        let content;
+        try {
+            content = await fs.readFile(this.registryFilePath, 'utf-8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                // File doesn't exist - return empty state
+                return;
+            }
+            throw error;
+        }
+        // Parse JSONL content
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i].trim();
+            // Skip empty lines
+            if (!line) {
+                continue;
+            }
+            // Parse JSON line
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch (error) {
+                throw new Error(`Malformed JSON on line ${i + 1}: ${error.message}`);
+            }
+            // Validate against schema
+            const validation = validateSpawnEvent(parsed);
+            if (!validation.success) {
+                const issues = validation.error.issues
+                    .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+                    .join(', ');
+                throw new Error(`Validation error on line ${i + 1}: ${issues}`);
+            }
+            const event = validation.data;
+            // Apply event to state (latest event for same ID wins)
+            this._applyEvent(event);
+        }
+    }
+    /**
+     * Applies an event to the in-memory state.
+     * If event for same spawn ID exists, updates it (latest wins).
+     *
+     * @private
+     */
+    _applyEvent(event) {
+        const { id, parentWuId, targetWuId } = event;
+        // Update main state map
+        this.spawns.set(id, event);
+        // Update parent index
+        if (!this.byParent.has(parentWuId)) {
+            this.byParent.set(parentWuId, []);
+        }
+        const parentSpawns = this.byParent.get(parentWuId);
+        if (!parentSpawns.includes(id)) {
+            parentSpawns.push(id);
+        }
+        // Update target index
+        this.byTarget.set(targetWuId, id);
+    }
+    /**
+     * Appends an event to the registry file.
+     *
+     * Uses append mode to avoid full file rewrite.
+     * Creates file and parent directories if they don't exist.
+     * Validates event before appending.
+     *
+     * @private
+     * @throws {Error} If event fails validation
+     */
+    async _appendEvent(event) {
+        // Validate event before appending
+        const validation = validateSpawnEvent(event);
+        if (!validation.success) {
+            const issues = validation.error.issues
+                .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+                .join(', ');
+            throw new Error(`Validation error: ${issues}`);
+        }
+        const line = JSON.stringify(event) + '\n';
+        // Ensure parent directory exists before appending
+        await fs.mkdir(this.baseDir, { recursive: true });
+        // Use append flag to avoid rewriting the file
+        await fs.appendFile(this.registryFilePath, line, 'utf-8');
+    }
+    /**
+     * Records a new spawn event with pending status.
+     *
+     * @param {string} parentWuId - Parent WU ID (orchestrator)
+     * @param {string} targetWuId - Target WU ID (spawned work)
+     * @param {string} lane - Lane for the spawned work
+     * @returns {Promise<string>} The generated spawn ID
+     * @throws {Error} If validation fails
+     *
+     * @example
+     * const spawnId = await store.record('WU-1000', 'WU-1001', 'Operations: Tooling');
+     */
+    async record(parentWuId, targetWuId, lane) {
+        const id = generateSpawnId(parentWuId, targetWuId);
+        const event = {
+            id,
+            parentWuId,
+            targetWuId,
+            lane,
+            spawnedAt: new Date().toISOString(),
+            status: SpawnStatus.PENDING,
+            completedAt: null,
+        };
+        await this._appendEvent(event);
+        this._applyEvent(event);
+        return id;
+    }
+    /**
+     * Updates the status of a spawn.
+     *
+     * @param {string} spawnId - Spawn ID to update
+     * @param {string} status - New status
+     * @returns {Promise<void>}
+     * @throws {Error} If spawn ID not found
+     *
+     * @example
+     * await store.updateStatus('spawn-a1b2', 'completed');
+     */
+    async updateStatus(spawnId, status) {
+        const existing = this.spawns.get(spawnId);
+        if (!existing) {
+            throw new Error(`Spawn ID ${spawnId} not found`);
+        }
+        const event = {
+            ...existing,
+            status: status,
+            completedAt: new Date().toISOString(),
+        };
+        await this._appendEvent(event);
+        this._applyEvent(event);
+    }
+    /**
+     * Gets all spawns for a parent WU.
+     *
+     * @param {string} parentWuId - Parent WU ID
+     * @returns {SpawnEvent[]} Array of spawn events
+     *
+     * @example
+     * const spawns = store.getByParent('WU-1000');
+     */
+    getByParent(parentWuId) {
+        const spawnIds = this.byParent.get(parentWuId) ?? [];
+        return spawnIds
+            .map((id) => this.spawns.get(id))
+            .filter((event) => event !== undefined);
+    }
+    /**
+     * Gets spawn for a target WU.
+     *
+     * @param {string} targetWuId - Target WU ID
+     * @returns {SpawnEvent | null} Spawn event or null
+     *
+     * @example
+     * const spawn = store.getByTarget('WU-1001');
+     */
+    getByTarget(targetWuId) {
+        const spawnId = this.byTarget.get(targetWuId);
+        if (!spawnId) {
+            return null;
+        }
+        return this.spawns.get(spawnId) ?? null;
+    }
+    /**
+     * Gets all pending spawns.
+     *
+     * @returns {SpawnEvent[]} Array of pending spawn events
+     *
+     * @example
+     * const pending = store.getPending();
+     */
+    getPending() {
+        return Array.from(this.spawns.values()).filter((spawn) => spawn.status === SpawnStatus.PENDING);
+    }
+    /**
+     * Gets all spawns as an array.
+     *
+     * @returns {SpawnEvent[]} Array of all spawn events
+     *
+     * @example
+     * const allSpawns = store.getAllSpawns();
+     */
+    getAllSpawns() {
+        return Array.from(this.spawns.values());
+    }
+    /**
+     * Gets spawn by ID.
+     *
+     * @param {string} spawnId - Spawn ID
+     * @returns {SpawnEvent | null} Spawn event or null
+     *
+     * @example
+     * const spawn = store.getById('spawn-a1b2');
+     */
+    getById(spawnId) {
+        return this.spawns.get(spawnId) ?? null;
+    }
+}

package/dist/spawn-tree.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Spawn Tree Builder (WU-1950)
+ *
+ * Builds and formats spawn trees for visualization.
+ * Used by spawn:list command to display parent-child relationships.
+ *
+ * Note: Domain-specific tree visualization for spawn registry.
+ * Integrates with spawn-registry-store and spawn-registry-schema.
+ * No external tree library needed - logic is tightly coupled to spawn data model.
+ *
+ * @see {@link tools/__tests__/spawn-list.test.mjs} - Tests
+ * @see {@link tools/spawn-list.mjs} - CLI command
+ * @see {@link tools/lib/spawn-registry-store.mjs} - Data source
+ */
+/**
+ * Status indicators for terminal output.
+ * Using unicode symbols for clear visual distinction.
+ */
+export declare const STATUS_INDICATORS: Readonly<{
+    pending: "○";
+    completed: "✓";
+    timeout: "⏱";
+    crashed: "✗";
+}>;
+/**
+ * Tree node structure
+ * @typedef {object} SpawnTreeNode
+ * @property {string} wuId - WU ID for this node
+ * @property {string|null} spawnId - Spawn ID (null for root)
+ * @property {string|null} status - Spawn status (null for root)
+ * @property {string|null} lane - Lane (null for root)
+ * @property {string|null} spawnedAt - Spawn timestamp (null for root)
+ * @property {SpawnTreeNode[]} children - Child nodes
+ */
+/**
+ * Builds a spawn tree from flat spawn events.
+ *
+ * @param {import('./spawn-registry-schema.js').SpawnEvent[]} spawns - Array of spawn events
+ * @param {string} rootWuId - Root WU ID to build tree from
+ * @returns {SpawnTreeNode} Tree rooted at rootWuId
+ *
+ * @example
+ * const tree = buildSpawnTree(spawns, 'WU-1000');
+ * // { wuId: 'WU-1000', children: [{ wuId: 'WU-1001', ... }] }
+ */
+export declare function buildSpawnTree(spawns: any, rootWuId: any): {
+    wuId: any;
+    spawnId: any;
+    status: any;
+    lane: any;
+    spawnedAt: any;
+    children: any[];
+};
+/**
+ * Formats a spawn tree for terminal display with indentation and tree characters.
+ *
+ * @param {SpawnTreeNode} tree - Tree to format
+ * @returns {string} Formatted tree string
+ *
+ * @example
+ * const formatted = formatSpawnTree(tree);
+ * // WU-1000 (root)
+ * // ├── ○ WU-1001 [spawn-1111] (Operations: Tooling)
+ * // │   └── ✓ WU-1002 [spawn-2222] (Core: Backend)
+ * // └── ○ WU-1003 [spawn-3333] (Experience: Web)
+ */
+export declare function formatSpawnTree(tree: any): string;
+/**
+ * Gets all spawns for a WU (both where WU is parent and descendants).
+ *
+ * Returns all spawns needed to build the full tree from this WU.
+ *
+ * @param {string} wuId - WU ID to get spawns for
+ * @param {string} baseDir - Directory containing spawn-registry.jsonl
+ * @returns {Promise<import('./spawn-registry-schema.js').SpawnEvent[]>} Array of spawn events
+ *
+ * @example
+ * const spawns = await getSpawnsByWU('WU-1000', '.beacon/state');
+ */
+export declare function getSpawnsByWU(wuId: any, baseDir: any): Promise<any[]>;
+/**
+ * Gets all spawns for an initiative.
+ *
+ * Reads WU YAML files to find which WUs belong to the initiative,
+ * then returns all spawns where parent or target WU belongs to initiative.
+ *
+ * @param {string} initiativeId - Initiative ID (e.g., 'INIT-001')
+ * @param {string} registryDir - Directory containing spawn-registry.jsonl
+ * @param {string} wuDir - Directory containing WU YAML files
+ * @returns {Promise<import('./spawn-registry-schema.js').SpawnEvent[]>} Array of spawn events
+ *
+ * @example
+ * const spawns = await getSpawnsByInitiative('INIT-001', '.beacon/state', 'docs/04-operations/tasks/wu');
+ */
+export declare function getSpawnsByInitiative(initiativeId: any, registryDir: any, wuDir: any): Promise<{
+    id: string;
+    parentWuId: string;
+    targetWuId: string;
+    lane: string;
+    spawnedAt: string;
+    status: "completed" | "timeout" | "pending" | "crashed" | "escalated";
+    completedAt?: string;
+}[]>;
+/**
+ * Converts a spawn tree to JSON format.
+ *
+ * @param {SpawnTreeNode} tree - Tree to convert
+ * @returns {object} JSON-serializable tree
+ *
+ * @example
+ * const json = treeToJSON(tree);
+ * console.log(JSON.stringify(json, null, 2));
+ */
+export declare function treeToJSON(tree: any): {
+    wuId: any;
+    spawnId: any;
+    status: any;
+    lane: any;
+    spawnedAt: any;
+    children: any;
+};