@paleo/worktree-env 0.1.0

package/README.md

@@ -0,0 +1,93 @@
+# @paleo/worktree-env
+
+Run multiple local dev environments side by side, one per git worktree, with isolated ports, databases, and config files. Built for branches worked in parallel, by humans or AI agents.
+
+Each project writes two custom scripts on top, using these entry points:
+
+- `runSetupWorktree(config)` — worktree lifecycle (create / setup / remove / set-owner).
+- `runDevServer(config)` — background dev-server start / stop / list.
+
+## Setup
+
+The `worktree-env-guide` skill is a setup-time companion. Install the skill (globally or locally):
+
+```bash
+npx skills add https://github.com/paleo/alignfirst --skill worktree-env-guide
+```
+
+Then, in your project, ask your agent:
+
+```text
+Use your worktree-env-guide skill. Set up worktree-based local environments in this project.
+```
+
+The agent reads the skill, adapts the reference scripts to your stack, installs `@paleo/worktree-env` as a dev dependency, and wires the npm scripts. After that, you can uninstall the skill, it won't be used by your project anymore.
+
+## Workflow
+
+```sh
+npm run setup-worktree -- --create feat/42   # new branch + worktree + isolated env
+npm run dev:up                               # start dev server in the background
+npm run dev:list                             # active dev-servers across all worktrees
+npm run dev:down                             # stop dev server (infrastructure stays up)
+npm run setup-worktree -- --remove feat/42   # full teardown
+```
+
+## API
+
+```ts
+import { runSetupWorktree, helpers } from "@paleo/worktree-env";
+
+await runSetupWorktree({
+  basePort: 8100,
+  portNames: ["server", "frontend", "db"],
+  devLimitEnvVar: "MYAPP_DEV_LIMIT",
+  devServerPidFiles: [".local-data/dev-server.pid"],
+  configFiles: [
+    {
+      path: ".env",
+      patch: (content, { ports }) =>
+        helpers.patchEnvFile(content, {
+          PORT: String(ports.frontend),
+          SERVER_PORT: String(ports.server),
+        }),
+    },
+  ],
+  provisionDatabase: async () => {},
+  installAndBuild: async () => {},
+  printSummary: ({ slot, branch, owner, ports }) =>
+    `Slot ${slot} (${branch}, ${owner}) — server :${ports.server}`,
+});
+```
+
+```ts
+import { runDevServer } from "@paleo/worktree-env";
+
+await runDevServer({
+  basePort: 8100,
+  devLimitEnvVar: "MYAPP_DEV_LIMIT",
+  servers: [
+    {
+      name: "dev",
+      command: "npm",
+      args: ["run", "dev"],
+      pidFile: ".local-data/dev-server.pid",
+      logFile: ".local-data/logs/dev-server.log",
+      detectSuccess: (log) => log.includes("Server is ready on port"),
+      portConfig: { file: ".env", var: "PORT" },
+    },
+  ],
+  printSummary: ({ slot, servers }) =>
+    `Dev servers started in slot ${slot.slot} (${slot.owner}): ${servers
+      .map((s) => `${s.server.name} :${s.port} (PID ${s.pid})`)
+      .join(", ")}`,
+});
+```
+
+## Build / test
+
+```sh
+npm install
+npm run build
+npm test
+```

package/dist/cli.d.ts

@@ -0,0 +1,29 @@
+export interface SetupArgs {
+    help?: boolean;
+    use?: string;
+    create?: string;
+    self?: boolean;
+    owner?: string;
+    "set-owner"?: string;
+    remove?: string;
+    "remove-self"?: boolean;
+    "no-remote-check"?: boolean;
+    slot?: string;
+    force?: boolean;
+    verbose?: boolean;
+}
+export interface DevServerArgs {
+    help?: boolean;
+    stop?: boolean;
+    list?: boolean;
+    all?: boolean;
+}
+export declare function parseSetupArgs(argv?: string[]): SetupArgs;
+export declare function parseDevServerArgs(argv?: string[]): DevServerArgs;
+export declare function printSetupHelp(): void;
+export declare function printDevServerHelp(): void;
+export declare function isSetupMode(args: SetupArgs): boolean;
+export declare function isRemoveMode(args: SetupArgs): boolean;
+export declare function isSetOwnerMode(args: SetupArgs): boolean;
+export declare function validateSetupFlags(args: SetupArgs): void;
+export declare function validateDevServerFlags(args: DevServerArgs): void;

