@paleo/worktree-env 0.5.2 → 0.6.1

package/README.md

@@ -37,9 +37,12 @@ npm run setup-worktree -- --remove feat/42   # full teardown
 ## API
 
 ```ts
+import { fileURLToPath } from "node:url";
 import { runSetupWorktree, helpers } from "@paleo/worktree-env";
 
 await runSetupWorktree({
+  scriptPath: fileURLToPath(import.meta.url),
+  devServerScript: fileURLToPath(new URL("./dev-server.mjs", import.meta.url)),
   basePort: 8100,
   portNames: ["server", "frontend", "db"],
   sharedDirs: [".local", ".plans"],
@@ -77,6 +80,7 @@ await runDevServer({
   devLimit: 5,
   servers: [
     {
+      kind: "spawn",
       name: "dev",
       exec: { command: "npm", args: ["run", "dev"] },
       port: helpers.readPortFromEnvFile(".env", "PORT"),

package/dist/dev-server.d.ts

@@ -1,4 +1,6 @@
+import type { CallbackServer, ServerContext, ServerDescriptor, SpawnServer } from "./server-descriptor.js";
 import { type ResolvedSlot } from "./slots.js";
+export type { CallbackServer, ServerContext, ServerDescriptor, SpawnServer };
 /** Configuration accepted by {@link runDevServer}. */
 export interface DevServerConfig {
     /** Anchor port for the slot range. Used to synthesize the main worktree's slot. */
@@ -13,36 +15,21 @@ export interface DevServerConfig {
     registryDir: string;
     /** Maximum concurrent dev-servers across all worktrees. Omit for no limit. */
     devLimit?: number;
-    /** One entry per process to spawn. Started in array order. */
+    /** One entry per server to start. Started in array order; stopped in reverse order. */
     servers: ServerDescriptor[];
-    /** Hook invoked once before any dev-server is spawned (e.g. `docker compose up -d`). */
-    ensureInfrastructure?: () => Promise<void> | void;
     /** Builds the post-start summary printed to stdout. Defaults to a generic layout. */
     printSummary?: (ctx: DevServerSummaryContext) => string;
 }
-/** Describes one process to spawn. */
-export interface ServerDescriptor {
-    /** Short label used in logs and the registry. Derives `<runtimeDir>/<name>.pid` and `<runtimeDir>/logs/<name>.log`. */
-    name: string;
-    /** Command and arguments passed to `child_process.spawn`. */
-    exec: {
-        command: string;
-        args: string[];
-    };
-    /** Port the process will listen on. Use `helpers.readPortFromEnvFile` / `readPortFromJsonFile` to read it from a config file. */
-    port: number;
-    /** Returns `true` once the log content indicates the server is ready. */
-    detectSuccess: (logContent: string) => boolean;
-    /** Returns a non-empty marker string when the log content indicates a fatal error, or `false` otherwise. */
-    detectError?: (logContent: string) => string | false;
-}
-/** Context passed to {@link DevServerConfig.printSummary}. */
+/**
+ * Context passed to {@link DevServerConfig.printSummary}. `port` and `pid` are present only for
+ * `kind: "spawn"` servers; callback servers expose neither.
+ */
 export interface DevServerSummaryContext {
     slot: ResolvedSlot;
     servers: {
         server: ServerDescriptor;
-        port: number;
-        pid: number;
+        port?: number;
+        pid?: number;
     }[];
 }
 export declare function runDevServer(config: DevServerConfig): Promise<void>;

package/dist/dev-server.js

@@ -1,17 +1,14 @@
 import { spawn } from "node:child_process";
-import { closeSync, mkdirSync, openSync, writeFileSync } from "node:fs";
+import { closeSync, mkdirSync, openSync } from "node:fs";
 import { createConnection } from "node:net";
 import { dirname, join } from "node:path";
 import { parseDevServerArgs, printDevServerHelp, validateDevServerFlags, } from "./cli.js";
-import { evictOldest, listDevServers, printActiveServers, pruneAndPersist, registerDevServer, stopAllRegistered, unregisterDevServer, } from "./dev-servers-registry.js";
+import { evictOldest, findOwnEntry, listDevServers, printActiveServers, pruneAndPersist, registerDevServer, removeDevServerEntryByWorktree, stopAllRegistered, unregisterDevServer, } from "./dev-servers-registry.js";
 import { ConfigError, StartupError } from "./errors.js";
 import { awaitAllReady, handleStartupFailure } from "./log-polling.js";
-import { cleanupPidFile, isProcessAlive, readPid, stopByPidFile } from "./process-control.js";
+import { isProcessAlive, stopProcessGroup } from "./process-control.js";
 import { resolveCurrentSlot } from "./slots.js";
 import { detectWorktree } from "./worktree.js";
-function pidFileFor(runtimeDir, name) {
-    return join(runtimeDir, `${name}.pid`);
-}
 function logFileFor(runtimeDir, name) {
     return join(runtimeDir, "logs", `${name}.log`);
 }
@@ -47,7 +44,7 @@ export async function runDevServer(config) {
         await stopAllRegistered({
             mainWorktree,
             registryDir: config.registryDir,
-            runtimeDir: config.runtimeDir,
+            callbackServers: callbackServersOf(config),
         });
         return;
     }
@@ -57,60 +54,85 @@ export async function runDevServer(config) {
     }
     await start(config, mainWorktree, { evict: Boolean(args.evict) });
 }
+function callbackServersOf(config) {
+    return config.servers.filter((s) => s.kind === "callback");
+}
 async function start(config, mainWorktree, { evict }) {
+    const ctx = { cwd: process.cwd() };
     await enforceCap(config, mainWorktree, evict);
+    checkNoLocalRegistryConflict(config, mainWorktree, ctx.cwd);
     await checkPortsFree(config.servers);
-    checkNoLocalPidConflict(config);
-    if (config.ensureInfrastructure)
-        await config.ensureInfrastructure();
-    const pids = [];
-    for (const server of config.servers) {
-        console.log(`Starting ${server.name} dev server...`);
-        pids.push(spawnServer(server, config.runtimeDir));
-    }
+    const spawnPids = {};
+    const startedCallbacks = [];
     try {
-        const pollables = config.servers.map((s) => ({
+        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,
         }));
-        await awaitAllReady(pollables, pids);
+        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);
-            console.error("\nStopping dev servers...");
-            await stopLocal(config, mainWorktree);
             process.exit(1);
         }
         throw err;
     }
     const slot = resolveCurrentSlot(config.basePort, config.registryDir);
-    const pidMap = {};
-    config.servers.forEach((server, i) => {
-        pidMap[server.name] = pids[i];
-    });
     registerDevServer(mainWorktree, config.registryDir, {
         slot: slot.slot,
         worktree: slot.worktree,
         branch: slot.branch,
         owner: slot.owner,
-        pids: pidMap,
+        pids: spawnPids,
         startedAt: new Date().toISOString(),
     });
+    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: config.servers.map((server, i) => ({
-                server,
-                port: server.port,
-                pid: pids[i],
-            })),
-        }));
+        console.log(config.printSummary({ slot, servers: summaryServers }));
     }
     else {
-        defaultPrintSummary(slot, config.servers, config.servers.map((s) => s.port), pids, config.runtimeDir);
+        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}`);
+        }
     }
 }
 // TOCTOU: the cap check and the subsequent register are not atomic. Two concurrent `dev:up --evict`
