@paleo/worktree-env 0.4.1 → 0.5.1

package/dist/setup-worktree.js

@@ -1,27 +1,14 @@
-import { existsSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, symlinkSync, writeFileSync, } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
-import { isRemoveMode, isSetOwnerMode, isSetupMode, parseSetupArgs, printSetupHelp, validateSetupFlags, } from "./cli.js";
+import { isFinalizeMode, isInfoMode, isRemoveMode, isSetOwnerMode, isSetupMode, isWaitMode, parseSetupArgs, printSetupHelp, validateSetupFlags, } from "./cli.js";
 import { removeDevServerEntryByWorktree } from "./dev-servers-registry.js";
 import { ConfigError } from "./errors.js";
 import { copyAndPatchFile } from "./helpers.js";
-import { defaultComputePorts, resolvePortScheme } from "./ports.js";
-import { handleSetOwner, readSlots, resolveAndRegisterSlot, validateSlotAvailability, writeSlots, } from "./slots.js";
-import { createBranch, detectWorktree, enforceWorktreeMode, getCurrentBranch, removeWorktree, useExistingBranch, verifyBranchAbsentFromRemote, } from "./worktree.js";
+import { defaultComputePorts, isValidPort, resolvePortScheme } from "./ports.js";
 import { cleanupPidFile, isProcessAlive, isProcessGroupAlive, killProcessGroup, readPid, } from "./process-control.js";
-function makeVerboseLog(verbose) {
-    return (msg) => {
-        if (verbose)
-            console.log(msg);
-    };
-}
-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).");
-}
+import { handleSetOwner, markSlotFailed, markSlotReady, readSlots, resolveAndRegisterSlot, resolveCurrentSlot, validateSlotAvailability, writeSlots, } from "./slots.js";
+import { createBranch, detectWorktree, enforceWorktreeMode, getCurrentBranch, removeWorktree, useExistingBranch, verifyBranchAbsentFromRemote, } from "./worktree.js";
 export async function runSetupWorktree(config) {
     let args;
     try {
@@ -36,6 +23,11 @@ export async function runSetupWorktree(config) {
         printSetupHelp();
         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);
+    }
     try {
         validateSetupFlags(args);
     }
@@ -46,6 +38,18 @@ export async function runSetupWorktree(config) {
         }
         throw err;
     }
+    if (isFinalizeMode(args)) {
+        await runFinalize(args, config);
+        return;
+    }
+    if (isWaitMode(args) && !isSetupMode(args)) {
+        await runWait(args, config);
+        return;
+    }
+    if (isInfoMode(args)) {
+        runInfo(args, config);
+        return;
+    }
     if (!isSetupMode(args) && !isRemoveMode(args) && !isSetOwnerMode(args)) {
         printSetupHelp();
         return;
@@ -58,18 +62,21 @@ export async function runSetupWorktree(config) {
         return;
     }
     if (isSetOwnerMode(args)) {
-        handleSetOwnerMode(args, ctx);
+        handleSetOwnerMode(args, ctx, config);
         return;
     }
-    await runSetup(args, ctx, run, config);
+    const { slot } = await runSetup(args, ctx, run, config);
+    if (isWaitMode(args)) {
+        await waitForSlot(slot, config);
+    }
 }
 async function runSetup(args, ctx, run, config) {
-    const verboseLog = makeVerboseLog(run.verbose);
     const scheme = resolvePortScheme(config);
     const portsFn = resolvePortsFn(config);
     validateSlotAvailability(args.slot, {
         currentWorktree: ctx.currentWorktree,
         mainWorktree: ctx.mainWorktree,
+        registryDir: config.registryDir,
         scheme,
     });
     const setupCtx = ensureWorktree(args, ctx, run);
@@ -78,42 +85,254 @@ async function runSetup(args, ctx, run, config) {
         slot: args.slot,
         currentWorktree: setupCtx.currentWorktree,
         mainWorktree: setupCtx.mainWorktree,
+        registryDir: config.registryDir,
         scheme,
         branch,
         requestedOwner: args.owner,
     });
     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 `--here` 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(", ")})`);
-    console.log(`WORKTREE_CREATED path=${setupCtx.currentWorktree} branch=${branch} slot=${slot}`);
-    const sharedDirs = config.sharedDirs ?? [".local", ".plans"];
-    linkSharedDirectories(setupCtx, sharedDirs, verboseLog);
+    linkSharedDirectories(setupCtx, config.sharedDirs, verboseLog);
     generateConfigFiles(setupCtx, config.configFiles, slot, ports, args.force ?? false, verboseLog);
-    const force = args.force ?? false;
-    const setupContext = {
-        currentWorktree: setupCtx.currentWorktree,
-        mainWorktree: setupCtx.mainWorktree,
+    teeLog(config.printSummary({
         slot,
         branch,
         owner,
         ports,
-        force,
-        verbose: run.verbose,
+        currentWorktree: setupCtx.currentWorktree,
+        mainWorktree: setupCtx.mainWorktree,
+    }));
+    teeLog(`WORKTREE_CREATED path=${setupCtx.currentWorktree} branch=${branch} slot=${slot}`);
+    teeLog(`Setup continuing in background. Tail: ${logPath}`);
+    const child = spawn(process.execPath, [config.scriptPath, "--__finalize", String(slot)], {
+        detached: true,
+        stdio: ["ignore", logFd, logFd],
+        cwd: setupCtx.currentWorktree,
+    });
+    child.unref();
+    closeSync(logFd);
+    return { slot };
+}
+async function runFinalize(args, config) {
+    const slot = Number(args.__finalize);
+    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);
+    }
+    if (entry.status === "ready" && !args.force) {
+        appendLog(`READY: branch ${entry.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,
+        slot,
+        branch: entry.branch,
+        owner: entry.owner,
+        ports,
+        force: args.force ?? false,
+        verbose: false,
     };
