@lumenflow/core 2.2.2 → 2.3.1

package/dist/template-loader.js

@@ -0,0 +1,372 @@
+/**
+ * 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
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import matter from 'gray-matter';
+import yaml from 'yaml';
+import { createError, ErrorCodes } from './error-handler.js';
+const MANIFEST_PATH = '.lumenflow/templates/manifest.yaml';
+const TEMPLATES_DIR = '.lumenflow/templates/spawn-prompt';
+/**
+ * Validate a template entry from the manifest.
+ * @throws If entry is missing required fields
+ */
+function validateTemplateEntry(entry, manifestPath) {
+    if (!entry || typeof entry !== 'object') {
+        throw createError(ErrorCodes.VALIDATION_ERROR, `manifest.yaml: Each template entry must be an object`, { path: manifestPath });
+    }
+    const templateEntry = entry;
+    const missingFields = [];
+    if (!templateEntry.id)
+        missingFields.push('id');
+    if (!templateEntry.path)
+        missingFields.push('path');
+    if (typeof templateEntry.required !== 'boolean')
+        missingFields.push('required');
+    if (typeof templateEntry.order !== 'number')
+        missingFields.push('order');
+    if (missingFields.length > 0) {
+        throw createError(ErrorCodes.VALIDATION_ERROR, `manifest.yaml: Template entry '${templateEntry.id || 'unknown'}' is missing required fields: ${missingFields.join(', ')}`, { path: manifestPath, entry: templateEntry });
+    }
+}
+/**
+ * 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 function loadManifest(baseDir) {
+    const manifestPath = join(baseDir, MANIFEST_PATH);
+    if (!existsSync(manifestPath)) {
+        throw createError(ErrorCodes.FILE_NOT_FOUND, `Template manifest.yaml not found at ${manifestPath}. ` +
+            `Create .lumenflow/templates/manifest.yaml to define template assembly order.`, { path: manifestPath });
+    }
+    const content = readFileSync(manifestPath, 'utf-8');
+    let parsed;
+    try {
+        parsed = yaml.parse(content);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw createError(ErrorCodes.YAML_PARSE_ERROR, `Failed to parse manifest.yaml: ${message}`, {
+            path: manifestPath,
+            originalError: message,
+        });
+    }
+    // Validate manifest structure
+    if (!parsed || typeof parsed !== 'object') {
+        throw createError(ErrorCodes.VALIDATION_ERROR, `manifest.yaml must be a valid YAML object`, {
+            path: manifestPath,
+        });
+    }
+    const manifest = parsed;
+    if (!manifest.version || typeof manifest.version !== 'string') {
+        throw createError(ErrorCodes.VALIDATION_ERROR, `manifest.yaml: 'version' field is required and must be a string`, { path: manifestPath });
+    }
+    if (!Array.isArray(manifest.templates)) {
+        throw createError(ErrorCodes.VALIDATION_ERROR, `manifest.yaml: 'templates' field is required and must be an array`, { path: manifestPath });
+    }
+    // Validate each template entry using extracted helper
+    for (const entry of manifest.templates) {
+        validateTemplateEntry(entry, manifestPath);
+    }
+    // Build validated manifest
+    const defaults = manifest.defaults || {};
+    return {
+        version: manifest.version,
+        defaults: {
+            tokenFormat: defaults.tokenFormat || '{TOKEN}',
+        },
+        templates: manifest.templates.map((entry) => {
+            const e = entry;
+            return {
+                id: e.id,
+                path: e.path,
+                required: e.required,
+                order: e.order,
+                condition: e.condition,
+            };
+        }),
+    };
+}
+/**
+ * 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 function loadTemplate(templatePath) {
+    if (!existsSync(templatePath)) {
+        throw createError(ErrorCodes.FILE_NOT_FOUND, `Template not found: ${templatePath}`, {
+            path: templatePath,
+        });
+    }
+    const fileContent = readFileSync(templatePath, 'utf-8');
+    // Parse frontmatter using gray-matter with modern yaml engine
+    // Pattern from backlog-parser.ts (WU-1065)
+    const { data, content } = matter(fileContent, {
+        engines: {
+            yaml: {
+                parse: yaml.parse.bind(yaml),
+                stringify: yaml.stringify.bind(yaml),
+            },
+        },
+    });
+    // Validate required frontmatter fields
+    const frontmatter = data;
+    if (!frontmatter.id || typeof frontmatter.id !== 'string') {
+        throw createError(ErrorCodes.VALIDATION_ERROR, `Template ${templatePath}: 'id' field is required in frontmatter`, { path: templatePath });
+    }
+    if (!frontmatter.name || typeof frontmatter.name !== 'string') {
+        throw createError(ErrorCodes.VALIDATION_ERROR, `Template ${templatePath}: 'name' field is required in frontmatter`, { path: templatePath });
+    }
+    if (typeof frontmatter.required !== 'boolean') {
+        throw createError(ErrorCodes.VALIDATION_ERROR, `Template ${templatePath}: 'required' field must be a boolean`, { path: templatePath });
+    }
+    if (typeof frontmatter.order !== 'number') {
+        throw createError(ErrorCodes.VALIDATION_ERROR, `Template ${templatePath}: 'order' field must be a number`, { path: templatePath });
+    }
+    return {
+        frontmatter: {
+            id: frontmatter.id,
+            name: frontmatter.name,
+            required: frontmatter.required,
+            order: frontmatter.order,
+            tokens: Array.isArray(frontmatter.tokens) ? frontmatter.tokens : undefined,
+            condition: typeof frontmatter.condition === 'string' ? frontmatter.condition : undefined,
+        },
+        content: content.trim(),
+        sourcePath: templatePath,
+    };
+}
+/**
+ * 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 function loadTemplatesWithOverrides(baseDir, clientName) {
+    const templates = new Map();
+    const baseTemplatesDir = join(baseDir, TEMPLATES_DIR);
+    const clientTemplatesDir = join(baseDir, `.lumenflow/templates.${clientName}/spawn-prompt`);
+    // Load base templates first
+    if (existsSync(baseTemplatesDir)) {
+        loadTemplatesFromDir(baseTemplatesDir, templates);
+    }
+    // Override with client-specific templates
+    if (existsSync(clientTemplatesDir)) {
+        loadTemplatesFromDir(clientTemplatesDir, templates);
+    }
+    return templates;
+}
+/**
+ * Load all templates from a directory into the provided map.
+ * Templates are keyed by their frontmatter id.
+ */
+function loadTemplatesFromDir(dirPath, templates) {
+    const entries = readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = join(dirPath, entry.name);
+        if (entry.isDirectory()) {
+            // Recursively load from subdirectories (e.g., lane-guidance/)
+            loadTemplatesFromDir(fullPath, templates);
+        }
+        else if (entry.name.endsWith('.md')) {
+            try {
+                const template = loadTemplate(fullPath);
+                templates.set(template.frontmatter.id, template);
+            }
+            catch {
+                // Silently skip templates that fail to load (intentional - optional templates)
+            }
+        }
+    }
+}
+/**
+ * Normalize context for condition evaluation.
+ *
+ * Adds lowercase aliases for common fields so conditions can use
+ * natural syntax like `type === 'feature'` instead of `TYPE === 'feature'`.
+ *
+ * Token replacement still uses uppercase keys (WU_ID, LANE).
+ */
+function normalizeContextForConditions(context) {
+    const normalized = { ...context };
+    // Add lowercase aliases for condition evaluation
+    if (context.TYPE !== undefined)
+        normalized.type = context.TYPE;
+    if (context.LANE !== undefined)
+        normalized.lane = context.LANE;
+    if (context.WU_ID !== undefined)
+        normalized.wuId = context.WU_ID;
+    if (context.TITLE !== undefined)
+        normalized.title = context.TITLE;
+    if (context.DESCRIPTION !== undefined)
+        normalized.description = context.DESCRIPTION;
+    if (context.WORKTREE_PATH !== undefined)
+        normalized.worktreePath = context.WORKTREE_PATH;
+    return normalized;
+}
+/**
+ * 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 function assembleTemplates(templates, manifest, context) {
+    // Sort manifest entries by order (ascending)
+    const sortedEntries = [...manifest.templates].sort((a, b) => a.order - b.order);
+    // Normalize context for condition evaluation (add lowercase aliases)
+    // Conditions use lowercase (type, lane) while tokens use uppercase (WU_ID, LANE)
+    const conditionContext = normalizeContextForConditions(context);
+    const sections = [];
+    for (const entry of sortedEntries) {
+        const template = templates.get(entry.id);
+        // Handle missing templates
+        if (!template) {
+            if (entry.required) {
+                throw createError(ErrorCodes.VALIDATION_ERROR, `Required template '${entry.id}' is missing. ` + `Expected at: ${entry.path}`, { templateId: entry.id, path: entry.path });
+            }
+            // Skip optional missing templates
+            continue;
+        }
+        // Evaluate condition if present (using normalized context)
+        const condition = entry.condition || template.frontmatter.condition;
+        if (condition && !evaluateCondition(condition, conditionContext)) {
+            continue;
+        }
+        // Replace tokens and add to output
+        const content = replaceTokens(template.content, context);
+        sections.push(content);
+    }
+    return sections.join('\n\n');
+}
+/**
+ * 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 function replaceTokens(content, tokens) {
+    let result = content;
+    for (const [key, value] of Object.entries(tokens)) {
+        if (value !== undefined) {
+            // Use global replace with escaped regex for safety
+            const pattern = new RegExp(`\\{${escapeRegex(key)}\\}`, 'g');
+            result = result.replace(pattern, value);
+        }
+    }
+    return result;
+}
+/**
+ * Escape special regex characters in a string.
+ */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Get a value from a nested path in an object.
+ * Supports both flat keys (e.g., 'type') and dotted paths (e.g., 'policy.testing').
+ *
+ * @param obj - Object to get value from
+ * @param path - Key path (may contain dots for nested access)
+ * @returns Value at path, or undefined if not found
+ */
+function getNestedValue(obj, path) {
+    // First try direct key lookup (for keys like 'policy.testing' stored as flat keys)
+    if (path in obj) {
+        return obj[path];
+    }
+    // Then try nested path traversal
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined || typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * 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 function evaluateCondition(condition, context) {
+    // Empty/undefined conditions always pass
+    if (!condition || condition.trim() === '') {
+        return true;
+    }
+    // Handle OR conditions first (lower precedence)
+    if (condition.includes('||')) {
+        const parts = condition.split('||').map((p) => p.trim());
+        return parts.some((part) => evaluateCondition(part, context));
+    }
+    // Handle AND conditions
+    if (condition.includes('&&')) {
+        const parts = condition.split('&&').map((p) => p.trim());
+        return parts.every((part) => evaluateCondition(part, context));
+    }
+    // Handle equality: key === 'value' (supports dotted paths like policy.testing)
+    const eqRegex = /^([\w.]+)\s*===\s*['"](.+)['"]$/;
+    const eqMatch = eqRegex.exec(condition);
+    if (eqMatch) {
+        const [, key, value] = eqMatch;
+        return getNestedValue(context, key) === value;
+    }
+    // Handle inequality: key !== 'value' (supports dotted paths like policy.testing)
+    const neqRegex = /^([\w.]+)\s*!==\s*['"](.+)['"]$/;
+    const neqMatch = neqRegex.exec(condition);
+    if (neqMatch) {
+        const [, key, value] = neqMatch;
+        return getNestedValue(context, key) !== value;
+    }
+    // Handle truthy check: key (supports dotted paths)
+    const truthyRegex = /^([\w.]+)$/;
+    const truthyMatch = truthyRegex.exec(condition);
+    if (truthyMatch) {
+        const key = truthyMatch[1];
+        return Boolean(getNestedValue(context, key));
+    }
+    // Unknown condition format - pass by default
+    return true;
+}

package/dist/test-baseline.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Test Baseline - Test Ratchet Pattern (WU-1253)
+ *
+ * Implements a "ratchet" pattern for test failures:
+ * - Track known failures in a baseline file (.lumenflow/test-baseline.json)
+ * - Block NEW failures (not in baseline)
+ * - Allow pre-existing failures with warning
+ * - Auto-update baseline when tests are fixed (ratchet forward)
+ *
+ * This enables agents to work on WUs without being blocked by unrelated
+ * test failures, while still preventing introduction of NEW failures.
+ *
+ * @see https://lumenflow.dev/reference/test-ratchet/
+ */
+import { z } from 'zod';
+/** Default path for the test baseline file */
+export declare const DEFAULT_BASELINE_PATH = ".lumenflow/test-baseline.json";
+/** Environment variable to override baseline path */
+export declare const BASELINE_PATH_ENV = "LUMENFLOW_TEST_BASELINE";
+/** Current schema version */
+export declare const BASELINE_VERSION = 1;
+/**
+ * Schema for a known test failure entry
+ */
+export declare const KnownFailureSchema: z.ZodObject<{
+    test_name: z.ZodString;
+    file_path: z.ZodString;
+    failure_reason: z.ZodString;
+    added_at: z.ZodString;
+    added_by_wu: z.ZodString;
+    expected_fix_wu: z.ZodOptional<z.ZodString>;
+    skip_reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type KnownFailure = z.infer<typeof KnownFailureSchema>;
+/**
+ * Schema for baseline statistics
+ */
+export declare const BaselineStatsSchema: z.ZodObject<{
+    total_known_failures: z.ZodNumber;
+    last_ratchet_forward: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type BaselineStats = z.infer<typeof BaselineStatsSchema>;
+/**
+ * Schema for the complete test baseline file
+ */
+export declare const TestBaselineSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    updated_at: z.ZodString;
+    updated_by: z.ZodString;
+    known_failures: z.ZodArray<z.ZodObject<{
+        test_name: z.ZodString;
+        file_path: z.ZodString;
+        failure_reason: z.ZodString;
+        added_at: z.ZodString;
+        added_by_wu: z.ZodString;
+        expected_fix_wu: z.ZodOptional<z.ZodString>;
+        skip_reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    stats: z.ZodObject<{
+        total_known_failures: z.ZodNumber;
+        last_ratchet_forward: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type TestBaseline = z.infer<typeof TestBaselineSchema>;
+/**
+ * Result from a test run (input to comparison)
+ */
+export interface TestResult {
+    test_name: string;
+    file_path: string;
+    passed: boolean;
+    error_message?: string;
+}
+/**
+ * Result of comparing test results against baseline
+ */
+export interface BaselineComparison {
+    /** Tests that failed but are NOT in baseline (blocks gate) */
+    newFailures: TestResult[];
+    /** Tests that failed and ARE in baseline (warning only) */
+    preExistingFailures: KnownFailure[];
+    /** Tests that were in baseline but now pass (ratchet forward candidates) */
+    fixedTests: KnownFailure[];
+    /** Should this block the gate? (true if newFailures > 0) */
+    shouldBlock: boolean;
+    /** Are there warnings to show? (true if preExistingFailures > 0) */
+    hasWarnings: boolean;
+    /** Should baseline be updated? (true if fixedTests > 0) */
+    shouldRatchetForward: boolean;
+}
+/**
+ * Parse result type
+ */
+export type ParseResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Options for updating the baseline
+ */
+export interface UpdateBaselineOptions {
+    /** Tests that were fixed (to remove from baseline) */
+    fixedTests?: string[];
+    /** New known failures to add to baseline */
+    newKnownFailures?: Array<{
+        test_name: string;
+        file_path: string;
+        failure_reason: string;
+        expected_fix_wu?: string;
+    }>;
+}
+/**
+ * Parse a test baseline JSON string
+ *
+ * @param json - JSON string content of baseline file
+ * @returns Parse result with baseline data or error
+ */
+export declare function parseTestBaseline(json: string): ParseResult<TestBaseline>;
+/**
+ * Create a new test baseline
+ *
+ * @param wuId - WU creating the baseline
+ * @param initialFailures - Optional initial failures to add
+ * @returns New test baseline
+ */
+export declare function createTestBaseline(wuId: string, initialFailures?: Array<{
+    test_name: string;
+    file_path: string;
+    failure_reason: string;
+    expected_fix_wu?: string;
+}>): TestBaseline;
+/**
+ * Compare current test results against the baseline
+ *
+ * This is the core ratchet logic:
+ * - NEW failures (not in baseline) block the gate
+ * - Pre-existing failures (in baseline) show warning
+ * - Fixed tests (in baseline but now passing) trigger ratchet forward
+ *
+ * @param baseline - The test baseline
+ * @param currentFailures - Current test failures from test run
+ * @returns Comparison result
+ */
+export declare function compareTestResults(baseline: TestBaseline, currentFailures: TestResult[]): BaselineComparison;
+/**
+ * Update the baseline (ratchet forward or add new known failures)
+ *
+ * @param baseline - Current baseline
+ * @param wuId - WU making the update
+ * @param options - Update options
+ * @returns Updated baseline (immutable)
+ */
+export declare function updateBaseline(baseline: TestBaseline, wuId: string, options: UpdateBaselineOptions): TestBaseline;
+/**
+ * Format a warning message for pre-existing failures
+ *
+ * @param preExisting - Pre-existing failures from baseline
+ * @returns Formatted warning string
+ */
+export declare function formatBaselineWarning(preExisting: KnownFailure[]): string;
+/**
+ * Format an error message for new failures
+ *
+ * @param newFailures - New test failures
+ * @returns Formatted error string
+ */
+export declare function formatNewFailureError(newFailures: TestResult[]): string;
+/**
+ * Get the path to the test baseline file
+ *
+ * @returns Baseline file path
+ */
+export declare function getBaselineFilePath(): string;