@@ -132,72 +154,99 @@ async function enforceCap(config, mainWorktree, evict) {
     }
     const toEvict = active.length - limit + 1;
     console.log(`Evicting ${toEvict} dev-server(s) to make room (cap ${limit}).`);
-    const evicted = await evictOldest(mainWorktree, config.registryDir, toEvict);
+    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}` : "";
         console.log(`Evicted slot ${entry.slot} (branch=${entry.branch}${ownerPart}, startedAt=${entry.startedAt}).`);
-        for (const name of Object.keys(entry.pids)) {
-            cleanupPidFile(join(entry.worktree, config.runtimeDir, `${name}.pid`));
-        }
     }
 }
 async function checkPortsFree(servers) {
-    const busy = await Promise.all(servers.map((s) => isPortBusy(s.port)));
+    const spawnServers = servers.filter((s) => s.kind === "spawn");
+    const busy = await Promise.all(spawnServers.map((s) => isPortBusy(s.port)));
     let anyBusy = false;
     busy.forEach((b, i) => {
         if (b) {
-            console.error(`Error: Port ${servers[i].port} (${servers[i].name}) is already in use.`);
+            console.error(`Error: Port ${spawnServers[i].port} (${spawnServers[i].name}) is already in use.`);
             anyBusy = true;
         }
     });
     if (anyBusy)
         process.exit(1);
 }
-function checkNoLocalPidConflict(config) {
-    for (const server of config.servers) {
-        const pidFile = pidFileFor(config.runtimeDir, server.name);
-        const existingPid = readPid(pidFile);
-        if (existingPid !== undefined && isProcessAlive(existingPid)) {
-            console.error(`Error: ${server.name} is already running (PID ${existingPid}).`);
+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);
         }
-        cleanupPidFile(pidFile);
     }
+    // Stale entry — drop it so registration overwrites cleanly.
+    removeDevServerEntryByWorktree(mainWorktree, config.registryDir, cwd);
 }
 async function stopLocal(config, mainWorktree) {
-    for (const server of config.servers) {
-        await stopByPidFile(pidFileFor(config.runtimeDir, server.name), server.name, (msg) => console.log(msg));
+    const ctx = { cwd: process.cwd() };
+    const entry = findOwnEntry(mainWorktree, config.registryDir, ctx.cwd);
+    if (!entry) {
+        console.log("No dev-server running in this worktree.");
+        return;
+    }
+    for (const [name, pid] of Object.entries(entry.pids)) {
+        if (!isProcessAlive(pid))
+            continue;
+        console.log(`Stopping ${name} (PID ${pid})...`);
+        await stopProcessGroup(pid);
     }
-    unregisterDevServer(mainWorktree, config.registryDir, process.cwd());
+    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);
 }
-function defaultPrintSummary(slot, servers, ports, pids, runtimeDir) {
+function defaultPrintSummary(slot, servers, runtimeDir) {
     console.log("\nDev servers started!");
     const ownerSuffix = slot.owner ? `, owner ${slot.owner}` : "";
     console.log(`  Worktree: slot ${slot.slot}${ownerSuffix}`);
-    servers.forEach((server, i) => {
-        const url = `http://localhost:${ports[i]}/`;
-        const logPath = join(process.cwd(), logFileFor(runtimeDir, server.name));
-        console.log(`  ${server.name}: ${url}  (PID ${pids[i]})`);
-        console.log(`    log: ${logPath}`);
-    });
+    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) {
+function spawnServer(server, runtimeDir, cwd) {
     const logFile = logFileFor(runtimeDir, server.name);
-    const pidFile = pidFileFor(runtimeDir, server.name);
     mkdirSync(dirname(logFile), { recursive: true });
-    mkdirSync(dirname(pidFile), { 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);
     }
-    writeFileSync(pidFile, String(child.pid));
     child.unref();
     closeSync(logFd);
     return child.pid;

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

@@ -1,3 +1,4 @@
+import type { CallbackServer } from "./server-descriptor.js";
 export interface DevServerEntry {
     slot: number;
     worktree: string;
@@ -15,17 +16,25 @@ export declare function printActiveServers(active: DevServerEntry[]): void;
 export interface StopAllInput {
     mainWorktree: string;
     registryDir: string;
-    runtimeDir: 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 EvictDeps {
+export interface EvictInput {
+    mainWorktree: string;
+    registryDir: string;
+    count: number;
+    callbackServers: CallbackServer[];
     isAlive?: IsAliveFn;
     stop?: (pid: number) => Promise<void>;
 }
-export declare function evictOldest(mainWorktree: string, registryDir: string, count: number, deps?: EvictDeps): Promise<DevServerEntry[]>;
+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;

package/dist/dev-servers-registry.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { isProcessAlive, stopProcessGroup } from "./process-control.js";
 const DEV_SERVERS_FILENAME = "dev-servers.json";
@@ -34,34 +34,40 @@ export async function stopAllRegistered(input) {
             console.log(`  ${name} (PID ${pid})`);
             await stopProcessGroup(pid);
         }
-        // `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);
-        }
+        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(mainWorktree, registryDir, count, deps = {}) {
-    const isAlive = deps.isAlive ?? isProcessAlive;
-    const stop = deps.stop ?? stopProcessGroup;
-    const data = pruneDeadServers(readDevServers(mainWorktree, registryDir), isAlive);
+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, count);
+    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(mainWorktree, registryDir, { servers: filtered });
+    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);
@@ -89,6 +95,12 @@ export function removeDevServerEntryByWorktree(mainWorktree, registryDir, worktr
         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);

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { runSetupWorktree } from "./setup-worktree.js";
-export type { SetupWorktreeConfig, SetupContext, SummaryContext, PatchContext, ConfigFileEntry, TeardownContext, } from "./setup-worktree.js";
+export type { SetupWorktreeConfig, SetupContext, SummaryContext, PatchContext, ConfigFileEntry, PurgeContext, } from "./setup-worktree.js";
 export { runDevServer } from "./dev-server.js";
-export type { DevServerConfig, DevServerSummaryContext, ServerDescriptor, } from "./dev-server.js";
+export type { DevServerConfig, DevServerSummaryContext, ServerDescriptor, ServerContext, SpawnServer, CallbackServer, } from "./dev-server.js";
 export type { ResolvedSlot } from "./slots.js";
 import * as helpers from "./helpers.js";
 export { helpers };

package/dist/process-control.d.ts

@@ -1,7 +1,4 @@
-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;

package/dist/process-control.js

@@ -1,16 +1,3 @@
-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;
@@ -21,15 +8,6 @@ export async function stopProcessGroup(pid, timeoutMs = 10_000) {
     }
     killProcessGroup(pid, "SIGKILL");
 }
-export function readPid(pidFile) {
-    if (!existsSync(pidFile))
-        return undefined;
-    const raw = readFileSync(pidFile, "utf-8").trim();
-    const pid = Number(raw);
-    if (!Number.isInteger(pid) || pid <= 0)
-        return undefined;
-    return pid;
-}
 export function isProcessAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -61,7 +39,3 @@ export function killProcessGroup(pid, signal) {
         }
     }
 }
