@lumenflow/core 3.1.3 → 3.2.1

package/dist/state-machine.js

@@ -0,0 +1,89 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * State Machine Validation Library
+ *
+ * Enforces canonical WU state transitions according to LumenFlow §2.4
+ * Prevents illegal state changes (e.g., done → in_progress) and ensures workflow integrity.
+ *
+ * Canonical state machine:
+ * - ready → in_progress (claim)
+ * - in_progress → blocked (block)
+ * - in_progress → waiting (implementation complete, awaiting sign-off)
+ * - in_progress → done (direct completion)
+ * - in_progress → ready (release - WU-1080: orphan recovery)
+ * - blocked → in_progress (unblock)
+ * - blocked → done (blocker resolved, direct completion)
+ * - waiting → in_progress (changes requested)
+ * - waiting → done (approved)
+ * - done → (terminal, no transitions)
+ */
+import { createError, ErrorCodes } from './error-handler.js';
+/**
+ * Valid WU states as defined in LumenFlow §2.4
+ */
+const VALID_STATES = new Set(['ready', 'in_progress', 'blocked', 'waiting', 'done']);
+/**
+ * Transition table mapping each state to its allowed next states
+ * Based on LumenFlow §2.4 Flow States & Lanes
+ */
+const TRANSITIONS = {
+    ready: ['in_progress'],
+    in_progress: ['blocked', 'waiting', 'done', 'ready'], // WU-1080: 'ready' via release for orphan recovery
+    blocked: ['in_progress', 'done'],
+    waiting: ['in_progress', 'done'],
+    done: [], // Terminal state - no outgoing transitions
+};
+/**
+ * Validates a state transition and throws if illegal
+ *
+ * @param {string|null|undefined} from - Current WU status
+ * @param {string|null|undefined} to - Desired WU status
+ * @param {string} wuid - Work Unit ID (e.g., 'WU-416') for error messages
+ * @throws {Error} If transition is illegal or states are invalid
+ */
+export function assertTransition(from, to, wuid) {
+    // Validate states exist and are non-empty
+    if (from === null || from === undefined || from === '') {
+        throw createError(ErrorCodes.STATE_ERROR, `Invalid state: ${from}`, {
+            wuid,
+            from,
+            to,
+            reason: 'from state is null/undefined/empty',
+        });
+    }
+    if (to === null || to === undefined || to === '') {
+        throw createError(ErrorCodes.STATE_ERROR, `Invalid state: ${to}`, {
+            wuid,
+            from,
+            to,
+            reason: 'to state is null/undefined/empty',
+        });
+    }
+    // Validate states are recognized
+    if (!VALID_STATES.has(from)) {
+        throw createError(ErrorCodes.STATE_ERROR, `Invalid state: ${from}`, {
+            wuid,
+            from,
+            to,
+            validStates: Array.from(VALID_STATES),
+        });
+    }
+    if (!VALID_STATES.has(to)) {
+        throw createError(ErrorCodes.STATE_ERROR, `Invalid state: ${to}`, {
+            wuid,
+            from,
+            to,
+            validStates: Array.from(VALID_STATES),
+        });
+    }
+    // Check if transition is allowed
+    const fromState = from;
+    const toState = to;
+    const allowedNextStates = TRANSITIONS[fromState];
+    if (!allowedNextStates.includes(toState)) {
+        const terminalHint = from === 'done' ? ' (done is a terminal state)' : '';
+        throw createError(ErrorCodes.STATE_ERROR, `Illegal state transition for ${wuid}: ${from} → ${to}${terminalHint}`, { wuid, from, to, allowedNextStates });
+    }
+}
+//# sourceMappingURL=state-machine.js.map

