@solaqua/gji 0.10.0 → 0.12.0

package/dist/bootstrap-preview.d.ts

@@ -0,0 +1,10 @@
+import type { DependencyBootstrapMode } from "./config.js";
+import { type BootstrapTarget, type DependencyBootstrapPreview } from "./dependency-bootstrap.js";
+export declare function createDependencyBootstrapPreview(mode: DependencyBootstrapMode, context: {
+    repoRoot: string;
+    currentRoot?: string;
+    worktreePath: string;
+    cargoBuildCommand?: string;
+    checkUvRuntime?: (target: BootstrapTarget) => Promise<boolean>;
+}): Promise<DependencyBootstrapPreview>;
+export declare function formatDependencyBootstrapPreview(preview: DependencyBootstrapPreview | undefined): string;

package/dist/bootstrap-preview.js

@@ -0,0 +1,21 @@
+import { prepareDependencyBootstrap, previewDependencyBootstrap, } from "./dependency-bootstrap.js";
+export async function createDependencyBootstrapPreview(mode, context) {
+    return previewDependencyBootstrap(await prepareDependencyBootstrap(mode, context));
+}
+export function formatDependencyBootstrapPreview(preview) {
+    if (!preview)
+        return "";
+    return preview.targets
+        .map(({ adapter, target, strategy }) => `Would ${formatBootstrapStrategy(strategy)} ${target} with ${adapter}\n`)
+        .join("");
+}
+function formatBootstrapStrategy(strategy) {
+    switch (strategy) {
+        case "cow-then-repair":
+            return "seed and repair";
+        case "repair-only":
+            return "repair";
+        case "install-only":
+            return "install";
+    }
+}

package/dist/clean.js

@@ -2,8 +2,10 @@ import { confirm, isCancel } from "@clack/prompts";
 import { loadEffectiveConfig } from "./config.js";
 import { isBranchMergedInto, readWorktreeHealth, resolveRemoteDefaultBranch, runGit, } from "./git.js";
 import { isHeadless } from "./headless.js";
+import { releaseWorktreeSlot } from "./slots.js";
+import { finalizeUndoOperation, recordUndoOperation } from "./undo.js";
 import { formatLastCommit, formatUpstreamState, readWorktreeInfos, serializeWorktreeInfo, } from "./worktree-info.js";
