worktree-add 1.2.1 → 1.3.1

package/dist/git/create-worktree.js

@@ -0,0 +1,39 @@
+import { getStatusLogger } from "../output/get-status-logger.js";
+import { git, localBranchExists, normalizeBranchName, remoteBranchExists, } from "./git.js";
+import { extractDiagnosticLine } from "./extract-diagnostic-line.js";
+/**
+ * Create a worktree for the given branch at the specified destination.
+ */
+export function createWorktree(branch, destinationDirectory, options) {
+    const logger = getStatusLogger(options?.logger);
+    const dryRun = options?.dryRun ?? false;
+    const normalized = normalizeBranchName(branch);
+    if (localBranchExists(normalized)) {
+        logger.step(`${dryRun ? "Would run " : ""}git worktree add -- ${destinationDirectory} refs/heads/${normalized}`);
+        if (dryRun)
+            return;
+        git("worktree", "add", "--", destinationDirectory, `refs/heads/${normalized}`);
+        return;
+    }
+    let branchExistsOnOrigin = options?.remoteBranchExists;
+    if (branchExistsOnOrigin === undefined) {
+        try {
+            branchExistsOnOrigin = remoteBranchExists(normalized);
+        }
+        catch (error) {
+            const diagnostic = extractDiagnosticLine(error);
+            throw new Error(`Failed to reach origin to check whether '${normalized}' exists: ${diagnostic}`);
+        }
+    }
+    if (branchExistsOnOrigin) {
+        logger.step(`${dryRun ? "Would run " : ""}git worktree add --track -b ${normalized} -- ${destinationDirectory} origin/${normalized}`);
+        if (dryRun)
+            return;
+        git("worktree", "add", "--track", "-b", normalized, "--", destinationDirectory, `origin/${normalized}`);
+        return;
+    }
+    logger.step(`${dryRun ? "Would run " : ""}git worktree add -b ${normalized} -- ${destinationDirectory}`);
+    if (dryRun)
+        return;
+    git("worktree", "add", "-b", normalized, "--", destinationDirectory);
+}

package/dist/git/extract-diagnostic-line.d.ts

@@ -0,0 +1 @@
+export declare function extractDiagnosticLine(error: unknown): string;

package/dist/git/extract-diagnostic-line.js

@@ -0,0 +1,13 @@
+export function extractDiagnosticLine(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const trimmed = message.trim();
+    const nonEmptyLines = trimmed
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+    return (
+    // Best-effort: match English prefixes; localized messages fall back to the last non-empty line.
+    nonEmptyLines.find((line) => /(?:^|\s)(?:fatal:|error:)/iu.test(line)) ??
+        nonEmptyLines.at(-1) ??
+        trimmed);
+}

package/dist/git/fetch-remote-branch.d.ts

@@ -0,0 +1,21 @@
+import type { StatusLogger } from "../output/create-status-logger.js";
+type RemoteBranchStatus = "exists" | "missing" | "unknown" | "diverged";
+type BranchDivergence = {
+    ahead: number;
+    behind: number;
+};
+type NonDivergedRemoteBranchStatus = Exclude<RemoteBranchStatus, "diverged">;
+export type FetchRemoteBranchResult = {
+    status: "diverged";
+    localExists: true;
+    divergence: BranchDivergence;
+} | {
+    status: NonDivergedRemoteBranchStatus;
+    localExists: boolean;
+    divergence: undefined;
+};
+export declare function fetchRemoteBranch(branch: string, options?: {
+    dryRun?: boolean;
+    logger?: StatusLogger;
+}): FetchRemoteBranchResult;
+export {};

package/dist/git/fetch-remote-branch.js

