@lumenflow/core 1.0.0 → 1.3.0

package/dist/rebase-artifact-cleanup.js

@@ -15,11 +15,12 @@
  * @see {@link tools/lib/wu-recovery.mjs} - Related zombie state handling
  */
 import { readFile, writeFile, unlink, access } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import yaml from 'js-yaml';
+import { existsSync, rmSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import fg from 'fast-glob';
+import { parseYAML, stringifyYAML } from './wu-yaml.js';
 import { WU_PATHS } from './wu-paths.js';
-import { WU_STATUS, LOG_PREFIX, EMOJI, YAML_OPTIONS, BACKLOG_SECTIONS, STATUS_SECTIONS, REMOTES, BRANCHES, } from './wu-constants.js';
+import { WU_STATUS, LOG_PREFIX, EMOJI, YAML_OPTIONS, BACKLOG_SECTIONS, STATUS_SECTIONS, REMOTES, BRANCHES, BUILD_ARTIFACT_GLOBS, BUILD_ARTIFACT_IGNORES, } from './wu-constants.js';
 import { findSectionBounds, removeBulletFromSection } from './backlog-editor.js';
 /** @constant {string} FRONTMATTER_DELIMITER - YAML frontmatter delimiter */
 const FRONTMATTER_DELIMITER = '---';
@@ -68,7 +69,7 @@ async function yamlIsDoneOnMain(gitAdapter, wuId) {
             'show',
             `${REMOTES.ORIGIN}/${BRANCHES.MAIN}:${WU_PATHS.WU(wuId)}`,
         ]);