-import { deleteBranch, forceDeleteBranch, forceRemoveWorktree, isBranchUnmergedError, isWorktreeDeletionError, isWorktreeForceRemovalError, loadLinkedWorktrees, removeWorktree, } from "./worktree-management.js";
+import { deleteBranch, forceDeleteBranch, forceRemoveWorktree, isBranchUnmergedError, isSubmoduleWorktreeRemovalError, isWorktreeDeletionError, isWorktreeForceRemovalError, loadLinkedWorktrees, removeWorktree, } from "./worktree-management.js";
 import { buildWorktreePromptEntries, promptForMultipleWorktrees, } from "./worktree-picker.js";
 import { defaultConfirmForceDeleteBranch, defaultConfirmForceRemoveWorktree, } from "./worktree-prompts.js";
 export function createCleanCommand(dependencies = {}) {
@@ -79,6 +81,18 @@ export function createCleanCommand(dependencies = {}) {
         }
         const removedWorktrees = [];
         const failures = [];
+        let journal;
+        try {
+            journal = await recordUndoOperation("clean", repository.repoRoot, selectedWorktrees);
+        }
+        catch (error) {
+            emitError(options, `could not write undo journal; no worktrees were removed: ${toMessage(error)}`);
+            return 1;
+        }
+        if (!journal) {
+            emitError(options, "could not capture undo state; no worktrees were removed");
+            return 1;
+        }
         for (const worktree of selectedWorktrees) {
             if (options.stale &&
                 !(await isStaleCleanupCandidate(repository.repoRoot, worktree, staleBaseRef))) {
@@ -97,7 +111,9 @@ export function createCleanCommand(dependencies = {}) {
                     });
                     continue;
                 }
-                if (options.stale && !isWorktreeDeletionError(error)) {
+                if (options.stale &&
+                    !isWorktreeDeletionError(error) &&
+                    !isSubmoduleWorktreeRemovalError(error)) {
                     options.stderr(`Skipped ${worktree.path}: no longer a safe stale cleanup candidate\n`);
                     continue;
                 }
@@ -129,7 +145,12 @@ export function createCleanCommand(dependencies = {}) {
                 }
                 catch (error) {
                     if (!isBranchUnmergedError(error)) {
-                        throw error;
+                        failures.push({
+                            branch: worktree.branch,
+                            message: toMessage(error),
+                            path: worktree.path,
+                        });
+                        continue;
                     }
                     if (options.force ||
                         (await confirmForceDeleteBranch(worktree.branch))) {
@@ -146,6 +167,8 @@ export function createCleanCommand(dependencies = {}) {
                 }
             }
         }
+        await finalizeUndoOperation(journal, removedWorktrees);
+        await Promise.all(removedWorktrees.map((worktree) => releaseWorktreeSlot(worktree.path)));
         if (options.json) {
             const removed = removedWorktrees.map((worktree) => {
                 const info = selectedInfoByPath.get(worktree.path);
@@ -160,6 +183,7 @@ export function createCleanCommand(dependencies = {}) {
             reportCleanFailures(failures, options.stderr);
         }
         else {
+            options.stderr("undo: gji undo\n");
             options.stdout(`${repository.repoRoot}\n`);
         }
         return failures.length === 0 ? 0 : 1;

package/dist/cli.d.ts

@@ -1,8 +1,12 @@
 import { Command } from "commander";
+import { type HubCommandDependencies } from "./hub.js";
 import { type PrOpenCommandDependencies } from "./pr-open.js";
 export interface RunCliOptions {
+    columns?: number;
     cwd?: string;
+    now?: number;
     prOpenDependencies?: Partial<PrOpenCommandDependencies>;
+    hubDependencies?: Partial<HubCommandDependencies>;
     stderr?: (chunk: string) => void;
     stdout?: (chunk: string) => void;
 }

package/dist/cli.js

@@ -6,9 +6,11 @@ import { runCleanCommand } from "./clean.js";
 import { runCompletionCommand } from "./completion.js";
 import { runConfigCommand } from "./config-command.js";
 import { runDoctorCommand } from "./doctor.js";
+import { runDoneCommand } from "./done.js";
 import { runGoCommand } from "./go.js";
 import { isHeadless } from "./headless.js";
 import { runHistoryCommand } from "./history-command.js";
+import { runHubCommand } from "./hub.js";
 import { runInitCommand } from "./init.js";
 import { runLsCommand } from "./ls.js";
 import { runNewCommand } from "./new.js";
@@ -23,6 +25,8 @@ import { runHookCommand } from "./run-hook.js";
 import { runStatusCommand } from "./status.js";
 import { runSyncCommand } from "./sync.js";
 import { runSyncFilesCommand } from "./sync-files-command.js";
+import { runTaskCommand } from "./task-command.js";
+import { runUndoCommand } from "./undo.js";
 import { runWarpCommand } from "./warp.js";
 export function createProgram() {
     const program = new Command();
@@ -34,6 +38,11 @@ export function createProgram() {
         .showHelpAfterError()
         .showSuggestionAfterError();
     registerCommands(program);
+    program.addHelpText("after", "\nCommon workflows:\n" +
+        "  gji new <branch>       create a worktree\n" +
+        "  gji go <branch>        navigate to a worktree\n" +
+        "  gji go                 choose; press Tab for all repositories\n" +
+        "  gji go -               return to the previous worktree\n");
     return program;
 }
 function readPackageMetadata() {
@@ -46,21 +55,28 @@ function readPackageMetadata() {
 }
 export async function runCli(argv, options = {}) {
     await maybeNotifyForUpdates(argv);
-    if (argv[0] !== "doctor") {
-        maybeRegisterCurrentRepo(options.cwd ?? process.cwd());
-    }
-    const program = createProgram();
     const cwd = options.cwd ?? process.cwd();
     const stdout = options.stdout ?? (() => undefined);
     const stderr = options.stderr ?? (() => undefined);
+    if (shouldRegisterCurrentRepo(argv) || isHubInvocation(argv)) {
+        await maybeRegisterCurrentRepo(cwd);
+    }
+    const program = createProgram();
     program.configureOutput({
         writeErr: stderr,
         writeOut: stdout,
     });
     program.exitOverride();
-    if (argv.length === 0) {
-        program.outputHelp();
-        return { exitCode: 0 };
+    if (isHubInvocation(argv)) {
+        const exitCode = await runHubCommand({
+            columns: options.columns,
+            cwd,
+            json: argv.includes("--json"),
+            now: options.now,
+            stderr,
+            stdout,
+        }, options.hubDependencies);
+        return { exitCode };
     }
     try {
         attachCommandActions(program, {
@@ -109,23 +125,62 @@ function defaultNotifyForUpdates(pkg) {
     const notifier = updateNotifier({ pkg });
     notifier.notify();
 }
-function maybeRegisterCurrentRepo(cwd) {
-    detectRepository(cwd)
-        .then(({ repoRoot }) => registerRepo(repoRoot))
-        .catch(() => undefined);
+function shouldRegisterCurrentRepo(argv) {
+    const command = argv[0];
+    return (argv.length > 0 &&
+        ![
+            "--help",
+            "-h",
+            "--version",
+            "-V",
+            "completion",
+            "config",
+            "doctor",
+            "help",
+            "init",
+        ].includes(command ?? ""));
+}
+function isHubInvocation(argv) {
+    return argv.length === 0 || (argv.length === 1 && argv[0] === "--json");
+}
+async function maybeRegisterCurrentRepo(cwd) {
+    try {
+        const { repoRoot } = await detectRepository(cwd);
+        await registerRepo(repoRoot);
+    }
+    catch {
+        // Registration is best effort; command behaviour should not depend on it.
+    }
 }
 function registerCommands(program) {
     program
         .command("new [branch]")
-        .description("create a new branch or detached linked worktree")
+        .description("create a new branch or detached linked worktree and CoW-bootstrap configured directories")
         .option("-f, --force", "remove and recreate the worktree if the target path already exists")
         .option("--detached", "create a detached worktree without a branch")
         .option("--from-current", "base the new branch on the current worktree instead of the main worktree (cannot be combined with --detached)")
+        .option("--no-fetch", "skip refreshing the remote default branch before creating the new branch")
+        .option("--take", "move current uncommitted changes into the new worktree")
+        .option("--task <description>", "record the purpose of the new worktree")
+        .option("--copy", "copy current uncommitted changes instead of moving them (requires --take)")
         .option("--open", "open the new worktree in an editor after creation")
         .option("--editor <cli>", "editor CLI to use with --open (code, cursor, zed, …)")
         .option("--dry-run", "show what would be created without executing any git commands or writing files")
         .option("--json", "emit JSON on success or error instead of human-readable output")
         .action(notImplemented("new"));
+    program
+        .command("done [branch]")
+        .description("finish the current linked worktree and return safely")
+        .option("--force", "remove dirty or unmerged worktrees without prompting")
+        .option("--keep-branch", "remove the worktree but preserve its branch")
+        .option("--json", "emit JSON on success or error instead of human-readable output")
+        .action(notImplemented("done"));
+    program
+        .command("undo [id]")
+        .description("restore the most recent destructive worktree operation")
+        .option("--list", "list recoverable operations")
+        .option("--json", "emit JSON on success or error instead of human-readable output")
+        .action(notImplemented("undo"));
     program
         .command("init [shell]")
         .description("set up shell integration interactively or print a shell wrapper")
@@ -176,8 +231,11 @@ function registerCommands(program) {
     program
         .command("go [branch]")
         .alias("jump")
-        .description("print or select a worktree path")
+        .description("resolve and jump to a worktree path")
+        .option("--root", "navigate to the main repository root")
         .option("--print", "print the resolved worktree path explicitly")
+        .option("--quiet", "suppress the context card")
+        .option("--json", "emit JSON for an existing worktree destination")
         .action(notImplemented("go"));
     program
         .command("root")
@@ -189,6 +247,12 @@ function registerCommands(program) {
         .description("summarize repository and worktree health")
         .option("--json", "print repository and worktree health as JSON")
         .action(notImplemented("status"));
+    program
+        .command("task [task]")
+        .description("show or update the current worktree task")
+        .option("--clear", "clear the current worktree task")
+        .option("--json", "emit task metadata as JSON")
+        .action(notImplemented("task"));
     program
         .command("sync")
         .description("fetch and update one or all worktrees")
@@ -233,7 +297,7 @@ function registerCommands(program) {
     program
         .command("remove [branch]")
         .alias("rm")
-        .description("remove a linked worktree and delete its branch when present")
+        .description("deprecated: use gji done for one worktree or gji clean for bulk cleanup")
         .option("-f, --force", "bypass prompts, force-remove a dirty worktree, and force-delete an unmerged branch")
         .option("--dry-run", "show what would be deleted without removing anything")
         .option("--json", "emit JSON on success or error instead of human-readable output")
@@ -245,8 +309,7 @@ function registerCommands(program) {
         .action(notImplemented("run-hook"));
     program
         .command("warp [branch]")
-        .description("jump to any worktree across all known repos")
-        .option("-n, --new [branch]", "create a new worktree in a registered repo")
+        .description("deprecated: use gji go (press Tab for all known repos)")
         // --print is the shell-wrapper bypass signal (see SHELL_WRAPPED_COMMANDS in init.ts).
         // The shell omits GJI_WARP_OUTPUT_FILE, so writeShellOutput falls through to stdout.
         .option("--print", "print the resolved worktree path without changing directory")
@@ -276,18 +339,51 @@ function attachCommandActions(program, options) {
         const exitCode = await runNewCommand({
             ...options,
             branch,
+            copy: commandOptions.copy,
             detached: commandOptions.detached,
             dryRun: commandOptions.dryRun,
             editor: commandOptions.editor,
             fromCurrent: commandOptions.fromCurrent,
             force: commandOptions.force,
+            noFetch: commandOptions.fetch === false,
             json: commandOptions.json,
             open: commandOptions.open,
+            take: commandOptions.take,
+            task: commandOptions.task,
         });
         if (exitCode !== 0) {
             throw commanderExit(exitCode);
         }
     });
+    program.commands
+        .find((command) => command.name() === "done")
+        ?.action(async (branch, commandOptions) => {
+        const exitCode = await runDoneCommand({
+            branch,
+            cwd: options.cwd,
+            force: commandOptions.force,
+            json: commandOptions.json,
+            keepBranch: commandOptions.keepBranch,
+            stderr: options.stderr,
+            stdout: options.stdout,
+        });
+        if (exitCode !== 0)
+            throw commanderExit(exitCode);
+    });
+    program.commands
+        .find((command) => command.name() === "undo")
+        ?.action(async (id, commandOptions) => {
+        const exitCode = await runUndoCommand({
+            cwd: options.cwd,
+            id,
+            json: commandOptions.json,
+            list: commandOptions.list,
+            stderr: options.stderr,
+            stdout: options.stdout,
+        });
+        if (exitCode !== 0)
+            throw commanderExit(exitCode);
+    });
     program.commands
         .find((command) => command.name() === "init")
         ?.action(async (shell, commandOptions) => {
@@ -415,7 +511,10 @@ function attachCommandActions(program, options) {
         const exitCode = await runGoCommand({
             branch,
             cwd: options.cwd,
+            json: commandOptions.json,
             print: commandOptions.print,
+            quiet: commandOptions.quiet,
+            root: commandOptions.root,
             stderr: options.stderr,
             stdout: options.stdout,
         });
@@ -447,6 +546,20 @@ function attachCommandActions(program, options) {
             throw commanderExit(exitCode);
         }
     });
+    program.commands
+        .find((command) => command.name() === "task")
+        ?.action(async (task, commandOptions) => {
+        const exitCode = await runTaskCommand({
+            clear: commandOptions.clear,
+            cwd: options.cwd,
+            json: commandOptions.json,
+            stderr: options.stderr,
+            task,
+            stdout: options.stdout,
+        });
+        if (exitCode !== 0)
+            throw commanderExit(exitCode);
+    });
     program.commands
         .find((command) => command.name() === "sync")
         ?.action(async (commandOptions) => {
@@ -564,7 +677,12 @@ function attachCommandActions(program, options) {
     };
     program.commands
         .find((command) => command.name() === "remove")
-        ?.action(runRemovalCommand);
+        ?.action(async (branch, commandOptions) => {
+        if (!commandOptions.json) {
+            options.stderr("gji remove is deprecated; use 'gji done' for one worktree or 'gji clean' for bulk cleanup.\n");
+        }
+        return runRemovalCommand(branch, commandOptions);
+    });
     program.commands
         .find((command) => command.name() === "run-hook")
         ?.action(async (hook) => {
@@ -580,14 +698,13 @@ function attachCommandActions(program, options) {
     program.commands
         .find((command) => command.name() === "warp")
         ?.action(async (branch, commandOptions) => {
-        const newFlag = commandOptions.new;
-        const newWorktree = newFlag !== undefined && newFlag !== false;
-        const newBranch = typeof newFlag === "string" ? newFlag : undefined;
+        if (!commandOptions.json) {
+            options.stderr("gji warp is deprecated; use 'gji go' (press Tab for all repositories).\n");
+        }
         const exitCode = await runWarpCommand({
-            branch: newWorktree ? (newBranch ?? branch) : branch,
+            branch,
             cwd: options.cwd,
             json: commandOptions.json,
-            newWorktree,
             stderr: options.stderr,
             stdout: options.stdout,
         });
@@ -625,6 +742,7 @@ function attachCommandActions(program, options) {
             action: "set",
             cwd: options.cwd,
             key,
+            stderr: options.stderr,
             stdout: options.stdout,
             value,
         });

package/dist/clone-failure-store.d.ts

@@ -0,0 +1,18 @@
+export interface CloneFailureStore {
+    isCached(repoRoot: string, directory: string, scope?: string): Promise<boolean>;
+    cache(repoRoot: string, directory: string, reason: string, scope?: string): Promise<void>;
+    clear(repoRoot: string, directory: string, scope?: string): Promise<void>;
+}
+export declare class FileCloneFailureStore implements CloneFailureStore {
+    private updateQueue;
+    isCached(repoRoot: string, directory: string, scope?: string): Promise<boolean>;
+    cache(repoRoot: string, directory: string, reason: string, scope?: string): Promise<void>;
+    clear(repoRoot: string, directory: string, scope?: string): Promise<void>;
+    private update;
+    private withStateLock;
+    private readState;
+    private writeState;
+    private stateFilePath;
+}
+export declare const defaultCloneFailureStore: CloneFailureStore;
+export declare function cloneFailureScope(source: string, destination: string): Promise<string>;

package/dist/clone-failure-store.js

@@ -0,0 +1,230 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, mkdtemp, readdir, readFile, rename, rm, rmdir, stat, unlink, utimes, writeFile, } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { GLOBAL_CONFIG_DIRECTORY } from "./config.js";
+const STATE_FILE_NAME = "state.json";
+const STATE_LOCK_SUFFIX = ".lock";
+const CLONE_FAILURE_TTL_MS = 24 * 60 * 60 * 1000;
+const STATE_LOCK_TTL_MS = 30 * 1000;
+export class FileCloneFailureStore {
+    updateQueue = Promise.resolve();
+    async isCached(repoRoot, directory, scope) {
+        const state = await this.readState();
+        const repoState = state.syncDirs?.[repoRoot];
+        const key = failureKey(directory, scope);
+        if (!repoState || !Object.hasOwn(repoState, key))
+            return false;
+        const failure = repoState[key];
+        return (isPlainObject(failure) &&
+            typeof failure.failedAt === "number" &&
+            Date.now() - failure.failedAt < CLONE_FAILURE_TTL_MS);
+    }
+    async cache(repoRoot, directory, reason, scope) {
+        await this.update(async () => {
+            const state = await this.readState();
+            const syncDirs = state.syncDirs ?? {};
+            const repoState = syncDirs[repoRoot] ?? {};
+            const key = failureKey(directory, scope);
+            syncDirs[repoRoot] = {
+                ...repoState,
+                [key]: { failedAt: Date.now(), reason },
+            };
+            await this.writeState({ ...state, syncDirs });
+        });
+    }
+    async clear(repoRoot, directory, scope) {
+        await this.update(async () => {
+            const state = await this.readState();
+            const repoState = state.syncDirs?.[repoRoot];
+            const key = failureKey(directory, scope);
+            if (!repoState || !Object.hasOwn(repoState, key))
+                return;
+            const nextRepoState = { ...repoState };
+            delete nextRepoState[key];
+            const syncDirs = { ...state.syncDirs };
+            if (Object.keys(nextRepoState).length === 0)
+                delete syncDirs[repoRoot];
+            else
+                syncDirs[repoRoot] = nextRepoState;
+            await this.writeState({ ...state, syncDirs });
+        });
+    }
+    async update(operation) {
+        const next = this.updateQueue.then(() => this.withStateLock(operation), () => this.withStateLock(operation));
+        this.updateQueue = next.then(() => undefined, () => undefined);
+        await next;
+    }
+    async withStateLock(operation) {
+        const lockPath = `${this.stateFilePath()}${STATE_LOCK_SUFFIX}`;
+        const lockToken = await acquireStateLock(lockPath);
+        if (lockToken === undefined)
+            return;
+        const stopHeartbeat = startStateLockHeartbeat(lockPath, lockToken);
+        try {
+            await operation();
+        }
+        finally {
+            stopHeartbeat();
+            await releaseStateLock(lockPath, lockToken);
+        }
+    }
+    async readState() {
+        try {
+            const raw = await readFile(this.stateFilePath(), "utf8");
+            const parsed = JSON.parse(raw);
+            if (!isPlainObject(parsed))
+                return {};
+            return isPlainObject(parsed.syncDirs)
+                ? parsed
+                : { ...parsed, syncDirs: {} };
+        }
+        catch {
+            return {};
+        }
+    }
+    async writeState(state) {
+        try {
+            const path = this.stateFilePath();
+            const directory = dirname(path);
+            await mkdir(directory, { recursive: true });
+            const temporaryDirectory = await mkdtemp(join(directory, `.gji-state-${randomUUID()}-`));
+            const temporaryPath = join(temporaryDirectory, STATE_FILE_NAME);
+            try {
+                await writeFile(temporaryPath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+                await rename(temporaryPath, path);
+            }
+            finally {
+                await rm(temporaryDirectory, { force: true, recursive: true });
+            }
+        }
+        catch {
+            // The cache is advisory and must never block worktree creation.
+        }
+    }
+    stateFilePath(home = homedir()) {
+        const configuredDirectory = process.env.GJI_CONFIG_DIR;
+        const directory = configuredDirectory
+            ? resolve(configuredDirectory)
+            : join(home, GLOBAL_CONFIG_DIRECTORY);
+        return join(directory, STATE_FILE_NAME);
+    }
+}
+async function acquireStateLock(lockPath) {
+    const lockToken = randomUUID();
+    await mkdir(dirname(lockPath), { recursive: true }).catch(() => undefined);
+    for (let attempt = 0; attempt < 200; attempt += 1) {
+        try {
+            await mkdir(lockPath);
+        }
+        catch (error) {
+            if (!isErrorCode(error, "EEXIST"))
+                return undefined;
+            try {
+                const freshnessPath = await lockFreshnessPath(lockPath);
+                const lockStats = await stat(freshnessPath);
+                if (Date.now() - lockStats.mtimeMs >= STATE_LOCK_TTL_MS) {
+                    const stalePath = `${lockPath}.stale-${randomUUID()}`;
+                    try {
+                        await rename(lockPath, stalePath);
+                    }
+                    catch (renameError) {
+                        if (isErrorCode(renameError, "ENOENT"))
+                            continue;
+                        return undefined;
+                    }
+                    await rm(stalePath, { force: true, recursive: true });
+                    continue;
+                }
+            }
+            catch (lockError) {
+                if (!isErrorCode(lockError, "ENOENT"))
+                    return undefined;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 25));
+            continue;
+        }
+        try {
+            await writeFile(join(lockPath, ownerFileName(lockToken)), `${lockToken}\n`, {
+                flag: "wx",
+            });
+            return lockToken;
+        }
+        catch {
+            await rm(lockPath, { force: true, recursive: true }).catch(() => undefined);
+            return undefined;
+        }
+    }
+    return undefined;
+}
+async function lockFreshnessPath(lockPath) {
+    try {
+        const owner = (await readdir(lockPath)).find((entry) => entry.startsWith("owner-"));
+        return owner ? join(lockPath, owner) : lockPath;
+    }
+    catch (error) {
+        if (isErrorCode(error, "ENOENT"))
+            throw error;
+        return lockPath;
+    }
+}
+function startStateLockHeartbeat(lockPath, lockToken) {
+    const timer = setInterval(() => {
+        void refreshStateLock(lockPath, lockToken);
+    }, STATE_LOCK_TTL_MS / 3);
+    timer.unref?.();
+    return () => clearInterval(timer);
+}
+async function refreshStateLock(lockPath, lockToken) {
+    try {
+        const ownerPath = join(lockPath, ownerFileName(lockToken));
+        await readFile(ownerPath, "utf8");
+        const now = new Date();
+        await utimes(ownerPath, now, now);
+    }
+    catch {
+        // The cache is advisory; a failed heartbeat must not block worktree creation.
+    }
+}
+async function releaseStateLock(lockPath, lockToken) {
+    try {
+        const ownerPath = join(lockPath, ownerFileName(lockToken));
+        await unlink(ownerPath);
+        await rmdir(lockPath);
+    }
+    catch (error) {
+        if (!isErrorCode(error, "ENOENT") && !isErrorCode(error, "ENOTEMPTY")) {
+            return;
+        }
+    }
+}
+function ownerFileName(lockToken) {
+    return `owner-${lockToken}`;
+}
+export const defaultCloneFailureStore = new FileCloneFailureStore();
+export async function cloneFailureScope(source, destination) {
+    const sourcePath = resolve(source);
+    const destinationParent = resolve(dirname(destination));
+    const [sourceDevice, destinationDevice] = await Promise.all([
+        readDevice(sourcePath),
+        readDevice(destinationParent),
+    ]);
+    return JSON.stringify([sourcePath, sourceDevice, destinationDevice]);
+}
+async function readDevice(path) {
+    try {
+        return (await stat(path)).dev;
+    }
+    catch {
+        return undefined;
+    }
+}
+function failureKey(directory, scope) {
+    return scope === undefined ? directory : JSON.stringify([scope, directory]);
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isErrorCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}

package/dist/command-runner.d.ts

@@ -0,0 +1,6 @@
+export type CommandRunner = (command: string, cwd: string, stderr: (chunk: string) => void, stdout?: (chunk: string) => void, options?: CommandRunnerOptions) => Promise<void>;
+export interface CommandRunnerOptions {
+    env?: NodeJS.ProcessEnv;
+    shell?: boolean;
+}
+export declare const runCommand: CommandRunner;