@@ -0,0 +1,106 @@
+import { getStatusLogger } from "../output/get-status-logger.js";
+import { fetchOriginBranch, getAheadBehindCounts, getLocalBranchHead, getRemoteBranchHead, git, findWorktreeByBranchName, localBranchExists, normalizeBranchName, remoteBranchExists, } from "./git.js";
+import { extractDiagnosticLine } from "./extract-diagnostic-line.js";
+export function fetchRemoteBranch(branch, options) {
+    const logger = getStatusLogger(options?.logger);
+    const dryRun = options?.dryRun ?? false;
+    const normalized = normalizeBranchName(branch);
+    const localExists = localBranchExists(normalized);
+    if (localExists) {
+        let remoteExists;
+        try {
+            remoteExists = remoteBranchExists(normalized);
+        }
+        catch (error) {
+            const diagnostic = extractDiagnosticLine(error);
+            logger.warn(`Failed to query origin for '${normalized}': ${diagnostic}. Using existing local branch. (If you expected a remote branch, double-check your network connection and branch name.)`);
+            return { status: "unknown", localExists, divergence: undefined };
+        }
+        if (!remoteExists) {
+            return { status: "missing", localExists, divergence: undefined };
+        }
+        try {
+            if (dryRun) {
+                logger.step(`Would fetch origin/${normalized}`);
+                logger.detail(`Dry run: local '${normalized}' may be fast-forwarded after fetch if it is behind origin/${normalized}.`);
+                logger.detail("Dry run does not check local/remote divergence because it skips fetch; a real run may stop with a divergence error.");
+                return { status: "exists", localExists, divergence: undefined };
+            }
+            logger.step(`Fetching origin/${normalized} …`);
+            fetchOriginBranch(normalized);
+        }
+        catch (error) {
+            const diagnostic = extractDiagnosticLine(error);
+            logger.warn(`Failed to fetch origin/${normalized}: ${diagnostic}. Using existing local branch (origin status unknown).`);
+            return { status: "unknown", localExists, divergence: undefined };
+        }
+        const localHead = getLocalBranchHead(normalized);
+        const remoteHead = getRemoteBranchHead(normalized);
+        if (!localHead || !remoteHead || localHead === remoteHead) {
+            return { status: "exists", localExists, divergence: undefined };
+        }
+        let counts;
+        try {
+            counts = getAheadBehindCounts(localHead, remoteHead);
+        }
+        catch (error) {
+            const diagnostic = extractDiagnosticLine(error);
+            logger.warn(`Failed to compare local '${normalized}' with origin/${normalized}: ${diagnostic}. Using existing local branch as-is.`);
+            return { status: "exists", localExists, divergence: undefined };
+        }
+        const { ahead, behind } = counts;
+        if (ahead === 0 && behind > 0) {
+            // Note: dryRun returns before fetching, so this path only runs when dryRun is false.
+            // resolveWorktreeContext already blocks this, but keep as a defensive check.
+            const activeWorktree = findWorktreeByBranchName(normalized);
+            if (activeWorktree) {
+                logger.warn(`Local branch '${normalized}' is checked out in ${activeWorktree}; skipping fast-forward.`);
+                return { status: "exists", localExists, divergence: undefined };
+            }
+            logger.detail(`Fast-forwarding '${normalized}' from ${localHead} to ${remoteHead}.`);
+            logger.step(`Fast-forwarding local '${normalized}' to origin/${normalized} …`);
+            git("branch", "-f", "--", normalized, `origin/${normalized}`);
+            return { status: "exists", localExists, divergence: undefined };
+        }
+        if (ahead === 0 && behind === 0) {
+            // Defensive: rev-list should report differences when heads differ,
+            // but shallow/corrupted refs can yield 0/0 counts.
+            logger.warn(`Local branch '${normalized}' differs from origin/${normalized}, but Git reports no ahead/behind differences. Using existing local branch; if you encounter issues, try re-cloning the repository.`);
+            return { status: "exists", localExists, divergence: undefined };
+        }
+        if (ahead > 0 && behind > 0) {
+            return {
+                status: "diverged",
+                localExists,
+                divergence: { ahead, behind },
+            };
+        }
+        logger.warn(`Local branch '${normalized}' is ahead of origin/${normalized} (ahead by ${ahead}); using existing local branch as-is.`);
+        return { status: "exists", localExists, divergence: undefined };
+    }
+    let remoteExists;
+    try {
+        remoteExists = remoteBranchExists(normalized);
+    }
+    catch (error) {
+        const diagnostic = extractDiagnosticLine(error);
+        logger.warn(`Failed to reach origin to check whether '${normalized}' exists: ${diagnostic}. (If you expected a remote branch, double-check your network connection and branch name.)`);
+        return { status: "unknown", localExists, divergence: undefined };
+    }
+    if (!remoteExists) {
+        return { status: "missing", localExists, divergence: undefined };
+    }
+    try {
+        if (dryRun) {
+            logger.step(`Would fetch origin/${normalized}`);
+            return { status: "exists", localExists, divergence: undefined };
+        }
+        logger.step(`Fetching origin/${normalized} …`);
+        fetchOriginBranch(normalized);
+    }
+    catch (error) {
+        const diagnostic = extractDiagnosticLine(error);
+        throw new Error(`Failed to fetch origin/${normalized}: ${diagnostic}. Cannot proceed without a local branch.`);
+    }
+    return { status: "exists", localExists, divergence: undefined };
+}

