@paleo/workspace 0.11.0

package/dist/dev-server.js

@@ -0,0 +1,349 @@
+import { spawn } from "node:child_process";
+import { closeSync, mkdirSync, openSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseDevServerArgs, printDevServerHelp, validateDevServerFlags, } from "./cli.js";
+import { evictOldest, findOwnEntry, listDevServers, printActiveServers, pruneAndPersist, registerDevServer, removeDevServerEntryByWorktree, stopAllRegistered, unregisterDevServer, } from "./dev-servers-registry.js";
+import { ConfigError, StartupError } from "./errors.js";
+import { detectCommonJsError, formatDuration } from "./helpers.js";
+import { awaitAllReady, handleStartupFailure } from "./log-polling.js";
+import { canonicalCwd, detectPortConflicts, sweepStalePorts, waitForPortsFree, } from "./port-holder.js";
+import { isProcessAlive, stopProcessGroup } from "./process-control.js";
+import { readSlots, resolveCurrentSlot } from "./slots.js";
+import { detectWorktree, getWorktreeBranch } from "./worktree.js";
+function logFileFor(runtimeDir, name) {
+    return join(runtimeDir, "logs", `${name}.log`);
+}
+export async function runDevServer(config) {
+    let args;
+    try {
+        args = parseDevServerArgs();
+    }
+    catch (err) {
+        console.error(err.message);
+        process.exit(1);
+    }
+    if (args.help) {
+        printDevServerHelp();
+        return;
+    }
+    try {
+        validateDevServerFlags(args);
+    }
+    catch (err) {
+        if (err instanceof ConfigError) {
+            console.error(err.message);
+            process.exit(err.exitCode);
+        }
+        throw err;
+    }
+    const { mainWorktree } = detectWorktree();
+    if (args.list) {
+        listDevServers(mainWorktree, config.registryDir);
+        return;
+    }
+    if (args.stop && args.all) {
+        await stopAllRegistered({
+            mainWorktree,
+            registryDir: config.registryDir,
+            callbackServers: callbackServersOf(config),
+        });
+        return;
+    }
+    if (args.stop) {
+        await stopLocal(config, mainWorktree);
+        return;
+    }
+    await start(config, mainWorktree, {
+        evict: Boolean(args.evict),
+        restart: Boolean(args.restart),
+    });
+}
+function callbackServersOf(config) {
+    return config.servers.filter((s) => s.kind === "callback");
+}
+async function start(config, mainWorktree, { evict, restart }) {
+    const ctx = { cwd: process.cwd() };
+    checkWorktreeReady(config, mainWorktree, ctx.cwd);
+    if (await handleAlreadyRunning(config, mainWorktree, ctx, restart))
+        return;
+    await enforceCap(config, mainWorktree, evict);
+    checkNoLocalRegistryConflict(config, mainWorktree, ctx.cwd);
+    await checkPortsFree(config.servers, ctx.cwd);
+    const spawnPids = {};
+    const startedCallbacks = [];
+    try {
+        for (const server of config.servers) {
+            console.log(`Starting ${server.name} dev server...`);
+            if (server.kind === "spawn") {
+                spawnPids[server.name] = spawnServer(server, config.runtimeDir, ctx.cwd);
+            }
+            else {
+                await server.start(ctx);
+                startedCallbacks.push(server);
+            }
+        }
+        const spawnEntries = config.servers.filter((s) => s.kind === "spawn");
+        const pollables = spawnEntries.map((s) => ({
+            name: s.name,
+            logFile: logFileFor(config.runtimeDir, s.name),
+            detectSuccess: s.detectSuccess,
+            detectError: s.detectError ?? detectCommonJsError,
+        }));
+        const pollPids = spawnEntries.map((s) => spawnPids[s.name]);
+        await awaitAllReady(pollables, pollPids);
+    }
+    catch (err) {
+        await rollbackStart(spawnPids, startedCallbacks, ctx);
+        if (err instanceof StartupError) {
+            handleStartupFailure(err);
+            process.exit(1);
+        }
+        throw err;
+    }
+    const slot = resolveCurrentSlot(config.basePort, config.registryDir);
+    const devEntry = {
+        slot: slot.slot,
+        worktree: slot.worktree,
+        owner: slot.owner,
+        pids: spawnPids,
+        startedAt: new Date().toISOString(),
+    };
+    if (slot.main)
+        devEntry.main = true;
+    registerDevServer(mainWorktree, config.registryDir, devEntry);
+    const summaryServers = config.servers.map((server) => {
+        if (server.kind === "spawn") {
+            return { server, port: server.port, pid: spawnPids[server.name] };
+        }
+        return { server };
+    });
+    if (config.printSummary) {
+        console.log(config.printSummary({ slot, servers: summaryServers }));
+    }
+    else {
+        defaultPrintSummary(slot, summaryServers, config.runtimeDir);
+    }
+}
+async function rollbackStart(spawnPids, startedCallbacks, ctx) {
+    console.error("\nStopping dev servers...");
+    for (const pid of Object.values(spawnPids)) {
+        try {
+            await stopProcessGroup(pid);
+        }
+        catch (err) {
+            console.error(`  Failed to stop PID ${pid}: ${err.message}`);
+        }
+    }
+    for (const server of [...startedCallbacks].reverse()) {
+        console.log(`Stopping ${server.name}...`);
+        try {
+            await server.stop(ctx);
+        }
+        catch (err) {
+            console.error(`  Failed to stop ${server.name}: ${err.message}`);
+        }
+    }
+}
+/**
+ * Pure builder for the `dev:up` worktree-readiness gate. Returns `ok` when the slot is `ready`
+ * or absent (synthesized main); otherwise returns the user-facing error message.
+ */
+export function buildWorktreeReadyMessage(input) {
+    const { slotPort, worktreePath, runtimeDir, entry, now } = input;
+    if (!entry || entry.status === "ready")
+        return { ok: true };
+    const logPath = join(worktreePath, runtimeDir, "wt-setup.log");
+    if (entry.status === "pending") {
+        const elapsed = formatDuration(now - Date.parse(entry.createdAt));
+        return {
+            ok: false,
+            message: `Error: Worktree setup is still in progress (slot ${slotPort}, started ${elapsed} ago).\n` +
+                `Tail: ${logPath}\n` +
+                "Run `workspace wait` to block until it finishes, or retry `dev:up` once ready.",
+        };
+    }
+    const failureAt = entry.failure?.at ?? entry.createdAt;
+    const elapsed = formatDuration(now - Date.parse(failureAt));
+    const reason = entry.failure?.message ?? "(no message)";
+    return {
+        ok: false,
+        message: `Error: Worktree setup failed (slot ${slotPort}, ${elapsed} ago): ${reason}\n` +
+            `Tail: ${logPath}\n` +
+            "Re-run `workspace setup` to retry the finalize.",
+    };
+}
+function checkWorktreeReady(config, mainWorktree, cwd) {
+    const slot = resolveCurrentSlot(config.basePort, config.registryDir);
+    const entry = readSlots(mainWorktree, config.registryDir).slots[String(slot.slot)];
+    const result = buildWorktreeReadyMessage({
+        slotPort: slot.slot,
+        worktreePath: cwd,
+        runtimeDir: config.runtimeDir,
+        entry,
+        now: Date.now(),
+    });
+    if (result.ok)
+        return;
+    console.error(result.message);
+    process.exit(1);
+}
+/**
+ * If a dev-server is already running in this worktree, either stop it (when `restart`) so the
+ * normal start path can proceed, or print a friendly notice and return `true` to short-circuit.
+ * Returns `true` when the caller should exit cleanly without starting.
+ */
+async function handleAlreadyRunning(config, mainWorktree, ctx, restart) {
+    const entry = findOwnEntry(mainWorktree, config.registryDir, ctx.cwd);
+    if (!entry)
+        return false;
+    const livePids = Object.entries(entry.pids).filter(([, pid]) => isProcessAlive(pid));
+    if (livePids.length === 0)
+        return false;
+    if (restart) {
+        console.log("Restarting dev-server in this worktree...");
+        await stopLocal(config, mainWorktree);
+        return false;
+    }
+    const pidList = livePids.map(([name, pid]) => `${name}=${pid}`).join(", ");
+    console.log(`dev-server already running for this worktree (slot ${entry.slot}, pids: ${pidList}).`);
+    console.log("Run `dev:down` to stop it, or re-run with --restart to restart.");
+    return true;
+}
+// TOCTOU: the cap check and the subsequent register are not atomic. Two concurrent `dev:up --evict`
+// from different worktrees can both pass the cap check and both register, exceeding the limit by
+// one. Accepted: the race window is narrow and the consequence is bounded (one extra dev-server).
+async function enforceCap(config, mainWorktree, evict) {
+    const limit = config.devLimit;
+    if (limit === undefined)
+        return;
+    const active = pruneAndPersist(mainWorktree, config.registryDir).servers;
+    if (active.length < limit)
+        return;
+    if (!evict) {
+        console.error(`Error: dev-server cap reached (${active.length}/${limit}). Active dev-servers:`);
+        printActiveServers(active);
+        console.error("Run `dev:down` in another worktree, or `dev:down --all`.");
+        console.error("Re-run with --evict to evict the oldest.");
+        process.exit(1);
+    }
+    const toEvict = active.length - limit + 1;
+    console.log(`Evicting ${toEvict} dev-server(s) to make room (cap ${limit}).`);
+    const evicted = await evictOldest({
+        mainWorktree,
+        registryDir: config.registryDir,
+        callbackServers: callbackServersOf(config),
+        count: toEvict,
+    });
+    for (const entry of evicted) {
+        const ownerPart = entry.owner ? `, owner=${entry.owner}` : "";
+        const branch = getWorktreeBranch(entry.worktree) ?? "(detached)";
+        console.log(`Evicted slot ${entry.slot} (branch=${branch}${ownerPart}, startedAt=${entry.startedAt}).`);
+    }
+}
+async function checkPortsFree(servers, cwd) {
+    const conflicts = await detectPortConflicts(servers, canonicalCwd(cwd));
+    const foreign = conflicts.filter((c) => c.kind === "foreign");
+    if (foreign.length > 0) {
+        for (const c of foreign) {
+            const info = c.holder
+                ? ` (PID ${c.holder.pid}: ${c.holder.cmd}${c.holder.cwd ? `, cwd ${c.holder.cwd}` : ""})`
+                : "";
+            console.error(`Error: Port ${c.server.port} (${c.server.name}) is already in use${info}.`);
+        }
+        process.exit(1);
+    }
+    const ours = conflicts.filter((c) => c.kind === "ours");
+    if (ours.length === 0)
+        return;
+    for (const c of ours) {
+        console.warn(`Stale ${c.server.name} dev-server detected on port ${c.server.port} (PID ${c.holder.pid}: ${c.holder.cmd}). Cleaning up...`);
+        if (c.holder.pgid === undefined) {
+            console.error(`  Cannot kill: pgid unknown for PID ${c.holder.pid}.`);
+            process.exit(1);
+        }
+        await stopProcessGroup(c.holder.pgid);
+    }
+    const stillBusy = await waitForPortsFree(ours.map((c) => c.server.port), 2000);
+    if (stillBusy.length > 0) {
+        for (const port of stillBusy) {
+            const server = ours.find((c) => c.server.port === port)?.server;
+            console.error(`Error: Port ${port}${server ? ` (${server.name})` : ""} still in use after cleanup attempt.`);
+        }
+        process.exit(1);
+    }
+}
+function checkNoLocalRegistryConflict(config, mainWorktree, cwd) {
+    const entry = findOwnEntry(mainWorktree, config.registryDir, cwd);
+    if (!entry)
+        return;
+    for (const [name, pid] of Object.entries(entry.pids)) {
+        if (isProcessAlive(pid)) {
+            console.error(`Error: ${name} is already running (PID ${pid}).`);
+            process.exit(1);
+        }
+    }
+    // Stale entry — drop it so registration overwrites cleanly.
+    removeDevServerEntryByWorktree(mainWorktree, config.registryDir, cwd);
+}
+async function stopLocal(config, mainWorktree) {
+    const ctx = { cwd: process.cwd() };
+    const entry = findOwnEntry(mainWorktree, config.registryDir, ctx.cwd);
+    if (!entry) {
+        console.log("No dev-server running in this worktree.");
+        await sweepStalePorts(config.servers, ctx.cwd);
+        return;
+    }
+    for (const [name, pid] of Object.entries(entry.pids)) {
+        if (!isProcessAlive(pid))
+            continue;
+        console.log(`Stopping ${name} (PID ${pid})...`);
+        await stopProcessGroup(pid);
+    }
+    const callbacks = callbackServersOf(config);
+    for (const server of [...callbacks].reverse()) {
+        console.log(`Stopping ${server.name}...`);
+        try {
+            await server.stop(ctx);
+        }
+        catch (err) {
+            console.error(`  Failed to stop ${server.name}: ${err.message}`);
+        }
+    }
+    unregisterDevServer(mainWorktree, config.registryDir, ctx.cwd);
+    await sweepStalePorts(config.servers, ctx.cwd);
+}
+function defaultPrintSummary(slot, servers, runtimeDir) {
+    console.log("\nDev servers started!");
+    const ownerSuffix = slot.owner ? `, owner ${slot.owner}` : "";
+    console.log(`  Worktree: slot ${slot.slot}${ownerSuffix}`);
+    for (const { server, port, pid } of servers) {
+        if (server.kind === "spawn") {
+            const url = `http://localhost:${port}/`;
+            const logPath = join(process.cwd(), logFileFor(runtimeDir, server.name));
+            console.log(`  ${server.name}: ${url}  (PID ${pid})`);
+            console.log(`    log: ${logPath}`);
+        }
+        else {
+            console.log(`  ${server.name}: ready`);
+        }
+    }
+    console.log("");
+}
+function spawnServer(server, runtimeDir, cwd) {
+    const logFile = logFileFor(runtimeDir, server.name);
+    mkdirSync(dirname(logFile), { recursive: true });
+    const logFd = openSync(logFile, "w");
+    const child = spawn(server.exec.command, server.exec.args, {
+        detached: true,
+        stdio: ["ignore", logFd, logFd],
+        cwd,
+    });
+    if (child.pid === undefined) {
+        closeSync(logFd);
+        console.error(`Error: failed to spawn ${server.name}.`);
+        process.exit(1);
+    }
+    child.unref();
+    closeSync(logFd);
+    return child.pid;
+}