package/dist/cli.js

@@ -0,0 +1,129 @@
+import { parseArgs } from "node:util";
+import { ConfigError } from "./errors.js";
+const SETUP_OPTIONS = {
+    help: { type: "boolean", short: "h", description: "Show this help message" },
+    use: {
+        type: "string",
+        arg: "branch",
+        description: "Create a worktree for an existing branch, then set up the local environment",
+    },
+    create: {
+        type: "string",
+        arg: "branch",
+        description: "Create a new branch + worktree, then set up the local environment. If the branch already exists, appends a numeric suffix (-2, -3, ...)",
+    },
+    self: {
+        type: "boolean",
+        description: "Set up the local environment in the current linked worktree",
+    },
+    owner: {
+        type: "string",
+        arg: "name",
+        description: 'Owner of the slot (free-form label, defaults to "default")',
+    },
+    "set-owner": {
+        type: "string",
+        arg: "name",
+        description: "Update the owner of the current linked worktree's slot (no rebuild)",
+    },
+    remove: {
+        type: "string",
+        arg: "branch",
+        description: "Remove a worktree by branch name (stop dev server, free slot, delete directory)",
+    },
+    "remove-self": {
+        type: "boolean",
+        description: "Remove the current linked worktree (same as --remove, but for the worktree you are in)",
+    },
+    "no-remote-check": {
+        type: "boolean",
+        description: "Skip remote branch verification when removing (use with --remove or --remove-self)",
+    },
+    slot: {
+        type: "string",
+        short: "s",
+        arg: "port",
+        description: "Use a specific slot instead of auto-assigning",
+    },
+    force: {
+        type: "boolean",
+        description: "Overwrite existing config files and re-provision the database",
+    },
+    verbose: { type: "boolean", short: "v", description: "Show intermediate output" },
+};
+const DEV_SERVER_OPTIONS = {
+    help: { type: "boolean", short: "h", description: "Show this help message" },
+    stop: { type: "boolean", description: "Stop dev servers in the current worktree" },
+    list: { type: "boolean", description: "List active dev-servers across all worktrees" },
+    all: { type: "boolean", description: "Apply --stop to every active dev-server" },
+};
+function parseOptions(argv, options) {
+    const cfg = { options: options, strict: true };
+    if (argv)
+        cfg.args = argv;
+    const { values } = parseArgs(cfg);
+    return values;
+}
+export function parseSetupArgs(argv) {
+    return parseOptions(argv, SETUP_OPTIONS);
+}
+export function parseDevServerArgs(argv) {
+    return parseOptions(argv, DEV_SERVER_OPTIONS);
+}
+function formatHelp(usage, intro, options) {
+    const lines = [`Usage: ${usage}`, "", intro, ""];
+    for (const [name, opt] of Object.entries(options)) {
+        const shortFlag = opt.short ? `-${opt.short}, ` : "";
+        const argSuffix = opt.arg ? ` <${opt.arg}>` : "";
+        const flag = `${shortFlag}--${name}${argSuffix}`;
+        lines.push(`  ${flag.padEnd(28)} ${opt.description}`);
+    }
+    return lines.join("\n");
+}
+export function printSetupHelp() {
+    console.log(formatHelp("setup-worktree [options]", "Manage worktree lifecycle: creation, local environment setup, and removal.", SETUP_OPTIONS));
+}
+export function printDevServerHelp() {
+    console.log(formatHelp("dev-server [options]", "Start, stop, or list background dev-server processes.", DEV_SERVER_OPTIONS));
+}
+export function isSetupMode(args) {
+    return args.use !== undefined || args.create !== undefined || Boolean(args.self);
+}
+export function isRemoveMode(args) {
+    return args.remove !== undefined || Boolean(args["remove-self"]);
+}
+export function isSetOwnerMode(args) {
+    return args["set-owner"] !== undefined;
+}
+export function validateSetupFlags(args) {
+    const modeFlags = [
+        args.use,
+        args.create,
+        args.self,
+        isRemoveMode(args),
+        isSetOwnerMode(args),
+    ].filter(Boolean);
+    if (modeFlags.length > 1) {
+        throw new ConfigError("Error: --use, --create, --self, --remove, --remove-self, and --set-owner are mutually exclusive.");
+    }
+    if (args.remove !== undefined && args["remove-self"]) {
+        throw new ConfigError("Error: --remove and --remove-self are mutually exclusive.");
+    }
+    if ((args.slot !== undefined || args.force) && !isSetupMode(args)) {
+        throw new ConfigError("Error: --slot and --force can only be used with --use, --create, or --self.");
+    }
+    if (args.owner !== undefined && !isSetupMode(args)) {
+        throw new ConfigError("Error: --owner is only valid with --use, --create, or --self.");
+    }
+    if (args["no-remote-check"] && !isRemoveMode(args)) {
+        throw new ConfigError("Error: --no-remote-check is only valid with --remove or --remove-self.");
+    }
+}
+export function validateDevServerFlags(args) {
+    if (args.all && !args.stop) {
+        throw new ConfigError("Error: --all requires --stop.");
+    }
+    if (args.list && (args.stop || args.all)) {
+        throw new ConfigError("Error: --list is mutually exclusive with --stop and --all.");
+    }
+}

