@lumenflow/core 1.0.0

package/dist/wu-create-validators.d.ts

@@ -0,0 +1,42 @@
+/**
+ * WU Create Validators (WU-2107)
+ *
+ * Validation helpers for wu:create, including lane inference surfacing.
+ *
+ * When agents create WUs, this module helps surface lane inference suggestions
+ * to guide better lane selection and improve parallelization.
+ *
+ * NOTE: This is domain-specific WU workflow code, not a general utility.
+ * No external library exists for LumenFlow lane inference validation.
+ */
+/**
+ * Generate a warning message when provided lane differs from inferred lane.
+ *
+ * Returns empty string if lanes match (no warning needed).
+ *
+ * @param {string} providedLane - Lane provided by the user
+ * @param {string} inferredLane - Lane suggested by inference
+ * @param {number} confidence - Confidence score (0-100)
+ * @returns {string} Warning message or empty string if lanes match
+ */
+export declare function generateLaneMismatchWarning(providedLane: any, inferredLane: any, confidence: any): string;
+/**
+ * Check if lane validation should show a suggestion
+ *
+ * @param {string} providedLane - Lane provided by the user
+ * @param {string[]} codePaths - Code paths from WU
+ * @param {string} description - WU description
+ * @param {Function} inferSubLane - Lane inference function
+ * @returns {{ shouldWarn: boolean, warning: string }} Validation result
+ */
+export declare function validateLaneWithInference(providedLane: any, codePaths: any, description: any, inferSubLane: any): {
+    shouldWarn: boolean;
+    warning: string;
+    inferredLane?: undefined;
+    confidence?: undefined;
+} | {
+    shouldWarn: boolean;
+    warning: string;
+    inferredLane: any;
+    confidence: any;
+};

package/dist/wu-create-validators.js