package/dist/dev-servers-registry.d.ts

@@ -0,0 +1,42 @@
+import type { CallbackServer } from "./server-descriptor.js";
+export interface DevServerEntry {
+    slot: number;
+    worktree: string;
+    owner?: string;
+    pids: Record<string, number>;
+    startedAt: string;
+    /** `true` for the main-worktree entry. */
+    main?: boolean;
+}
+export interface DevServersData {
+    servers: DevServerEntry[];
+}
+export type IsAliveFn = (pid: number) => boolean;
+export declare function listDevServers(mainWorktree: string, registryDir: string): void;
+export declare function printActiveServers(active: DevServerEntry[]): void;
+export interface StopAllInput {
+    mainWorktree: string;
+    registryDir: string;
+    /** Callback-managed servers from the current process's config. Their `stop()` is invoked for each
+     *  victim with `ctx.cwd = entry.worktree`. */
+    callbackServers: CallbackServer[];
+}
+export declare function stopAllRegistered(input: StopAllInput): Promise<void>;
+export interface EvictInput {
+    mainWorktree: string;
+    registryDir: string;
+    count: number;
+    callbackServers: CallbackServer[];
+    isAlive?: IsAliveFn;
+    stop?: (pid: number) => Promise<void>;
+}
+export declare function evictOldest(input: EvictInput): Promise<DevServerEntry[]>;
+export declare function registerDevServer(mainWorktree: string, registryDir: string, entry: DevServerEntry): void;
+export declare function unregisterDevServer(mainWorktree: string, registryDir: string, worktreePath: string): void;
+export declare function removeDevServerEntryByWorktree(mainWorktree: string, registryDir: string, worktreePath: string): void;
+/** Returns the entry whose worktree matches `worktreePath`, or `undefined`. Does not prune. */
+export declare function findOwnEntry(mainWorktree: string, registryDir: string, worktreePath: string): DevServerEntry | undefined;
+export declare function pruneAndPersist(mainWorktree: string, registryDir: string, isAlive?: IsAliveFn): DevServersData;
+export declare function pruneDeadServers(data: DevServersData, isAlive?: IsAliveFn): DevServersData;
+export declare function readDevServers(mainWorktree: string, registryDir: string): DevServersData;
+export declare function writeDevServers(mainWorktree: string, registryDir: string, data: DevServersData): void;

