@cjhyy/code-shell-core 0.6.0-rc.9 → 0.7.0

package/dist/git/worktree/crud.d.ts

@@ -0,0 +1,69 @@
+import type { SandboxBackend } from "../../tool-system/sandbox/index.js";
+export interface WorktreeSession {
+    originalCwd: string;
+    worktreePath: string;
+    worktreeName: string;
+    worktreeBranch: string;
+    originalBranch?: string;
+    sessionId: string;
+    createdAt: number;
+}
+/** Per-platform setup/cleanup scripts (a project's localEnvironment). */
+export interface PlatformScripts {
+    default?: string;
+    macos?: string;
+    linux?: string;
+    windows?: string;
+}
+export interface CreateWorktreeOptions {
+    prefix?: string;
+}
+/**
+ * Pick the setup/cleanup script for the running platform, falling back to
+ * `default`. Empty/whitespace-only scripts are treated as absent so a project
+ * can leave a platform key blank without spawning an empty shell. `platform`
+ * defaults to `process.platform` so callers usually omit it; tests pass a
+ * fixed value.
+ */
+export declare function selectPlatformScript(scripts: PlatformScripts | undefined, platform?: NodeJS.Platform): string | undefined;
+/**
+ * Create an isolated git worktree for an agent session.
+ */
+export declare function createWorktree(cwd: string, slug: string, sessionId: string, opts?: CreateWorktreeOptions): Promise<WorktreeSession>;
+export interface WorktreeSetupResult {
+    /** True if no setup script was configured for this platform (nothing ran). */
+    skipped: boolean;
+    /** True if a script ran and exited 0. */
+    ok: boolean;
+    /** Combined stdout/stderr, for surfacing to the user on failure. */
+    output: string;
+    /** Exit code when a script ran; undefined when skipped. */
+    exitCode?: number | null;
+}
+/**
+ * Run a project's `localEnvironment.setupScripts` once, in the freshly-created
+ * worktree's root, right after `git worktree add`.
+ */
+export declare function runWorktreeSetup(worktreePath: string, script: string | undefined, opts?: {
+    sandbox?: SandboxBackend;
+    shellEnv?: Record<string, string>;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<WorktreeSetupResult>;
+export interface RemoveWorktreeResult {
+    /** True once `git worktree remove` completed and the directory is gone. */
+    dirRemoved: boolean;
+    /** The branch targeted for deletion when removeBranch=true. */
+    branch?: string;
+    /** True when removeBranch=true and branch deletion completed. */
+    branchDeleted?: boolean;
+    /** Non-empty when the worktree directory is gone but branch deletion failed. */
+    branchError?: string;
+}
+export interface RemoveWorktreeOptions {
+    prefix?: string;
+}
+/**
+ * Remove a worktree and optionally its branch.
+ */
+export declare function removeWorktree(worktreePath: string, removeBranch?: boolean, opts?: RemoveWorktreeOptions): RemoveWorktreeResult;

package/dist/git/worktree/crud.js

@@ -0,0 +1,206 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, symlinkSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { safeSpawnShell } from "../../runtime/safe-spawn.js";
+import { buildSandboxEnv, defaultShellBinary, mergeShellEnv } from "../../runtime/spawn-common.js";
+import { execGit, execGitSync, gitErrorMessage } from "./git-exec.js";
+import { assertBranchNotCheckedOut, currentBranch, findGitRoot } from "./query.js";
+import { applyPrefix, isManagedWorktreeBranch, validateWorktreeSlug } from "./slug.js";
+/**
+ * Pick the setup/cleanup script for the running platform, falling back to
+ * `default`. Empty/whitespace-only scripts are treated as absent so a project
+ * can leave a platform key blank without spawning an empty shell. `platform`
+ * defaults to `process.platform` so callers usually omit it; tests pass a
+ * fixed value.
+ */
+export function selectPlatformScript(scripts, platform = process.platform) {
+    if (!scripts)
+        return undefined;
+    const key = platform === "darwin" ? "macos" : platform === "win32" ? "windows" : "linux";
+    // A blank platform key shouldn't shadow a real `default` — fall through.
+    const platformScript = scripts[key]?.trim() ? scripts[key] : undefined;
+    const candidate = platformScript ?? scripts.default;
+    const trimmed = candidate?.trim();
+    return trimmed ? candidate : undefined;
+}
+/**
+ * Create an isolated git worktree for an agent session.
+ */
+export async function createWorktree(cwd, slug, sessionId, opts = {}) {
+    validateWorktreeSlug(slug);
+    const gitRoot = await findGitRoot(cwd);
+    const branchName = applyPrefix(opts.prefix, slug, sessionId);
+    const worktreePath = resolve(gitRoot, "..", `.worktrees/${slug}-${sessionId.slice(0, 8)}`);
+    await assertBranchNotCheckedOut(gitRoot, branchName);
+    const originalBranch = await currentBranch(gitRoot);
+    // The argv form keeps branchName/worktreePath as literal positional
+    // arguments even if a future caller bypasses validateWorktreeSlug.
+    await execGit(gitRoot, ["worktree", "add", "-b", branchName, worktreePath], 30000);
+    // Symlink large directories to avoid disk bloat.
+    symlinkLargeDirectories(gitRoot, worktreePath);
+    return {
+        originalCwd: cwd,
+        worktreePath,
+        worktreeName: slug,
+        worktreeBranch: branchName,
+        originalBranch,
+        sessionId,
+        createdAt: Date.now(),
+    };
+}
+/**
+ * Run a project's `localEnvironment.setupScripts` once, in the freshly-created
+ * worktree's root, right after `git worktree add`.
+ */
+export async function runWorktreeSetup(worktreePath, script, opts = {}) {
+    const trimmed = script?.trim();
+    if (!trimmed)
+        return { skipped: true, ok: true, output: "" };
+    const shell = defaultShellBinary();
+    const backend = opts.sandbox;
+    const baseEnv = backend && backend.name !== "off" ? buildSandboxEnv() : { ...process.env };
+    const env = mergeShellEnv(baseEnv, opts.shellEnv);
+    const result = await safeSpawnShell(trimmed, {
+        cwd: worktreePath,
+        env,
+        timeoutMs: opts.timeoutMs ?? 120_000,
+        maxOutputBytes: 1024 * 1024,
+        sandbox: backend,
+        shell,
+        signal: opts.signal,
+    });
+    const parts = [];
+    if (result.stdout)
+        parts.push(result.stdout);
+    if (result.stderr)
+        parts.push(result.stderr);
+    const output = parts.join("\n").trim();
+    if (result.aborted)
+        return { skipped: false, ok: false, output: output || "setup aborted" };
+    if (result.timedOut)
+        return { skipped: false, ok: false, output: output || "setup timed out" };
+    if (result.spawnFailed) {
+        return { skipped: false, ok: false, output: result.error ?? "failed to spawn setup script" };
+    }
+    return { skipped: false, ok: result.exitCode === 0, output, exitCode: result.exitCode };
+}
+/**
+ * Remove a worktree and optionally its branch.
+ */
+export function removeWorktree(worktreePath, removeBranch = false, opts = {}) {
+    // The MAIN repo root, not the worktree's own toplevel. `git rev-parse
+    // --show-toplevel` from inside a worktree returns the worktree path, which
+    // is about to be deleted; the branch-delete must run from the main repo,
+    // which outlives the worktree. Derive it from the common git dir.
+    let mainRoot;
+    try {
+        const commonDir = execGitSync(worktreePath, ["rev-parse", "--path-format=absolute", "--git-common-dir"], 5000).trim();
+        mainRoot = dirname(commonDir);
+    }
+    catch (err) {
+        throw new Error(`failed to inspect worktree ${worktreePath}: ${gitErrorMessage(err)}`, {
+            cause: err,
+        });
+    }
+    // Capture the worktree's branch BEFORE removing the worktree — afterwards
+    // the directory is gone and `git branch --show-current` in it would fail.
+    let branch = "";
+    if (removeBranch) {
+        try {
+            branch = execGitSync(worktreePath, ["branch", "--show-current"], 5000).trim();
+        }
+        catch (err) {
+            throw new Error(`failed to determine branch for worktree ${worktreePath}: ${gitErrorMessage(err)}`, { cause: err });
+        }
+        if (!branch) {
+            throw new Error(`failed to determine branch for worktree ${worktreePath}`);
+        }
+        if (!isManagedWorktreeBranch(branch, opts.prefix)) {
+            throw new Error(`refusing to delete non-CodeShell worktree branch ${branch}`);
+        }
+    }
+    try {
+        execGitSync(mainRoot, ["worktree", "remove", worktreePath, "--force"], 30000);
+    }
+    catch (err) {
+        throw new Error(`failed to remove worktree ${worktreePath}: ${gitErrorMessage(err)}`, {
+            cause: err,
+        });
+    }
+    if (removeBranch) {
+        try {
+            execGitSync(mainRoot, ["branch", "-D", branch], 10000);
+        }
+        catch (err) {
+            return {
+                dirRemoved: true,
+                branch,
+                branchDeleted: false,
+                branchError: gitErrorMessage(err),
+            };
+        }
+    }
+    return removeBranch ? { dirRemoved: true, branch, branchDeleted: true } : { dirRemoved: true };
+}
+/**
+ * Symlink large directories (node_modules, .venv, etc.) from main repo to
+ * worktree. Also links each monorepo workspace package's private
+ * `node_modules` (e.g. `packages/desktop/node_modules`, where bun keeps
+ * un-hoisted deps like electron) so a fresh worktree can build/run the whole
+ * workspace, not just the packages whose deps happen to be hoisted to the root.
+ */
+function symlinkLargeDirectories(sourceRoot, worktreePath) {
+    const largeDirs = ["node_modules", ".venv", "vendor", ".pnpm-store"];
+    for (const dir of largeDirs) {
+        linkDir(join(sourceRoot, dir), join(worktreePath, dir));
+    }
+    // Monorepo workspace packages keep private node_modules that are NOT hoisted
+    // to the root. Link `<pkg>/node_modules` for each package under `packages/`.
+    const packagesDir = join(sourceRoot, "packages");
+    if (!dirExists(packagesDir))
+        return;
+    let pkgNames;
+    try {
+        pkgNames = readdirSync(packagesDir);
+    }
+    catch {
+        return;
+    }
+    for (const pkg of pkgNames) {
+        const source = join(packagesDir, pkg, "node_modules");
+        if (!dirExists(source))
+            continue;
+        const targetPkgDir = join(worktreePath, "packages", pkg);
+        // The worktree only has package dirs that exist in this branch's tree; a
+        // package present in the main repo but not checked out here is skipped.
+        if (!dirExists(targetPkgDir)) {
+            try {
+                mkdirSync(targetPkgDir, { recursive: true });
+            }
+            catch {
+                continue;
+            }
+        }
+        linkDir(source, join(targetPkgDir, "node_modules"));
+    }
+}
+function dirExists(path) {
+    try {
+        return lstatSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function linkDir(source, target) {
+    // Windows directory symlinks need admin/Developer Mode and throw EPERM for a
+    // normal user; NTFS junctions don't and behave the same for our purpose.
+    const linkType = process.platform === "win32" ? "junction" : "dir";
+    if (dirExists(source) && !existsSync(target)) {
+        try {
+            symlinkSync(source, target, linkType);
+        }
+        catch {
+            // Symlink/junction might fail on some systems — non-fatal.
+        }
+    }
+}

package/dist/git/worktree/diff.d.ts

@@ -0,0 +1,14 @@
+export interface WorktreeDiffSummary {
+    /** Best-effort base used for the branch comparison, usually main/master. */
+    baseRef?: string;
+    /** Unique files changed either by commits ahead of base or by uncommitted changes. */
+    changedFiles: number;
+    /** Commits reachable from HEAD but not from baseRef. */
+    aheadCommits: number;
+    /** True when `git status --porcelain` reports local changes. */
+    hasUncommittedChanges: boolean;
+}
+export declare function getWorktreeDiff(worktreePath: string, baseRef?: string): Promise<WorktreeDiffSummary>;
+export declare function worktreeHasUncommittedChanges(worktreePath: string): Promise<boolean>;
+export declare function worktreeHasUncommittedOrAheadChanges(worktreePath: string, baseRef?: string): Promise<boolean>;
+export declare function findComparisonBaseRef(cwd: string): Promise<string | undefined>;

package/dist/git/worktree/diff.js

@@ -0,0 +1,82 @@
+import { gitOutput } from "./git-exec.js";
+export async function getWorktreeDiff(worktreePath, baseRef) {
+    const comparisonBase = baseRef && (await commitRefExists(worktreePath, baseRef))
+        ? baseRef
+        : await findComparisonBaseRef(worktreePath);
+    return diffSummary(worktreePath, comparisonBase);
+}
+export async function worktreeHasUncommittedChanges(worktreePath) {
+    const out = await gitOutput(worktreePath, ["status", "--porcelain"], 10000);
+    return (out?.trim().length ?? 0) > 0;
+}
+export async function worktreeHasUncommittedOrAheadChanges(worktreePath, baseRef) {
+    if (await worktreeHasUncommittedChanges(worktreePath))
+        return true;
+    const comparisonBase = baseRef && (await commitRefExists(worktreePath, baseRef))
+        ? baseRef
+        : await findComparisonBaseRef(worktreePath);
+    return comparisonBase ? (await aheadCommitCount(worktreePath, comparisonBase)) > 0 : false;
+}
+export async function findComparisonBaseRef(cwd) {
+    for (const ref of ["main", "master", "origin/main", "origin/master"]) {
+        if (await commitRefExists(cwd, ref))
+            return ref;
+    }
+    return undefined;
+}
+async function commitRefExists(cwd, ref) {
+    const out = await gitOutput(cwd, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], 5000);
+    return out !== undefined;
+}
+async function diffSummary(cwd, baseRef) {
+    const [dirtyFiles, committedFiles, aheadCommits] = await Promise.all([
+        statusFileSet(cwd),
+        baseRef ? changedFilesSinceBase(cwd, baseRef) : Promise.resolve(new Set()),
+        baseRef ? aheadCommitCount(cwd, baseRef) : Promise.resolve(0),
+    ]);
+    const changedFiles = new Set([...dirtyFiles, ...committedFiles]);
+    return {
+        ...(baseRef ? { baseRef } : {}),
+        changedFiles: changedFiles.size,
+        aheadCommits,
+        hasUncommittedChanges: dirtyFiles.size > 0,
+    };
+}
+async function changedFilesSinceBase(cwd, baseRef) {
+    const out = await gitOutput(cwd, ["diff", "--name-only", `${baseRef}...HEAD`]);
+    const raw = out ?? (await gitOutput(cwd, ["diff", "--name-only", `${baseRef}..HEAD`])) ?? "";
+    return new Set(raw
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean));
+}
+async function aheadCommitCount(cwd, baseRef) {
+    const out = await gitOutput(cwd, ["rev-list", "--count", `${baseRef}..HEAD`]);
+    const n = Number.parseInt(out?.trim() ?? "0", 10);
+    return Number.isFinite(n) ? n : 0;
+}
+async function statusFileSet(cwd) {
+    const raw = (await gitOutput(cwd, ["status", "--porcelain=v1"])) ?? "";
+    const files = new Set();
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        const path = line.slice(3).trim();
+        if (!path)
+            continue;
+        const renameTarget = path.includes(" -> ") ? path.split(" -> ").at(-1) : path;
+        if (renameTarget)
+            files.add(unquoteGitPath(renameTarget));
+    }
+    return files;
+}
+function unquoteGitPath(path) {
+    if (!path.startsWith('"') || !path.endsWith('"'))
+        return path;
+    try {
+        return JSON.parse(path);
+    }
+    catch {
+        return path.slice(1, -1);
+    }
+}

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

@@ -0,0 +1,7 @@
+export declare const GIT_BIN: string;
+export declare function execGit(cwd: string, args: string[], timeout?: number): Promise<string>;
+export declare function execGitSync(cwd: string, args: string[], timeout?: number): string;
+export declare function gitOutput(cwd: string, args: string[], timeout?: number): Promise<string | undefined>;
+export declare function gitOutputSync(cwd: string, args: string[], timeout?: number): string | undefined;
+export declare function gitErrorMessage(err: unknown): string;
+export declare function normalizeBranchName(branch: string): string;

package/dist/git/worktree/git-exec.js

@@ -0,0 +1,51 @@
+import { execFile, execFileSync } from "node:child_process";
+import { promisify } from "node:util";
+import { resolveExecutable } from "../../utils/exec.js";
+// git resolved via PATH×PATHEXT on Windows (.cmd/.exe shim); no-op on POSIX.
+export const GIT_BIN = resolveExecutable("git");
+const execFileAsync = promisify(execFile);
+export async function execGit(cwd, args, timeout = 10000) {
+    const { stdout } = await execFileAsync(GIT_BIN, args, {
+        cwd,
+        encoding: "utf-8",
+        timeout,
+    });
+    return stdout;
+}
+export function execGitSync(cwd, args, timeout = 10000) {
+    return execFileSync(GIT_BIN, args, {
+        cwd,
+        encoding: "utf-8",
+        timeout,
+    });
+}
+export async function gitOutput(cwd, args, timeout = 10000) {
+    try {
+        return await execGit(cwd, args, timeout);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function gitOutputSync(cwd, args, timeout = 10000) {
+    try {
+        return execGitSync(cwd, args, timeout);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function gitErrorMessage(err) {
+    const stderr = err.stderr;
+    if (Buffer.isBuffer(stderr)) {
+        const msg = stderr.toString("utf-8").trim();
+        if (msg)
+            return msg;
+    }
+    if (typeof stderr === "string" && stderr.trim())
+        return stderr.trim();
+    return err instanceof Error ? err.message : String(err);
+}
+export function normalizeBranchName(branch) {
+    return branch.replace(/^refs\/heads\//, "");
+}

package/dist/git/worktree/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./git-exec.js";
+export * from "./slug.js";
+export * from "./diff.js";
+export * from "./query.js";
+export * from "./crud.js";

package/dist/git/worktree/index.js

@@ -0,0 +1,5 @@
+export * from "./git-exec.js";
+export * from "./slug.js";
+export * from "./diff.js";
+export * from "./query.js";
+export * from "./crud.js";

package/dist/git/worktree/query.d.ts

@@ -0,0 +1,42 @@
+import type { SessionWorkspace } from "../../types.js";
+import { type WorktreeDiffSummary } from "./diff.js";
+export interface WorktreeWorkspaceOwner {
+    sessionId: string;
+    workspace?: SessionWorkspace;
+}
+export interface ListWorktreesFastOptions {
+    currentSessionId?: string;
+    workspaceOwners?: WorktreeWorkspaceOwner[];
+    owners?: WorktreeWorkspaceOwner[];
+    prefix?: string;
+}
+export interface ListWorktreesOptions extends ListWorktreesFastOptions {
+    includeDiffSummary?: boolean;
+}
+export interface WorktreeInfo {
+    path: string;
+    branch: string;
+    head: string;
+    isMain?: boolean;
+    isManaged?: boolean;
+    diff?: WorktreeDiffSummary;
+    occupiedBySessionIds?: string[];
+    occupiedByOtherSession?: boolean;
+}
+/**
+ * Find the canonical git root (resolves worktree -> main repo).
+ */
+export declare function findGitRoot(cwd: string): Promise<string>;
+export declare function findMainWorktreeRoot(cwd: string): Promise<string>;
+export declare function findWorktreeForBranch(cwd: string, branch: string): Promise<string | undefined>;
+export declare function assertBranchNotCheckedOut(cwd: string, branch: string): Promise<void>;
+export declare function branchExists(cwd: string, branch: string): Promise<boolean>;
+export declare function isGitWorktreeRoot(cwd: string): Promise<boolean>;
+export declare function currentBranch(cwd: string): Promise<string | undefined>;
+export declare function listWorktreesFast(cwd: string, opts?: ListWorktreesFastOptions): Promise<WorktreeInfo[]>;
+/**
+ * List active worktrees. Kept for internal/test compatibility; use
+ * listWorktreesFast for UI lists that should not block on diff work.
+ */
+export declare function listWorktrees(cwd: string, opts?: ListWorktreesOptions): Promise<WorktreeInfo[]>;
+export declare function ownersForWorktree(path: string, owners: WorktreeWorkspaceOwner[]): string[];

package/dist/git/worktree/query.js

@@ -0,0 +1,121 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { getWorktreeDiff } from "./diff.js";
+import { execGit, gitOutput, normalizeBranchName } from "./git-exec.js";
+import { isManagedWorktreeBranch } from "./slug.js";
+/**
+ * Find the canonical git root (resolves worktree -> main repo).
+ */
+export async function findGitRoot(cwd) {
+    return await findMainWorktreeRoot(cwd);
+}
+export async function findMainWorktreeRoot(cwd) {
+    const commonDir = (await execGit(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"], 5000)).trim();
+    return dirname(commonDir);
+}
+export async function findWorktreeForBranch(cwd, branch) {
+    const normalized = normalizeBranchName(branch);
+    return (await listWorktreesFast(cwd)).find((entry) => entry.branch === normalized)?.path;
+}
+export async function assertBranchNotCheckedOut(cwd, branch) {
+    const existingPath = await findWorktreeForBranch(cwd, branch);
+    if (existingPath) {
+        throw new Error(`branch ${normalizeBranchName(branch)} already checked out at ${existingPath}`);
+    }
+}
+export async function branchExists(cwd, branch) {
+    const out = await gitOutput(cwd, ["branch", "--list", normalizeBranchName(branch)], 10000);
+    return (out?.trim().length ?? 0) > 0;
+}
+export async function isGitWorktreeRoot(cwd) {
+    if (!existsSync(join(cwd, ".git")))
+        return false;
+    try {
+        const inside = (await execGit(cwd, ["rev-parse", "--is-inside-work-tree"], 5000)).trim();
+        if (inside !== "true")
+            return false;
+        const topLevel = (await execGit(cwd, ["rev-parse", "--path-format=absolute", "--show-toplevel"], 5000)).trim();
+        return resolve(topLevel) === resolve(cwd);
+    }
+    catch {
+        return false;
+    }
+}
+export async function currentBranch(cwd) {
+    const branch = (await gitOutput(cwd, ["branch", "--show-current"], 5000))?.trim();
+    return branch || undefined;
+}
+export async function listWorktreesFast(cwd, opts = {}) {
+    let raw;
+    try {
+        raw = (await execGit(cwd, ["worktree", "list", "--porcelain"], 10000)).trim();
+    }
+    catch {
+        return [];
+    }
+    if (!raw)
+        return [];
+    const entries = [];
+    let current = { path: "", branch: "", head: "" };
+    for (const line of raw.split("\n")) {
+        if (line.startsWith("worktree ")) {
+            if (current.path)
+                entries.push(current);
+            current = { path: line.slice(9), branch: "", head: "" };
+        }
+        else if (line.startsWith("HEAD ")) {
+            current.head = line.slice(5, 13);
+        }
+        else if (line.startsWith("branch ")) {
+            current.branch = normalizeBranchName(line.slice(7));
+        }
+    }
+    if (current.path)
+        entries.push(current);
+    let mainRoot = "";
+    try {
+        mainRoot = await findMainWorktreeRoot(cwd);
+    }
+    catch {
+        mainRoot = entries[0]?.path ?? "";
+    }
+    const owners = opts.workspaceOwners ?? opts.owners ?? [];
+    return entries.map((entry) => {
+        const ownerIds = ownersForWorktree(entry.path, owners);
+        return {
+            ...entry,
+            ...(mainRoot ? { isMain: resolve(entry.path) === resolve(mainRoot) } : {}),
+            isManaged: Boolean(entry.branch) && isManagedWorktreeBranch(entry.branch, opts.prefix),
+            ...(ownerIds.length > 0
+                ? {
+                    occupiedBySessionIds: ownerIds,
+                    occupiedByOtherSession: ownerIds.some((id) => id !== opts.currentSessionId),
+                }
+                : {}),
+        };
+    });
+}
+/**
+ * List active worktrees. Kept for internal/test compatibility; use
+ * listWorktreesFast for UI lists that should not block on diff work.
+ */
+export async function listWorktrees(cwd, opts = {}) {
+    const entries = await listWorktreesFast(cwd, opts);
+    if (!opts.includeDiffSummary)
+        return entries;
+    return Promise.all(entries.map(async (entry) => ({
+        ...entry,
+        diff: await getWorktreeDiff(entry.path),
+    })));
+}
+export function ownersForWorktree(path, owners) {
+    const target = resolve(path);
+    return owners
+        .filter((owner) => {
+        const workspace = owner.workspace;
+        if (!workspace)
+            return false;
+        return resolve(workspace.root) === target;
+    })
+        .map((owner) => owner.sessionId);
+}

package/dist/git/worktree/slug.d.ts

@@ -0,0 +1,11 @@
+export declare const DEFAULT_WORKTREE_BRANCH_PREFIX = "worktree/";
+export declare const HISTORICAL_WORKTREE_BRANCH_PREFIX = "worktree/";
+/**
+ * Validate worktree slug to prevent path traversal attacks.
+ */
+export declare function validateWorktreeSlug(slug: string): void;
+export declare function normalizeWorktreeBranchPrefix(prefix?: string | undefined): string;
+export declare function isValidWorktreeBranchPrefix(prefix: string): boolean;
+export declare function applyPrefix(prefix: string | undefined, slug: string, sessionId: string): string;
+export declare function managedBranchPrefixes(prefix?: string): string[];
+export declare function isManagedWorktreeBranch(branch: string, prefix?: string): boolean;

package/dist/git/worktree/slug.js

@@ -0,0 +1,58 @@
+export const DEFAULT_WORKTREE_BRANCH_PREFIX = "worktree/";
+export const HISTORICAL_WORKTREE_BRANCH_PREFIX = "worktree/";
+/**
+ * Validate worktree slug to prevent path traversal attacks.
+ */
+export function validateWorktreeSlug(slug) {
+    if (slug.trim().length === 0)
+        throw new Error("Worktree slug cannot be empty");
+    if (slug.length > 64)
+        throw new Error("Worktree slug too long (max 64 chars)");
+    if (/[^a-zA-Z0-9._-]/.test(slug))
+        throw new Error("Worktree slug contains invalid characters");
+    if (slug.startsWith(".") || slug.includes(".."))
+        throw new Error("Worktree slug cannot start with '.' or contain '..'");
+}
+export function normalizeWorktreeBranchPrefix(prefix = DEFAULT_WORKTREE_BRANCH_PREFIX) {
+    const raw = (prefix ?? DEFAULT_WORKTREE_BRANCH_PREFIX).trim();
+    if (!isValidWorktreeBranchPrefix(raw)) {
+        throw new Error(`Invalid worktree branch prefix: ${prefix ?? ""}`);
+    }
+    return raw.endsWith("/") ? raw : `${raw}/`;
+}
+export function isValidWorktreeBranchPrefix(prefix) {
+    const raw = prefix.trim();
+    if (!raw)
+        return false;
+    if (raw.startsWith("/") || raw.includes("//"))
+        return false;
+    if (raw.includes("..") || raw.includes("@{"))
+        return false;
+    if (/[\x00-\x20~^:?*[\]\\]/.test(raw))
+        return false;
+    const withoutTrailingSlash = raw.endsWith("/") ? raw.slice(0, -1) : raw;
+    if (!withoutTrailingSlash)
+        return false;
+    return withoutTrailingSlash.split("/").every((part) => {
+        if (!part)
+            return false;
+        if (part.startsWith(".") || part.endsWith("."))
+            return false;
+        if (part.endsWith(".lock"))
+            return false;
+        return true;
+    });
+}
+export function applyPrefix(prefix, slug, sessionId) {
+    validateWorktreeSlug(slug);
+    return `${normalizeWorktreeBranchPrefix(prefix)}${slug}-${sessionId.slice(0, 8)}`;
+}
+export function managedBranchPrefixes(prefix) {
+    const configured = normalizeWorktreeBranchPrefix(prefix);
+    return configured === HISTORICAL_WORKTREE_BRANCH_PREFIX
+        ? [configured]
+        : [configured, HISTORICAL_WORKTREE_BRANCH_PREFIX];
+}
+export function isManagedWorktreeBranch(branch, prefix) {
+    return managedBranchPrefixes(prefix).some((candidate) => branch.startsWith(candidate));
+}