@paleo/workspace 0.11.0

package/dist/helpers.js

@@ -0,0 +1,141 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export function patchEnvFile(content, patches) {
+    const lines = content.trimEnd().split("\n");
+    for (const [key, value] of Object.entries(patches)) {
+        const idx = lines.findIndex((l) => l.startsWith(`${key}=`));
+        if (idx !== -1) {
+            lines[idx] = `${key}=${value}`;
+        }
+        else {
+            lines.push(`${key}=${value}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function extractHost(content, key, fallback = "localhost") {
+    const re = new RegExp(`^${key}=(?:https?://)?([^:\\s]+)`, "m");
+    const m = content.match(re);
+    return m ? m[1] : fallback;
+}
+/**
+ * Reads `<varName>=<value>` from a dotenv-style file and parses it as a port.
+ * Exits with code 1 on missing file, missing variable, or non-numeric value.
+ */
+export function readPortFromEnvFile(file, varName) {
+    if (!existsSync(file)) {
+        console.error(`Error: ${file} not found. Run \`workspace setup\` first.`);
+        process.exit(1);
+    }
+    const content = readFileSync(file, "utf-8");
+    const match = content.match(new RegExp(`^${varName}=(.+)`, "m"));
+    if (!match) {
+        console.error(`Error: ${varName} not found in ${file}.`);
+        process.exit(1);
+    }
+    return toPort(match[1].trim(), file);
+}
+/**
+ * Reads a dotted path (e.g. `server.port`) from a JSON file and parses it as a port.
+ * Exits with code 1 on missing file, missing path, or non-numeric value.
+ */
+export function readPortFromJsonFile(file, jsonPath) {
+    if (!existsSync(file)) {
+        console.error(`Error: ${file} not found. Run \`workspace setup\` first.`);
+        process.exit(1);
+    }
+    const data = JSON.parse(readFileSync(file, "utf-8"));
+    let cur = data;
+    for (const seg of jsonPath.split(".")) {
+        if (cur === null || cur === undefined || typeof cur !== "object") {
+            console.error(`Error: ${jsonPath} not found in ${file}.`);
+            process.exit(1);
+        }
+        cur = cur[seg];
+    }
+    if (cur === undefined || cur === null) {
+        console.error(`Error: ${jsonPath} not found in ${file}.`);
+        process.exit(1);
+    }
+    return toPort(String(cur), file);
+}
+export function copyAndPatchFile(ctx, relPath, patchFn, label, force, optional = false) {
+    const targetPath = join(ctx.currentWorktree, relPath);
+    const sourcePath = join(ctx.mainWorktree, relPath);
+    const alreadyExists = existsSync(targetPath);
+    if (alreadyExists && !force) {
+        ctx.log(`Skipped ${label} (already exists; use --force to overwrite).`);
+        return;
+    }
+    if (!existsSync(sourcePath)) {
+        if (!optional) {
+            console.error(`Error: ${relPath} not found in main worktree. Bootstrap the main worktree first ` +
+                "(`workspace setup`), or mark the entry as optional.");
+            process.exit(1);
+        }
+        ctx.log(`Warning: ${relPath} not found in main worktree, skipping (optional).`);
+        return;
+    }
+    const content = readFileSync(sourcePath, "utf-8");
+    const patched = patchFn(content);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, patched);
+    ctx.log(`${alreadyExists ? "Overwritten" : "Created"} ${label}.`);
+}
+/**
+ * Detects common fatal JS startup failures in a log buffer. Returns a short marker string
+ * naming the matched pattern, or `false` when none match. Used as the default `detectError`
+ * for spawn servers that don't supply one. A custom `detectError` can compose with this:
+ * `detectError: (log) => myDetector(log) || helpers.detectCommonJsError(log)`.
+ */
+/**
+ * Formats a millisecond duration as the two largest units among `d`/`h`/`m`/`s`.
+ * Drops the smaller unit when zero (`5d` instead of `5d 0h`). Sub-second values
+ * round up to `1s` (zero stays `0s`). Negative input returns `0s`.
+ */
+export function formatDuration(ms) {
+    if (ms <= 0)
+        return "0s";
+    if (ms < 1000)
+        return "1s";
+    const totalSec = Math.floor(ms / 1000);
+    const d = Math.floor(totalSec / 86400);
+    const h = Math.floor((totalSec % 86400) / 3600);
+    const m = Math.floor((totalSec % 3600) / 60);
+    const s = totalSec % 60;
+    const units = [
+        ["d", d],
+        ["h", h],
+        ["m", m],
+        ["s", s],
+    ];
+    const topIdx = units.findIndex(([, v]) => v > 0);
+    if (topIdx === -1)
+        return "0s";
+    const [topLabel, topVal] = units[topIdx];
+    const next = units[topIdx + 1];
+    if (!next || next[1] === 0)
+        return `${topVal}${topLabel}`;
+    return `${topVal}${topLabel} ${next[1]}${next[0]}`;
+}
+export function detectCommonJsError(log) {
+    if (log.includes("[nodemon] app crashed"))
+        return "[nodemon] app crashed";
+    if (/^Node\.js v/m.test(log))
+        return "Node.js v";
+    if (log.includes("Error: Cannot find module "))
+        return "Error: Cannot find module";
+    if (/^SyntaxError: /m.test(log))
+        return "SyntaxError";
+    if (log.includes("UnhandledPromiseRejection"))
+        return "UnhandledPromiseRejection";
+    return false;
+}
+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/index.d.ts

@@ -0,0 +1,10 @@
+export { runWorkspace } from "./workspace.js";
+export { defaultWorktreeDirName } from "./worktree.js";
+export type { WorktreeDirNameFn } from "./worktree.js";
+export type { WorkspaceConfig, SetupContext, SummaryContext, PatchContext, ConfigFileEntry, PurgeContext, } from "./workspace.js";
+export { runDevServer } 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 };
+export { StartupError, ConfigError } from "./errors.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { runWorkspace } from "./workspace.js";
+export { defaultWorktreeDirName } from "./worktree.js";
+export { runDevServer } from "./dev-server.js";
+import * as helpers from "./helpers.js";
+export { helpers };
+export { StartupError, ConfigError } from "./errors.js";

package/dist/log-polling.d.ts

@@ -0,0 +1,17 @@
+import { StartupError } from "./errors.js";
+export declare const LOG_TAIL_LINES = 30;
+export declare const POLL_INTERVAL_MS = 500;
+export declare const TIMEOUT_MS = 120000;
+export interface PollableServer {
+    name: string;
+    logFile: string;
+    detectSuccess: (logContent: string) => boolean;
+    detectError?: (logContent: string) => string | false;
+}
+export interface AwaitOptions {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    isAlive?: (pid: number) => boolean;
+}
+export declare function awaitAllReady(servers: PollableServer[], pids: number[], options?: AwaitOptions): Promise<void>;
+export declare function handleStartupFailure(err: StartupError): void;

package/dist/log-polling.js

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { StartupError } from "./errors.js";
+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 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;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!isAlive(pid)) {
+            throw new StartupError(server.name, "process exited unexpectedly", server.logFile);
+        }
+        if (existsSync(server.logFile)) {
+            const logContent = readFileSync(server.logFile, "utf-8");
+            if (server.detectSuccess(logContent))
+                return;
+            const matched = server.detectError?.(logContent);
+            if (matched) {
+                throw new StartupError(server.name, `error detected (${matched})`, server.logFile);
+            }
+        }
+        await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+    throw new StartupError(server.name, `did not become ready within ${timeoutMs / 1000}s`, server.logFile);
+}

