@paleo/worktree-env 0.4.1 → 0.5.1

package/dist/dev-servers-registry.js

@@ -1,76 +1,9 @@
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { isProcessAlive, stopProcessGroup } from "./process-control.js";
-export const DEV_SERVERS_FILE = ".local/worktrees/dev-servers.json";
-export const WORKTREES_DIR = ".local/worktrees";
-function filePath(mainWorktree) {
-    return join(mainWorktree, DEV_SERVERS_FILE);
-}
-export function readDevServers(mainWorktree) {
-    const fp = filePath(mainWorktree);
-    if (!existsSync(fp))
-        return { servers: [] };
-    return JSON.parse(readFileSync(fp, "utf-8"));
-}
-export function writeDevServers(mainWorktree, data) {
-    const fp = filePath(mainWorktree);
-    mkdirSync(join(mainWorktree, WORKTREES_DIR), { recursive: true });
-    writeFileSync(fp, `${JSON.stringify(data, undefined, 2)}\n`);
-}
-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 pruneAndPersist(mainWorktree, isAlive = isProcessAlive) {
-    const data = readDevServers(mainWorktree);
-    const pruned = pruneDeadServers(data, isAlive);
-    if (pruned.servers.length !== data.servers.length) {
-        writeDevServers(mainWorktree, pruned);
-    }
-    return pruned;
-}
-export function registerDevServer(mainWorktree, entry) {
-    const data = pruneAndPersist(mainWorktree);
-    data.servers.push(entry);
-    writeDevServers(mainWorktree, data);
-}
-export function unregisterDevServer(mainWorktree, worktreePath) {
-    const fp = filePath(mainWorktree);
-    if (!existsSync(fp))
-        return;
-    const data = pruneAndPersist(mainWorktree);
-    const target = resolve(worktreePath);
-    const filtered = data.servers.filter((entry) => resolve(entry.worktree) !== target);
-    if (filtered.length === data.servers.length)
-        return;
-    writeDevServers(mainWorktree, { servers: filtered });
-}
-export function removeDevServerEntryByWorktree(mainWorktree, worktreePath) {
-    const fp = filePath(mainWorktree);
-    if (!existsSync(fp))
-        return;
-    const data = readDevServers(mainWorktree);
-    const target = resolve(worktreePath);
-    const filtered = data.servers.filter((entry) => resolve(entry.worktree) !== target);
-    if (filtered.length === data.servers.length)
-        return;
-    writeDevServers(mainWorktree, { servers: filtered });
-}
-function formatEntry(entry) {
-    const pids = Object.entries(entry.pids)
-        .map(([name, pid]) => `${name}=${pid}`)
-        .join(",");
-    const ownerPart = entry.owner ? `  owner=${entry.owner}` : "";
-    return `  slot ${entry.slot}  branch=${entry.branch}${ownerPart}  pids=${pids}  startedAt=${entry.startedAt}  worktree=${entry.worktree}`;
-}
-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 function listDevServers(mainWorktree) {
-    const data = pruneAndPersist(mainWorktree);
+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;
@@ -80,8 +13,14 @@ export function listDevServers(mainWorktree) {
         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);
+    const data = pruneAndPersist(input.mainWorktree, input.registryDir);
     if (data.servers.length === 0) {
         console.log("No dev-servers running.");
         return;
@@ -95,12 +34,91 @@ export async function stopAllRegistered(input) {
             console.log(`  ${name} (PID ${pid})`);
             await stopProcessGroup(pid);
         }
-        for (const pidFile of input.pidFiles) {
-            const fp = join(entry.worktree, pidFile);
+        // `runtimeDir` is repo-wide, so each entry's PID files live at the same relative path.
+        // Server names vary per entry, hence reading them from `entry.pids` rather than caller config.
+        for (const name of Object.keys(entry.pids)) {
+            const fp = join(entry.worktree, input.runtimeDir, `${name}.pid`);
             if (existsSync(fp))
                 unlinkSync(fp);
         }
     }
-    writeDevServers(input.mainWorktree, { servers: [] });
+    writeDevServers(input.mainWorktree, input.registryDir, { servers: [] });
     console.log(`Stopped ${data.servers.length} dev-server(s).`);
 }
+export async function evictOldest(mainWorktree, registryDir, count, deps = {}) {
+    const isAlive = deps.isAlive ?? isProcessAlive;
+    const stop = deps.stop ?? stopProcessGroup;
+    const data = pruneDeadServers(readDevServers(mainWorktree, registryDir), isAlive);
+    const sorted = [...data.servers].sort((a, b) => a.startedAt.localeCompare(b.startedAt));
+    const victims = sorted.slice(0, count);
+    for (const entry of victims) {
+        for (const pid of Object.values(entry.pids)) {
+            if (isAlive(pid))
+                await stop(pid);
+        }
+    }
+    const victimSlots = new Set(victims.map((v) => v.slot));
+    const filtered = data.servers.filter((entry) => !victimSlots.has(entry.slot));
+    writeDevServers(mainWorktree, registryDir, { servers: filtered });
+    return victims;
+}
+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 });
+}
+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}` : "";
+    return `  slot ${entry.slot}  branch=${entry.branch}${ownerPart}  pids=${pids}  startedAt=${entry.startedAt}  worktree=${entry.worktree}`;
+}

package/dist/errors.d.ts

@@ -8,4 +8,3 @@ export declare class ConfigError extends Error {
     exitCode: number;
     constructor(message: string, exitCode?: number);
 }
-export declare function exitWith(code: number, message: string): never;

package/dist/errors.js

@@ -16,7 +16,3 @@ export class ConfigError extends Error {
         this.exitCode = exitCode;
     }
 }
-export function exitWith(code, message) {
-    console.error(message);
-    process.exit(code);
-}

package/dist/helpers.js

@@ -59,14 +59,6 @@ export function readPortFromJsonFile(file, jsonPath) {
     }
     return toPort(String(cur), file);
 }
-function toPort(raw, file) {
-    const port = Number(raw);
-    if (!Number.isFinite(port)) {
-        console.error(`Error: invalid port "${raw}" in ${file}.`);
-        process.exit(1);
-    }
-    return port;
-}
 export function copyAndPatchFile(ctx, relPath, patchFn, label, force, required = false) {
     const targetPath = join(ctx.currentWorktree, relPath);
     const sourcePath = join(ctx.mainWorktree, relPath);
@@ -89,3 +81,11 @@ export function copyAndPatchFile(ctx, relPath, patchFn, label, force, required =
     writeFileSync(targetPath, patched);
     ctx.log(`${alreadyExists ? "Overwritten" : "Created"} ${label}.`);
 }
+function toPort(raw, file) {
+    const port = Number(raw);
+    if (!Number.isFinite(port)) {
+        console.error(`Error: invalid port "${raw}" in ${file}.`);
+        process.exit(1);
+    }
+    return port;
+}

package/dist/log-polling.d.ts

@@ -13,6 +13,5 @@ export interface AwaitOptions {
     pollIntervalMs?: number;
     isAlive?: (pid: number) => boolean;
 }
-export declare function waitForReady(server: PollableServer, pid: number, options?: AwaitOptions): Promise<void>;
 export declare function awaitAllReady(servers: PollableServer[], pids: number[], options?: AwaitOptions): Promise<void>;
 export declare function handleStartupFailure(err: StartupError): void;

package/dist/log-polling.js

@@ -5,7 +5,19 @@ import { isProcessAlive as defaultIsAlive } from "./process-control.js";
 export const LOG_TAIL_LINES = 30;
 export const POLL_INTERVAL_MS = 500;
 export const TIMEOUT_MS = 120_000;
-export async function waitForReady(server, pid, options = {}) {
+export async function awaitAllReady(servers, pids, options) {
+    await Promise.all(servers.map((server, i) => waitForReady(server, pids[i], options)));
+}
+export function handleStartupFailure(err) {
+    console.error(`\nError: ${err.label} ${err.reason}.`);
+    if (err.logFile && existsSync(err.logFile)) {
+        const lines = readFileSync(err.logFile, "utf-8").split("\n").slice(-LOG_TAIL_LINES);
+        console.error(`\n--- ${err.label} log tail (last ${LOG_TAIL_LINES} lines) ---`);
+        console.error(lines.join("\n"));
+        console.error(`--- end ---\nFull log: ${join(process.cwd(), err.logFile)}`);
+    }
+}
+async function waitForReady(server, pid, options = {}) {
     const timeoutMs = options.timeoutMs ?? TIMEOUT_MS;
     const pollIntervalMs = options.pollIntervalMs ?? POLL_INTERVAL_MS;
     const isAlive = options.isAlive ?? defaultIsAlive;
@@ -27,15 +39,3 @@ export async function waitForReady(server, pid, options = {}) {
     }
     throw new StartupError(server.name, `did not become ready within ${timeoutMs / 1000}s`, server.logFile);
 }
-export async function awaitAllReady(servers, pids, options) {
-    await Promise.all(servers.map((server, i) => waitForReady(server, pids[i], options)));
-}
-export function handleStartupFailure(err) {
-    console.error(`\nError: ${err.label} ${err.reason}.`);
-    if (err.logFile && existsSync(err.logFile)) {
-        const lines = readFileSync(err.logFile, "utf-8").split("\n").slice(-LOG_TAIL_LINES);
-        console.error(`\n--- ${err.label} log tail (last ${LOG_TAIL_LINES} lines) ---`);
-        console.error(lines.join("\n"));
-        console.error(`--- end ---\nFull log: ${join(process.cwd(), err.logFile)}`);
-    }
-}

package/dist/ports.d.ts

@@ -1,8 +1,3 @@
-export interface PortSchemeOptions {
-    basePort: number;
-    portStep?: number;
-    maxSlotCount?: number;
-}
 export interface PortScheme {
     basePort: number;
     portStep: number;
@@ -10,6 +5,11 @@ export interface PortScheme {
     minPort: number;
     maxPort: number;
 }
+export interface PortSchemeOptions {
+    basePort: number;
+    portStep?: number;
+    maxSlotCount?: number;
+}
 export declare function resolvePortScheme(opts: PortSchemeOptions): PortScheme;
 export declare function isValidPort(port: number, scheme: PortScheme): boolean;
 export declare function allPorts(scheme: PortScheme): number[];

package/dist/process-control.d.ts

@@ -1,7 +1,7 @@
+export declare function stopByPidFile(pidFile: string, label: string, log?: (msg: string) => void): Promise<void>;
+export declare function stopProcessGroup(pid: number, timeoutMs?: number): Promise<void>;
 export declare function readPid(pidFile: string): number | undefined;
 export declare function isProcessAlive(pid: number): boolean;
 export declare function isProcessGroupAlive(pid: number): boolean;
 export declare function killProcessGroup(pid: number, signal: NodeJS.Signals): void;
 export declare function cleanupPidFile(pidFile: string): void;
-export declare function stopProcessGroup(pid: number, timeoutMs?: number): Promise<void>;
-export declare function stopByPidFile(pidFile: string, label: string, log?: (msg: string) => void): Promise<void>;

package/dist/process-control.js

@@ -1,4 +1,26 @@
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
+export async function stopByPidFile(pidFile, label, log = () => { }) {
+    const pid = readPid(pidFile);
+    if (pid === undefined || !isProcessAlive(pid)) {
+        cleanupPidFile(pidFile);
+        log(`No ${label} process is running.`);
+        return;
+    }
+    log(`Stopping ${label} (PID ${pid})...`);
+    await stopProcessGroup(pid);
+    cleanupPidFile(pidFile);
+    log(`${label} stopped.`);
+}
+export async function stopProcessGroup(pid, timeoutMs = 10_000) {
+    killProcessGroup(pid, "SIGTERM");
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 300));
+        if (!isProcessGroupAlive(pid))
+            return;
+    }
+    killProcessGroup(pid, "SIGKILL");
+}
 export function readPid(pidFile) {
     if (!existsSync(pidFile))
         return undefined;
@@ -43,25 +65,3 @@ export function cleanupPidFile(pidFile) {
     if (existsSync(pidFile))
         unlinkSync(pidFile);
 }
-export async function stopProcessGroup(pid, timeoutMs = 10_000) {
-    killProcessGroup(pid, "SIGTERM");
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        await new Promise((r) => setTimeout(r, 300));
-        if (!isProcessGroupAlive(pid))
-            return;
-    }
-    killProcessGroup(pid, "SIGKILL");
-}
-export async function stopByPidFile(pidFile, label, log = () => { }) {
-    const pid = readPid(pidFile);
-    if (pid === undefined || !isProcessAlive(pid)) {
-        cleanupPidFile(pidFile);
-        log(`No ${label} process is running.`);
-        return;
-    }
-    log(`Stopping ${label} (PID ${pid})...`);
-    await stopProcessGroup(pid);
-    cleanupPidFile(pidFile);
-    log(`${label} stopped.`);
-}

package/dist/setup-worktree.d.ts

@@ -1,4 +1,49 @@
-/** Context passed to setup-time hooks (`setupWorktreeData`, `installAndBuild`, `afterDatabase`). */
+/** Configuration accepted by {@link runSetupWorktree}. */
+export interface SetupWorktreeConfig {
+    /**
+     * Absolute path to the wrapper script that calls `runSetupWorktree`. The package re-spawns this
+     * file as a detached child for the finalize phase, so it must point at a runnable Node entrypoint
+     * — typically `fileURLToPath(import.meta.url)` from your `setup-worktree.mjs`.
+     */
+    scriptPath: string;
+    /** Anchor port for the slot range. Slots are derived from this value. */
+    basePort: number;
+    /** Distance between consecutive slots. Defaults to `10`. */
+    portStep?: number;
+    /** Maximum number of slots. Defaults to `19`. */
+    maxSlotCount?: number;
+    /** Custom port computation; takes precedence over `portNames`. */
+    ports?: (slot: number) => Record<string, number>;
+    /** Named offsets `[name0, name1, ...]` mapped to `slot+0`, `slot+1`, ... Required if `ports` is omitted. */
+    portNames?: string[];
+    /** Directories symlinked from the main worktree. */
+    sharedDirs: string[];
+    /**
+     * Per-worktree runtime directory, relative to the worktree root (e.g. `.local-wt`).
+     * Holds the setup log, dev-server PID files, and dev-server logs.
+     */
+    runtimeDir: string;
+    /**
+     * Shared registry directory, relative to a worktree root (e.g. `.local/wt-registry`).
+     * Holds `slots.json` and `dev-servers.json`. Must resolve to the same physical directory
+     * across linked worktrees — typically via a symlink listed in `sharedDirs` (e.g. `.local`).
+     */
+    registryDir: string;
+    /** Config files copied from the main worktree and patched per slot. */
+    configFiles: ConfigFileEntry[];
+    /**
+     * MUST be idempotent. After a failure, the user re-runs `setup-worktree --here` from inside
+     * the worktree — this callback will be invoked again with the same context. Re-runs must not
+     * error on pre-existing state (created directories, started containers, ran migrations,
+     * installed deps, etc.).
+     */
+    finalizeWorktree: (ctx: SetupContext) => Promise<void> | void;
+    /** Tears down infrastructure on `--remove` (e.g. `docker compose down -v`). Best-effort; errors should be swallowed. */
+    teardownInfrastructure?: (ctx: TeardownContext) => Promise<void> | void;
+    /** Builds the post-setup summary printed to stdout. */
+    printSummary: (ctx: SummaryContext) => string;
+}
+/** Context passed to {@link SetupWorktreeConfig.finalizeWorktree}. */
 export interface SetupContext {
     currentWorktree: string;
     mainWorktree: string;
@@ -9,12 +54,20 @@ export interface SetupContext {
     force: boolean;
     verbose: boolean;
 }
-/** Context passed to {@link ConfigFileEntry.patch}. */
-export interface PatchContext {
+/** Context passed to {@link SetupWorktreeConfig.printSummary}. */
+export interface SummaryContext {
     slot: number;
+    branch: string;
+    owner?: string;
     ports: Record<string, number>;
-    mainWorktree: string;
     currentWorktree: string;
+    mainWorktree: string;
+}
+/** Context passed to {@link SetupWorktreeConfig.teardownInfrastructure}. */
+export interface TeardownContext {
+    worktree: string;
+    mainWorktree: string;
+    verbose: boolean;
 }
 /** One config file copied from the main worktree and patched per slot. */
 export interface ConfigFileEntry {
@@ -25,52 +78,11 @@ export interface ConfigFileEntry {
     /** When `true`, abort if the source file is missing in the main worktree. Defaults to `false`. */
     required?: boolean;
 }
-/** Context passed to {@link SetupWorktreeConfig.printSummary}. */
-export interface SummaryContext {
+/** Context passed to {@link ConfigFileEntry.patch}. */
+export interface PatchContext {
     slot: number;
-    branch: string;
-    owner?: string;
     ports: Record<string, number>;
-    currentWorktree: string;
     mainWorktree: string;
-}
-/** Context passed to {@link SetupWorktreeConfig.teardownInfrastructure}. */
-export interface TeardownContext {
-    worktree: string;
-    mainWorktree: string;
-    verbose: boolean;
-}
-/** Configuration accepted by {@link runSetupWorktree}. */
-export interface SetupWorktreeConfig {
-    /** Anchor port for the slot range. Slots are derived from this value. */
-    basePort: number;
-    /** Distance between consecutive slots. Defaults to `10`. */
-    portStep?: number;
-    /** Maximum number of slots. Defaults to `9`. */
-    maxSlotCount?: number;
-    /** Custom port computation; takes precedence over `portNames`. */
-    ports?: (slot: number) => Record<string, number>;
-    /** Named offsets `[name0, name1, ...]` mapped to `slot+0`, `slot+1`, ... Required if `ports` is omitted. */
-    portNames?: string[];
-    /** Directories symlinked from the main worktree. Defaults to `[".local", ".plans"]`. */
-    sharedDirs?: string[];
-    /** PID files written by `dev-server`, used by `--remove` to stop processes before teardown. */
-    devServerPidFiles: string[];
-    /** Config files copied from the main worktree and patched per slot. */
-    configFiles: ConfigFileEntry[];
-    /**
-     * Runs after symlinks and config files. Owns per-worktree data setup:
-     * create any required directories (e.g. `.local-data/...`), copy or
-     * provision databases / file storage, start infrastructure containers.
-     */
-    setupWorktreeData: (ctx: SetupContext) => Promise<void> | void;
-    /** Tears down infrastructure on `--remove` (e.g. `docker compose down -v`). Best-effort; errors should be swallowed. */
-    teardownInfrastructure?: (ctx: TeardownContext) => Promise<void> | void;
-    /** Runs after `setupWorktreeData`. Typically `npm install && npm run build`. */
-    installAndBuild: (ctx: SetupContext) => Promise<void> | void;
-    /** Runs after `installAndBuild`. Typically migrations and seeds. */
-    afterDatabase?: (ctx: SetupContext) => Promise<void> | void;
-    /** Builds the post-setup summary printed to stdout. */
-    printSummary: (ctx: SummaryContext) => string;
+    currentWorktree: string;
 }
 export declare function runSetupWorktree(config: SetupWorktreeConfig): Promise<void>;