@lumenflow/core 1.0.0

package/dist/git-adapter.d.ts

@@ -0,0 +1,395 @@
+/**
+ * @file git-adapter.mjs
+ * @description Git operations adapter using simple-git library
+ * WU-1082: Extract shared utilities (eliminate run() duplication)
+ * WU-1213: Refactor to use simple-git library (eliminate execSync)
+ * WU-2242: Add runtime type assertions to prevent silent API misuse
+ *
+ * Replaces run() function in:
+ * - tools/wu-claim.mjs
+ * - tools/wu-done.mjs
+ * - tools/wu-block.mjs
+ * - tools/wu-unblock.mjs
+ * - tools/wu-create.mjs
+ * - tools/wu-cleanup.mjs
+ * - tools/gates-pre-commit.mjs
+ * - tools/validate.mjs
+ * - tools/guard-worktree-commit.mjs
+ */
+import { type SimpleGit } from 'simple-git';
+interface GitAdapterOptions {
+    git?: SimpleGit;
+    baseDir?: string;
+}
+interface PushOptions {
+    setUpstream?: boolean;
+}
+interface MergeOptions {
+    ffOnly?: boolean;
+}
+interface WorktreeRemoveOptions {
+    force?: boolean;
+}
+interface DeleteBranchOptions {
+    force?: boolean;
+}
+interface ResetOptions {
+    hard?: boolean;
+}
+interface LogOptions {
+    maxCount?: number;
+}
+/**
+ * Git operations adapter with dependency injection support
+ * @class GitAdapter
+ */
+export declare class GitAdapter {
+    private readonly git;
+    /**
+     * Create a GitAdapter instance
+     * @param {object} [options] - Configuration options
+     * @param {object} [options.git] - simple-git instance (for testing)
+     * @param {string} [options.baseDir] - Base directory for git operations
+     */
+    constructor(options?: GitAdapterOptions);
+    /**
+     * Get current branch name
+     * @returns {Promise<string>} Current branch name
+     * @example
+     * await git.getCurrentBranch(); // "lane/operations/wu-1213"
+     */
+    getCurrentBranch(): Promise<string>;
+    /**
+     * Get git status (porcelain format string for compatibility)
+     * @returns {Promise<string>} Status output in porcelain format
+     * @example
+     * await git.getStatus(); // " M file.txt\n?? untracked.txt"
+     */
+    getStatus(): Promise<string>;
+    /**
+     * Check if a branch exists
+     * @param {string} branch - Branch name
+     * @returns {Promise<boolean>} True if branch exists
+     * @throws {TypeError} If branch is not a string
+     * @throws {Error} If branch is empty
+     * @example
+     * await git.branchExists('main'); // true
+     * await git.branchExists('nonexistent'); // false
+     */
+    branchExists(branch: string): Promise<boolean>;
+    /**
+     * Fetch from remote
+     * @param {string} [remote] - Remote name (defaults to fetching all)
+     * @param {string} [branch] - Branch name
+     * @throws {TypeError} If remote or branch is not a string (when provided)
+     * @example
+     * await git.fetch('origin', 'main');
+     * await git.fetch(); // Fetch all remotes
+     */
+    fetch(remote?: string, branch?: string): Promise<void>;
+    /**
+     * Pull from remote branch
+     * @param {string} remote - Remote name
+     * @param {string} branch - Branch name
+     * @throws {TypeError} If remote or branch is not a string
+     * @example
+     * await git.pull('origin', 'main');
+     */
+    pull(remote: string, branch: string): Promise<void>;
+    /**
+     * Get git config value
+     * @param {string} key - Config key (e.g., 'user.email')
+     * @returns {Promise<string>} Config value
+     * @example
+     * await git.getConfigValue('user.email'); // "user@example.com"
+     */
+    getConfigValue(key: string): Promise<string>;
+    /**
+     * Check if working tree is clean (no uncommitted changes)
+     * @returns {Promise<boolean>} True if clean
+     * @example
+     * await git.isClean(); // true or false
+     */
+    isClean(): Promise<boolean>;
+    /**
+     * Add files to staging area
+     * @param {string|string[]} files - Files to add
+     * @throws {TypeError} If files is not a string or array
+     * @throws {Error} If files is empty string or empty array
+     * @example
+     * await git.add('file.txt');
+     * await git.add(['file1.txt', 'file2.txt']);
+     * await git.add('.'); // Add all
+     */
+    add(files: string | string[]): Promise<void>;
+    /**
+     * Add files to staging area including deletions
+     *
+     * WU-1813: Stages modifications, additions, AND deletions for specified files.
+     * Unlike add(), this uses `git add -A` which properly handles tracked file deletions.
+     *
+     * When files array is empty, stages all changes in the working directory (git add -A .)
+     * to catch any deletions that might not have been explicitly listed.
+     *
+     * @param {string[]} files - Files to add (empty array = add all)
+     * @example
+     * await git.addWithDeletions(['modified.txt', 'deleted.txt']);
+     * await git.addWithDeletions([]); // Add all changes including deletions
+     */
+    addWithDeletions(files: string[]): Promise<void>;
+    /**
+     * Commit changes
+     * @param {string} message - Commit message
+     * @throws {TypeError} If message is not a string
+     * @throws {Error} If message is empty
+     * @example
+     * await git.commit('feat: add new feature');
+     */
+    commit(message: string): Promise<void>;
+    /**
+     * Push to remote
+     * @param {string} [remote='origin'] - Remote name
+     * @param {string} [branch] - Branch name (uses current branch if not specified)
+     * @param {object} [options] - Push options
+     * @param {boolean} [options.setUpstream] - Set upstream tracking (-u flag)
+     * @throws {TypeError} If remote or branch is not a string (when provided)
+     * @example
+     * await git.push('origin', 'main');
+     * await git.push('origin', 'feature', { setUpstream: true });
+     */
+    push(remote?: string, branch?: string, options?: PushOptions): Promise<void>;
+    /**
+     * Push using refspec to push local ref to different remote ref
+     *
+     * WU-1435: Enables push-only pattern to keep local main pristine.
+     * Pushes directly to origin/main without updating local main.
+     *
+     * @param {string} remote - Remote name (e.g., 'origin')
+     * @param {string} localRef - Local ref to push (e.g., 'tmp/wu-claim/wu-123')
+     * @param {string} remoteRef - Remote ref to update (e.g., 'main')
+     * @example
+     * await git.pushRefspec('origin', 'tmp/wu-claim/wu-123', 'main');
+     * // Equivalent to: git push origin tmp/wu-claim/wu-123:main
+     */
+    pushRefspec(remote: string, localRef: string, remoteRef: string): Promise<void>;
+    /**
+     * Create and checkout a new branch
+     * @param {string} branch - Branch name
+     * @param {string} [startPoint] - Starting commit (defaults to HEAD)
+     * @throws {TypeError} If branch is not a string, or startPoint is not a string (when provided)
+     * @throws {Error} If branch is empty
+     * @example
+     * await git.createBranch('feature/new-feature');
+     * await git.createBranch('hotfix/bug', 'main');
+     */
+    createBranch(branch: string, startPoint?: string): Promise<void>;
+    /**
+     * Checkout a branch
+     * @param {string} branch - Branch name
+     * @throws {TypeError} If branch is not a string
+     * @throws {Error} If branch is empty
+     * @example
+     * await git.checkout('main');
+     */
+    checkout(branch: string): Promise<void>;
+    /**
+     * Get commit hash
+     * @param {string} [ref='HEAD'] - Git ref
+     * @returns {Promise<string>} Commit hash
+     * @example
+     * await git.getCommitHash(); // "a1b2c3d..."
+     * await git.getCommitHash('main'); // "e4f5g6h..."
+     */
+    getCommitHash(ref?: string): Promise<string>;
+    /**
+     * Merge a branch
+     *
+     * WU-1749: Bug 1 fix - Return success status and handle false positive failures.
+     * simple-git's merge() returns a MergeSummary that we now properly handle.
+     *
+     * @param {string} branch - Branch to merge
+     * @param {object} [options] - Merge options
+     * @param {boolean} [options.ffOnly] - Fast-forward only merge
+     * @returns {Promise<{success: boolean}>} Merge result
+     * @throws {TypeError} If branch is not a string
+     * @throws {Error} If branch is empty
+     * @example
+     * await git.merge('feature-branch');
+     * await git.merge('feature-branch', { ffOnly: true });
+     */
+    merge(branch: string, options?: MergeOptions): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get commit log
+     *
+     * WU-1749: Bug 4 fix - Add log() method for counting commits.
+     * Used by wu-done-retry-helpers.mjs to count previous completion attempts.
+     *
+     * @param {object} [options] - Log options
+     * @param {number} [options.maxCount] - Maximum number of commits to return
+     * @returns {Promise<{all: Array<{hash: string, message: string}>, total: number}>} Log result
+     * @example
+     * await git.log({ maxCount: 50 });
+     */
+    log(options?: LogOptions): Promise<import("simple-git").LogResult<import("simple-git").DefaultLogFields>>;
+    /**
+     * Find common ancestor (merge base) of two refs
+     * @param {string} ref1 - First ref
+     * @param {string} ref2 - Second ref
+     * @returns {Promise<string>} Common ancestor commit hash
+     * @throws {TypeError} If ref1 or ref2 is not a string
+     * @example
+     * await git.mergeBase('main', 'feature'); // "abc123def456"
+     */
+    mergeBase(ref1: string, ref2: string): Promise<string>;
+    /**
+     * Simulate merge and detect conflicts without touching working tree
+     * @param {string} base - Base commit hash
+     * @param {string} ref1 - First ref to merge
+     * @param {string} ref2 - Second ref to merge
+     * @returns {Promise<string>} Merge tree output (contains conflict markers if conflicts exist)
+     * @example
+     * await git.mergeTree('base123', 'main', 'feature');
+     */
+    mergeTree(base: string, ref1: string, ref2: string): Promise<string>;
+    /**
+     * List commits with various options
+     * @param {string[]} args - Arguments to pass to git rev-list
+     * @returns {Promise<string>} Rev-list output
+     * @example
+     * await git.revList(['--count', '--left-right', 'main...feature']); // "5\t0"
+     */
+    revList(args: string[]): Promise<string>;
+    /**
+     * Add a worktree with new branch
+     * @param {string} path - Worktree path
+     * @param {string} branch - Branch name
+     * @param {string} [startPoint] - Starting commit (defaults to HEAD)
+     * @throws {TypeError} If path or branch is not a string
+     * @throws {Error} If path or branch is empty
+     * @example
+     * await git.worktreeAdd('worktrees/feature', 'feature-branch', 'main');
+     */
+    worktreeAdd(path: string, branch: string, startPoint?: string): Promise<void>;
+    /**
+     * Remove a worktree
+     *
+     * WU-1476: Layer 1 defense - explicit directory cleanup after git worktree remove.
+     * Git worktree remove can leave orphan directories when:
+     * - The worktree was forcefully removed
+     * - Git worktree metadata was corrupted
+     * - Previous wu:done failed mid-workflow
+     *
+     * @param {string} worktreePath - Worktree path
+     * @param {object} [options] - Remove options
+     * @param {boolean} [options.force] - Force removal
+     * @example
+     * await git.worktreeRemove('worktrees/feature');
+     * await git.worktreeRemove('worktrees/feature', { force: true });
+     */
+    worktreeRemove(worktreePath: string, options?: WorktreeRemoveOptions): Promise<void>;
+    /**
+     * List all worktrees
+     * @returns {Promise<string>} Worktree list in porcelain format
+     * @example
+     * await git.worktreeList();
+     */
+    worktreeList(): Promise<string>;
+    /**
+     * Delete a branch
+     * @param {string} branch - Branch name
+     * @param {object} [options] - Delete options
+     * @param {boolean} [options.force] - Force delete (use -D instead of -d)
+     * @throws {TypeError} If branch is not a string
+     * @throws {Error} If branch is empty
+     * @example
+     * await git.deleteBranch('feature');
+     * await git.deleteBranch('feature', { force: true });
+     */
+    deleteBranch(branch: string, options?: DeleteBranchOptions): Promise<void>;
+    /**
+     * Create a branch WITHOUT switching to it (WU-1262)
+     * Used for micro-worktree pattern where main checkout stays on main
+     * @param {string} branch - Branch name to create
+     * @param {string} [startPoint] - Starting commit (defaults to HEAD)
+     * @example
+     * await git.createBranchNoCheckout('tmp/wu-create/wu-123', 'main');
+     */
+    createBranchNoCheckout(branch: string, startPoint?: string): Promise<void>;
+    /**
+     * Add a worktree for an EXISTING branch (WU-1262)
+     * Unlike worktreeAdd, this doesn't create a new branch
+     * @param {string} path - Worktree path
+     * @param {string} branch - Existing branch name
+     * @example
+     * await git.worktreeAddExisting('/tmp/wu-create-xyz', 'tmp/wu-create/wu-123');
+     */
+    worktreeAddExisting(path: string, branch: string): Promise<void>;
+    /**
+     * Rebase current branch onto target (WU-1262)
+     * Used in micro-worktree to rebase temp branch when main moves
+     * @param {string} onto - Target ref to rebase onto
+     * @throws {TypeError} If onto is not a string
+     * @throws {Error} If onto is empty
+     * @example
+     * await git.rebase('main');
+     */
+    rebase(onto: string): Promise<void>;
+    /**
+     * Reset HEAD to specified commit
+     * @param {string} [ref] - Commit ref to reset to (defaults to HEAD)
+     * @param {object} [options] - Reset options
+     * @param {boolean} [options.hard] - Hard reset (--hard flag)
+     * @example
+     * await git.reset('abc123', { hard: true });
+     */
+    reset(ref?: string, options?: ResetOptions): Promise<void>;
+    /**
+     * Execute arbitrary git command via raw()
+     * @param {string[]} args - Git command arguments
+     * @returns {Promise<string>} Command output
+     * @throws {TypeError} If args is not an array
+     * @example
+     * await git.raw(['status', '--porcelain']);
+     */
+    raw(args: string[]): Promise<string>;
+    /**
+     * @deprecated Use async methods directly instead
+     * Legacy method for backward compatibility
+     * Execute a git command and return trimmed output
+     * @param {string} cmd - Command to execute
+     * @returns {string} Trimmed command output
+     */
+    run(cmd: string): never;
+    /**
+     * @deprecated Use worktreeAdd() instead
+     */
+    addWorktree(path: string, branch: string, startPoint?: string): Promise<void>;
+    /**
+     * @deprecated Use worktreeRemove() instead
+     */
+    removeWorktree(path: string, options?: WorktreeRemoveOptions): Promise<void>;
+}
+/**
+ * Create a GitAdapter for a specific directory
+ * Use this when you need git operations in an explicit path (e.g., worktree vs main)
+ * @param {string} baseDir - Directory for git operations
+ * @returns {GitAdapter} New GitAdapter instance for the specified directory
+ * @example
+ * const gitWorktree = createGitForPath('/path/to/worktree');
+ * const gitMain = createGitForPath('/path/to/main');
+ */
+export declare function createGitForPath(baseDir: string): GitAdapter;
+/**
+ * Create a GitAdapter for the current working directory
+ * Captures process.cwd() at call time (not import time)
+ * Use this after process.chdir() to get an adapter for the new directory
+ * @returns {GitAdapter} New GitAdapter instance for current process.cwd()
+ * @example
+ * process.chdir(worktreePath);
+ * const git = getGitForCwd(); // Uses new directory
+ */
+export declare function getGitForCwd(): GitAdapter;
+export declare const git: GitAdapter;
+export {};