-export function cleanupPidFile(pidFile) {
-    if (existsSync(pidFile))
-        unlinkSync(pidFile);
-}

package/dist/server-descriptor.d.ts

@@ -0,0 +1,41 @@
+/** Context threaded into every callback-managed server lifecycle hook. */
+export interface ServerContext {
+    /**
+     * Worktree directory for this lifecycle call. Equals `process.cwd()` at start time for local
+     * starts/stops; equals the victim entry's worktree for cross-worktree stops (eviction,
+     * `dev:down --all`). Callbacks MUST thread this into every child-process call
+     * (`{ cwd: ctx.cwd }` on `execSync`, `spawn`, etc.) and resolve relative paths against it.
+     */
+    cwd: string;
+}
+/** One process spawned and tracked by the runner. */
+export interface SpawnServer {
+    kind: "spawn";
+    /** Short label used in logs and the registry. Derives `<runtimeDir>/logs/<name>.log`. */
+    name: string;
+    /** Command and arguments passed to `child_process.spawn`. */
+    exec: {
+        command: string;
+        args: string[];
+    };
+    /** Port the process will listen on. Use `helpers.readPortFromEnvFile` / `readPortFromJsonFile`. */
+    port: number;
+    /** Returns `true` once the log content indicates the server is ready. */
+    detectSuccess: (logContent: string) => boolean;
+    /** Returns a non-empty marker string when the log content indicates a fatal error, or `false`. */
+    detectError?: (logContent: string) => string | false;
+}
+/**
+ * A resource whose lifecycle the user owns (typically Docker / databases). The runner only
+ * invokes `start` and `stop`; it never spawns, polls logs, or tracks PIDs for callback servers.
+ */
+export interface CallbackServer {
+    kind: "callback";
+    /** Short label used in logs. */
+    name: string;
+    /** Must resolve only once the resource is ready. Thread `ctx.cwd` into every child-process call. */
+    start: (ctx: ServerContext) => Promise<void>;
+    /** Tears down the resource. Thread `ctx.cwd` into every child-process call. */
+    stop: (ctx: ServerContext) => Promise<void>;
+}
+export type ServerDescriptor = SpawnServer | CallbackServer;