package/dist/port-holder.d.ts

@@ -0,0 +1,25 @@
+import type { ServerDescriptor, SpawnServer } from "./server-descriptor.js";
+export interface PortHolder {
+    pid: number;
+    /** Process group id. Absent when `ps` output couldn't be parsed; callers must skip group kills. */
+    pgid?: number;
+    cmd: string;
+    cwd?: string;
+}
+export type PortConflict = {
+    kind: "ours";
+    server: SpawnServer;
+    holder: PortHolder;
+} | {
+    kind: "foreign";
+    server: SpawnServer;
+    holder?: PortHolder;
+};
+export declare function canonicalCwd(cwd: string): string;
+export declare function findPortHolder(port: number): PortHolder | undefined;
+export declare function isPidOurs(holder: PortHolder, ourCanonicalCwd: string): boolean;
+export declare function isPortBusy(port: number): Promise<boolean>;
+export declare function detectPortConflicts(servers: ServerDescriptor[], ourCanonicalCwd: string): Promise<PortConflict[]>;
+/** Polls the given ports until all are free or `timeoutMs` elapses. Returns ports still busy. */
+export declare function waitForPortsFree(ports: number[], timeoutMs: number): Promise<number[]>;
+export declare function sweepStalePorts(servers: ServerDescriptor[], cwd: string): Promise<void>;