package/dist/git/git.d.ts

@@ -21,10 +21,16 @@ export declare function normalizeBranchName(name: string): string;
 export declare function localBranchExists(branch: string): boolean;
 /**
  * Check if a remote branch exists on origin.
+ *
+ * Note: this function may throw on network/auth failures or when the `origin`
+ * remote is missing/misconfigured. Callers that want a degraded-mode fallback
+ * should wrap it in try/catch.
  */
 export declare function remoteBranchExists(branch: string): boolean;
 /**
- * Fetch a branch from origin.
+ * Fetch a branch from origin into the remote-tracking ref.
+ *
+ * This does not update any local branch heads.
  */
 export declare function fetchOriginBranch(branch: string): void;
 /**
@@ -35,6 +41,10 @@ export declare function getLocalBranchHead(branch: string): string | undefined;
  * Get the current head commit for a remote-tracking branch.
  */
 export declare function getRemoteBranchHead(branch: string): string | undefined;
+export declare function getAheadBehindCounts(localHead: string, remoteHead: string): {
+    ahead: number;
+    behind: number;
+};
 /**
  * Convert an arbitrary string to a filesystem-safe single path segment.
  *
@@ -50,10 +60,6 @@ export declare function fileExists(p: string): Promise<boolean>;
  * Print an error message and exit the process with status 1.
  */
 export declare function exitWithMessage(message: string): never;
-/**
- * Prompt for input and return the user's response.
- */
-export declare function prompt(message: string): Promise<string>;
 /**
  * Prompts user for yes/no confirmation
  * @param message The message to display to the user

package/dist/git/git.js

@@ -24,6 +24,8 @@ export function git(...arguments_) {
     const result = spawnSync("git", gitArguments, {
         encoding: "utf8",
         maxBuffer: 100 * 1024 * 1024, // 100 MB to accommodate large outputs
+        stdio: ["ignore", "pipe", "pipe"],
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
         ...(cwd && { cwd }),
     });
     if (result.error)
@@ -63,30 +65,26 @@ export function localBranchExists(branch) {
 }
 /**
  * Check if a remote branch exists on origin.
+ *
+ * Note: this function may throw on network/auth failures or when the `origin`
+ * remote is missing/misconfigured. Callers that want a degraded-mode fallback
+ * should wrap it in try/catch.
  */
 export function remoteBranchExists(branch) {
-    try {
-        const normalized = normalizeBranchName(branch);
-        return !!git("ls-remote", "--heads", "origin", normalized);
-    }
-    catch {
-        return false;
-    }
+    const normalized = normalizeBranchName(branch);
+    // Use a fully-qualified ref to avoid option-parsing ambiguity for branch
+    // names starting with '-'.
+    return !!git("ls-remote", "--heads", "origin", `refs/heads/${normalized}`);
 }
 /**
- * Fetch a branch from origin.
+ * Fetch a branch from origin into the remote-tracking ref.
+ *
+ * This does not update any local branch heads.
  */
 export function fetchOriginBranch(branch) {
     const normalized = normalizeBranchName(branch);
     const refspec = `+refs/heads/${normalized}:refs/remotes/origin/${normalized}`;
-    const result = spawnSync("git", ["fetch", "origin", "--", refspec], {
-        stdio: "inherit",
-    });
-    if (result.error)
-        throw result.error;
-    if (result.status !== 0) {
-        throw new Error(`git fetch origin ${refspec} failed`);
-    }
+    git("fetch", "origin", "--", refspec);
 }
 /**
  * Get the current head commit for a local branch.
@@ -112,6 +110,16 @@ export function getRemoteBranchHead(branch) {
         return undefined;
     }
 }
+export function getAheadBehindCounts(localHead, remoteHead) {
+    const output = git("rev-list", "--left-right", "--count", `${localHead}...${remoteHead}`);
+    const [aheadRaw, behindRaw] = output.split(/\s+/u);
+    const ahead = Number.parseInt(aheadRaw ?? "0");
+    const behind = Number.parseInt(behindRaw ?? "0");
+    return {
+        ahead: Number.isNaN(ahead) ? 0 : ahead,
+        behind: Number.isNaN(behind) ? 0 : behind,
+    };
+}
 /**
  * Convert an arbitrary string to a filesystem-safe single path segment.
  *
@@ -149,7 +157,7 @@ export function exitWithMessage(message) {
 /**
  * Prompt for input and return the user's response.
  */