package/dist/state-machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.js","sourceRoot":"","sources":["../src/state-machine.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE7D;;GAEG;AACH,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;AAGrF;;;GAGG;AACH,MAAM,WAAW,GAA+B;IAC9C,KAAK,EAAE,CAAC,aAAa,CAAC;IACtB,WAAW,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mDAAmD;IACzG,OAAO,EAAE,CAAC,aAAa,EAAE,MAAM,CAAC;IAChC,OAAO,EAAE,CAAC,aAAa,EAAE,MAAM,CAAC;IAChC,IAAI,EAAE,EAAE,EAAE,2CAA2C;CACtD,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAA+B,EAC/B,EAA6B,EAC7B,IAAY;IAEZ,0CAA0C;IAC1C,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QACvD,MAAM,WAAW,CAAC,UAAU,CAAC,WAAW,EAAE,kBAAkB,IAAI,EAAE,EAAE;YAClE,IAAI;YACJ,IAAI;YACJ,EAAE;YACF,MAAM,EAAE,oCAAoC;SAC7C,CAAC,CAAC;IACL,CAAC;IACD,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACjD,MAAM,WAAW,CAAC,UAAU,CAAC,WAAW,EAAE,kBAAkB,EAAE,EAAE,EAAE;YAChE,IAAI;YACJ,IAAI;YACJ,EAAE;YACF,MAAM,EAAE,kCAAkC;SAC3C,CAAC,CAAC;IACL,CAAC;IAED,iCAAiC;IACjC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAe,CAAC,EAAE,CAAC;QACvC,MAAM,WAAW,CAAC,UAAU,CAAC,WAAW,EAAE,kBAAkB,IAAI,EAAE,EAAE;YAClE,IAAI;YACJ,IAAI;YACJ,EAAE;YACF,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC;SACtC,CAAC,CAAC;IACL,CAAC;IACD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,EAAa,CAAC,EAAE,CAAC;QACrC,MAAM,WAAW,CAAC,UAAU,CAAC,WAAW,EAAE,kBAAkB,EAAE,EAAE,EAAE;YAChE,IAAI;YACJ,IAAI;YACJ,EAAE;YACF,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC;SACtC,CAAC,CAAC;IACL,CAAC;IAED,iCAAiC;IACjC,MAAM,SAAS,GAAG,IAAe,CAAC;IAClC,MAAM,OAAO,GAAG,EAAa,CAAC;IAC9B,MAAM,iBAAiB,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;IACjD,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACzC,MAAM,YAAY,GAAG,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,6BAA6B,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1E,MAAM,WAAW,CACf,UAAU,CAAC,WAAW,EACtB,gCAAgC,IAAI,KAAK,IAAI,MAAM,EAAE,GAAG,YAAY,EAAE,EACtE,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,iBAAiB,EAAE,CACtC,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/stream-error-handler.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Stream Error Handler
+ *
+ * WU-1233: Centralized EPIPE protection for CLI commands.
+ *
+ * When CLI output is piped through head/tail, the pipe may close before
+ * all output is written. Node.js throws EPIPE errors in this case.
+ * This handler catches those errors and exits gracefully.
+ *
+ * Unix convention: Exit with code 0 on EPIPE (the consumer got what it needed).
+ *
+ * @example
+ * ```typescript
+ * import { StreamErrorHandler } from '@lumenflow/core';
+ *
+ * // In CLI entry point:
+ * const handler = StreamErrorHandler.createWithDefaults();
+ * handler.attach();
+ * ```
+ */
+import type { WriteStream } from 'node:tty';
+/**
+ * Dependencies for StreamErrorHandler
+ *
+ * Uses dependency injection for testability.
+ */
+export interface StreamErrorHandlerDeps {
+    /** Standard output stream */
+    stdout: WriteStream;
+    /** Standard error stream */
+    stderr: WriteStream;
+    /** Exit function (defaults to setting process.exitCode) */
+    exitFn: (code: number) => void;
+}
+export declare function setProcessExitCode(code: number): void;
+/**
+ * StreamErrorHandler
+ *
+ * Attaches error listeners to stdout/stderr to handle EPIPE errors gracefully.
+ * Follows single responsibility principle - only handles stream errors.
+ */
+export declare class StreamErrorHandler {
+    private readonly deps;
+    private attached;
+    private stdoutHandler;
+    private stderrHandler;
+    constructor(deps: StreamErrorHandlerDeps);
+    /**
+     * Create a handler with default dependencies (process.stdout, process.stderr, process.exitCode)
+     */
+    static createWithDefaults(): StreamErrorHandler;
+    /**
+     * Attach error listeners to stdout and stderr
+     *
+     * Safe to call multiple times - will not attach duplicate listeners.
+     */
+    attach(): void;
+    /**
+     * Detach error listeners from stdout and stderr
+     *
+     * Safe to call even if not attached.
+     */
+    detach(): void;
+    /**
+     * Create an error handler that catches EPIPE and exits gracefully
+     */
+    private createErrorHandler;
+}
+//# sourceMappingURL=stream-error-handler.d.ts.map

