@lumenflow/core 1.0.0

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

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+/**
+ * Worktree mode completion workflow for wu:done
+ * Extracted from wu-done.mjs (WU-1215 refactoring)
+ * Updated in WU-1369 to use atomic transaction pattern.
+ *
+ * Flow (WU-1369 Atomic Pattern):
+ * 1. cd into worktree
+ * 2. Read and validate WU state
+ * 3. Run ALL validations FIRST (before any file writes)
+ * 4. Collect all metadata changes into transaction (in memory)
+ * 5. Commit transaction (atomic write)
+ * 6. Stage and format files
+ * 7. Git commit in worktree
+ * 8. Return to main checkout
+ * 9. Either merge (default) OR create PR (pr-mode)
+ * 10. Push to origin
+ *
+ * Key guarantee: If any validation fails, NO files are modified.
+ */
+/**
+ * @typedef {Object} WorktreeContext
+ * @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 {string} worktreePath - Path to worktree
+ * @property {number} maxCommitLength - Max commit header length from commitlint
+ * @property {function} validateStagedFiles - Staged files validator
+ * NOTE: recordTransactionState/rollbackTransaction removed in WU-1369 (atomic pattern)
+ */
+/**
+ * @typedef {Object} WorktreeResult
+ * @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 (vs PR created)
+ * @property {string|null} prUrl - PR URL if PR mode was used
+ * @property {boolean} [recovered] - Whether zombie state was recovered
+ * @property {boolean} [cleanupSafe] - WU-1811: Whether worktree cleanup is safe (all steps succeeded)
+ */
+/**
+ * Execute worktree mode completion
+ *
+ * @param {WorktreeContext} context - Worktree mode context
+ * @returns {Promise<WorktreeResult>} Completion result
+ * @throws {Error} On validation or git operation failure
+ */
+export declare function executeWorktreeCompletion(context: any): Promise<{
+    success: boolean;
+    committed: boolean;
+    pushed: boolean;
+    merged: boolean;
+    prUrl: any;
+    cleanupSafe: boolean;
+}>;
+/**
+ * Check for branch drift (commits behind main)
+ * WU-755 pre-flight check
+ *
+ * @param {string} branch - Lane branch name
+ * @returns {Promise<number>} Number of commits behind main
+ */
+export declare function checkBranchDrift(branch: any): Promise<number>;
+/**
+ * Auto-rebase branch onto main
+ * WU-1303: Auto-rebase on wu:done to handle diverged branches automatically
+ * WU-1371: Added wuId parameter for post-rebase artifact cleanup
+ * WU-1749 Bug 3: Auto-resolve append-only file conflicts during rebase
+ *
+ * @param {string} branch - Lane branch name
+ * @param {string} worktreePath - Path to worktree
+ * @param {string} [wuId] - WU ID for artifact cleanup (e.g., 'WU-1371')
+ * @returns {Promise<{success: boolean, error?: string}>} Rebase result
+ */
+export declare function autoRebaseBranch(branch: any, worktreePath: any, wuId: any): Promise<{
+    success: boolean;
+    error?: undefined;
+} | {
+    success: boolean;
+    error: string;
+}>;
+/**
+ * Check for branch divergence (main has advanced since branch creation)
+ * WU-1303: Added autoRebase option (default ON) to automatically rebase diverged branches
+ * WU-1371: Added wuId option for post-rebase artifact cleanup
+ *
+ * @param {string} branch - Lane branch name
+ * @param {CheckBranchOptions} [options] - Check options
+ * @throws {Error} If divergence detected and auto-rebase fails or is disabled
+ */
+interface CheckBranchOptions {
+    /** Automatically rebase if diverged */
+    autoRebase?: boolean;
+    /** Path to worktree (required if autoRebase=true) */
+    worktreePath?: string | null;
+    /** WU ID for artifact cleanup (e.g., 'WU-1371') */
+    wuId?: string | null;
+}
+export declare function checkBranchDivergence(branch: any, options?: CheckBranchOptions): Promise<void>;
+/**
+ * Check for merge commits in lane branch that would violate linear history
+ * WU-1384: GitHub requires linear history; merge commits in lane branches must be eliminated
+ * WU-1371: Added wuId option for post-rebase artifact cleanup
+ *
+ * If merge commits are found, triggers auto-rebase to linearize history.
+ *
+ * @param {string} branch - Lane branch name
+ * @param {CheckBranchOptions} [options] - Check options
+ * @throws {Error} If merge commits found and auto-rebase fails or is disabled
+ */
+export declare function checkMergeCommits(branch: any, options?: CheckBranchOptions): Promise<void>;
+/**
+ * Check for merge conflicts using git merge-tree
+ * WU-755 pre-flight check
+ *
+ * @param {string} branch - Lane branch name
+ */
+export declare function checkMergeConflicts(branch: any): Promise<void>;
+/**
+ * WU-1456: Check for empty merge (no work commits beyond claim)
+ * WU-1460: Upgraded to BLOCK when code_paths defined but files not modified
+ *
+ * Detects when an agent runs wu:done without committing actual work.
+ * - If code_paths defined: BLOCK if those files weren't modified
+ * - If no code_paths: WARNING only (docs-only or metadata updates are valid)
+ *
+ * @param {string} branch - Lane branch name
+ * @param {object} [doc] - WU document with code_paths array (optional for backwards compatibility)
+ * @returns {Promise<void>}
+ * @throws {Error} When code_paths defined but files not modified in commits
+ */
+export declare function checkEmptyMerge(branch: any, doc?: any): Promise<void>;
+export declare function isBranchAlreadyMerged(branch: any): Promise<boolean>;
+/**
+ * Merge lane branch to main with exponential backoff retry (WU-1747)
+ *
+ * Uses retry strategy to handle concurrent completions gracefully.
+ * WU-1749 Bug 2: Will auto-rebase lane branch onto new main on retry.
+ *
+ * @param {string} branch - Lane branch name
+ * @param {Object} [options] - Merge options
+ * @param {MergeLaneBranchOptions} [options] - Merge options
+ * @throws {Error} On merge failure after all retries
+ */
+interface MergeLaneBranchOptions extends CheckBranchOptions {
+    /** Override max retry attempts */
+    maxAttempts?: number;
+}
+export declare function mergeLaneBranch(branch: any, options?: MergeLaneBranchOptions): Promise<void>;
+/**
+ * WU-1943: Check if the session has checkpoints for the given WU
+ *
+ * Used to warn agents when they're completing a WU without any checkpoints,
+ * which means no recovery data if the session crashes.
+ *
+ * @param {string} wuId - WU ID to check
+ * @param {Array|null} nodes - Memory nodes for the WU (from queryByWu)
+ * @returns {boolean} True if checkpoints exist, false otherwise
+ */
+export declare function hasSessionCheckpoints(wuId: any, nodes: any): boolean;
+/**
+ * WU-1943: Rollback branch to pre-commit SHA when merge fails
+ *
+ * When wu:done commits metadata to the lane branch but the subsequent merge
+ * to main fails, this function rolls back the branch to its pre-commit state.
+ * This prevents "zombie" states where the branch shows done but wasn't merged.
+ *
+ * @param {object} gitAdapter - Git adapter instance (must be in worktree context)
+ * @param {string} preCommitSha - SHA to reset to (captured before metadata commit)
+ * @param {string} wuId - WU ID for logging
+ * @returns {Promise<{success: boolean, error?: string}>} Rollback result
+ */
+export declare function rollbackBranchOnMergeFailure(gitAdapter: any, preCommitSha: any, wuId: any): Promise<{
+    success: boolean;
+    error?: undefined;
+} | {
+    success: boolean;
+    error: any;
+}>;
+export {};