@prestyj/cli 5.20.0 → 5.21.0

package/dist/core/worktree.d.ts

@@ -0,0 +1,161 @@
+export type GitLayout = {
+    worktreeRoot: string;
+    gitDir: string;
+    /** True when `.git` is a real directory (the primary checkout), false for a linked worktree. */
+    isMain: boolean;
+};
+/**
+ * Walk up from `startDir` to the nearest `.git`. A `.git` directory means the
+ * main worktree; a `.git` *file* (`gitdir: <path>`) means an already-linked
+ * worktree. Returns null when no repository encloses `startDir`.
+ */
+export declare function gitLayout(startDir: string): Promise<GitLayout | null>;
+/** The enclosing repo's root, but only when `startDir` is inside the MAIN worktree. */
+export declare function findMainWorktreeRoot(startDir: string): Promise<string | null>;
+export interface WorktreeEntry {
+    path: string;
+    branch: string | null;
+    head: string | null;
+    isBare: boolean;
+    isMain: boolean;
+}
+/**
+ * Parse `git worktree list --porcelain`. The first block is always the main
+ * worktree. Paths are canonicalised so callers can compare them by string
+ * equality (/var vs /private/var aliasing on macOS).
+ */
+export declare function listWorktrees(repoDir: string): Promise<WorktreeEntry[]>;
+/** True when `git status --porcelain` reports anything (tracked or untracked). */
+export declare function isWorkingTreeDirty(dir: string): Promise<boolean>;
+/**
+ * Normalise arbitrary text into a branch name git will accept. Returns "" when
+ * nothing usable survives, so callers can fall back to a generated name.
+ */
+export declare function slugifyBranch(input: string): string;
+/** Pure: `<home>/.ezcoder/worktrees/<basename(repoRoot)>`. */
+export declare function worktreesRootFor(repoRoot: string, homeDir?: string): string;
+export interface CreateWorktreeOptions {
+    repoDir: string;
+    branch?: string;
+    baseRef?: string;
+    allowDirty?: boolean;
+}
+export interface CreatedWorktree {
+    path: string;
+    branch: string;
+    baseRef: string;
+    created: true;
+}
+/**
+ * Create a linked worktree on a fresh branch under `worktreesRootFor(mainRoot)`.
+ * Refuses to run against a dirty main checkout unless `allowDirty` is set — a
+ * half-committed main tree is the fastest way to lose work across worktrees.
+ */
+export declare function createWorktree(opts: CreateWorktreeOptions): Promise<CreatedWorktree>;
+/**
+ * Pure: is `candidate` inside `root`?
+ *
+ * `path.relative` rather than `startsWith`: the string form says yes to
+ * `/a/worktrees-evil` for root `/a/worktrees`, and on Windows says no to a
+ * correct path that differs only in separator or drive-letter case. An empty
+ * relative path (candidate IS root) is deliberately NOT contained — removing
+ * the container itself is never what a caller means.
+ */
+export declare function isInsideWorktreesRoot(root: string, candidate: string): boolean;
+/**
+ * The first symlink at or above `dir` (stopping at the filesystem root), or
+ * null when the whole chain is real directories.
+ *
+ * A containment check alone cannot see this: `stat` dereferences every path
+ * component, so a symlink at `~/.ezcoder/worktrees` makes every path under it
+ * look like an ordinary contained directory while the removal lands in whatever
+ * checkout it points at — the user's real repo, most likely. `lstat` sees the
+ * link itself. Every destructive path routes through here.
+ */
+export declare function redirectedAncestor(dir: string): Promise<string | null>;
+export interface WorktreeStatus {
+    path: string;
+    branch: string | null;
+    /** Ref it forked from; null when unrecorded and no fallback resolved. */
+    baseRef: string | null;
+    /** Staged, modified and untracked files. Non-zero means unsaved work. */
+    dirtyFiles: number;
+    /** Commits on `branch` that `baseRef` does not contain. */
+    commitsAhead: number;
+    /** The branch is fully contained in `baseRef`. */
+    merged: boolean;
+    /** Another window is working here, so it must not be touched. */
+    busy: boolean;
+    /** Safe to remove with nothing lost. */
+    reclaimable: boolean;
+    /** Why not, in the user's words. Empty exactly when `reclaimable`. */
+    blockedBy: string[];
+}
+/**
+ * Describe one worktree well enough to decide its fate, from the worktree's own
+ * directory so a stale main-checkout view cannot mislead.
+ *
+ * Unknowns always count AGAINST reclaiming: a git call that fails leaves the
+ * entry blocked rather than deleted. The cost of a wrong "keep" is a stale
+ * folder; the cost of a wrong "delete" is lost work.
+ */
+export declare function worktreeStatus(mainRoot: string, entry: WorktreeEntry, busyPaths?: readonly string[]): Promise<WorktreeStatus>;
+/** Status for every linked worktree of `repoDir`'s repo, main checkout excluded. */
+export declare function worktreeStatuses(repoDir: string, busyPaths?: readonly string[]): Promise<WorktreeStatus[]>;
+/** Worktrees that can be removed right now with nothing lost. */
+export declare function reclaimableWorktrees(repoDir: string, busyPaths?: readonly string[]): Promise<WorktreeStatus[]>;
+export interface WorktreeRelease {
+    /** Something was at the path when the release started. */
+    existed: boolean;
+    /** The path is free now — a `worktree add` over it would succeed. */
+    freed: boolean;
+    /** The branch is gone too. */
+    branchDeleted: boolean;
+    /** Why it is not free. Set exactly when `existed && !freed`. */
+    reason?: string;
+}
+/**
+ * Free a worktree's path AND its branch. Never throws: cleanup runs on window
+ * close and on daemon startup, where an exception would surface as a crash in
+ * an unrelated flow. Everything it could not do comes back in the result.
+ *
+ * The order below is load-bearing and `prune` is not optional. `worktree
+ * remove` needs the directory to be there; a user reclaiming disk with
+ * `rm -rf ~/.ezcoder/worktrees` leaves the tree REGISTERED BUT MISSING, and git
+ * then refuses both of the things the next run needs:
+ *
+ *     $ git worktree add <path> <branch>
+ *     fatal: '<path>' is a missing but already registered worktree;
+ *     use 'add -f' to override, or 'prune' or 'remove' to clear
+ *
+ * and `git branch -d <branch>`, because the branch counts as checked out in
+ * that phantom. `git worktree prune` is the only thing that clears the
+ * registration, and it is a no-op when nothing is stale — so it runs
+ * unconditionally, and BEFORE the branch delete that depends on it.
+ */
+export declare function removeWorktree(opts: {
+    repoDir: string;
+    worktreePath: string;
+    /** Remove even with uncommitted or unmerged work. Caller must have confirmed. */
+    force?: boolean;
+    /** Delete the branch too. Default true. */
+    deleteBranch?: boolean;
+}): Promise<WorktreeRelease>;
+export interface SweepResult {
+    removed: WorktreeStatus[];
+    kept: {
+        status: WorktreeStatus;
+        reason: string;
+    }[];
+}
+/**
+ * Remove every worktree of `repoDir`'s repo that is provably free of work.
+ *
+ * The automatic entry point: window close and daemon startup. It never forces,
+ * so anything holding uncommitted or unmerged work is reported as kept, with
+ * the reason, and waits for a human. Failures are collected rather than thrown
+ * — one wedged worktree must not stop the rest of the sweep.
+ */
+export declare function sweepWorktrees(repoDir: string, busyPaths?: readonly string[]): Promise<SweepResult>;
+/** True when the repo already has at least one linked worktree registered. */
+export declare function repoHasLinkedWorktrees(mainRoot: string): Promise<boolean>;