package/dist/server-descriptor.js

@@ -0,0 +1 @@
+export {};

package/dist/setup-worktree.d.ts

@@ -20,7 +20,7 @@ export interface SetupWorktreeConfig {
     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.
+     * Holds the setup log and dev-server logs.
      */
     runtimeDir: string;
     /**
@@ -38,8 +38,18 @@ export interface SetupWorktreeConfig {
      * 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;
+    /**
+     * Absolute path to your dev-server script (the file that calls `runDevServer`). On `--remove`,
+     * the kernel shells out to `node <devServerScript> --stop` with `cwd: <target worktree>`.
+     * Typically `fileURLToPath(new URL('./dev-server.mjs', import.meta.url))` from your
+     * `setup-worktree.mjs`.
+     */
+    devServerScript: string;
+    /**
+     * Destructive infrastructure teardown on `--remove` (e.g. `docker compose down -v` to wipe
+     * volumes). Runs after the dev-server stop. Best-effort; errors should be swallowed.
+     */
+    purgeInfrastructure?: (ctx: PurgeContext) => Promise<void> | void;
     /** Builds the post-setup summary printed to stdout. */
     printSummary: (ctx: SummaryContext) => string;
 }
@@ -63,8 +73,8 @@ export interface SummaryContext {
     currentWorktree: string;
     mainWorktree: string;
 }