-        const doc = yaml.load(content);
+        const doc = parseYAML(content);
         return doc && doc.status === WU_STATUS.DONE;
     }
     catch {
@@ -162,7 +163,7 @@ export async function detectRebasedArtifacts(worktreePath, wuId, gitAdapter) {
     if (await fileExists(wuYamlPath)) {
         try {
             const content = await readFile(wuYamlPath, { encoding: 'utf-8' });
-            const doc = yaml.load(content);
+            const doc = parseYAML(content);
             if (doc && doc.status === WU_STATUS.DONE) {
                 localYamlDone = true;
             }
@@ -236,7 +237,7 @@ export async function cleanupRebasedArtifacts(worktreePath, wuId) {
     try {
         if (await fileExists(wuYamlPath)) {
             const content = await readFile(wuYamlPath, { encoding: 'utf-8' });
-            const doc = yaml.load(content);
+            const doc = parseYAML(content);
             if (doc && doc.status === WU_STATUS.DONE) {
                 // Reset status
                 doc.status = WU_STATUS.IN_PROGRESS;
@@ -244,7 +245,7 @@ export async function cleanupRebasedArtifacts(worktreePath, wuId) {
                 delete doc.locked;
                 delete doc.completed_at;
                 // Write back
-                const updatedContent = yaml.dump(doc, { lineWidth: YAML_OPTIONS.LINE_WIDTH });
+                const updatedContent = stringifyYAML(doc, { lineWidth: YAML_OPTIONS.LINE_WIDTH });
                 await writeFile(wuYamlPath, updatedContent, { encoding: 'utf-8' });
                 yamlReset = true;
                 console.log(LOG_PREFIX.CLEANUP, `${EMOJI.WARNING} Reset YAML status from done to in_progress for ${wuId} (artifact from main rebase)`);
@@ -431,3 +432,43 @@ export async function deduplicateBacklogAfterRebase(worktreePath, wuId) {
         errors,
     };
 }
+/**
+ * Clean up build artifacts in a worktree (dist folders + tsbuildinfo files)
+ *
+ * WU-1042: Provide a safe helper for clearing build artifacts that can
+ * trigger TS5055 or stale build issues in worktrees.
+ *
+ * @param {string} worktreePath - Path to the worktree directory
+ * @returns {Promise<object>} Cleanup result
+ * @returns {string[]} result.distDirectories - Removed dist directories (relative paths)
+ * @returns {string[]} result.tsbuildinfoFiles - Removed tsbuildinfo files (relative paths)
+ * @returns {number} result.removedCount - Total removed artifacts
+ */
+export async function cleanupWorktreeBuildArtifacts(worktreePath) {
+    const root = resolve(worktreePath);
+    const distDirectories = await fg(BUILD_ARTIFACT_GLOBS.DIST_DIRS, {
+        cwd: root,
+        onlyDirectories: true,
+        dot: true,
+        followSymbolicLinks: false,
+        ignore: BUILD_ARTIFACT_IGNORES,
+    });
+    const tsbuildinfoFiles = await fg(BUILD_ARTIFACT_GLOBS.TSBUILDINFO_FILES, {
+        cwd: root,
+        onlyFiles: true,
+        dot: true,
+        followSymbolicLinks: false,
+        ignore: BUILD_ARTIFACT_IGNORES,
+    });
+    for (const dir of distDirectories) {
+        rmSync(join(root, dir), { recursive: true, force: true });
+    }
+    for (const file of tsbuildinfoFiles) {
+        rmSync(join(root, file), { force: true });
+    }
+    return {
+        distDirectories,
+        tsbuildinfoFiles,
+        removedCount: distDirectories.length + tsbuildinfoFiles.length,
+    };
+}

package/dist/spawn-strategy.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Strategy interface for client-specific spawn behavior
+ */
+export interface SpawnStrategy {
+    /**
+     * Get the context loading preamble for the specific client
+     */
+    getPreamble(wuId: string): string;
+    /**
+     * Get instructions for loading agent skills/tools
+     */
+    getSkillLoadingInstruction(): string;
+}
+/**
+ * Base class with shared preamble logic
+ */
+declare abstract class BaseSpawnStrategy implements SpawnStrategy {
+    protected getCorePreamble(wuId: string): string;
+    abstract getPreamble(wuId: string): string;
+    abstract getSkillLoadingInstruction(): string;
+}
+/**
+ * Strategy for Claude Code (Local/Terminal)
+ */
+export declare class ClaudeCodeStrategy extends BaseSpawnStrategy {
+    getPreamble(wuId: string): string;
+    getSkillLoadingInstruction(): string;
+}
+/**
+ * Strategy for Gemini CLI (Multimodal/Ecosystem)
+ */
+export declare class GeminiCliStrategy extends BaseSpawnStrategy {
+    getPreamble(wuId: string): string;
+    getSkillLoadingInstruction(): string;
+}
+/**
+ * Generic Strategy (Unknown/Other clients)
+ */
+export declare class GenericStrategy extends BaseSpawnStrategy {
+    getPreamble(wuId: string): string;
+    getSkillLoadingInstruction(): string;
+}
+/**
+ * Factory for creating strategies
+ */
+export declare class SpawnStrategyFactory {
+    /**
+     * Create a strategy for the given client
+     * @param clientName - Client name (e.g. 'claude-code', 'gemini-cli')
+     */
+    static create(clientName: string): SpawnStrategy;
+}
+export {};

package/dist/spawn-strategy.js

@@ -0,0 +1,106 @@
+import { existsSync } from 'node:fs';
+/**
+ * Base class with shared preamble logic
+ */
+class BaseSpawnStrategy {
+    getCorePreamble(wuId) {
+        return `Load the following context in this order:
+
+1. Read LUMENFLOW.md (workflow fundamentals and critical rules)
+2. Read .lumenflow/constraints.md (non-negotiable constraints)
+3. Read README.md (project structure and tech stack)
+4. Read docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md sections 1-7 (TDD, gates, Definition of Done)
+5. Read docs/04-operations/tasks/wu/${wuId}.yaml (the specific WU you're working on)`;
+    }
+}
+/**
+ * Strategy for Claude Code (Local/Terminal)
+ */
+export class ClaudeCodeStrategy extends BaseSpawnStrategy {
+    getPreamble(wuId) {
+        let preamble = this.getCorePreamble(wuId);
+        // Vendor overlay
+        if (existsSync('.claude/CLAUDE.md')) {
+            // Insert after LUMENFLOW.md if possible, or just append/prepend
+            // For simplicity and clarity, we'll prepend the vendor specific instructions
+            // relying on the user to follow the specific order if stated.
+            // Actually, checking original behavior: CLAUDE.md was #1.
+            // But new plan says LUMENFLOW.md is core.
+            // We will append it as an overlay step.
+            preamble += `\n6. Read .claude/CLAUDE.md (Claude-specific workflow overlay)`;
+        }
+        return preamble;
+    }
+    getSkillLoadingInstruction() {
+        return `## Skills Selection
+    
+1. Check \`.lumenflow/agents\` for available skills.
+2. Check \`.claude/agents\` for Claude-specific overrides or additions.
+3. Select relevant skills for this task.`;
+    }
+}
+/**
+ * Strategy for Gemini CLI (Multimodal/Ecosystem)
+ */
+export class GeminiCliStrategy extends BaseSpawnStrategy {
+    getPreamble(wuId) {
+        let preamble = this.getCorePreamble(wuId);
+        if (existsSync('GEMINI.md')) {
+            preamble += `\n6. Read GEMINI.md (Gemini-specific workflow overlay)`;
+        }
+        return preamble;
+    }
+    getSkillLoadingInstruction() {
+        return `## Skills Selection
+    
+1. Check \`.lumenflow/agents\` for available skills.
+2. Select relevant skills for this task.`;
+    }
+}
+/**
+ * Generic Strategy (Unknown/Other clients)
+ */
+export class GenericStrategy extends BaseSpawnStrategy {
+    getPreamble(wuId) {
+        return this.getCorePreamble(wuId);
+    }
+    getSkillLoadingInstruction() {
+        return `## Skills Selection
+    
+1. Check \`.lumenflow/agents\` for available skills.
+2. Select relevant skills for this task.`;
+    }
+}
+/**
+ * Factory for creating strategies
+ */
+export class SpawnStrategyFactory {
+    /**
+     * Create a strategy for the given client
+     * @param clientName - Client name (e.g. 'claude-code', 'gemini-cli')
+     */
+    static create(clientName) {
+        switch (clientName.toLowerCase()) {
+            case 'claude': // Legacy alias
+            case 'claude-code':
+                return new ClaudeCodeStrategy();
+            case 'gemini': // Alias
+            case 'gemini-cli':
+                return new GeminiCliStrategy();
+            case 'codex': // Deprecated alias
+            case 'codex-cli':
+                // Codex might need its own strategy later (sandbox), but for now generic or claude-like?
+                // Plan says: "codex: preamble: false, strategy: cloud-sandbox" -> implies Generic or dedicated.
+                // For now, let's map to Generic but maybe we should add CodexStrategy if it has diff behavior.
+                // Re-reading plan: "CodexStrategy: Emphasizes cloud sandbox constraints"
+                // But for this "Minimal" pass, let's stick to Generic with a comment,
+                // OR essentially treat it as Generic since we don't have constraints logic here yet (it's in wu-spawn).
+                // Actually, let's return GenericStrategy but we might handle constraints elsewhere.
+                return new GenericStrategy();
+            default:
+                // Warn? The factory just creates. The caller should warn if it fell back.
+                // But here we just return Generic.
+                return new GenericStrategy();
+        }
+    }
+}

package/dist/stamp-utils.d.ts

@@ -26,6 +26,16 @@ export declare const STAMP_FORMAT_ERRORS: Readonly<{
     /** WU ID in stamp does not match expected ID */
     WU_ID_MISMATCH: "WU_ID_MISMATCH";
 }>;
+/**
+ * Validate that a date string is a valid ISO date (YYYY-MM-DD)
+ *
+ * WU-1006: Uses date-fns parse() and isValid() instead of manual parseInt parsing
+ * Library-First principle: leverage well-known libraries over brittle custom code
+ *
+ * @param {string} dateStr - Date string in YYYY-MM-DD format
+ * @returns {boolean} True if date is valid
+ */
+export declare function isValidDateString(dateStr: string): boolean;
 /**
  * Create stamp file (idempotent - safe to call multiple times)
  *

package/dist/stamp-utils.js

@@ -14,6 +14,7 @@ import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
 import { readFile, access } from 'node:fs/promises';
 import { constants } from 'node:fs';
 import path from 'node:path';
+import { parse, isValid } from 'date-fns';
 import { WU_PATHS } from './wu-paths.js';
 import { todayISO } from './date-utils.js';
 /**
@@ -34,34 +35,31 @@ export const STAMP_FORMAT_ERRORS = Object.freeze({
     WU_ID_MISMATCH: 'WU_ID_MISMATCH',
 });
 /**
- * Valid date regex: YYYY-MM-DD format
+ * Valid date regex: YYYY-MM-DD format (for format checking before parsing)
  * @type {RegExp}
  */
-const DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+const DATE_FORMAT_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
 /**
- * Validate that a date string is a valid ISO date
+ * Validate that a date string is a valid ISO date (YYYY-MM-DD)
+ *
+ * WU-1006: Uses date-fns parse() and isValid() instead of manual parseInt parsing
+ * Library-First principle: leverage well-known libraries over brittle custom code
+ *
  * @param {string} dateStr - Date string in YYYY-MM-DD format
  * @returns {boolean} True if date is valid
  */
-function isValidDate(dateStr) {
-    const match = dateStr.match(DATE_PATTERN);
-    if (!match) {
-        return false;
-    }
-    const year = parseInt(match[1], 10);
-    const month = parseInt(match[2], 10);
-    const day = parseInt(match[3], 10);
-    // Basic validation
-    if (month < 1 || month > 12) {
-        return false;
-    }
-    // Check day validity for the month
-    const daysInMonth = new Date(year, month, 0).getDate();
-    if (day < 1 || day > daysInMonth) {
+export function isValidDateString(dateStr) {
+    // Quick format check - must be YYYY-MM-DD pattern
+    if (!dateStr || !DATE_FORMAT_PATTERN.test(dateStr)) {
         return false;
     }
-    return true;
+    // Parse with date-fns and validate the result
+    // parse() with strict format ensures proper date validation
+    const parsed = parse(dateStr, 'yyyy-MM-dd', new Date());
+    return isValid(parsed);
 }
+// Internal alias for backward compatibility
+const isValidDate = isValidDateString;
 /**
  * Stamp file body template (eliminates magic string)
  * Single source of truth for stamp format

package/dist/token-counter.js

@@ -9,7 +9,7 @@
 import { get_encoding } from 'tiktoken';
 import { readFileSync } from 'fs';
 import { createHash } from 'crypto';
-import { load as loadYAML } from 'js-yaml';
+import { parseYAML } from './wu-yaml.js';
 import { createError, ErrorCodes } from './error-handler.js';
 import { EXIT_CODES, STRING_LITERALS } from './wu-constants.js';
 // Cache tokenizer instance (expensive to create)
@@ -65,7 +65,7 @@ export function loadPrompt(promptPath) {
     try {
         const raw = readFileSync(promptPath, { encoding: 'utf-8' });
         // Parse YAML to access prompt structure
-        const parsed = loadYAML(raw);
+        const parsed = parseYAML(raw);
         // Extract prompt text (handle different YAML structures)
         let promptText = '';
         if (typeof parsed === 'string') {

package/dist/wu-consistency-checker.js

@@ -15,7 +15,7 @@
 import { readFile, writeFile, readdir, mkdir, access } from 'node:fs/promises';
 import { constants } from 'node:fs';
 import path from 'node:path';
-import yaml from 'js-yaml';
+import { parseYAML, stringifyYAML } from './wu-yaml.js';
 import { WU_PATHS } from './wu-paths.js';
 import { CONSISTENCY_TYPES, LOG_PREFIX, REMOTES, STRING_LITERALS, toKebab, WU_STATUS, YAML_OPTIONS, } from './wu-constants.js';
 import { todayISO } from './date-utils.js';
@@ -41,7 +41,7 @@ export async function checkWUConsistency(id, projectRoot = process.cwd()) {
         return { valid: true, errors: [], stats: { wuExists: false } };
     }
     const wuContent = await readFile(wuPath, { encoding: 'utf-8' });
-    const wuDoc = yaml.load(wuContent);
+    const wuDoc = parseYAML(wuContent);
     const yamlStatus = wuDoc?.status || 'unknown';
     const lane = wuDoc?.lane || '';
     const title = wuDoc?.title || '';
@@ -202,7 +202,7 @@ export async function checkLaneForOrphanDoneWU(lane, excludeId, projectRoot = pr
         }
         let wuDoc;
         try {
-            wuDoc = yaml.load(wuContent);
+            wuDoc = parseYAML(wuContent);
         }
         catch {
             // Skip malformed YAML files - they're a separate issue
@@ -341,7 +341,7 @@ async function updateYamlToDone(id, projectRoot) {
     const wuPath = path.join(projectRoot, WU_PATHS.WU(id));
     // Read current YAML
     const content = await readFile(wuPath, { encoding: 'utf-8' });
-    const wuDoc = yaml.load(content);
+    const wuDoc = parseYAML(content);
     if (!wuDoc) {
         throw new Error(`Failed to parse WU YAML: ${wuPath}`);
     }
@@ -353,7 +353,7 @@ async function updateYamlToDone(id, projectRoot) {
         wuDoc.completed = todayISO();
     }
     // Write updated YAML
-    const updatedContent = yaml.dump(wuDoc, { lineWidth: YAML_OPTIONS.LINE_WIDTH });
+    const updatedContent = stringifyYAML(wuDoc, { lineWidth: YAML_OPTIONS.LINE_WIDTH });
     await writeFile(wuPath, updatedContent, { encoding: 'utf-8' });
 }
 /**

package/dist/wu-constants.d.ts

@@ -270,6 +270,23 @@ export declare const FILE_SYSTEM: {
     /** UTF-8 encoding (alias for compatibility) */
     UTF8: string;
 };
+/**
+ * Build artifact cleanup globs
+ *
+ * Centralized glob patterns for worktree artifact cleanup.
+ */
+export declare const BUILD_ARTIFACT_GLOBS: {
+    /** Common dist directories inside worktrees */
+    DIST_DIRS: string[];
+    /** TypeScript build info files */
+    TSBUILDINFO_FILES: string[];
+};
+/**
+ * Build artifact cleanup ignore patterns
+ *
+ * Centralized ignore globs for artifact cleanup.
+ */
+export declare const BUILD_ARTIFACT_IGNORES: string[];
 /**
  * Process stdio constants
  *
@@ -352,12 +369,12 @@ export declare const DEFAULTS: {
  * YAML serialization options
  *
  * Centralized from duplicated { lineWidth: 100 } across wu-* scripts (WU-1256).
- * Use with js-yaml dump() function.
+ * Use with yaml stringify() options.
  */
 export declare const YAML_OPTIONS: {
     /** Standard line width for YAML dump (100 chars) */
     LINE_WIDTH: number;
-    /** No line wrapping (-1 disables wrapping in js-yaml) */
+    /** No line wrapping (-1 disables wrapping) */
     NO_WRAP: number;
 };
 /**
@@ -918,7 +935,6 @@ export declare const ESLINT_DEFAULTS: {
      *
      * WU-1866: Temporarily increased from 0 to 100 to unblock gates.
      * There are ~82 pre-existing warnings that need proper fixes.
-     * TODO: Create follow-up WU to fix warnings and restore zero-warnings policy.
      */
     MAX_WARNINGS: string;
 };
@@ -997,6 +1013,8 @@ export declare const GITLEAKS_ARGS: {
 export declare const PRETTIER_ARGS: {
     /** Check formatting without writing */
     CHECK: string;
+    /** List files with formatting differences */
+    LIST_DIFFERENT: string;
 };
 /**
  * Audit command arguments

package/dist/wu-constants.js

@@ -285,6 +285,30 @@ export const FILE_SYSTEM = {
     /** UTF-8 encoding (alias for compatibility) */
     UTF8: 'utf8',
 };
+/**
+ * Build artifact cleanup globs
+ *
+ * Centralized glob patterns for worktree artifact cleanup.
+ */
+export const BUILD_ARTIFACT_GLOBS = {
+    /** Common dist directories inside worktrees */
+    DIST_DIRS: [
+        'packages/*/dist',
+        'packages/**/dist',
+        'apps/*/dist',
+        'apps/**/dist',
+        'tools/*/dist',
+        'tools/**/dist',
+    ],
+    /** TypeScript build info files */
+    TSBUILDINFO_FILES: ['**/*.tsbuildinfo'],
+};
+/**
+ * Build artifact cleanup ignore patterns
+ *
+ * Centralized ignore globs for artifact cleanup.
+ */
+export const BUILD_ARTIFACT_IGNORES = ['**/node_modules/**', '**/.git/**', '**/.turbo/**'];
 /**
  * Process stdio constants
  *
@@ -367,12 +391,12 @@ export const DEFAULTS = {
  * YAML serialization options
  *
  * Centralized from duplicated { lineWidth: 100 } across wu-* scripts (WU-1256).
- * Use with js-yaml dump() function.
+ * Use with yaml stringify() options.
  */
 export const YAML_OPTIONS = {
     /** Standard line width for YAML dump (100 chars) */
     LINE_WIDTH: 100,
-    /** No line wrapping (-1 disables wrapping in js-yaml) */
+    /** No line wrapping (-1 disables wrapping) */
     NO_WRAP: -1,
 };
 /**
@@ -951,7 +975,6 @@ export const ESLINT_DEFAULTS = {
      *
      * WU-1866: Temporarily increased from 0 to 100 to unblock gates.
      * There are ~82 pre-existing warnings that need proper fixes.
-     * TODO: Create follow-up WU to fix warnings and restore zero-warnings policy.
      */
     MAX_WARNINGS: '100',
 };
@@ -1030,6 +1053,8 @@ export const GITLEAKS_ARGS = {
 export const PRETTIER_ARGS = {
     /** Check formatting without writing */
     CHECK: '--check',
+    /** List files with formatting differences */
+    LIST_DIFFERENT: '--list-different',
 };
 /**
  * Audit command arguments

package/dist/wu-done-branch-utils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Branch utilities for wu:done workflows.
+ */
+/**
+ * Check if branch is already merged to main
+ *
+ * @param {string} branch - Lane branch name
+ * @returns {Promise<boolean>} Whether branch is already merged
+ */
+export declare function isBranchAlreadyMerged(branch: any): Promise<boolean>;

package/dist/wu-done-branch-utils.js

@@ -0,0 +1,31 @@
+/**
+ * Branch utilities for wu:done workflows.
+ */
+import { getGitForCwd } from './git-adapter.js';
+import { BRANCHES, LOG_PREFIX } from './wu-constants.js';
+import { PREFLIGHT } from './wu-done-messages.js';
+/** @constant {number} SHA_SHORT_LENGTH - Length of shortened git SHA hashes for display */
+const SHA_SHORT_LENGTH = 8;
+/**
+ * Check if branch is already merged to main
+ *
+ * @param {string} branch - Lane branch name
+ * @returns {Promise<boolean>} Whether branch is already merged
+ */
+export async function isBranchAlreadyMerged(branch) {
+    const gitAdapter = getGitForCwd();
+    try {
+        const branchTip = (await gitAdapter.getCommitHash(branch)).trim();
+        const mergeBase = (await gitAdapter.mergeBase(BRANCHES.MAIN, branch)).trim();
+        const mainHead = (await gitAdapter.getCommitHash(BRANCHES.MAIN)).trim();
+        if (branchTip === mergeBase) {
+            console.log(PREFLIGHT.BRANCH_INFO(branch, branchTip.substring(0, SHA_SHORT_LENGTH), mergeBase.substring(0, SHA_SHORT_LENGTH), mainHead.substring(0, SHA_SHORT_LENGTH)));
+            return true;
+        }
+        return false;
+    }
+    catch (e) {
+        console.warn(`${LOG_PREFIX.DONE} Warning: Could not check if branch is merged: ${e.message}`);
+        return false;
+    }
+}

package/dist/wu-done-cleanup.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Cleanup helpers for wu:done.
+ */
+/**
+ * Run cleanup operations after successful merge
+ * Removes worktree and optionally deletes lane branch
+ */
+export declare function runCleanup(docMain: any, args: any): Promise<void>;