@@ -0,0 +1,93 @@
+/**
+ * WU Create Validators (WU-2107)
+ *
+ * Validation helpers for wu:create, including lane inference surfacing.
+ *
+ * When agents create WUs, this module helps surface lane inference suggestions
+ * to guide better lane selection and improve parallelization.
+ *
+ * NOTE: This is domain-specific WU workflow code, not a general utility.
+ * No external library exists for LumenFlow lane inference validation.
+ */
+/** Confidence threshold for showing suggestion (percentage) */
+const CONFIDENCE_THRESHOLD_LOW = 30;
+/**
+ * Generate a warning message when provided lane differs from inferred lane.
+ *
+ * Returns empty string if lanes match (no warning needed).
+ *
+ * @param {string} providedLane - Lane provided by the user
+ * @param {string} inferredLane - Lane suggested by inference
+ * @param {number} confidence - Confidence score (0-100)
+ * @returns {string} Warning message or empty string if lanes match
+ */
+export function generateLaneMismatchWarning(providedLane, inferredLane, confidence) {
+    // Normalize lanes for comparison (handle parent-only vs sub-lane)
+    const normalizedProvided = providedLane.trim();
+    const normalizedInferred = inferredLane.trim();
+    // If lanes match exactly, no warning needed
+    if (normalizedProvided === normalizedInferred) {
+        return '';
+    }
+    // Check if provided is parent-only and inferred is a sub-lane of that parent
+    const inferredParent = normalizedInferred.split(':')[0].trim();
+    if (normalizedProvided === inferredParent) {
+        // User provided parent-only, suggest the specific sub-lane
+        return formatWarningMessage(normalizedInferred, confidence, true);
+    }
+    // Lanes are different, show suggestion
+    return formatWarningMessage(normalizedInferred, confidence, false);
+}
+/**
+ * Format the warning message based on confidence level
+ *
+ * @param {string} suggestedLane - The suggested lane
+ * @param {number} confidence - Confidence score (0-100)
+ * @param {boolean} isSubLaneSuggestion - True if suggesting sub-lane for parent-only input
+ * @returns {string} Formatted warning message
+ */
+function formatWarningMessage(suggestedLane, confidence, isSubLaneSuggestion) {
+    const confidenceStr = `${confidence}%`;
+    if (confidence < CONFIDENCE_THRESHOLD_LOW) {
+        return (`Lane suggestion (low confidence ${confidenceStr}): "${suggestedLane}"\n` +
+            `Run: pnpm wu:infer-lane --id WU-XXX to verify\n` +
+            `See: .lumenflow.lane-inference.yaml for lane taxonomy`);
+    }
+    if (isSubLaneSuggestion) {
+        return (`Suggested sub-lane (${confidenceStr} confidence): "${suggestedLane}"\n` +
+            `Using specific sub-lanes improves parallelization.\n` +
+            `Run: pnpm wu:infer-lane --id WU-XXX to verify`);
+    }
+    return (`Lane inference suggests: "${suggestedLane}" (${confidenceStr} confidence)\n` +
+        `Consider using the inferred lane for better lane distribution.\n` +
+        `Run: pnpm wu:infer-lane --id WU-XXX to verify`);
+}
+/**
+ * Check if lane validation should show a suggestion
+ *
+ * @param {string} providedLane - Lane provided by the user
+ * @param {string[]} codePaths - Code paths from WU
+ * @param {string} description - WU description
+ * @param {Function} inferSubLane - Lane inference function
+ * @returns {{ shouldWarn: boolean, warning: string }} Validation result
+ */
+export function validateLaneWithInference(providedLane, codePaths, description, inferSubLane) {
+    // Skip inference if no code paths provided
+    if (!codePaths || codePaths.length === 0) {
+        return { shouldWarn: false, warning: '' };
+    }
+    try {
+        const { lane: inferredLane, confidence } = inferSubLane(codePaths, description);
+        const warning = generateLaneMismatchWarning(providedLane, inferredLane, confidence);
+        return {
+            shouldWarn: warning.length > 0,
+            warning,
+            inferredLane,
+            confidence,
+        };
+    }
+    catch {
+        // Inference failed, don't block creation
+        return { shouldWarn: false, warning: '' };
+    }
+}

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

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * Branch-Only mode completion workflow for wu:done
+ * Extracted from wu-done.mjs (WU-1215 refactoring)
+ *
+ * Flow:
+ * 1. Switch to main branch
+ * 2. Merge lane branch (if not --no-merge)
+ * 3. Calculate paths relative to main checkout
+ * 4. Update metadata files (WU YAML, status.md, backlog.md, stamp)
+ * 5. Validate spec completeness
+ * 6. Stage and format files
+ * 7. Commit on main
+ * 8. Push to origin
+ */
+/**
+ * @typedef {Object} BranchOnlyContext
+ * @property {string} id - WU ID (e.g., "WU-1215")
+ * @property {Object} args - Parsed CLI arguments
+ * @property {Object} docMain - WU YAML document from main checkout
+ * @property {string} title - WU title for commit message
+ * @property {boolean} isDocsOnly - Whether this is a docs-only WU
+ * @property {number} maxCommitLength - Max commit header length from commitlint
+ * @property {function} recordTransactionState - Transaction state recorder
+ * @property {function} rollbackTransaction - Transaction rollback function
+ * @property {function} validateStagedFiles - Staged files validator
+ */
+/**
+ * @typedef {Object} BranchOnlyResult
+ * @property {boolean} success - Whether completion succeeded
+ * @property {boolean} committed - Whether changes were committed
+ * @property {boolean} pushed - Whether changes were pushed
+ * @property {boolean} merged - Whether lane branch was merged
+ */
+/**
+ * Execute branch-only mode completion
+ *
+ * @param {BranchOnlyContext} context - Branch-only mode context
+ * @returns {Promise<BranchOnlyResult>} Completion result
+ * @throws {Error} On validation or git operation failure
+ */
+export declare function executeBranchOnlyCompletion(context: any): Promise<{
+    success: boolean;
+    committed: boolean;
+    pushed: boolean;
+    merged: boolean;
+    recovered: boolean;
+} | {
+    success: boolean;
+    committed: boolean;
+    pushed: boolean;
+    merged: boolean;
+    recovered?: undefined;
+}>;
+/**
+ * Merge lane branch to main with retry logic
+ * Internal helper for branch-only mode
+ *
+ * @param {string} laneBranch - Lane branch name to merge
+ * @throws {Error} On merge failure
+ */
+declare function mergeLaneBranch(laneBranch: any): Promise<void>;
+export { mergeLaneBranch };

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

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * Branch-Only mode completion workflow for wu:done
+ * Extracted from wu-done.mjs (WU-1215 refactoring)
+ *
+ * Flow:
+ * 1. Switch to main branch
+ * 2. Merge lane branch (if not --no-merge)
+ * 3. Calculate paths relative to main checkout
+ * 4. Update metadata files (WU YAML, status.md, backlog.md, stamp)
+ * 5. Validate spec completeness
+ * 6. Stage and format files
+ * 7. Commit on main
+ * 8. Push to origin
+ */
+import path from 'node:path';
+import { defaultBranchFrom, branchExists, generateCommitMessage, updateMetadataFiles, stageAndFormatMetadata, } from './wu-done-validators.js';
+import { getGitForCwd } from './git-adapter.js';
+import { readWU } from './wu-yaml.js';
+import { BRANCHES, REMOTES, LOG_PREFIX, EMOJI, STRING_LITERALS } from './wu-constants.js';
+import { RECOVERY } from './wu-done-messages.js';
+import { die, createError, ErrorCodes } from './error-handler.js';
+import { validateWU, validateDoneWU } from './wu-schema.js';
+import { assertTransition } from './state-machine.js';
+import { detectZombieState, recoverZombieState } from './wu-recovery.js';
+/**
+ * @typedef {Object} BranchOnlyContext
+ * @property {string} id - WU ID (e.g., "WU-1215")
+ * @property {Object} args - Parsed CLI arguments
+ * @property {Object} docMain - WU YAML document from main checkout
+ * @property {string} title - WU title for commit message
+ * @property {boolean} isDocsOnly - Whether this is a docs-only WU
+ * @property {number} maxCommitLength - Max commit header length from commitlint
+ * @property {function} recordTransactionState - Transaction state recorder
+ * @property {function} rollbackTransaction - Transaction rollback function
+ * @property {function} validateStagedFiles - Staged files validator
+ */
+/**
+ * @typedef {Object} BranchOnlyResult
+ * @property {boolean} success - Whether completion succeeded
+ * @property {boolean} committed - Whether changes were committed
+ * @property {boolean} pushed - Whether changes were pushed
+ * @property {boolean} merged - Whether lane branch was merged
+ */
+/**
+ * Execute branch-only mode completion
+ *
+ * @param {BranchOnlyContext} context - Branch-only mode context
+ * @returns {Promise<BranchOnlyResult>} Completion result
+ * @throws {Error} On validation or git operation failure
+ */
+export async function executeBranchOnlyCompletion(context) {
+    const { id, args, docMain, title, isDocsOnly, maxCommitLength, recordTransactionState, rollbackTransaction, validateStagedFiles, } = context;
+    let merged = false;
+    // Step 1: Switch to main and optionally merge lane branch
+    const gitAdapter = getGitForCwd();
+    if (!args.noMerge) {
+        const laneBranch = await defaultBranchFrom(docMain);
+        if (laneBranch && (await branchExists(laneBranch))) {
+            console.log(`\n${LOG_PREFIX.DONE} Switching to ${BRANCHES.MAIN} for merge...`);
+            await gitAdapter.checkout(BRANCHES.MAIN);
+            await mergeLaneBranch(laneBranch);
+            merged = true;
+        }
+        else {
+            console.log(`${LOG_PREFIX.DONE} No lane branch found (${laneBranch || 'unknown'}), skipping merge`);
+            await gitAdapter.checkout(BRANCHES.MAIN);
+        }
+    }
+    else {
+        console.log(`\n${LOG_PREFIX.DONE} Switching to ${BRANCHES.MAIN} for completion commit...`);
+        await gitAdapter.checkout(BRANCHES.MAIN);
+    }
+    // Step 2: Calculate paths relative to main checkout
+    const metadataBasePath = '.';
+    const metadataWUPath = path.join(metadataBasePath, 'docs', '04-operations', 'tasks', 'wu', `${id}.yaml`);
+    const metadataStatusPath = path.join(metadataBasePath, 'docs', '04-operations', 'tasks', 'status.md');
+    const metadataBacklogPath = path.join(metadataBasePath, 'docs', '04-operations', 'tasks', 'backlog.md');
+    const metadataStampsDir = path.join(metadataBasePath, '.beacon', 'stamps');
+    const metadataStampPath = path.join(metadataStampsDir, `${id}.done`);
+    // Step 3: Read WU YAML and validate current state
+    const docForUpdate = readWU(metadataWUPath, id);
+    const currentStatus = docForUpdate.status || 'in_progress';
+    // Check for zombie state (recovery mode)
+    if (detectZombieState(docForUpdate, null)) {
+        await recoverZombieState({ id, doc: docForUpdate, _worktreePath: null, _args: args });
+        console.log(`\n${RECOVERY.SUCCESS}`);
+        console.log(`- WU: ${id} — ${title}`);
+        return { success: true, committed: false, pushed: false, merged, recovered: true };
+    }
+    // Validate state transition
+    try {
+        assertTransition(currentStatus, 'done', id);
+    }
+    catch (error) {
+        die(`State transition validation failed: ${error.message}`);
+    }
+    // Step 4: Record transaction state for atomic rollback
+    const transactionState = recordTransactionState(id, metadataWUPath, metadataStampPath, metadataBacklogPath, metadataStatusPath);
+    console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Transaction BEGIN - state recorded for rollback (WU YAML + backlog + status)`);
+    try {
+        // Step 5: Validate spec completeness
+        const schemaResult = validateWU(docForUpdate);
+        if (!schemaResult.success) {
+            const errors = schemaResult.error.issues.map((issue) => `  - ${issue.path.join('.')}: ${issue.message}`);
+            die(`WU YAML validation failed:\n${errors.join(STRING_LITERALS.NEWLINE)}`);
+        }
+        const completenessResult = validateDoneWU(docForUpdate);
+        if (!completenessResult.valid) {
+            die(`Cannot mark WU as done - spec incomplete:\n  ${completenessResult.errors.join('\n  ')}`);
+        }
+        // Step 6: Update metadata files
+        // WU-1572: Now async for state store integration
+        await updateMetadataFiles({
+            id,
+            title,
+            doc: docForUpdate,
+            wuPath: metadataWUPath,
+            statusPath: metadataStatusPath,
+            backlogPath: metadataBacklogPath,
+        });
+        // Step 7: Stage and format files
+        await stageAndFormatMetadata({
+            id,
+            wuPath: metadataWUPath,
+            statusPath: metadataStatusPath,
+            backlogPath: metadataBacklogPath,
+            stampsDir: metadataStampsDir,
+        });
+        // Validate staged files
+        await validateStagedFiles(id, isDocsOnly);
+        // Step 8: Commit on main
+        const msg = generateCommitMessage(id, title, maxCommitLength);
+        const gitCwd = getGitForCwd();
+        await gitCwd.commit(msg);
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Metadata committed on main`);
+        // Step 9: Push to origin
+        await gitAdapter.push(REMOTES.ORIGIN, BRANCHES.MAIN);
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Pushed to ${REMOTES.ORIGIN}/${BRANCHES.MAIN}`);
+        return { success: true, committed: true, pushed: true, merged };
+    }
+    catch (err) {
+        // Atomic rollback on failure
+        await rollbackTransaction(transactionState, metadataWUPath, metadataStampPath, metadataBacklogPath, metadataStatusPath);
+        // Re-throw with context
+        console.log('\n╔══════════════════════════════════════════════════════════════════╗');
+        console.log('║  WU:DONE FAILED (Branch-Only Mode)');
+        console.log('╠══════════════════════════════════════════════════════════════════╣');
+        console.log(`║  Error: ${err.message}`);
+        console.log('║');
+        console.log('║  Transaction rolled back - WU remains not-done.');
+        console.log('║');
+        console.log('║  Recovery steps:');
+        console.log('║  1. Fix the issue');
+        console.log(`║  2. Retry: pnpm wu:done --id ${id}`);
+        console.log('╚══════════════════════════════════════════════════════════════════╝');
+        throw err;
+    }
+}
+/**
+ * Merge lane branch to main with retry logic
+ * Internal helper for branch-only mode
+ *
+ * @param {string} laneBranch - Lane branch name to merge
+ * @throws {Error} On merge failure
+ */
+async function mergeLaneBranch(laneBranch) {
+    console.log(`${LOG_PREFIX.DONE} Merging ${laneBranch} to main (ff-only)...`);
+    const gitAdapter = getGitForCwd();
+    try {
+        // First attempt: fast-forward only
+        await gitAdapter.merge(laneBranch, { ffOnly: true });
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Lane branch merged to main`);
+    }
+    catch {
+        // Retry with pull if ff-only fails (main may have advanced)
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Fast-forward merge failed, attempting pull + retry...`);
+        try {
+            await gitAdapter.pull(REMOTES.ORIGIN, BRANCHES.MAIN);
+            await gitAdapter.merge(laneBranch, { ffOnly: true });
+            console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Lane branch merged after pull`);
+        }
+        catch (retryErr) {
+            throw createError(ErrorCodes.GIT_ERROR, `Failed to merge lane branch ${laneBranch}: ${retryErr.message}\n` +
+                `Suggestion: Rebase your lane branch on main and retry:\n` +
+                `  cd worktrees/<lane>-<wu>; git rebase main`, { branch: laneBranch, error: retryErr.message });
+        }
+    }
+}
+// Export for testing
+export { mergeLaneBranch };

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