-/** Context passed to {@link SetupWorktreeConfig.teardownInfrastructure}. */
-export interface TeardownContext {
+/** Context passed to {@link SetupWorktreeConfig.purgeInfrastructure}. */
+export interface PurgeContext {
     worktree: string;
     mainWorktree: string;
     verbose: boolean;

package/dist/setup-worktree.js

@@ -1,12 +1,11 @@
-import { spawn } from "node:child_process";
-import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, symlinkSync, writeFileSync, } from "node:fs";
+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 { isFinalizeMode, isInfoMode, isRemoveMode, isSetOwnerMode, isSetupMode, isWaitMode, parseSetupArgs, printSetupHelp, validateSetupFlags, } from "./cli.js";
-import { removeDevServerEntryByWorktree } from "./dev-servers-registry.js";
+import { findOwnEntry, removeDevServerEntryByWorktree } from "./dev-servers-registry.js";
 import { ConfigError } from "./errors.js";
 import { copyAndPatchFile } from "./helpers.js";
 import { defaultComputePorts, isValidPort, resolvePortScheme } from "./ports.js";
-import { cleanupPidFile, isProcessAlive, isProcessGroupAlive, killProcessGroup, readPid, } from "./process-control.js";
 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) {
@@ -288,9 +287,15 @@ async function handleRemove(args, ctx, run, config) {
         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({
+    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,
@@ -406,41 +411,23 @@ function resolveRemoveTarget(args, ctx, registry, removeHere) {
     }
     return { slotPort: entry[0], branch, worktreePath, owner: entry[1].owner };
 }
-async function stopAllDevServersInRuntimeDir(worktreePath, runtimeDir, log) {
-    const dir = join(worktreePath, runtimeDir);
-    let entries;
-    try {
-        entries = readdirSync(dir);
-    }
-    catch {
-        return;
+/**
+ * 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}`);
     }
-    for (const name of entries) {
-        if (!name.endsWith(".pid"))
-            continue;
-        const pidFile = join(dir, name);
-        const pid = readPid(pidFile);
-        if (pid === undefined)
-            continue;
-        if (!isProcessAlive(pid)) {
-            cleanupPidFile(pidFile);
-            continue;
-        }
-        log(`Stopping dev server (PID ${pid})...`);
-        killProcessGroup(pid, "SIGTERM");
-        const deadline = Date.now() + 5_000;
-        let stillAlive = true;
-        while (Date.now() < deadline) {
-            if (!isProcessGroupAlive(pid)) {
-                stillAlive = false;
-                break;
-            }
-            await new Promise((r) => setTimeout(r, 300));
-        }
-        if (stillAlive) {
-            killProcessGroup(pid, "SIGKILL");
-        }
-        cleanupPidFile(pidFile);
+    else if (result.status !== 0) {
+        console.warn(`Warning: dev-server --stop exited with code ${result.status}.`);
     }
 }
 function resolvePortsFn(config) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paleo/worktree-env",
-  "version": "0.5.2",
+  "version": "0.6.1",
   "description": "Worktree-based concurrent local environment kernel.",
   "keywords": [
     "worktree",