package/dist/port-holder.js

@@ -0,0 +1,147 @@
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { createConnection } from "node:net";
+import { platform } from "node:os";
+import { stopProcessGroup } from "./process-control.js";
+export function canonicalCwd(cwd) {
+    try {
+        return realpathSync(cwd);
+    }
+    catch {
+        return cwd;
+    }
+}
+export function findPortHolder(port) {
+    if (platform() === "win32")
+        return;
+    const pid = listenerPid(port);
+    if (pid === undefined)
+        return;
+    const psInfo = pidPgidAndCommand(pid);
+    const cwd = pidCwd(pid);
+    return { pid, pgid: psInfo?.pgid, cmd: psInfo?.cmd ?? "", cwd };
+}
+export function isPidOurs(holder, ourCanonicalCwd) {
+    if (holder.cwd === undefined)
+        return false;
+    const holderCwd = canonicalCwd(holder.cwd);
+    return holderCwd === ourCanonicalCwd || holderCwd.startsWith(`${ourCanonicalCwd}/`);
+}
+export 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", () => {
+            socket.destroy();
+            resolve(false);
+        });
+    });
+}
+export async function detectPortConflicts(servers, ourCanonicalCwd) {
+    const conflicts = [];
+    for (const server of spawnServersOf(servers)) {
+        if (!(await isPortBusy(server.port)))
+            continue;
+        const holder = findPortHolder(server.port);
+        if (holder && isPidOurs(holder, ourCanonicalCwd)) {
+            conflicts.push({ kind: "ours", server, holder });
+        }
+        else {
+            conflicts.push({ kind: "foreign", server, holder });
+        }
+    }
+    return conflicts;
+}
+/** Polls the given ports until all are free or `timeoutMs` elapses. Returns ports still busy. */
+export async function waitForPortsFree(ports, timeoutMs) {
+    const intervalMs = 100;
+    const deadline = Date.now() + timeoutMs;
+    let pending = [...ports];
+    while (pending.length > 0) {
+        const results = await Promise.all(pending.map(async (p) => ({ p, busy: await isPortBusy(p) })));
+        pending = results.filter((r) => r.busy).map((r) => r.p);
+        if (pending.length === 0 || Date.now() >= deadline)
+            break;
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+    return pending;
+}
+export async function sweepStalePorts(servers, cwd) {
+    if (platform() === "win32")
+        return;
+    const ourCwd = canonicalCwd(cwd);
+    for (const server of spawnServersOf(servers)) {
+        await sweepOnePort(server, ourCwd);
+    }
+}
+function spawnServersOf(servers) {
+    return servers.filter((s) => s.kind === "spawn");
+}
+async function sweepOnePort(server, ourCanonicalCwd) {
+    const holder = findPortHolder(server.port);
+    if (holder === undefined)
+        return;
+    if (isPidOurs(holder, ourCanonicalCwd)) {
+        if (holder.pgid === undefined) {
+            console.warn(`Leaked ${server.name} on port ${server.port} (PID ${holder.pid}: ${holder.cmd}); pgid unknown, left untouched.`);
+            return;
+        }
+        console.warn(`Sweeping leaked ${server.name} on port ${server.port} (PID ${holder.pid}: ${holder.cmd}).`);
+        await stopProcessGroup(holder.pgid);
+    }
+    else {
+        const cwdPart = holder.cwd ? ` (cwd ${holder.cwd})` : "";
+        console.warn(`Port ${server.port} (${server.name}) still in use by PID ${holder.pid}: ${holder.cmd}${cwdPart}. Left untouched.`);
+    }
+}
+function listenerPid(port) {
+    if (!Number.isInteger(port) || port <= 0)
+        return;
+    const out = tryExec("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"]);
+    if (out === undefined)
+        return;
+    const trimmed = out.trim();
+    if (trimmed === "")
+        return;
+    const pid = Number(trimmed.split(/\s+/)[0]);
+    return Number.isFinite(pid) ? pid : undefined;
+}
+function pidPgidAndCommand(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return;
+    const out = tryExec("ps", ["-p", String(pid), "-o", "pgid=,command="]);
+    if (out === undefined)
+        return;
+    const match = out.trim().match(/^(\d+)\s+(.+)$/);
+    if (match === null)
+        return;
+    const parsed = Number(match[1]);
+    if (!Number.isFinite(parsed))
+        return;
+    return { pgid: parsed, cmd: match[2] };
+}
+function pidCwd(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return;
+    const out = tryExec("lsof", ["-p", String(pid), "-a", "-d", "cwd", "-Fn"]);
+    if (out === undefined)
+        return;
+    const match = out.match(/^n(.+)$/m);
+    return match === null ? undefined : match[1];
+}
+function tryExec(file, args) {
+    try {
+        return execFileSync(file, args, { stdio: ["ignore", "pipe", "ignore"] }).toString();
+    }
+    catch {
+        return;
+    }
+}

