@lumenflow/core 2.2.2 → 2.3.1

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

@@ -0,0 +1,67 @@
+/**
+ * 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 process.exit) */
+    exitFn: (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.exit)
+     */
+    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;
+}

package/dist/stream-error-handler.js

@@ -0,0 +1,94 @@
+/**
+ * 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 { STREAM_ERRORS, EXIT_CODES } from './wu-constants.js';
+/**
+ * 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.exit)
+     */
+    static createWithDefaults() {
+        return new StreamErrorHandler({
+            stdout: process.stdout,
+            stderr: process.stderr,
+            exitFn: (code) => process.exit(code),
+        });
+    }
+    /**
+     * 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
+        };
+    }
+}

package/dist/telemetry.d.ts

@@ -3,7 +3,7 @@
  * Telemetry Module - DORA/SPACE Metrics Emission
  *
  * Emits structured NDJSON telemetry for gates execution and WU flow metrics.
- * Used by gates-local.mjs and flow-report.mjs.
+ * Used by gates-local.ts and flow-report.ts.
  */
 /**
  * Emit a telemetry event as NDJSON

package/dist/telemetry.js

@@ -3,7 +3,7 @@
  * Telemetry Module - DORA/SPACE Metrics Emission
  *
  * Emits structured NDJSON telemetry for gates execution and WU flow metrics.
- * Used by gates-local.mjs and flow-report.mjs.
+ * Used by gates-local.ts and flow-report.ts.
  */
 import { appendFileSync, mkdirSync, existsSync } from 'node:fs';
 import { execSync } from 'node:child_process';

package/dist/template-loader.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Template Loader (WU-1253)
+ *
+ * Loads, parses, and assembles prompt templates from .lumenflow/templates/
+ * with YAML frontmatter support. Enables extraction of hardcoded templates
+ * from wu-spawn.ts into maintainable markdown files.
+ *
+ * Features:
+ * - YAML frontmatter parsing via gray-matter
+ * - Manifest-driven assembly order
+ * - Client-specific overrides (templates.claude/, templates.cursor/)
+ * - Token replacement ({WU_ID}, {LANE}, etc.)
+ * - Conditional template inclusion
+ *
+ * @see {@link https://lumenflow.dev/reference/template-system/} - Template documentation
+ */
+/**
+ * Template frontmatter parsed from YAML.
+ * All templates must include these fields in their frontmatter block.
+ */
+export interface TemplateFrontmatter {
+    /** Unique identifier matching manifest entry (e.g., 'tdd-directive') */
+    id: string;
+    /** Human-readable name for debugging and documentation */
+    name: string;
+    /** Whether this template must be present for assembly to succeed */
+    required: boolean;
+    /** Assembly position - lower numbers appear first in output */
+    order: number;
+    /** Token names for replacement (e.g., ['WU_ID', 'LANE']) */
+    tokens?: string[];
+    /** Conditional expression for inclusion (e.g., "type === 'feature'") */
+    condition?: string;
+}
+/**
+ * Loaded template with content and metadata.
+ * Returned by loadTemplate() after parsing.
+ */
+export interface LoadedTemplate {
+    /** Parsed frontmatter fields */
+    frontmatter: TemplateFrontmatter;
+    /** Markdown content after frontmatter block */
+    content: string;
+    /** Original file path for debugging */
+    sourcePath: string;
+}
+/**
+ * Manifest entry defining a template's inclusion in assembly.
+ */
+export interface ManifestEntry {
+    /** Template identifier matching frontmatter id */
+    id: string;
+    /** Relative path within templates/spawn-prompt/ */
+    path: string;
+    /** Must be present for assembly to succeed */
+    required: boolean;
+    /** Assembly position (ascending order) */
+    order: number;
+    /** Optional condition expression */
+    condition?: string;
+}
+/**
+ * Complete manifest structure parsed from manifest.yaml.
+ */
+export interface TemplateManifest {
+    /** Manifest format version */
+    version: string;
+    /** Default settings for template processing */
+    defaults: {
+        /** Token format: '{TOKEN}' or '{{TOKEN}}' */
+        tokenFormat: string;
+    };
+    /** Ordered list of template entries */
+    templates: ManifestEntry[];
+}
+/**
+ * Context for token replacement during assembly.
+ * Values are substituted for {TOKEN} placeholders.
+ */
+export interface TemplateContext {
+    /** Work Unit identifier (e.g., 'WU-1253') */
+    WU_ID: string;
+    /** Lane name (e.g., 'Framework: Core') */
+    LANE: string;
+    /** WU type (e.g., 'feature', 'bug', 'documentation') */
+    TYPE: string;
+    /** Optional WU title */
+    TITLE?: string;
+    /** Optional WU description */
+    DESCRIPTION?: string;
+    /** Optional worktree path */
+    WORKTREE_PATH?: string;
+    /** Optional parent lane extracted from LANE */
+    laneParent?: string;
+    /** Allow additional context properties */
+    [key: string]: string | undefined;
+}
+/**
+ * Load and parse the template manifest.
+ *
+ * @param baseDir - Project root directory containing .lumenflow/
+ * @returns Parsed manifest with validated structure
+ * @throws If manifest is missing or has invalid structure
+ */
+export declare function loadManifest(baseDir: string): TemplateManifest;
+/**
+ * Load a single template file with frontmatter parsing.
+ *
+ * Uses gray-matter with the yaml engine for robust parsing,
+ * matching the pattern established in backlog-parser.ts.
+ *
+ * @param templatePath - Absolute path to template file
+ * @returns Parsed template with frontmatter and content
+ * @throws If file is missing or frontmatter is invalid
+ */
+export declare function loadTemplate(templatePath: string): LoadedTemplate;
+/**
+ * Load all templates from a directory, respecting client overrides.
+ *
+ * Override resolution order:
+ * 1. .lumenflow/templates.{client}/spawn-prompt/{template}.md (highest priority)
+ * 2. .lumenflow/templates/spawn-prompt/{template}.md (fallback)
+ *
+ * @param baseDir - Project root directory
+ * @param clientName - Client name for overrides (e.g., 'claude', 'cursor')
+ * @returns Map of template id to loaded template
+ */
+export declare function loadTemplatesWithOverrides(baseDir: string, clientName: string): Map<string, LoadedTemplate>;
+/**
+ * Assemble templates in manifest order with token replacement.
+ *
+ * @param templates - Map of loaded templates by id
+ * @param manifest - Manifest defining assembly order
+ * @param context - Token values for replacement
+ * @returns Assembled content with all tokens replaced
+ * @throws If required template is missing
+ */
+export declare function assembleTemplates(templates: Map<string, LoadedTemplate>, manifest: TemplateManifest, context: TemplateContext): string;
+/**
+ * Replace {TOKEN} placeholders with context values.
+ *
+ * @param content - Template content with placeholders
+ * @param tokens - Token name to value mapping
+ * @returns Content with tokens replaced
+ */
+export declare function replaceTokens(content: string, tokens: Record<string, string | undefined>): string;
+/**
+ * Evaluate a simple condition expression against context.
+ *
+ * Supports:
+ * - Equality: type === 'feature'
+ * - Inequality: type !== 'documentation'
+ * - Truthy: worktreePath
+ * - AND: type === 'feature' && lane === 'Core'
+ * - OR: type === 'feature' || type === 'bug'
+ * - Dotted paths: policy.testing === 'tdd' (WU-1260)
+ *
+ * @param condition - Condition expression string
+ * @param context - Context values for evaluation
+ * @returns Whether condition evaluates to true
+ */
+export declare function evaluateCondition(condition: string | undefined, context: Record<string, unknown>): boolean;