-export async function prompt(message) {
+async function prompt(message) {
     const rl = readline.createInterface({
         input: process.stdin,
         output: process.stderr,

package/dist/git/remove-worktree.d.ts

@@ -0,0 +1 @@
+export declare function removeWorktree(destinationDirectory: string): void;

package/dist/git/remove-worktree.js

@@ -0,0 +1,4 @@
+import { git } from "./git.js";
+export function removeWorktree(destinationDirectory) {
+    git("worktree", "remove", "--force", "--", destinationDirectory);
+}

package/dist/output/create-status-logger.d.ts

@@ -0,0 +1,13 @@
+export type StatusLogger = {
+    readonly step: (message: string) => void;
+    readonly success: (message: string) => void;
+    readonly detail: (message: string) => void;
+    readonly warn: (message: string) => void;
+};
+type StatusLoggerOptions = {
+    readonly verbose: boolean;
+    readonly dryRun: boolean;
+    readonly decorate: boolean;
+};
+export declare function createStatusLogger(options: StatusLoggerOptions): StatusLogger;
+export {};

package/dist/output/create-status-logger.js

@@ -0,0 +1,32 @@
+const emit = (message) => {
+    console.error(message);
+};
+export function createStatusLogger(options) {
+    const shouldLogSteps = options.verbose || options.dryRun;
+    const shouldLogDetails = options.verbose || options.dryRun;
+    const stepPrefix = options.decorate ? "➤ " : "";
+    const successPrefix = options.decorate ? "✓ " : "";
+    const warningPrefix = options.decorate ? "⚠ " : "Warning: ";
+    const detailPrefix = options.decorate ? "  • " : "  - ";
+    const dryRunPrefix = options.dryRun ? "DRY RUN: " : "";
+    return {
+        step(message) {
+            if (!shouldLogSteps)
+                return;
+            emit(`${dryRunPrefix}${stepPrefix}${message}`);
+        },
+        success(message) {
+            if (!options.verbose)
+                return;
+            emit(`${dryRunPrefix}${successPrefix}${message}`);
+        },
+        detail(message) {
+            if (!shouldLogDetails)
+                return;
+            emit(`${dryRunPrefix}${detailPrefix}${message}`);
+        },
+        warn(message) {
+            emit(`${warningPrefix}${message}`);
+        },
+    };
+}

package/dist/output/get-status-logger.d.ts

@@ -0,0 +1,2 @@
+import type { StatusLogger } from "./create-status-logger.js";
+export declare function getStatusLogger(logger: StatusLogger | undefined): StatusLogger;

package/dist/output/get-status-logger.js

@@ -0,0 +1,12 @@
+// Fallback logger only emits warnings so important signals aren't dropped.
+const fallbackLogger = {
+    step() { },
+    success() { },
+    detail() { },
+    warn(message) {
+        console.error(message);
+    },
+};
+export function getStatusLogger(logger) {
+    return logger ?? fallbackLogger;
+}

package/dist/project/install-commands.js

@@ -40,7 +40,7 @@ export async function getInstallCommand(pm, cwd) {
  */
 export function getInstallMessage(cmd) {
     if (cmd.command === "npm" && cmd.args[0] === "ci") {
-        return "➤ Running npm ci (using package-lock.json) …";
+        return "Running npm ci (using package-lock.json) …";
     }
-    return `➤ Running ${formatCommand(cmd.command, cmd.args)} …`;
+    return `Running ${formatCommand(cmd.command, cmd.args)} …`;
 }

package/dist/project/next.d.ts

@@ -3,5 +3,8 @@
  *
  * Utilities for working with Next.js projects
  */
+import type { StatusLogger } from "../output/create-status-logger.js";
 export declare const isNextProject: (directory: string) => Promise<boolean>;
-export declare const isNextTypegenSupported: (directory: string) => Promise<boolean>;
+export declare const isNextTypegenSupported: (directory: string, options?: {
+    logger?: StatusLogger;
+}) => Promise<boolean>;

package/dist/project/next.js

@@ -26,9 +26,9 @@ export const isNextProject = async (directory) => {
     }
     return Boolean(packageJson.dependencies?.next ?? packageJson.devDependencies?.next);
 };
-export const isNextTypegenSupported = async (directory) => {
+export const isNextTypegenSupported = async (directory, options = {}) => {
     try {
-        const result = await runPackageManagerBinary(directory, "next", ["--help"], { stdio: "pipe" });
+        const result = await runPackageManagerBinary(directory, "next", ["--help"], { stdio: "pipe", logger: options.logger });
         if (!result) {
             return false;
         }

package/dist/project/package-manager.d.ts

@@ -3,8 +3,11 @@
  *
  * Helpers for detecting and running package managers
  */
+import type { StatusLogger } from "../output/create-status-logger.js";
 interface RunOptions {
     readonly stdio?: "inherit" | "pipe";
+    readonly dryRun?: boolean;
+    readonly logger?: StatusLogger;
 }
 interface RunBinaryResult {
     readonly stdout: string;
@@ -13,6 +16,9 @@ interface RunBinaryResult {
 /**
  * Install dependencies for a project using the detected package manager.
  */
-export declare function installDependencies(cwd: string): Promise<void>;
+export declare function installDependencies(cwd: string, options?: {
+    dryRun?: boolean;
+    logger?: StatusLogger;
+}): Promise<void>;
 export declare function runPackageManagerBinary(cwd: string, binary: string, arguments_?: string[], options?: RunOptions): Promise<RunBinaryResult | undefined>;
 export {};

package/dist/project/package-manager.js

@@ -7,6 +7,7 @@ import { spawnSync } from "node:child_process";
 import { detect } from "package-manager-detector/detect";
 import { formatCommand, getBinaryRunCommand, } from "./package-manager-commands.js";
 import { getInstallCommand, getInstallMessage } from "./install-commands.js";
+import { getStatusLogger } from "../output/get-status-logger.js";
 const runOrThrow = (command, arguments_, cwd, options = {}) => {
     const result = spawnSync(command, arguments_, {
         cwd,
@@ -42,16 +43,24 @@ async function detectPackageManager(cwd) {
 /**
  * Install dependencies for a project using the detected package manager.
  */
-export async function installDependencies(cwd) {
+export async function installDependencies(cwd, options = {}) {
+    const logger = getStatusLogger(options.logger);
+    const dryRun = options.dryRun ?? false;
     const pm = await detectPackageManager(cwd);
     const cmd = await getInstallCommand(pm, cwd);
-    console.log(getInstallMessage(cmd));
+    logger.step(getInstallMessage(cmd));
+    if (dryRun)
+        return;
     runOrThrow(cmd.command, cmd.args, cwd);
 }
 export async function runPackageManagerBinary(cwd, binary, arguments_ = [], options = {}) {
+    const logger = getStatusLogger(options.logger);
+    const dryRun = options.dryRun ?? false;
     const pm = await detectPackageManager(cwd);
     const { command, args: commandArguments } = getBinaryRunCommand(pm, binary, arguments_);
-    console.log(`➤ Running ${formatCommand(command, commandArguments)} …`);
+    logger.step(`Running ${formatCommand(command, commandArguments)} …`);
+    if (dryRun)
+        return undefined;
     const result = runOrThrow(command, commandArguments, cwd, options);
     if (options.stdio === "pipe") {
         return {

package/dist/project/setup.d.ts

@@ -3,7 +3,11 @@
  *
  * Utilities for setting up project dependencies and build artifacts
  */
+import type { StatusLogger } from "../output/create-status-logger.js";
 /**
  * Install dependencies and run Next.js typegen if applicable
  */
-export declare function setupProject(destinationDirectory: string): Promise<void>;
+export declare function setupProject(destinationDirectory: string, options?: {
+    dryRun?: boolean;
+    logger?: StatusLogger;
+}): Promise<void>;

package/dist/project/setup.js

@@ -5,27 +5,35 @@
  */
 import path from "node:path";
 import { fileExists } from "../git/git.js";
+import { getStatusLogger } from "../output/get-status-logger.js";
 import { installDependencies, runPackageManagerBinary, } from "./package-manager.js";
 import { isNextProject, isNextTypegenSupported } from "./next.js";
 /**
  * Install dependencies and run Next.js typegen if applicable
  */
-export async function setupProject(destinationDirectory) {
+export async function setupProject(destinationDirectory, options = {}) {
+    const logger = getStatusLogger(options.logger);
+    const dryRun = options.dryRun ?? false;
     const packageJsonPath = path.join(destinationDirectory, "package.json");
     if (!(await fileExists(packageJsonPath))) {
         return;
     }
-    await installDependencies(destinationDirectory);
+    await installDependencies(destinationDirectory, { dryRun, logger });
     // Run Next.js type generation if applicable
     if (await isNextProject(destinationDirectory)) {
-        console.log("➤ Checking Next.js CLI typegen support …");
-        const hasTypegenSupport = await isNextTypegenSupported(destinationDirectory);
+        if (dryRun) {
+            logger.step("Would run next typegen if supported");
+            return;
+        }
+        logger.step("Checking Next.js CLI typegen support …");
+        const hasTypegenSupport = await isNextTypegenSupported(destinationDirectory, { logger });
         if (hasTypegenSupport) {
-            console.log("➤ Running next typegen …");
-            await runPackageManagerBinary(destinationDirectory, "next", ["typegen"]);
+            await runPackageManagerBinary(destinationDirectory, "next", ["typegen"], {
+                logger,
+            });
         }
         else {
-            console.warn("! Skipping next typegen: installed Next.js CLI does not support this command.");
+            logger.warn("Skipping next typegen: installed Next.js CLI does not support this command.");
         }
     }
 }

package/dist/worktree/destination-directory.d.ts

@@ -3,8 +3,15 @@
  *
  * Utilities for managing worktree directories
  */
+import type { StatusLogger } from "../output/create-status-logger.js";
 /**
- * Check if directory exists and prompt for removal if needed
- * Returns true if the directory should be created
+ * Check if directory exists and handle removal if needed.
  */
-export declare function handleExistingDirectory(destinationDirectory: string): Promise<void>;
+type HandleExistingDirectoryOptions = {
+    readonly dryRun?: boolean;
+    readonly assumeYes?: boolean;
+    readonly interactive?: boolean;
+    readonly logger?: StatusLogger;
+};
+export declare function handleExistingDirectory(destinationDirectory: string, options?: HandleExistingDirectoryOptions): Promise<boolean>;
+export {};