package/dist/ports.d.ts

@@ -0,0 +1,16 @@
+export interface PortScheme {
+    basePort: number;
+    portStep: number;
+    maxSlotCount: number;
+    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[];
+export declare function defaultComputePorts(portNames: string[]): (slot: number) => Record<string, number>;

package/dist/ports.js

@@ -0,0 +1,37 @@
+export function resolvePortScheme(opts) {
+    const portStep = opts.portStep ?? 10;
+    const maxSlotCount = opts.maxSlotCount ?? 19;
+    const basePort = opts.basePort;
+    return {
+        basePort,
+        portStep,
+        maxSlotCount,
+        minPort: basePort + portStep,
+        maxPort: basePort + maxSlotCount * portStep,
+    };
+}
+export function isValidPort(port, scheme) {
+    return (Number.isInteger(port) &&
+        port >= scheme.minPort &&
+        port <= scheme.maxPort &&
+        (port - scheme.basePort) % scheme.portStep === 0);
+}
+export function allPorts(scheme) {
+    const ports = [];
+    for (let p = scheme.minPort; p <= scheme.maxPort; p += scheme.portStep) {
+        ports.push(p);
+    }
+    return ports;
+}
+export function defaultComputePorts(portNames) {
+    if (portNames.length === 0) {
+        throw new Error("portNames must not be empty");
+    }
+    return (slot) => {
+        const out = {};
+        portNames.forEach((name, i) => {
+            out[name] = slot + i;
+        });
+        return out;
+    };
+}

package/dist/process-control.d.ts

@@ -0,0 +1,4 @@
+export declare function stopProcessGroup(pid: number, timeoutMs?: number): Promise<void>;
+export declare function isProcessAlive(pid: number): boolean;
+export declare function isProcessGroupAlive(pid: number): boolean;
+export declare function killProcessGroup(pid: number, signal: NodeJS.Signals): void;

package/dist/process-control.js

@@ -0,0 +1,41 @@
+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 isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function isProcessGroupAlive(pid) {
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function killProcessGroup(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            // already dead
+        }
+    }
+}

package/dist/server-descriptor.d.ts

@@ -0,0 +1,45 @@
+/** 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`.
+     * When omitted, `helpers.detectCommonJsError` is used as a default. To disable detection,
+     * pass `() => 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/slots.d.ts

@@ -0,0 +1,63 @@
+import { type PortScheme } from "./ports.js";
+export interface ResolvedSlot {
+    slot: number;
+    worktree: string;
+    owner?: string;
+    /** `true` when this slot is the main worktree. */
+    main?: boolean;
+}
+export type SlotStatus = "pending" | "ready" | "failed";
+export interface SlotEntry {
+    worktree: string;
+    owner?: string;
+    createdAt: string;
+    status: SlotStatus;
+    failure?: {
+        at: string;
+        message: string;
+    };
+    /** `true` for the main-worktree entry. Absent on linked entries. */
+    main?: boolean;
+}
+export interface SlotsRegistry {
+    slots: Record<string, SlotEntry>;
+}
+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;
+    requestedOwner?: string;
+    /** When `true`, the slot is forced to `scheme.basePort` regardless of `slot` arg. */
+    isMainWorktree: boolean;
+    /** When `true`, an existing `ready` slot is reset to `pending` so the re-finalize is observable. */
+    force?: boolean;
+}
+export declare function resolveAndRegisterSlot(input: RegisterSlotInput): {
+    port: number;
+    owner: string | undefined;
+    status: SlotStatus;
+};
+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 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): {
+    slotPort: string;
+    owner: string | undefined;
+};