package/dist/dev-limit.d.ts

@@ -0,0 +1,6 @@
+export interface ReadDevLimitOptions {
+    projectVar: string;
+    defaultLimit?: number;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function readDevLimit(opts: ReadDevLimitOptions): number;

package/dist/dev-limit.js

@@ -0,0 +1,13 @@
+export function readDevLimit(opts) {
+    const env = opts.env ?? process.env;
+    const defaultLimit = opts.defaultLimit ?? 5;
+    const candidates = [env[opts.projectVar], env.PROJECT_DEV_LIMIT];
+    for (const raw of candidates) {
+        if (raw === undefined || raw === "")
+            continue;
+        const parsed = Number(raw);
+        if (Number.isInteger(parsed) && parsed >= 0)
+            return parsed;
+    }
+    return defaultLimit;
+}

package/dist/dev-server.d.ts

@@ -0,0 +1,35 @@
+import { type ResolvedSlot } from "./slots.js";
+export type PortConfig = {
+    file: string;
+    var: string;
+} | {
+    file: string;
+    jsonPath: string;
+};
+export interface DevServerConfig {
+    basePort: number;
+    devLimitEnvVar: string;
+    defaultLimit?: number;
+    servers: ServerDescriptor[];
+    ensureInfrastructure?: () => Promise<void> | void;
+    printSummary?: (ctx: DevServerSummaryContext) => string;
+}
+export interface ServerDescriptor {
+    name: string;
+    command: string;
+    args: string[];
+    pidFile: string;
+    logFile: string;
+    detectSuccess: (logContent: string) => boolean;
+    detectError?: (logContent: string) => string | false;
+    portConfig: PortConfig;
+}
+export interface DevServerSummaryContext {
+    slot: ResolvedSlot;
+    servers: {
+        server: ServerDescriptor;
+        port: number;
+        pid: number;
+    }[];
+}
+export declare function runDevServer(config: DevServerConfig): Promise<void>;

package/dist/dev-server.js

@@ -0,0 +1,234 @@
+import { spawn } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { createConnection } from "node:net";
+import { dirname, join } from "node:path";
+import { parseDevServerArgs, printDevServerHelp, validateDevServerFlags, } from "./cli.js";
+import { readDevLimit } from "./dev-limit.js";
+import { listDevServers, printActiveServers, pruneAndPersist, registerDevServer, 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 { resolveCurrentSlot } from "./slots.js";
+import { detectWorktree } from "./worktree.js";
+function readEnvFileVar(filePath, varName) {
+    const content = readFileSync(filePath, "utf-8");
+    const match = content.match(new RegExp(`^${varName}=(.+)`, "m"));
+    if (!match) {
+        console.error(`Error: ${varName} not found in ${filePath}.`);
+        process.exit(1);
+    }
+    return match[1].trim();
+}
+function readJsonPath(filePath, jsonPath) {
+    const content = readFileSync(filePath, "utf-8");
+    const data = JSON.parse(content);
+    const segments = jsonPath.split(".");
+    let cur = data;
+    for (const seg of segments) {
+        if (cur === null || cur === undefined || typeof cur !== "object") {
+            console.error(`Error: ${jsonPath} not found in ${filePath}.`);
+            process.exit(1);
+        }
+        cur = cur[seg];
+    }
+    if (cur === undefined || cur === null) {
+        console.error(`Error: ${jsonPath} not found in ${filePath}.`);
+        process.exit(1);
+    }
+    return String(cur);
+}
+function readPortFromConfig(portConfig) {
+    if (!existsSync(portConfig.file)) {
+        console.error(`Error: ${portConfig.file} not found. Run setup-worktree first.`);
+        process.exit(1);
+    }
+    const raw = "var" in portConfig
+        ? readEnvFileVar(portConfig.file, portConfig.var)
+        : readJsonPath(portConfig.file, portConfig.jsonPath);
+    const port = Number(raw);
+    if (!Number.isFinite(port)) {
+        console.error(`Error: invalid port "${raw}" in ${portConfig.file}.`);
+        process.exit(1);
+    }
+    return port;
+}
+function isPortBusy(port) {
+    return new Promise((resolve) => {
+        const socket = createConnection({ port, host: "127.0.0.1" });
+        socket.setTimeout(500);
+        socket.once("connect", () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.once("timeout", () => {
+            socket.destroy();
+            resolve(false);
+        });
+        socket.once("error", () => {
+            resolve(false);
+        });
+    });
+}
+function spawnServer(server) {
+    mkdirSync(dirname(server.logFile), { recursive: true });
+    mkdirSync(dirname(server.pidFile), { recursive: true });
+    const logFd = openSync(server.logFile, "w");
+    const child = spawn(server.command, server.args, {
+        detached: true,
+        stdio: ["ignore", logFd, logFd],
+    });
+    if (child.pid === undefined) {
+        closeSync(logFd);
+        console.error(`Error: failed to spawn ${server.name}.`);
+        process.exit(1);
+    }
+    writeFileSync(server.pidFile, String(child.pid));
+    child.unref();
+    closeSync(logFd);
+    return child.pid;
+}
+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);
+        return;
+    }
+    if (args.stop && args.all) {
+        await stopAllRegistered({
+            mainWorktree,
+            pidFiles: config.servers.map((s) => s.pidFile),
+        });
+        return;
+    }
+    if (args.stop) {
+        await stopLocal(config, mainWorktree);
+        return;
+    }
+    await start(config, mainWorktree);
+}
+async function start(config, mainWorktree) {
+    const limit = readDevLimit({
+        projectVar: config.devLimitEnvVar,
+        defaultLimit: config.defaultLimit,
+    });
+    const active = pruneAndPersist(mainWorktree).servers;
+    if (limit > 0 && active.length >= limit) {
+        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`.");
+        process.exit(1);
+    }
+    const serverPorts = config.servers.map((server) => [
+        server,
+        readPortFromConfig(server.portConfig),
+    ]);
+    const busyResults = await Promise.all(serverPorts.map(([, port]) => isPortBusy(port)));
+    let anyBusy = false;
+    busyResults.forEach((busy, i) => {
+        if (busy) {
+            const [server, port] = serverPorts[i];
+            console.error(`Error: Port ${port} (${server.name}) is already in use.`);
+            anyBusy = true;
+        }
+    });
+    if (anyBusy)
+        process.exit(1);
+    for (const server of config.servers) {
+        const existingPid = readPid(server.pidFile);
+        if (existingPid !== undefined && isProcessAlive(existingPid)) {
+            console.error(`Error: ${server.name} is already running (PID ${existingPid}).`);
+            process.exit(1);
+        }
+        cleanupPidFile(server.pidFile);
+    }
+    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));
+    }
+    try {
+        const pollables = config.servers.map((s) => ({
+            name: s.name,
+            logFile: s.logFile,
+            detectSuccess: s.detectSuccess,
+            detectError: s.detectError,
+        }));
+        await awaitAllReady(pollables, pids);
+    }
+    catch (err) {
+        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);
+    const pidMap = {};
+    config.servers.forEach((server, i) => {
+        pidMap[server.name] = pids[i];
+    });
+    registerDevServer(mainWorktree, {
+        slot: slot.slot,
+        worktree: slot.worktree,
+        branch: slot.branch,
+        owner: slot.owner,
+        pids: pidMap,
+        startedAt: new Date().toISOString(),
+    });
+    if (config.printSummary) {
+        console.log(config.printSummary({
+            slot,
+            servers: config.servers.map((server, i) => ({
+                server,
+                port: serverPorts[i][1],
+                pid: pids[i],
+            })),
+        }));
+    }
+    else {
+        defaultPrintSummary(slot, config.servers, serverPorts.map(([, p]) => p), pids);
+    }
+}
+function defaultPrintSummary(slot, servers, ports, pids) {
+    console.log("\nDev servers started!");
+    console.log(`  Worktree: slot ${slot.slot}, owner ${slot.owner}`);
+    servers.forEach((server, i) => {
+        const url = `http://localhost:${ports[i]}/`;
+        const logPath = join(process.cwd(), server.logFile);
+        console.log(`  ${server.name}: ${url}  (PID ${pids[i]})`);
+        console.log(`    log: ${logPath}`);
+    });
+    console.log("");
+}
+async function stopLocal(config, mainWorktree) {
+    for (const server of config.servers) {
+        await stopByPidFile(server.pidFile, server.name, (msg) => console.log(msg));
+    }
+    unregisterDevServer(mainWorktree, process.cwd());
+}

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

