@paleo/workspace 0.11.0

package/dist/workspace.js

@@ -0,0 +1,550 @@
+import { spawn, spawnSync } from "node:child_process";
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, symlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { parseWorkspaceArgs, printWorkspaceHelp } from "./cli.js";
+import { findOwnEntry, removeDevServerEntryByWorktree } from "./dev-servers-registry.js";
+import { ConfigError } from "./errors.js";
+import { copyAndPatchFile, formatDuration } from "./helpers.js";
+import { isProcessAlive } from "./process-control.js";
+import { defaultComputePorts, isValidPort, resolvePortScheme } from "./ports.js";
+import { handleSetOwner, markSlotFailed, markSlotReady, readSlots, resolveAndRegisterSlot, resolveCurrentSlot, validateSlotAvailability, writeSlots, } from "./slots.js";
+import { createBranch, detectWorktree, enforceWorktreeMode, getWorktreeBranch, removeWorktree, useExistingBranch, verifyBranchAbsentFromRemote, } from "./worktree.js";
+export async function runWorkspace(config) {
+    let command;
+    let verbose;
+    try {
+        ({ command, verbose } = parseWorkspaceArgs());
+    }
+    catch (err) {
+        if (err instanceof ConfigError) {
+            console.error(err.message);
+            process.exit(err.exitCode);
+        }
+        throw err;
+    }
+    if (command.kind === "help") {
+        printWorkspaceHelp();
+        return;
+    }
+    if (!existsSync(config.scriptPath)) {
+        console.error(`Error: scriptPath does not exist: ${config.scriptPath}. ` +
+            "Pass `fileURLToPath(import.meta.url)` from your wrapper script.");
+        process.exit(1);
+    }
+    switch (command.kind) {
+        case "finalize":
+            await runFinalize(command, config);
+            return;
+        case "wait":
+            await runWait(command, config);
+            return;
+        case "info":
+            runInfo(command, config);
+            return;
+        case "list":
+            runList(config);
+            return;
+    }
+    const ctx = detectWorktree();
+    enforceWorktreeMode(command, ctx);
+    const run = { verbose };
+    switch (command.kind) {
+        case "remove":
+            await handleRemove(command, ctx, run, config);
+            return;
+        case "set-owner":
+            handleSetOwnerMode(command, ctx, config);
+            return;
+        case "setup": {
+            const { slot } = await runSetup(command, ctx, run, config);
+            if (command.wait)
+                await waitForSlot(slot, config, { printSummary: false });
+            return;
+        }
+    }
+}
+async function runSetup(command, ctx, run, config) {
+    const scheme = resolvePortScheme(config);
+    const portsFn = resolvePortsFn(config);
+    validateSlotAvailability(command.slot, {
+        currentWorktree: ctx.currentWorktree,
+        mainWorktree: ctx.mainWorktree,
+        registryDir: config.registryDir,
+        scheme,
+    });
+    const setupCtx = ensureWorktree(command, ctx, run, config.worktreeDirName);
+    refuseIfFinalizePending(setupCtx, config.registryDir, command.force);
+    const branch = getWorktreeBranch(setupCtx.currentWorktree) ?? "(detached)";
+    const { port: slot, owner, status, } = resolveAndRegisterSlot({
+        slot: command.slot,
+        currentWorktree: setupCtx.currentWorktree,
+        mainWorktree: setupCtx.mainWorktree,
+        registryDir: config.registryDir,
+        scheme,
+        requestedOwner: command.owner,
+        isMainWorktree: setupCtx.isMainWorktree,
+        force: command.force,
+    });
+    const ports = portsFn(slot);
+    const runtimeDir = join(setupCtx.currentWorktree, config.runtimeDir);
+    mkdirSync(runtimeDir, { recursive: true });
+    const logPath = join(runtimeDir, "wt-setup.log");
+    // Truncate any prior log so `workspace setup` retries start with a clean record (the previous run's
+    // FAILED: banner would otherwise linger and produce false positives for grep-based tooling).
+    writeFileSync(logPath, "");
+    // Opened "a" so the same fd can be inherited by the detached finalize child below.
+    const logFd = openSync(logPath, "a");
+    const teeLog = (message) => {
+        console.log(message);
+        appendFileSync(logFd, `${message}\n`);
+    };
+    const verboseLog = (msg) => {
+        if (run.verbose)
+            teeLog(msg);
+        else
+            appendFileSync(logFd, `${msg}\n`);
+    };
+    verboseLog(`Using slot ${slot} (${Object.entries(ports)
+        .map(([k, v]) => `${k}: ${v}`)
+        .join(", ")})`);
+    if (config.preSetup) {
+        await config.preSetup({
+            currentWorktree: setupCtx.currentWorktree,
+            mainWorktree: setupCtx.mainWorktree,
+            isMainWorktree: setupCtx.isMainWorktree,
+            force: command.force,
+            log: teeLog,
+        });
+    }
+    linkSharedDirectories(setupCtx, config.sharedDirs, verboseLog);
+    generateConfigFiles(setupCtx, config.configFiles, slot, ports, command.force, verboseLog);
+    teeLog(config.printSummary({
+        slot,
+        branch,
+        owner,
+        ports,
+        currentWorktree: setupCtx.currentWorktree,
+        mainWorktree: setupCtx.mainWorktree,
+        isMainWorktree: setupCtx.isMainWorktree,
+        status,
+    }));
+    teeLog(`WORKTREE_CREATED path=${setupCtx.currentWorktree} branch=${branch} slot=${slot}`);
+    if (status !== "ready") {
+        teeLog(`Setup continuing in background. Tail: ${logPath}`);
+        teeLog(`Block until ready: workspace wait --slot ${slot}`);
+    }
+    const finalizeArgs = [config.scriptPath, "__finalize", String(slot)];
+    if (command.force)
+        finalizeArgs.push("--force");
+    const child = spawn(process.execPath, finalizeArgs, {
+        detached: true,
+        stdio: ["ignore", logFd, logFd],
+        cwd: setupCtx.currentWorktree,
+    });
+    child.unref();
+    closeSync(logFd);
+    return { slot };
+}
+function refuseIfFinalizePending(ctx, registryDir, force) {
+    if (force)
+        return;
+    const registry = readSlots(ctx.mainWorktree, registryDir);
+    const resolvedCurrent = resolve(ctx.currentWorktree);
+    const found = Object.entries(registry.slots).find(([, e]) => resolve(e.worktree) === resolvedCurrent && e.status === "pending");
+    if (!found)
+        return;
+    const [slotPort] = found;
+    console.error(`Error: Setup is already in progress for slot ${slotPort}. ` +
+        `Run 'workspace wait --slot ${slotPort}' to wait for it to finish (or fail), ` +
+        "then retry. Use --force to bypass.");
+    process.exit(1);
+}
+async function runFinalize(command, config) {
+    const slot = Number(command.slot);
+    const ctx = detectWorktree();
+    const logPath = join(ctx.currentWorktree, config.runtimeDir, "wt-setup.log");
+    const appendLog = (message) => {
+        appendFileSync(logPath, `${message}\n`);
+    };
+    const registry = readSlots(ctx.mainWorktree, config.registryDir);
+    const entry = registry.slots[String(slot)];
+    if (!entry || resolve(entry.worktree) !== resolve(ctx.currentWorktree)) {
+        appendLog(`FAILED: No matching slot ${slot} for worktree ${ctx.currentWorktree}.`);
+        process.exit(1);
+    }
+    const branch = getWorktreeBranch(ctx.currentWorktree) ?? "(detached)";
+    if (entry.status === "ready" && !command.force) {
+        appendLog(`READY: branch ${branch} (slot ${slot}) already finalized; skipping.`);
+        return;
+    }
+    const portsFn = resolvePortsFn(config);
+    const ports = portsFn(slot);
+    appendLog(`--- finalizing slot ${slot} at ${new Date().toISOString()} ---`);
+    const setupContext = {
+        currentWorktree: ctx.currentWorktree,
+        mainWorktree: ctx.mainWorktree,
+        isMainWorktree: ctx.isMainWorktree,
+        slot,
+        branch,
+        owner: entry.owner,
+        ports,
+        force: command.force,
+        verbose: false,
+    };
+    try {
+        await config.finalizeWorktree(setupContext);
+        markSlotReady(ctx.mainWorktree, config.registryDir, slot);
+        appendLog("============================================================");
+        appendLog(`READY: branch ${branch} (slot ${slot})`);
+        appendLog("============================================================");
+    }
+    catch (err) {
+        const message = err.message;
+        const stack = err.stack ?? "";
+        markSlotFailed(ctx.mainWorktree, config.registryDir, slot, message);
+        appendLog(`FAILED: ${message}`);
+        if (stack)
+            appendLog(stack);
+        process.exit(1);
+    }
+}
+function resolveTargetSlot(slotArg, config) {
+    if (slotArg !== undefined) {
+        const slot = Number(slotArg);
+        const scheme = resolvePortScheme(config);
+        if (!isValidPort(slot, scheme)) {
+            console.error(`Error: --slot expects a port in [${scheme.minPort}, ${scheme.maxPort}] stepped by ${scheme.portStep}; got "${slotArg}".`);
+            process.exit(1);
+        }
+        return slot;
+    }
+    return resolveCurrentSlot(config.basePort, config.registryDir).slot;
+}
+function printWorktreeInfo(config, slot, worktreeForLog, fallback) {
+    const ctx = detectWorktree();
+    const registry = readSlots(ctx.mainWorktree, config.registryDir);
+    const entry = registry.slots[String(slot)];
+    const ports = resolvePortsFn(config)(slot);
+    const owner = entry?.owner ?? fallback.owner;
+    const status = entry?.status ?? "pending";
+    const setupLogPath = join(worktreeForLog, config.runtimeDir, "wt-setup.log");
+    const now = Date.now();
+    const isMainWorktree = entry?.main ?? false;
+    const targetWorktree = entry?.worktree ?? ctx.currentWorktree;
+    const branch = getWorktreeBranch(targetWorktree) ?? "(detached)";
+    console.log(config.printSummary({
+        slot,
+        branch,
+        owner,
+        ports,
+        currentWorktree: targetWorktree,
+        mainWorktree: ctx.mainWorktree,
+        isMainWorktree,
+        status,
+    }));
+    if (status === "failed") {
+        const at = entry?.failure?.at ?? entry?.createdAt;
+        const elapsed = at ? formatDuration(now - Date.parse(at)) : "?";
+        const reason = entry?.failure?.message ?? "(no message)";
+        console.log(`Failure: ${reason} (${elapsed} ago, tail ${setupLogPath})`);
+    }
+    else if (status === "pending" && entry) {
+        const elapsed = formatDuration(now - Date.parse(entry.createdAt));
+        console.log(`Pending since ${elapsed} ago (tail ${setupLogPath})`);
+    }
+    printDevServerBlock(config, ctx.mainWorktree, targetWorktree, now);
+}
+function printDevServerBlock(config, mainWorktree, targetWorktree, now) {
+    const entry = findOwnEntry(mainWorktree, config.registryDir, targetWorktree);
+    const liveEntries = entry
+        ? Object.entries(entry.pids)
+            .filter(([, pid]) => isProcessAlive(pid))
+            .sort(([a], [b]) => a.localeCompare(b))
+        : [];
+    if (liveEntries.length === 0 || !entry) {
+        console.log("Dev-server: not running");
+        return;
+    }
+    const elapsed = formatDuration(now - Date.parse(entry.startedAt));
+    console.log(`Dev-server: running, started ${elapsed} ago`);
+    for (const [name, pid] of liveEntries) {
+        console.log(`  ${name}: PID ${pid}`);
+        console.log(`    log: ${join(targetWorktree, config.runtimeDir, "logs", `${name}.log`)}`);
+    }
+}
+function runInfo(command, config) {
+    if (command.slot !== undefined) {
+        const slot = resolveTargetSlot(command.slot, config);
+        const ctx = detectWorktree();
+        const entry = readSlots(ctx.mainWorktree, config.registryDir).slots[String(slot)];
+        if (!entry) {
+            console.error(`Error: No slot ${slot} in registry.`);
+            process.exit(1);
+        }
+        printWorktreeInfo(config, slot, entry.worktree, { owner: entry.owner });
+        return;
+    }
+    const resolved = resolveCurrentSlot(config.basePort, config.registryDir);
+    printWorktreeInfo(config, resolved.slot, resolved.worktree, {
+        owner: resolved.owner,
+    });
+}
+function runList(config) {
+    const ctx = detectWorktree();
+    const entries = Object.entries(readSlots(ctx.mainWorktree, config.registryDir).slots).sort(([a], [b]) => Number(a) - Number(b));
+    if (entries.length === 0) {
+        console.log("No worktrees registered.");
+        return;
+    }
+    const rows = entries.map(([port, e]) => ({
+        slot: port,
+        type: e.main ? "main" : "linked",
+        status: e.status,
+        branch: getWorktreeBranch(e.worktree) ?? "(detached)",
+        worktree: e.worktree,
+        owner: e.owner ?? "-",
+        created: e.createdAt,
+    }));
+    const headers = {
+        slot: "SLOT",
+        type: "TYPE",
+        status: "STATUS",
+        branch: "BRANCH",
+        worktree: "WORKTREE",
+        owner: "OWNER",
+        created: "CREATED",
+    };
+    const widths = {
+        slot: Math.max(headers.slot.length, ...rows.map((r) => r.slot.length)),
+        type: Math.max(headers.type.length, ...rows.map((r) => r.type.length)),
+        status: Math.max(headers.status.length, ...rows.map((r) => r.status.length)),
+        branch: Math.max(headers.branch.length, ...rows.map((r) => r.branch.length)),
+        worktree: Math.max(headers.worktree.length, ...rows.map((r) => r.worktree.length)),
+        owner: Math.max(headers.owner.length, ...rows.map((r) => r.owner.length)),
+    };
+    const fmt = (r) => `${r.slot.padEnd(widths.slot)}  ${r.type.padEnd(widths.type)}  ${r.status.padEnd(widths.status)}  ${r.branch.padEnd(widths.branch)}  ${r.worktree.padEnd(widths.worktree)}  ${r.owner.padEnd(widths.owner)}  ${r.created}`;
+    console.log(fmt(headers));
+    for (const r of rows)
+        console.log(fmt(r));
+}
+async function runWait(command, config) {
+    // standalone `workspace wait` (no prior setup in this invocation) → print the full summary on success.
+    const slot = resolveTargetSlot(command.slot, config);
+    await waitForSlot(slot, config);
+}
+async function waitForSlot(slot, config, options = {}) {
+    const printSummary = options.printSummary ?? true;
+    const ctx = detectWorktree();
+    const initial = readSlots(ctx.mainWorktree, config.registryDir).slots[String(slot)];
+    if (!initial) {
+        console.error(`Error: No slot ${slot} in registry.`);
+        process.exit(1);
+    }
+    const pollMs = 500;
+    // Poll slots.json — the finalize child writes `status` on success or failure. Tiny file, no
+    // log-tailing race.
+    for (;;) {
+        const entry = readSlots(ctx.mainWorktree, config.registryDir).slots[String(slot)];
+        if (!entry) {
+            console.error(`Error: Slot ${slot} disappeared from registry.`);
+            process.exit(1);
+        }
+        if (entry.status === "ready") {
+            console.log("\n… ready");
+            if (printSummary) {
+                printWorktreeInfo(config, slot, entry.worktree, {
+                    owner: entry.owner,
+                });
+            }
+            return;
+        }
+        if (entry.status === "failed") {
+            const logPath = join(entry.worktree, config.runtimeDir, "wt-setup.log");
+            console.error(`FAILED: ${entry.failure?.message ?? "(no message)"}`);
+            console.error(`Full log: ${logPath}`);
+            process.exit(1);
+        }
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+}
+async function handleRemove(command, ctx, run, config) {
+    const verboseLog = makeVerboseLog(run.verbose);
+    const removeHere = command.branch === undefined;
+    const registry = readSlots(ctx.mainWorktree, config.registryDir);
+    const target = resolveRemoveTarget(command, ctx, registry);
+    // Refuse to remove while the detached finalize is still writing to slots.json / wt-setup.log:
+    // racing the two corrupts the registry and leaves the worktree directory orphaned.
+    if (registry.slots[target.slotPort]?.status === "pending") {
+        console.error(`Error: Setup is still in progress for slot ${target.slotPort}. ` +
+            `Run 'workspace wait --slot ${target.slotPort}' to wait for it to finish (or fail), then retry the removal.`);
+        process.exit(1);
+    }
+    if (!command.noRemoteCheck) {
+        verifyBranchAbsentFromRemote(target.branch, run);
+    }
+    const ownerSuffix = target.owner ? `, owner ${target.owner}` : "";
+    if (!existsSync(target.worktreePath)) {
+        console.warn(`Warning: Worktree directory ${target.worktreePath} not found. Cleaning up registry only.`);
+        delete registry.slots[target.slotPort];
+        writeSlots(ctx.mainWorktree, config.registryDir, registry);
+        console.log(`Removed registry entry for branch "${target.branch}" (slot ${target.slotPort}${ownerSuffix}).`);
+        return;
+    }
+    const targetEntry = findOwnEntry(ctx.mainWorktree, config.registryDir, target.worktreePath);
+    if (targetEntry) {
+        stopTargetDevServer(config.devServerScript, target.worktreePath, verboseLog);
+    }
+    else {
+        verboseLog(`No dev-server running in ${target.worktreePath}; skipping --stop.`);
+    }
+    if (config.purgeInfrastructure) {
+        await config.purgeInfrastructure({
+            worktree: target.worktreePath,
+            mainWorktree: ctx.mainWorktree,
+            verbose: run.verbose,
+        });
+    }
+    delete registry.slots[target.slotPort];
+    writeSlots(ctx.mainWorktree, config.registryDir, registry);
+    removeDevServerEntryByWorktree(ctx.mainWorktree, config.registryDir, target.worktreePath);
+    if (removeHere) {
+        process.chdir(ctx.mainWorktree);
+    }
+    removeWorktree(target.worktreePath, run);
+    console.log(`Removed worktree for branch "${target.branch}" (slot ${target.slotPort}${ownerSuffix}). ` +
+        `Branch "${target.branch}" kept.`);
+    if (removeHere) {
+        console.log(`Now run: cd ${ctx.mainWorktree}`);
+    }
+}
+function handleSetOwnerMode(command, ctx, config) {
+    const newOwner = command.name;
+    const { slotPort } = handleSetOwner({
+        newOwner,
+        currentWorktree: ctx.currentWorktree,
+        mainWorktree: ctx.mainWorktree,
+        registryDir: config.registryDir,
+        isMainWorktree: ctx.isMainWorktree,
+    });
+    // Propagate to dev-servers.json entries for this worktree.
+    const devServersPath = join(ctx.mainWorktree, config.registryDir, "dev-servers.json");
+    if (existsSync(devServersPath)) {
+        const data = JSON.parse(readFileSync(devServersPath, "utf-8"));
+        let changed = false;
+        const resolvedCurrent = resolve(ctx.currentWorktree);
+        for (const server of data.servers) {
+            if (resolve(server.worktree) === resolvedCurrent) {
+                if (newOwner !== undefined)
+                    server.owner = newOwner;
+                else
+                    delete server.owner;
+                changed = true;
+            }
+        }
+        if (changed) {
+            mkdirSync(dirname(devServersPath), { recursive: true });
+            writeFileSync(devServersPath, `${JSON.stringify(data, undefined, 2)}\n`);
+        }
+    }
+    console.log(`Owner for slot ${slotPort}: ${newOwner ?? "(none)"}`);
+}
+function ensureWorktree(command, ctx, run, dirNameFn) {
+    if (command.branch === undefined)
+        return ctx;
+    if (command.newBranch)
+        return createBranch(command.branch, ctx, run, dirNameFn);
+    return useExistingBranch(command.branch, ctx, run, dirNameFn);
+}
+function linkSharedDirectories(ctx, dirs, log) {
+    for (const dirName of dirs) {
+        const link = join(ctx.currentWorktree, dirName);
+        const mainDir = join(ctx.mainWorktree, dirName);
+        if (!existsSync(mainDir)) {
+            log(`Skipped ${dirName} symlink (not present in main worktree).`);
+        }
+        else if (existsSync(link)) {
+            log(`Skipped ${dirName} symlink (already exists).`);
+        }
+        else {
+            const relTarget = relative(ctx.currentWorktree, mainDir);
+            symlinkSync(relTarget, link);
+            log(`Created ${dirName} symlink → main worktree.`);
+        }
+    }
+}
+function generateConfigFiles(ctx, entries, slot, ports, force, log) {
+    for (const entry of entries) {
+        copyAndPatchFile({ currentWorktree: ctx.currentWorktree, mainWorktree: ctx.mainWorktree, log }, entry.path, (content) => entry.patch(content, {
+            slot,
+            ports,
+            mainWorktree: ctx.mainWorktree,
+            currentWorktree: ctx.currentWorktree,
+        }), entry.path, force, entry.optional ?? false);
+    }
+}
+function resolveRemoveTarget(command, ctx, registry) {
+    if (command.branch === undefined) {
+        if (ctx.isMainWorktree) {
+            console.error("Error: Cannot remove the main worktree.");
+            process.exit(1);
+        }
+        const resolvedCurrent = resolve(ctx.currentWorktree);
+        const entry = Object.entries(registry.slots).find(([, v]) => resolve(v.worktree) === resolvedCurrent);
+        if (!entry) {
+            console.error("Error: No slot found for this worktree in the registry.");
+            process.exit(1);
+        }
+        const branch = getWorktreeBranch(ctx.currentWorktree) ?? "(detached)";
+        return {
+            slotPort: entry[0],
+            branch,
+            worktreePath: ctx.currentWorktree,
+            owner: entry[1].owner,
+        };
+    }
+    const branch = command.branch;
+    const entry = Object.entries(registry.slots).find(([, v]) => getWorktreeBranch(v.worktree) === branch);
+    if (!entry) {
+        console.error(`Error: No worktree found for branch "${branch}" in the slot registry.`);
+        process.exit(1);
+    }
+    const worktreePath = entry[1].worktree;
+    if (resolve(ctx.currentWorktree) === resolve(worktreePath)) {
+        console.error("Error: You are currently in this worktree. Run `workspace remove` (no branch) instead.");
+        process.exit(1);
+    }
+    return { slotPort: entry[0], branch, worktreePath, owner: entry[1].owner };
+}
+/**
+ * Stops the dev-server running in the target worktree by shelling out to
+ * `node <devServerScript> --stop` with `cwd: worktreePath`. The subprocess runs the target's
+ * own stop flow — registry-based spawn-PID kill + callback `stop()` from the target's branch.
+ */
+function stopTargetDevServer(devServerScript, worktreePath, log) {
+    log(`Stopping dev-server in ${worktreePath}...`);
+    const result = spawnSync(process.execPath, [devServerScript, "--stop"], {
+        cwd: worktreePath,
+        stdio: "inherit",
+        timeout: 30_000,
+    });
+    if (result.error) {
+        console.warn(`Warning: failed to run dev-server --stop: ${result.error.message}`);
+    }
+    else if (result.status !== 0) {
+        console.warn(`Warning: dev-server --stop exited with code ${result.status}.`);
+    }
+}
+function resolvePortsFn(config) {
+    if (config.ports)
+        return config.ports;
+    if (config.portNames && config.portNames.length > 0) {
+        return defaultComputePorts(config.portNames);
+    }
+    throw new ConfigError("Config error: provide either `ports` (function) or `portNames` (array).");
+}
+function makeVerboseLog(verbose) {
+    return (msg) => {
+        if (verbose)
+            console.log(msg);
+    };
+}

package/dist/worktree.d.ts

@@ -0,0 +1,28 @@
+import type { WorkspaceCommand } from "./cli.js";
+export interface WorktreeContext {
+    currentWorktree: string;
+    mainWorktree: string;
+    isMainWorktree: boolean;
+}
+export interface RunCtx {
+    verbose: boolean;
+}
+export declare function detectWorktree(): WorktreeContext;
+export declare function enforceWorktreeMode(command: WorkspaceCommand, ctx: WorktreeContext): void;
+export declare function useExistingBranch(branch: string, ctx: WorktreeContext, run: RunCtx, dirNameFn?: WorktreeDirNameFn): WorktreeContext;
+export declare function createBranch(requestedBranch: string, ctx: WorktreeContext, run: RunCtx, dirNameFn?: WorktreeDirNameFn): WorktreeContext;
+export declare function verifyBranchAbsentFromRemote(branch: string, run: RunCtx): void;
+export declare function getWorktreeBranch(worktreePath: string): string | undefined;
+export declare function removeWorktree(worktreePath: string, run: RunCtx): void;
+/** Pure function that produces the basename of a worktree directory from a branch. */
+export type WorktreeDirNameFn = (opts: {
+    branch: string;
+    repoName: string;
+}) => string;
+/**
+ * Default {@link WorktreeDirNameFn}. Strips a recognizable ticket suffix from the last branch
+ * segment (`feat/ABC-123-extra` → `feat-ABC-123`), caps the result at 22 chars, and strips
+ * trailing dashes. Falls back to the full sanitized branch when no ticket pattern is found.
+ */
+export declare const defaultWorktreeDirName: WorktreeDirNameFn;
+export declare function computeWorktreePath(mainWorktree: string, branch: string, dirNameFn?: WorktreeDirNameFn): string;