package/dist/stream-error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-error-handler.d.ts","sourceRoot":"","sources":["../src/stream-error-handler.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAG5C;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,6BAA6B;IAC7B,MAAM,EAAE,WAAW,CAAC;IACpB,4BAA4B;IAC5B,MAAM,EAAE,WAAW,CAAC;IACpB,2DAA2D;IAC3D,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AASD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAErD;AAED;;;;;GAKG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyB;IAC9C,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,aAAa,CAAiD;IACtE,OAAO,CAAC,aAAa,CAAiD;gBAE1D,IAAI,EAAE,sBAAsB;IAIxC;;OAEG;IACH,MAAM,CAAC,kBAAkB,IAAI,kBAAkB;IAQ/C;;;;OAIG;IACH,MAAM,IAAI,IAAI;IAcd;;;;OAIG;IACH,MAAM,IAAI,IAAI;IAkBd;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAW3B"}

package/dist/stream-error-handler.js

@@ -0,0 +1,80 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+import { STREAM_ERRORS, EXIT_CODES } from './wu-constants.js';
+export function setProcessExitCode(code) {
+    process.exitCode = code;
+}
+/**
+ * StreamErrorHandler
+ *
+ * Attaches error listeners to stdout/stderr to handle EPIPE errors gracefully.
+ * Follows single responsibility principle - only handles stream errors.
+ */
+export class StreamErrorHandler {
+    deps;
+    attached = false;
+    stdoutHandler = null;
+    stderrHandler = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Create a handler with default dependencies (process.stdout, process.stderr, process.exitCode)
+     */
+    static createWithDefaults() {
+        return new StreamErrorHandler({
+            stdout: process.stdout,
+            stderr: process.stderr,
+            exitFn: setProcessExitCode,
+        });
+    }
+    /**
+     * Attach error listeners to stdout and stderr
+     *
+     * Safe to call multiple times - will not attach duplicate listeners.
+     */
+    attach() {
+        if (this.attached) {
+            return;
+        }
+        this.stdoutHandler = this.createErrorHandler();
+        this.stderrHandler = this.createErrorHandler();
+        this.deps.stdout.on('error', this.stdoutHandler);
+        this.deps.stderr.on('error', this.stderrHandler);
+        this.attached = true;
+    }
+    /**
+     * Detach error listeners from stdout and stderr
+     *
+     * Safe to call even if not attached.
+     */
+    detach() {
+        if (!this.attached) {
+            return;
+        }
+        if (this.stdoutHandler) {
+            this.deps.stdout.removeListener('error', this.stdoutHandler);
+            this.stdoutHandler = null;
+        }
+        if (this.stderrHandler) {
+            this.deps.stderr.removeListener('error', this.stderrHandler);
+            this.stderrHandler = null;
+        }
+        this.attached = false;
+    }
+    /**
+     * Create an error handler that catches EPIPE and exits gracefully
+     */
+    createErrorHandler() {
+        return (err) => {
+            // Only handle EPIPE errors
+            if (err.code === STREAM_ERRORS.EPIPE) {
+                // Exit gracefully with success code (Unix convention)
+                // The consumer of the pipe got what it needed
+                this.deps.exitFn(EXIT_CODES.SUCCESS);
+            }
+            // Non-EPIPE errors are not handled here - let them propagate
+        };
+    }
+}
+//# sourceMappingURL=stream-error-handler.js.map