@@ -0,0 +1,28 @@
+export declare const DEV_SERVERS_FILE = ".local/worktrees/dev-servers.json";
+export declare const WORKTREES_DIR = ".local/worktrees";
+export interface DevServerEntry {
+    slot: number;
+    worktree: string;
+    branch: string;
+    owner: string;
+    pids: Record<string, number>;
+    startedAt: string;
+}
+export interface DevServersData {
+    servers: DevServerEntry[];
+}
+export declare function readDevServers(mainWorktree: string): DevServersData;
+export declare function writeDevServers(mainWorktree: string, data: DevServersData): void;
+export type IsAliveFn = (pid: number) => boolean;
+export declare function pruneDeadServers(data: DevServersData, isAlive?: IsAliveFn): DevServersData;
+export declare function pruneAndPersist(mainWorktree: string, isAlive?: IsAliveFn): DevServersData;
+export declare function registerDevServer(mainWorktree: string, entry: DevServerEntry): void;
+export declare function unregisterDevServer(mainWorktree: string, worktreePath: string): void;
+export declare function removeDevServerEntryByWorktree(mainWorktree: string, worktreePath: string): void;
+export declare function printActiveServers(active: DevServerEntry[]): void;
+export declare function listDevServers(mainWorktree: string): void;
+export interface StopAllInput {
+    mainWorktree: string;
+    pidFiles: string[];
+}
+export declare function stopAllRegistered(input: StopAllInput): Promise<void>;

package/dist/dev-servers-registry.js

@@ -0,0 +1,104 @@
+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(",");
+    return `  slot ${entry.slot}  branch=${entry.branch}  owner=${entry.owner}  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);
+    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 async function stopAllRegistered(input) {
+    const data = pruneAndPersist(input.mainWorktree);
+    if (data.servers.length === 0) {
+        console.log("No dev-servers running.");
+        return;
+    }
+    for (const entry of data.servers) {
+        console.log(`Stopping slot ${entry.slot} (${entry.branch}, owner=${entry.owner})...`);
+        for (const [name, pid] of Object.entries(entry.pids)) {
+            if (!isProcessAlive(pid))
+                continue;
+            console.log(`  ${name} (PID ${pid})`);
+            await stopProcessGroup(pid);
+        }
+        for (const pidFile of input.pidFiles) {
+            const fp = join(entry.worktree, pidFile);
+            if (existsSync(fp))
+                unlinkSync(fp);
+        }
+    }
+    writeDevServers(input.mainWorktree, { servers: [] });
+    console.log(`Stopped ${data.servers.length} dev-server(s).`);
+}

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+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);
+}
+export declare function exitWith(code: number, message: string): never;