-    await config.setupWorktreeData(setupContext);
-    await config.installAndBuild(setupContext);
-    if (config.afterDatabase)
-        await config.afterDatabase(setupContext);
+    try {
+        await config.finalizeWorktree(setupContext);
+        markSlotReady(ctx.mainWorktree, config.registryDir, slot);
+        appendLog("============================================================");
+        appendLog(`READY: branch ${entry.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(args, config) {
+    if (args.slot !== undefined) {
+        const slot = Number(args.slot);
+        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 "${args.slot}".`);
+            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 branch = entry?.branch ?? fallback.branch;
+    const owner = entry?.owner ?? fallback.owner;
+    // Main worktree has no slot entry by design — treat it as ready when the registry has no row.
+    const slotStatus = entry?.status ?? (ctx.isMainWorktree ? "ready" : "pending");
+    const logHint = ` (tail ${join(worktreeForLog, config.runtimeDir, "wt-setup.log")})`;
+    const display = slotStatus === "ready"
+        ? "ready"
+        : slotStatus === "failed"
+            ? `failed: ${entry?.failure?.message ?? "(no message)"}${logHint}`
+            : `pending${logHint}`;
+    console.log(`Status: ${display}`);
     console.log(config.printSummary({
         slot,
         branch,
         owner,
         ports,
-        currentWorktree: setupCtx.currentWorktree,
-        mainWorktree: setupCtx.mainWorktree,
+        currentWorktree: entry?.worktree ?? ctx.currentWorktree,
+        mainWorktree: ctx.mainWorktree,
     }));
 }