package/dist/dev-servers-registry.js

@@ -0,0 +1,140 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { isProcessAlive, stopProcessGroup } from "./process-control.js";
+import { getWorktreeBranch } from "./worktree.js";
+const DEV_SERVERS_FILENAME = "dev-servers.json";
+export function listDevServers(mainWorktree, registryDir) {
+    const data = pruneAndPersist(mainWorktree, registryDir);
+    if (data.servers.length === 0) {
+        console.log("No dev-servers running.");
+        return;
+    }
+    const sorted = [...data.servers].sort((a, b) => a.slot - b.slot);
+    for (const entry of sorted) {
+        console.log(formatEntry(entry));
+    }
+}
+export function printActiveServers(active) {
+    const sorted = [...active].sort((a, b) => a.slot - b.slot);
+    for (const entry of sorted) {
+        process.stderr.write(`${formatEntry(entry)}\n`);
+    }
+}
+export async function stopAllRegistered(input) {
+    const data = pruneAndPersist(input.mainWorktree, input.registryDir);
+    if (data.servers.length === 0) {
+        console.log("No dev-servers running.");
+        return;
+    }
+    for (const entry of data.servers) {
+        const ownerSuffix = entry.owner ? `, owner=${entry.owner}` : "";
+        const branch = getWorktreeBranch(entry.worktree) ?? "(detached)";
+        console.log(`Stopping slot ${entry.slot} (${branch}${ownerSuffix})...`);
+        for (const [name, pid] of Object.entries(entry.pids)) {
+            if (!isProcessAlive(pid))
+                continue;
+            console.log(`  ${name} (PID ${pid})`);
+            await stopProcessGroup(pid);
+        }
+        await stopCallbacksForVictim(input.callbackServers, entry.worktree);
+    }
+    writeDevServers(input.mainWorktree, input.registryDir, { servers: [] });
+    console.log(`Stopped ${data.servers.length} dev-server(s).`);
+}
+export async function evictOldest(input) {
+    const isAlive = input.isAlive ?? isProcessAlive;
+    const stop = input.stop ?? stopProcessGroup;
+    const data = pruneDeadServers(readDevServers(input.mainWorktree, input.registryDir), isAlive);
+    const sorted = [...data.servers].sort((a, b) => a.startedAt.localeCompare(b.startedAt));
+    const victims = sorted.slice(0, input.count);
+    for (const entry of victims) {
+        for (const pid of Object.values(entry.pids)) {
+            if (isAlive(pid))
+                await stop(pid);
+        }
+        await stopCallbacksForVictim(input.callbackServers, entry.worktree);
+    }
+    const victimSlots = new Set(victims.map((v) => v.slot));
+    const filtered = data.servers.filter((entry) => !victimSlots.has(entry.slot));
+    writeDevServers(input.mainWorktree, input.registryDir, { servers: filtered });
+    return victims;
+}
+async function stopCallbacksForVictim(callbackServers, worktree) {
+    for (const server of [...callbackServers].reverse()) {
+        console.log(`  ${server.name} (callback)`);
+        try {
+            await server.stop({ cwd: worktree });
+        }
+        catch (err) {
+            console.error(`  Failed to stop ${server.name} (${worktree}): ${err.message}`);
+        }
+    }
+}
+export function registerDevServer(mainWorktree, registryDir, entry) {
+    const data = pruneAndPersist(mainWorktree, registryDir);
+    data.servers.push(entry);
+    writeDevServers(mainWorktree, registryDir, data);
+}
+export function unregisterDevServer(mainWorktree, registryDir, worktreePath) {
+    const fp = filePath(mainWorktree, registryDir);
+    if (!existsSync(fp))
+        return;
+    const data = pruneAndPersist(mainWorktree, registryDir);
+    const target = resolve(worktreePath);
+    const filtered = data.servers.filter((entry) => resolve(entry.worktree) !== target);
+    if (filtered.length === data.servers.length)
+        return;
+    writeDevServers(mainWorktree, registryDir, { servers: filtered });
+}
+export function removeDevServerEntryByWorktree(mainWorktree, registryDir, worktreePath) {
+    const fp = filePath(mainWorktree, registryDir);
+    if (!existsSync(fp))
+        return;
+    const data = readDevServers(mainWorktree, registryDir);
+    const target = resolve(worktreePath);
+    const filtered = data.servers.filter((entry) => resolve(entry.worktree) !== target);
+    if (filtered.length === data.servers.length)
+        return;
+    writeDevServers(mainWorktree, registryDir, { servers: filtered });
+}
+/** Returns the entry whose worktree matches `worktreePath`, or `undefined`. Does not prune. */
+export function findOwnEntry(mainWorktree, registryDir, worktreePath) {
+    const data = readDevServers(mainWorktree, registryDir);
+    const target = resolve(worktreePath);
+    return data.servers.find((entry) => resolve(entry.worktree) === target);
+}
+export function pruneAndPersist(mainWorktree, registryDir, isAlive = isProcessAlive) {
+    const data = readDevServers(mainWorktree, registryDir);
+    const pruned = pruneDeadServers(data, isAlive);
+    if (pruned.servers.length !== data.servers.length) {
+        writeDevServers(mainWorktree, registryDir, pruned);
+    }
+    return pruned;
+}
+export function pruneDeadServers(data, isAlive = isProcessAlive) {
+    const live = data.servers.filter((entry) => Object.values(entry.pids).some((pid) => isAlive(pid)));
+    return { servers: live };
+}
+export function readDevServers(mainWorktree, registryDir) {
+    const fp = filePath(mainWorktree, registryDir);
+    if (!existsSync(fp))
+        return { servers: [] };
+    return JSON.parse(readFileSync(fp, "utf-8"));
+}
+export function writeDevServers(mainWorktree, registryDir, data) {
+    const fp = filePath(mainWorktree, registryDir);
+    mkdirSync(join(mainWorktree, registryDir), { recursive: true });
+    writeFileSync(fp, `${JSON.stringify(data, undefined, 2)}\n`);
+}
+function filePath(mainWorktree, registryDir) {
+    return join(mainWorktree, registryDir, DEV_SERVERS_FILENAME);
+}
+function formatEntry(entry) {
+    const pids = Object.entries(entry.pids)
+        .map(([name, pid]) => `${name}=${pid}`)
+        .join(",");
+    const ownerPart = entry.owner ? `  owner=${entry.owner}` : "";
+    const type = entry.main ? "main" : "linked";
+    const branch = getWorktreeBranch(entry.worktree) ?? "(detached)";
+    return `  slot ${entry.slot}  type=${type}  branch=${branch}${ownerPart}  pids=${pids}  startedAt=${entry.startedAt}  worktree=${entry.worktree}`;
+}