package/dist/stream-error-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-error-handler.js","sourceRoot":"","sources":["../src/stream-error-handler.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAwBzC,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAuB9D,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,kBAAkB;IACZ,IAAI,CAAyB;IACtC,QAAQ,GAAG,KAAK,CAAC;IACjB,aAAa,GAA4C,IAAI,CAAC;IAC9D,aAAa,GAA4C,IAAI,CAAC;IAEtE,YAAY,IAA4B;QACtC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,kBAAkB;QACvB,OAAO,IAAI,kBAAkB,CAAC;YAC5B,MAAM,EAAE,OAAO,CAAC,MAAqB;YACrC,MAAM,EAAE,OAAO,CAAC,MAAqB;YACrC,MAAM,EAAE,kBAAkB;SAC3B,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,MAAM;QACJ,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,OAAO;QACT,CAAC;QAED,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC/C,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAE/C,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;QAEjD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,MAAM;QACJ,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,OAAO;QACT,CAAC;QAED,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;YAC7D,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;QAC5B,CAAC;QAED,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;YAC7D,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;QAC5B,CAAC;QAED,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;IACxB,CAAC;IAED;;OAEG;IACK,kBAAkB;QACxB,OAAO,CAAC,GAAoB,EAAE,EAAE;YAC9B,2BAA2B;YAC3B,IAAI,GAAG,CAAC,IAAI,KAAK,aAAa,CAAC,KAAK,EAAE,CAAC;gBACrC,sDAAsD;gBACtD,8CAA8C;gBAC9C,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;YACvC,CAAC;YACD,6DAA6D;QAC/D,CAAC,CAAC;IACJ,CAAC;CACF"}