+function runInfo(args, config) {
+    if (args.slot !== undefined) {
+        const slot = resolveTargetSlot(args, 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, { branch: entry.branch, owner: entry.owner });
+        return;
+    }
+    const resolved = resolveCurrentSlot(config.basePort, config.registryDir);
+    printWorktreeInfo(config, resolved.slot, ".", { branch: resolved.branch, owner: resolved.owner });
+}
+async function runWait(args, config) {
+    const slot = resolveTargetSlot(args, config);
+    await waitForSlot(slot, config);
+}
+async function waitForSlot(slot, config) {
+    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") {
+            printWorktreeInfo(config, slot, entry.worktree, { branch: entry.branch, 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(args, ctx, run, config) {
+    const verboseLog = makeVerboseLog(run.verbose);
+    const removeHere = Boolean(args["remove-here"]);
+    const registry = readSlots(ctx.mainWorktree, config.registryDir);
+    const target = resolveRemoveTarget(args, ctx, registry, removeHere);
+    if (!args["no-remote-check"]) {
+        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;
+    }
+    await stopAllDevServersInRuntimeDir(target.worktreePath, config.runtimeDir, verboseLog);
+    if (config.teardownInfrastructure) {
+        await config.teardownInfrastructure({
+            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(args, ctx, config) {
+    const newOwner = args["set-owner"];
+    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(args, ctx, run) {
     if (args.use)
         return useExistingBranch(args.use, ctx, run);
@@ -180,9 +399,19 @@ function resolveRemoveTarget(args, ctx, registry, removeHere) {
     }
     return { slotPort: entry[0], branch, worktreePath, owner: entry[1].owner };
 }
-async function stopDevServerByPidFiles(worktreePath, pidFiles, log) {
-    for (const pidFileRel of pidFiles) {
-        const pidFile = join(worktreePath, pidFileRel);
+async function stopAllDevServersInRuntimeDir(worktreePath, runtimeDir, log) {
+    const dir = join(worktreePath, runtimeDir);
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries) {
+        if (!name.endsWith(".pid"))
+            continue;
+        const pidFile = join(dir, name);
         const pid = readPid(pidFile);
         if (pid === undefined)
             continue;
@@ -207,69 +436,17 @@ async function stopDevServerByPidFiles(worktreePath, pidFiles, log) {
         cleanupPidFile(pidFile);
     }
 }
-async function handleRemove(args, ctx, run, config) {
-    const verboseLog = makeVerboseLog(run.verbose);
-    const removeHere = Boolean(args["remove-here"]);
-    const registry = readSlots(ctx.mainWorktree);
-    const target = resolveRemoveTarget(args, ctx, registry, removeHere);
-    if (!args["no-remote-check"]) {
-        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, registry);
-        console.log(`Removed registry entry for branch "${target.branch}" (slot ${target.slotPort}${ownerSuffix}).`);
-        return;
-    }
-    await stopDevServerByPidFiles(target.worktreePath, config.devServerPidFiles, verboseLog);
-    if (config.teardownInfrastructure) {
-        await config.teardownInfrastructure({
-            worktree: target.worktreePath,
-            mainWorktree: ctx.mainWorktree,
-            verbose: run.verbose,
-        });
-    }
-    delete registry.slots[target.slotPort];
-    writeSlots(ctx.mainWorktree, registry);
-    removeDevServerEntryByWorktree(ctx.mainWorktree, target.worktreePath);
-    if (removeHere) {
-        process.chdir(ctx.mainWorktree);
-    }
-    removeWorktree(target.worktreePath, run);
-    console.log(`Removed worktree for branch "${target.branch}" (slot ${target.slotPort}${ownerSuffix}).`);
-    if (removeHere) {
-        console.log(`Now run: cd ${ctx.mainWorktree}`);
+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 handleSetOwnerMode(args, ctx) {
-    const newOwner = args["set-owner"];
-    const { slotPort } = handleSetOwner({
-        newOwner,
-        currentWorktree: ctx.currentWorktree,
-        mainWorktree: ctx.mainWorktree,
-        isMainWorktree: ctx.isMainWorktree,
-    });
-    // Propagate to dev-servers.json entries for this worktree.
-    const devServersPath = join(ctx.mainWorktree, ".local/worktrees/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 makeVerboseLog(verbose) {
+    return (msg) => {
+        if (verbose)
+            console.log(msg);
+    };
 }

package/dist/slots.d.ts

@@ -1,33 +1,32 @@
 import { type PortScheme } from "./ports.js";
-export declare const WORKTREES_DIR = ".local/worktrees";
-export declare const SLOTS_FILE = ".local/worktrees/slots.json";
-export interface SlotEntry {
+export interface ResolvedSlot {
+    slot: number;
     worktree: string;
     branch: string;
     owner?: string;
 }
-export interface SlotsRegistry {
-    slots: Record<string, SlotEntry>;
-}
-export interface ResolvedSlot {
-    slot: number;
+export type SlotStatus = "pending" | "ready" | "failed";
+export interface SlotEntry {
     worktree: string;
     branch: string;
     owner?: string;
+    createdAt: string;
+    status: SlotStatus;
+    failure?: {
+        at: string;
+        message: string;
+    };
 }
-export declare function readSlots(mainWorktree: string): SlotsRegistry;
-export declare function writeSlots(mainWorktree: string, registry: SlotsRegistry): void;
-export interface PickSlotArgs {
-    slot?: string;
-    currentWorktree: string;
-    mainWorktree: string;
-    scheme: PortScheme;
+export interface SlotsRegistry {
+    slots: Record<string, SlotEntry>;
 }
-export declare function pickSlotPort(args: PickSlotArgs, registry: SlotsRegistry): number;
+export declare function readSlots(mainWorktree: string, registryDir: string): SlotsRegistry;
+export declare function writeSlots(mainWorktree: string, registryDir: string, registry: SlotsRegistry): void;
 export interface RegisterSlotInput {
     slot?: string;
     currentWorktree: string;
     mainWorktree: string;
+    registryDir: string;
     scheme: PortScheme;
     branch: string;
     requestedOwner?: string;
@@ -36,18 +35,20 @@ export declare function resolveAndRegisterSlot(input: RegisterSlotInput): {
     port: number;
     owner: string | undefined;
 };
+export declare function markSlotReady(mainWorktree: string, registryDir: string, slotPort: number): void;
+export declare function markSlotFailed(mainWorktree: string, registryDir: string, slotPort: number, message: string): void;
 export declare function validateSlotAvailability(slotArg: string | undefined, ctx: {
     currentWorktree: string;
     mainWorktree: string;
+    registryDir: string;
     scheme: PortScheme;
 }): void;
-export declare function lookupSlotForCwd(): ResolvedSlot | undefined;
-export declare function synthesizeMainSlot(basePort: number): ResolvedSlot | undefined;
-export declare function resolveCurrentSlot(basePort: number): ResolvedSlot;
+export declare function resolveCurrentSlot(basePort: number, registryDir: string): ResolvedSlot;
 export interface SetOwnerInput {
     newOwner: string | undefined;
     currentWorktree: string;
     mainWorktree: string;
+    registryDir: string;
     isMainWorktree: boolean;
 }
 export declare function handleSetOwner(input: SetOwnerInput): {