package/dist/errors.d.ts

@@ -0,0 +1,10 @@
+export declare class StartupError extends Error {
+    label: string;
+    reason: string;
+    logFile: string | undefined;
+    constructor(label: string, reason: string, logFile?: string);
+}
+export declare class ConfigError extends Error {
+    exitCode: number;
+    constructor(message: string, exitCode?: number);
+}

package/dist/errors.js

@@ -0,0 +1,18 @@
+export class StartupError extends Error {
+    label;
+    reason;
+    logFile;
+    constructor(label, reason, logFile) {
+        super(`${label}: ${reason}`);
+        this.label = label;
+        this.reason = reason;
+        this.logFile = logFile;
+    }
+}
+export class ConfigError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}

package/dist/helpers.d.ts

@@ -0,0 +1,31 @@
+export declare function patchEnvFile(content: string, patches: Record<string, string>): string;
+export declare function extractHost(content: string, key: string, fallback?: string): string;
+/**
+ * Reads `<varName>=<value>` from a dotenv-style file and parses it as a port.
+ * Exits with code 1 on missing file, missing variable, or non-numeric value.
+ */
+export declare function readPortFromEnvFile(file: string, varName: string): number;
+/**
+ * Reads a dotted path (e.g. `server.port`) from a JSON file and parses it as a port.
+ * Exits with code 1 on missing file, missing path, or non-numeric value.
+ */
+export declare function readPortFromJsonFile(file: string, jsonPath: string): number;
+export interface CopyAndPatchCtx {
+    currentWorktree: string;
+    mainWorktree: string;
+    log: (msg: string) => void;
+}
+export declare function copyAndPatchFile(ctx: CopyAndPatchCtx, relPath: string, patchFn: (content: string) => string, label: string, force: boolean, optional?: boolean): void;
+/**
+ * Detects common fatal JS startup failures in a log buffer. Returns a short marker string
+ * naming the matched pattern, or `false` when none match. Used as the default `detectError`
+ * for spawn servers that don't supply one. A custom `detectError` can compose with this:
+ * `detectError: (log) => myDetector(log) || helpers.detectCommonJsError(log)`.
+ */
+/**
+ * Formats a millisecond duration as the two largest units among `d`/`h`/`m`/`s`.
+ * Drops the smaller unit when zero (`5d` instead of `5d 0h`). Sub-second values
+ * round up to `1s` (zero stays `0s`). Negative input returns `0s`.
+ */
+export declare function formatDuration(ms: number): string;
+export declare function detectCommonJsError(log: string): string | false;