package/dist/telemetry.d.ts

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * Telemetry Module - DORA/SPACE Metrics Emission
+ *
+ * Emits structured NDJSON telemetry for gates execution and WU flow metrics.
+ * Used by gates-local.ts and flow-report.ts.
+ */
+/**
+ * Emit a telemetry event as NDJSON
+ * @param {string} filePath - Path to NDJSON file
+ * @param {object} event - Event data to emit
+ */
+export declare function emit(filePath: UnsafeAny, event: UnsafeAny): void;
+/**
+ * Emit a gates execution event
+ * @param {object} data - Gates event data
+ * @param {string} data.wu_id - Work Unit ID (e.g., 'WU-402')
+ * @param {string} data.lane - Lane name (e.g., 'Operations')
+ * @param {string} data.gate_name - Gate name (e.g., 'format:check')
+ * @param {boolean} data.passed - Whether gate passed
+ * @param {number} data.duration_ms - Execution duration in milliseconds
+ */
+export declare function emitGateEvent(data: UnsafeAny): void;
+/**
+ * Get current WU ID from git branch or environment
+ * @returns {string|null} WU ID or null
+ */
+export declare function getCurrentWU(): string | null;
+/**
+ * Get lane from git branch or environment
+ * @returns {string|null} Lane name or null
+ */
+export declare function getCurrentLane(): string | null;
+/**
+ * Emit LLM classification start event
+ * @param {object} data - Classification start data
+ * @param {string} data.classification_type - Type of classification (e.g., 'mode_detection', 'red_flag', 'sensitive_data_detection')
+ * @param {boolean} [data.has_context] - Whether conversation context was provided
+ * @param {string} [data.wu_id] - Work Unit ID
+ * @param {string} [data.lane] - Lane name
+ * @param {string} [logPath] - Optional log path override (for testing)
+ */
+export declare function emitLLMClassificationStart(data: UnsafeAny, logPath?: string): void;
+/**
+ * Emit LLM classification complete event
+ * @param {object} data - Classification completion data
+ * @param {string} data.classification_type - Type of classification
+ * @param {number} data.duration_ms - Processing duration in milliseconds
+ * @param {number} data.tokens_used - Total tokens consumed
+ * @param {number} data.estimated_cost_usd - Estimated cost in USD
+ * @param {number} data.confidence - Classification confidence score (0-1)
+ * @param {boolean} data.fallback_used - Whether fallback (regex) was used
+ * @param {string} [data.fallback_reason] - Reason fallback was triggered
+ * @param {string} [data.wu_id] - Work Unit ID
+ * @param {string} [data.lane] - Lane name
+ * @param {string} [logPath] - Optional log path override (for testing)
+ */
+export declare function emitLLMClassificationComplete(data: UnsafeAny, logPath?: string): void;
+/**
+ * Emit LLM classification error event
+ * @param {object} data - Classification error data
+ * @param {string} data.classification_type - Type of classification
+ * @param {string} data.error_type - Error type (e.g., 'timeout', 'rate_limit', 'validation')
+ * @param {string} data.error_message - Error message (must be PII-free)
+ * @param {number} [data.duration_ms] - Duration before error occurred
+ * @param {string} [data.wu_id] - Work Unit ID
+ * @param {string} [data.lane] - Lane name
+ * @param {string} [logPath] - Optional log path override (for testing)
+ */
+export declare function emitLLMClassificationError(data: UnsafeAny, logPath?: string): void;
+/**
+ * Emit WU flow telemetry event to .lumenflow/flow.log
+ *
+ * Used by wu-claim, wu-done, wu-unblock for workflow tracking.
+ * Centralized from duplicated emitTelemetry() functions (WU-1256).
+ *
+ * @param {object} event - Event data (script, wu_id, lane, step, etc.)
+ * @param {string} [logPath] - Optional log path override (for testing)
+ */
+export declare function emitWUFlowEvent(event: UnsafeAny, logPath?: string): void;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":";AAGA;;;;;GAKG;AAuBH;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,QASzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,QAU5C;AAED;;;GAGG;AACH,wBAAgB,YAAY,kBAiB3B;AAED;;;GAGG;AACH,wBAAgB,cAAc,kBAkB7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,SAAyB,QAU3F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,SAAyB,QAqB9F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,SAAyB,QAsB3F;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,SAAW,QAanE"}