@@ -0,0 +1,119 @@
+/**
+ * @file wu-done-messages.mjs
+ * @description Constants and message templates for wu-done operations
+ * WU-1159: Eliminate string literals (DRY/SOLID compliance)
+ * WU-1281: Use centralized LOG_PREFIX and EMOJI from wu-constants.mjs
+ *
+ * All log messages, error messages, and text templates extracted to constants.
+ * Prevents duplication and makes text maintainable.
+ */
+import { LOG_PREFIX } from './wu-constants.js';
+export { LOG_PREFIX };
+/**
+ * Recovery mode messages (WU-1159)
+ */
+export declare const RECOVERY: {
+    DETECTED: string;
+    RESUMING: string;
+    EXPLANATION: string;
+    CREATING_STAMP: string;
+    STAMP_CREATED: string;
+    UPDATING_YAML: string;
+    YAML_UPDATED: string;
+    UPDATING_DOCS: string;
+    DOCS_UPDATED: string;
+    COMMITTING: string;
+    COMMIT_SUCCESS: string;
+    COMMIT_FAILED: (error: any) => string;
+    MARKERS_VERIFIED: string;
+    PROCEEDING_CLEANUP: string;
+    SUCCESS: string;
+};
+/**
+ * Worktree operations
+ */
+export declare const WORKTREE: {
+    REMOVED: (path: any) => string;
+    NOT_FOUND: string;
+    REMOVE_FAILED: (path: any, error: any) => string;
+    PRESERVED_PR_MODE: string;
+};
+/**
+ * Branch operations
+ */
+export declare const BRANCH: {
+    DELETED_LOCAL: (branch: any) => string;
+    DELETED_REMOTE: (branch: any) => string;
+    DELETE_FAILED: (branch: any, error: any) => string;
+    DELETE_REMOTE_FAILED: (error: any) => string;
+    PRESERVED_PR_MODE: string;
+};
+/**
+ * Completion messages
+ */
+export declare const COMPLETION: {
+    SUCCESS_HEADER: (id: any, title: any) => string;
+    TRANSACTION_COMMIT: string;
+};
+/**
+ * State transition errors
+ */
+export declare const STATE_TRANSITION: {
+    VALIDATION_FAILED: (error: any) => string;
+};
+/**
+ * Auto-rebase messages (WU-1303)
+ */
+export declare const REBASE: {
+    STARTING: (branch: any, mainBranch: any) => string;
+    SUCCESS: string;
+    FAILED: (error: any) => string;
+    ABORTED: string;
+    MANUAL_FIX: (worktreePath: any, remote: any, mainBranch: any, branch: any) => string;
+};
+/**
+ * Pre-flight check messages (WU-755, WU-1303, WU-1370)
+ */
+export declare const PREFLIGHT: {
+    RUNNING: string;
+    BRANCH_BEHIND: (commitsBehind: any, threshold: any) => string;
+    BRANCH_DRIFT_INFO: (commitsBehind: any) => string;
+    BRANCH_DRIFT_WARNING: (commitsBehind: any) => string;
+    DIVERGENCE_DETECTED: (commitCount: any) => string;
+    NO_DIVERGENCE: string;
+    NO_CONFLICTS: string;
+    ALREADY_MERGED: string;
+    ALREADY_MERGED_EXPLANATION: string;
+    BRANCH_INFO: (branch: any, branchTip: any, mergeBase: any, mainHead: any) => string;
+    BRANCH_DRIFT_ERROR: (mainAhead: any, threshold: any, remote: any, mainBranch: any) => string;
+    DIVERGENCE_ERROR: (commitCount: any, remote: any, mainBranch: any, branch: any) => string;
+    CONFLICT_ERROR: (remote?: string, mainBranch?: string) => string;
+    MERGE_COMMITS_DETECTED: (count: any) => string;
+    MERGE_COMMITS_REBASING: string;
+    NO_MERGE_COMMITS: string;
+    EMPTY_MERGE_WARNING: (commitCount: any) => string;
+    EMPTY_MERGE_CHECK: string;
+    CODE_PATHS_NOT_MODIFIED: (missingFiles: any) => string;
+    CODE_PATHS_VERIFIED: string;
+};
+/**
+ * Merge operation messages (WU-1303)
+ */
+export declare const MERGE: {
+    STARTING: (branch: any) => string;
+    BRANCH_MERGE: (branch: any) => string;
+    SUCCESS: (branch: any) => string;
+    ATOMIC_SUCCESS: string;
+    FF_FAILED_RETRY: string;
+    UPDATED_MAIN: (remote: any) => string;
+    PUSHED: (remote: any, mainBranch: any) => string;
+    FF_MERGE_ERROR: (branch: any, mergeError: any, pullError: any, remote?: string, mainBranch?: string) => string;
+    FF_DIVERGED_ERROR: (branch: any, originalError: any, mainBranch?: string) => string;
+    FF_FAILED_NON_DIVERGED_ERROR: (branch: any, originalError: any, mainBranch?: string) => string;
+};
+/**
+ * Pre-push gate messages (WU-1303)
+ */
+export declare const PREPUSH: {
+    WORKTREE_SKIP: string;
+};