@lumenflow/core 2.2.1 → 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/system-map-validator.d.ts

@@ -78,3 +78,21 @@ export declare function validateSystemMap(systemMap: any, deps: any): Promise<{
     queryErrors: any[];
     classificationErrors: any[];
 }>;
+export interface SystemMapValidationResult {
+    valid: boolean;
+    skipped: boolean;
+    pathErrors: string[];
+    orphanDocs: string[];
+    audienceErrors: string[];
+    queryErrors: string[];
+    classificationErrors: string[];
+}
+export declare function runSystemMapValidation(options?: {
+    cwd?: string;
+    systemMapPath?: string;
+    logger?: {
+        log: (message: string) => void;
+        warn?: (message: string) => void;
+        error?: (message: string) => void;
+    };
+}): Promise<SystemMapValidationResult>;

package/dist/system-map-validator.js

@@ -12,6 +12,7 @@
  * @module system-map-validator
  */
 import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
 import fg from 'fast-glob';
 import { parseYAML } from './wu-yaml.js';
 /**
@@ -274,34 +275,64 @@ export async function validateSystemMap(systemMap, deps) {
     };
 }
 const DEFAULT_SYSTEM_MAP_PATH = 'SYSTEM-MAP.yaml';
-function emitErrors(label, errors) {
-    if (!errors || errors.length === 0)
-        return;
-    console.error(`\n${label}:`);
-    for (const error of errors) {
-        console.error(`  - ${error}`);
-    }
-}
-async function runCLI() {
-    const systemMapPath = process.env.SYSTEM_MAP_PATH || DEFAULT_SYSTEM_MAP_PATH;
-    if (!existsSync(systemMapPath)) {
-        console.warn(`[system-map] ${systemMapPath} not found; skipping validation.`);
-        process.exit(0);
+export async function runSystemMapValidation(options = {}) {
+    const { cwd = process.cwd(), systemMapPath, logger = console } = options;
+    const resolvedPath = systemMapPath ?? path.join(cwd, DEFAULT_SYSTEM_MAP_PATH);
+    if (!existsSync(resolvedPath)) {
+        logger.warn?.(`[system-map] ${resolvedPath} not found; skipping validation.`);
+        return {
+            valid: true,
+            skipped: true,
+            pathErrors: [],
+            orphanDocs: [],
+            audienceErrors: [],
+            queryErrors: [],
+            classificationErrors: [],
+        };
     }
     let systemMap;
     try {
-        const raw = readFileSync(systemMapPath, 'utf-8');
+        const raw = readFileSync(resolvedPath, 'utf-8');
         systemMap = parseYAML(raw);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        console.error(`[system-map] Failed to read or parse ${systemMapPath}: ${message}`);
-        process.exit(1);
+        logger.error?.(`[system-map] Failed to read or parse ${resolvedPath}: ${message}`);
+        return {
+            valid: false,
+            skipped: false,
+            pathErrors: [message],
+            orphanDocs: [],
+            audienceErrors: [],
+            queryErrors: [],
+            classificationErrors: [],
+        };
     }
     const result = await validateSystemMap(systemMap, {
         exists: (path) => existsSync(path),
         glob: (pattern) => fg(pattern, { dot: false }),
     });
+    return {
+        valid: result.valid,
+        skipped: false,
+        pathErrors: result.pathErrors,
+        orphanDocs: result.orphanDocs,
+        audienceErrors: result.audienceErrors,
+        queryErrors: result.queryErrors,
+        classificationErrors: result.classificationErrors,
+    };
+}
+function emitErrors(label, errors) {
+    if (!errors || errors.length === 0)
+        return;
+    console.error(`\n${label}:`);
+    for (const error of errors) {
+        console.error(`  - ${error}`);
+    }
+}
+async function runCLI() {
+    const systemMapPath = process.env.SYSTEM_MAP_PATH || DEFAULT_SYSTEM_MAP_PATH;
+    const result = await runSystemMapValidation({ systemMapPath });
     if (!result.valid) {
         console.error('\n[system-map] Validation failed');
         emitErrors('Missing paths', result.pathErrors);
@@ -311,6 +342,9 @@ async function runCLI() {
         emitErrors('Classification routing violations', result.classificationErrors);
         process.exit(1);
     }
+    if (result.skipped) {
+        process.exit(0);
+    }
     console.log('[system-map] Validation passed');
     process.exit(0);
 }

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;