package/dist/telemetry.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Telemetry Module - DORA/SPACE Metrics Emission
+ *
+ * Emits structured NDJSON telemetry for gates execution and WU flow metrics.
+ * Used by gates-local.ts and flow-report.ts.
+ */
+import { appendFileSync, mkdirSync, existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import path from 'node:path';
+import { LUMENFLOW_PATHS, FILE_EXTENSIONS, STDIO, STRING_LITERALS } from './wu-constants.js';
+const TELEMETRY_DIR = LUMENFLOW_PATHS.TELEMETRY;
+const GATES_LOG = `${TELEMETRY_DIR}/gates${FILE_EXTENSIONS.NDJSON}`;
+const LLM_CLASSIFICATION_LOG = `${TELEMETRY_DIR}/llm-classification${FILE_EXTENSIONS.NDJSON}`;
+const FLOW_LOG = LUMENFLOW_PATHS.FLOW_LOG;
+/**
+ * Ensure telemetry directory exists
+ */
+function ensureTelemetryDir() {
+    try {
+        mkdirSync(TELEMETRY_DIR, { recursive: true });
+    }
+    catch {
+        // Directory may already exist, ignore
+    }
+}
+/**
+ * Emit a telemetry event as NDJSON
+ * @param {string} filePath - Path to NDJSON file
+ * @param {object} event - Event data to emit
+ */
+export function emit(filePath, event) {
+    ensureTelemetryDir();
+    const line = `${JSON.stringify(event)}${STRING_LITERALS.NEWLINE}`;
+    try {
+        appendFileSync(filePath, line, { encoding: 'utf-8' });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[telemetry] Failed to emit to ${filePath}:`, message);
+    }
+}
+/**
+ * Emit a gates execution event
+ * @param {object} data - Gates event data
+ * @param {string} data.wu_id - Work Unit ID (e.g., 'WU-402')
+ * @param {string} data.lane - Lane name (e.g., 'Operations')
+ * @param {string} data.gate_name - Gate name (e.g., 'format:check')
+ * @param {boolean} data.passed - Whether gate passed
+ * @param {number} data.duration_ms - Execution duration in milliseconds
+ */
+export function emitGateEvent(data) {
+    const event = {
+        timestamp: new Date().toISOString(),
+        wu_id: data.wu_id || null,
+        lane: data.lane || null,
+        gate_name: data.gate_name,
+        passed: data.passed,
+        duration_ms: data.duration_ms,
+    };
+    emit(GATES_LOG, event);
+}
+/**
+ * Get current WU ID from git branch or environment
+ * @returns {string|null} WU ID or null
+ */
+export function getCurrentWU() {
+    try {
+        // eslint-disable-next-line sonarjs/no-os-command-from-path -- git resolved from PATH; workflow tooling requires git
+        const branch = execSync('git rev-parse --abbrev-ref HEAD', {
+            encoding: 'utf-8',
+            stdio: [STDIO.PIPE, STDIO.PIPE, STDIO.IGNORE],
+        }).trim();
+        // Extract WU ID from branch name (e.g., lane/operations/wu-402 -> WU-402)
+        const match = branch.match(/wu-(\d+)/i);
+        if (match) {
+            return `WU-${match[1]}`.toUpperCase();
+        }
+    }
+    catch {
+        // Not in a git repo or command failed
+    }
+    return null;
+}
+/**
+ * Get lane from git branch or environment
+ * @returns {string|null} Lane name or null
+ */
+export function getCurrentLane() {
+    try {
+        // eslint-disable-next-line sonarjs/no-os-command-from-path -- git resolved from PATH; workflow tooling requires git
+        const branch = execSync('git rev-parse --abbrev-ref HEAD', {
+            encoding: 'utf-8',
+            stdio: [STDIO.PIPE, STDIO.PIPE, STDIO.IGNORE],
+        }).trim();
+        // Extract lane from branch name (e.g., lane/operations/wu-402 -> Operations)
+        const match = branch.match(/^lane\/([^/]+)\//i);
+        const laneSegment = match?.[1];
+        if (laneSegment) {
+            return laneSegment.charAt(0).toUpperCase() + laneSegment.slice(1).toLowerCase();
+        }
+    }
+    catch {
+        // Not in a git repo or command failed
+    }
+    return null;
+}
+/**
+ * Emit LLM classification start event
+ * @param {object} data - Classification start data
+ * @param {string} data.classification_type - Type of classification (e.g., 'mode_detection', 'red_flag', 'sensitive_data_detection')
+ * @param {boolean} [data.has_context] - Whether conversation context was provided
+ * @param {string} [data.wu_id] - Work Unit ID
+ * @param {string} [data.lane] - Lane name
+ * @param {string} [logPath] - Optional log path override (for testing)
+ */
+export function emitLLMClassificationStart(data, logPath = LLM_CLASSIFICATION_LOG) {
+    const event = {
+        timestamp: new Date().toISOString(),
+        event_type: 'llm.classification.start',
+        classification_type: data.classification_type,
+        has_context: data.has_context ?? false,
+        wu_id: data.wu_id || getCurrentWU(),
+        lane: data.lane || getCurrentLane(),
+    };
+    emit(logPath, event);
+}
+/**
+ * Emit LLM classification complete event
+ * @param {object} data - Classification completion data
+ * @param {string} data.classification_type - Type of classification
+ * @param {number} data.duration_ms - Processing duration in milliseconds
+ * @param {number} data.tokens_used - Total tokens consumed
+ * @param {number} data.estimated_cost_usd - Estimated cost in USD
+ * @param {number} data.confidence - Classification confidence score (0-1)
+ * @param {boolean} data.fallback_used - Whether fallback (regex) was used
+ * @param {string} [data.fallback_reason] - Reason fallback was triggered
+ * @param {string} [data.wu_id] - Work Unit ID
+ * @param {string} [data.lane] - Lane name
+ * @param {string} [logPath] - Optional log path override (for testing)
+ */
+export function emitLLMClassificationComplete(data, logPath = LLM_CLASSIFICATION_LOG) {
+    // PII Protection: Explicitly exclude UnsafeAny user input fields
+    const event = {
+        timestamp: new Date().toISOString(),
+        event_type: 'llm.classification.complete',
+        classification_type: data.classification_type,
+        duration_ms: data.duration_ms,
+        tokens_used: data.tokens_used,
+        estimated_cost_usd: data.estimated_cost_usd,
+        confidence: data.confidence,
+        fallback_used: data.fallback_used,
+        wu_id: data.wu_id || getCurrentWU(),
+        lane: data.lane || getCurrentLane(),
+    };
+    // Add fallback_reason only if fallback was used
+    if (data.fallback_used && data.fallback_reason) {
+        event.fallback_reason = data.fallback_reason;
+    }
+    emit(logPath, event);
+}
+/**
+ * Emit LLM classification error event
+ * @param {object} data - Classification error data
+ * @param {string} data.classification_type - Type of classification
+ * @param {string} data.error_type - Error type (e.g., 'timeout', 'rate_limit', 'validation')
+ * @param {string} data.error_message - Error message (must be PII-free)
+ * @param {number} [data.duration_ms] - Duration before error occurred
+ * @param {string} [data.wu_id] - Work Unit ID
+ * @param {string} [data.lane] - Lane name
+ * @param {string} [logPath] - Optional log path override (for testing)
+ */
+export function emitLLMClassificationError(data, logPath = LLM_CLASSIFICATION_LOG) {
+    // PII Protection: Never log user input or sensitive data
+    const event = {
+        timestamp: new Date().toISOString(),
+        event_type: 'llm.classification.error',
+        classification_type: data.classification_type,
+        error_type: data.error_type,
+        error_message: data.error_message, // Caller must ensure this is PII-free
+        wu_id: data.wu_id || getCurrentWU(),
+        lane: data.lane || getCurrentLane(),
+    };
+    if (data.duration_ms !== undefined) {
+        event.duration_ms = data.duration_ms;
+    }
+    // Explicitly redact UnsafeAny input_text_preview to prevent PII leakage
+    if (data.input_text_preview) {
+        event.input_text_preview = '[REDACTED]';
+    }
+    emit(logPath, event);
+}
+/**
+ * Emit WU flow telemetry event to .lumenflow/flow.log
+ *
+ * Used by wu-claim, wu-done, wu-unblock for workflow tracking.
+ * Centralized from duplicated emitTelemetry() functions (WU-1256).
+ *
+ * @param {object} event - Event data (script, wu_id, lane, step, etc.)
+ * @param {string} [logPath] - Optional log path override (for testing)
+ */
+export function emitWUFlowEvent(event, logPath = FLOW_LOG) {
+    const logDir = path.dirname(logPath);
+    if (!existsSync(logDir)) {
+        mkdirSync(logDir, { recursive: true });
+    }
+    const line = JSON.stringify({ timestamp: new Date().toISOString(), ...event });
+    try {
+        appendFileSync(logPath, `${line}${STRING_LITERALS.NEWLINE}`, { encoding: 'utf-8' });
+    }
+    catch (err) {
+        // Silently fail - telemetry should not block workflow
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[telemetry] Failed to emit flow event: ${message}`);
+    }
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"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"}