@paleo/workspace 0.14.1 → 0.15.0

package/README.md

@@ -27,7 +27,7 @@ The agent reads the skill, adapts the reference scripts to your stack, installs
 
 ```sh
 npm run workspace -- setup feat/42 -c   # new branch + worktree + isolated env
-npm run dev                             # start in the foreground; holds the terminal, stops on CTRL+C
+npm run dev                             # foreground: stream logs from startup, CTRL+C stops; attaches if already running (CTRL+C then detaches)
 npm run dev -- up                       # start in the background (no-op if already running here)
 npm run dev -- up --restart             # stop the dev-server in this worktree if running, then start fresh
 npm run dev -- up --evict               # if devLimit is reached, evict the oldest dev-server and start

package/dist/cli.js

@@ -182,6 +182,7 @@ export function printWorkspaceHelp() {
         "",
         "Global options:",
         "  -v, --verbose   Show intermediate output.",
+        "  -h, --help      Show this help message.",
     ].join("\n"));
 }
 export function parseDevArgs(argv = process.argv.slice(2)) {
@@ -285,13 +286,15 @@ export function printDevHelp() {
         "Start, stop, or list dev-server processes for worktree-based environments.",
         "",
         "Commands:",
-        "  dev               Start in the foreground; holds the terminal, stops on CTRL+C.",
+        "  dev               Start in the foreground, streaming logs from startup; CTRL+C stops it.",
+        "                    If one is already running here, attach to its logs instead",
+        "                    (CTRL+C then detaches, leaving it running).",
         "  dev up            Start in the background and return once ready.",
         "  dev restart       Stop this worktree's dev-server if running, then start in the background.",
         "  dev down [--all]  Stop this worktree's dev-server, or every dev-server with --all.",
         "  dev list          List active dev-servers across all worktrees.",
         "  dev status        Report whether this worktree's dev-server is UP or DOWN.",
-        "  dev --help        Show this help message.",
+        "  dev --help        Show this help message (alias: -h).",
         "",
         "Options (dev, dev up, dev restart):",
         "  --evict     Evict the oldest dev-server when the cap is reached.",

package/dist/dev-server.js

@@ -1,11 +1,11 @@
 import { spawn } from "node:child_process";
-import { closeSync, existsSync, mkdirSync, openSync, readSync, statSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { parseDevArgs, printDevHelp } from "./cli.js";
 import { evictOldest, findOwnEntry, listDevServers, printActiveServers, pruneAndPersist, registerDevServer, removeDevServerEntryByWorktree, stopAllRegistered, unregisterDevServer, } from "./dev-servers-registry.js";
 import { ConfigError, StartupError } from "./errors.js";
-import { detectCommonJsError, formatDuration, setupLogPath } from "./helpers.js";
-import { awaitAllReady, handleStartupFailure } from "./log-polling.js";
+import { detectCommonJsError, formatDuration, lastLines, setupLogPath } from "./helpers.js";
+import { awaitAllReady, handleStartupFailure, LOG_TAIL_LINES, } from "./log-polling.js";
 import { canonicalCwd, detectPortConflicts, sweepStalePorts, waitForPortsFree, } from "./port-holder.js";
 import { isProcessAlive, stopProcessGroup } from "./process-control.js";
 import { readSlots, resolveCurrentSlot } from "./slots.js";
@@ -82,17 +82,7 @@ async function start(config, mainWorktree, options) {
     if (await runStartChecks(config, mainWorktree, ctx, options))
         return;
     const state = { spawnPids: {}, startedCallbacks: [] };
-    try {
-        await spawnAndAwait(config, ctx, state);
-    }
-    catch (err) {
-        await rollbackStart(state.spawnPids, state.startedCallbacks, ctx);
-        if (err instanceof StartupError) {
-            handleStartupFailure(err);
-            process.exit(1);
-        }
-        throw err;
-    }
+    await spawnWithRollback(config, ctx, state);
     const slot = registerStartedServer(config, mainWorktree, state.spawnPids);
     printStartSummary(config, slot, state.spawnPids);
 }
@@ -103,6 +93,11 @@ async function start(config, mainWorktree, options) {
  */
 async function runForeground(config, mainWorktree, options) {
     const ctx = { cwd: process.cwd() };
+    if (!options.restart) {
+        const running = findOwnLiveEntry(config, mainWorktree, ctx.cwd);
+        if (running)
+            return attachForeground(config, running);
+    }
     const state = { spawnPids: {}, startedCallbacks: [] };
     let started = false;
     let shuttingDown = false;
@@ -121,21 +116,16 @@ async function runForeground(config, mainWorktree, options) {
     process.on("SIGTERM", onSignal);
     if (await runStartChecks(config, mainWorktree, ctx, options))
         process.exit(0);
-    try {
-        await spawnAndAwait(config, ctx, state);
-    }
-    catch (err) {
-        await rollbackStart(state.spawnPids, state.startedCallbacks, ctx);
-        if (err instanceof StartupError) {
-            handleStartupFailure(err);
-            process.exit(1);
-        }
-        throw err;
+    // Stream logs from the first byte so the whole startup (e.g. a slow build) is visible live.
+    const streamLogs = () => tailLogs(config, state.spawnPids, { fromStart: true });
+    // A signal during startup hands teardown to onSignal (rollback + exit 130); block so we
+    // neither roll back twice nor register a server that is being torn down.
+    if (!(await spawnWithRollback(config, ctx, state, () => shuttingDown, streamLogs))) {
+        await new Promise(() => { });
     }
     const slot = registerStartedServer(config, mainWorktree, state.spawnPids);
     started = true;
     printStartSummary(config, slot, state.spawnPids);
-    tailLogs(config, state.spawnPids);
     watchForExternalStop(Object.values(state.spawnPids), () => {
         if (shuttingDown)
             return;
@@ -145,6 +135,42 @@ async function runForeground(config, mainWorktree, options) {
     });
     await new Promise(() => { });
 }
+function findOwnLiveEntry(config, mainWorktree, cwd) {
+    const entry = findOwnEntry(mainWorktree, config.registryDir, cwd);
+    if (!entry)
+        return;
+    return Object.values(entry.pids).some(isProcessAlive) ? entry : undefined;
+}
+/**
+ * Attach to a dev-server already running in this worktree: replay the recent log, follow it live,
+ * and exit when it stops. CTRL+C only detaches — this session does not own the server.
+ */
+async function attachForeground(config, entry) {
+    const pidList = Object.entries(entry.pids)
+        .map(([name, pid]) => `${name}=${pid}`)
+        .join(", ");
+    console.log(`Attaching to the dev-server in this worktree (slot ${entry.slot}, pids: ${pidList}).`);
+    console.log("Showing live logs. Press CTRL+C to detach — the dev-server keeps running.");
+    let detaching = false;
+    const onSignal = () => {
+        if (detaching)
+            return;
+        detaching = true;
+        console.log("\nDetached. The dev-server is still running (`dev down` to stop it).");
+        process.exit(0);
+    };
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+    tailLogs(config, entry.pids, { replayLines: LOG_TAIL_LINES });
+    watchForExternalStop(Object.values(entry.pids).filter(isProcessAlive), () => {
+        if (detaching)
+            return;
+        detaching = true;
+        console.log("\nDev-server stopped externally (e.g. `dev down`). Exiting.");
+        process.exit(0);
+    });
+    await new Promise(() => { });
+}
 async function shutdownForeground(config, mainWorktree) {
     console.log("\nStopping dev servers...");
     await stopLocal(config, mainWorktree);
@@ -160,7 +186,28 @@ async function runStartChecks(config, mainWorktree, ctx, { evict, restart }) {
     await checkPortsFree(config.servers, ctx.cwd);
     return false;
 }
-async function spawnAndAwait(config, ctx, state) {
+/**
+ * Spawn and await readiness, rolling back on failure. Returns `false` when `isAborted` reports a
+ * concurrent shutdown — the caller must then yield teardown to whoever set it, not proceed.
+ */
+async function spawnWithRollback(config, ctx, state, isAborted = () => false, onSpawned) {
+    try {
+        await spawnAndAwait(config, ctx, state, onSpawned);
+    }
+    catch (err) {
+        if (isAborted())
+            return false;
+        await rollbackStart(state.spawnPids, state.startedCallbacks, ctx);
+        if (err instanceof StartupError) {
+            // The foreground (onSpawned set) already streamed the log live, so skip the redundant tail.
+            handleStartupFailure(err, { includeTail: onSpawned === undefined });
+            process.exit(1);
+        }
+        throw err;
+    }
+    return !isAborted();
+}
+async function spawnAndAwait(config, ctx, state, onSpawned) {
     for (const server of config.servers) {
         console.log(`Starting ${server.name} dev server...`);
         if (server.kind === "spawn") {
@@ -171,6 +218,7 @@ async function spawnAndAwait(config, ctx, state) {
             state.startedCallbacks.push(server);
         }
     }
+    onSpawned?.();
     const spawnEntries = config.servers.filter((s) => s.kind === "spawn");
     const pollables = spawnEntries.map((s) => ({
         name: s.name,
@@ -211,16 +259,30 @@ function printStartSummary(config, slot, spawnPids) {
 }
 const TAIL_INTERVAL_MS = 300;
 const LIVENESS_POLL_MS = 1000;
-function tailLogs(config, spawnPids) {
+function tailLogs(config, spawnPids, mode) {
     const names = Object.keys(spawnPids);
     const prefixed = names.length > 1;
     for (const name of names) {
         const path = join(process.cwd(), logFileFor(config.runtimeDir, name));
-        followLogFile(path, prefixed ? `[${name}] ` : "");
+        const prefix = prefixed ? `[${name}] ` : "";
+        const offset = "fromStart" in mode ? 0 : replayTail(path, prefix, mode.replayLines);
+        followLogFile(path, prefix, offset);
     }
 }
-function followLogFile(path, prefix) {
-    let offset = existsSync(path) ? statSync(path).size : 0;
+function replayTail(path, prefix, lines) {
+    if (!existsSync(path))
+        return 0;
+    const content = readFileSync(path, "utf8");
+    const tail = lastLines(content, lines);
+    if (tail.length > 0)
+        writeWithPrefix(tail.endsWith("\n") ? tail : `${tail}\n`, prefix);
+    return Buffer.byteLength(content, "utf8");
+}
+function writeWithPrefix(text, prefix) {
+    process.stdout.write(prefix === "" ? text : text.replace(/^(?=.)/gm, prefix));
+}
+function followLogFile(path, prefix, initialOffset) {
+    let offset = initialOffset;
     setInterval(() => {
         if (!existsSync(path))
             return;
@@ -235,8 +297,7 @@ function followLogFile(path, prefix) {
         const bytesRead = readSync(fd, buffer, 0, length, offset);
         closeSync(fd);
         offset += bytesRead;
-        const text = buffer.subarray(0, bytesRead).toString("utf8");
-        process.stdout.write(prefix === "" ? text : text.replace(/^(?=.)/gm, prefix));
+        writeWithPrefix(buffer.subarray(0, bytesRead).toString("utf8"), prefix);
     }, TAIL_INTERVAL_MS);
 }
 /**

package/dist/helpers.d.ts

@@ -1,6 +1,7 @@
 export declare function setupLogPath(worktreeRoot: string, runtimeDir: string): string;
 export declare function patchEnvFile(content: string, patches: Record<string, string>): string;
 export declare function extractHost(content: string, key: string, fallback?: string): string;
+export declare function lastLines(content: string, count: number): string;
 /**
  * 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.

package/dist/helpers.js

@@ -21,6 +21,9 @@ export function extractHost(content, key, fallback = "localhost") {
     const m = content.match(re);
     return m ? m[1] : fallback;
 }
+export function lastLines(content, count) {
+    return content.split("\n").slice(-count).join("\n");
+}
 /**
  * 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.

package/dist/log-polling.d.ts

@@ -14,4 +14,8 @@ export interface AwaitOptions {
     isAlive?: (pid: number) => boolean;
 }
 export declare function awaitAllReady(servers: PollableServer[], pids: number[], options?: AwaitOptions): Promise<void>;
-export declare function handleStartupFailure(err: StartupError): void;
+export interface StartupFailureOptions {
+    /** When false (the foreground already streamed the log live), skip the redundant log tail. */
+    includeTail?: boolean;
+}
+export declare function handleStartupFailure(err: StartupError, options?: StartupFailureOptions): void;

package/dist/log-polling.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { StartupError } from "./errors.js";
+import { lastLines } from "./helpers.js";
 import { isProcessAlive as defaultIsAlive } from "./process-control.js";
 export const LOG_TAIL_LINES = 30;
 export const POLL_INTERVAL_MS = 500;
@@ -8,14 +9,18 @@ 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) {
+export function handleStartupFailure(err, options = {}) {
     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);
+    if (!err.logFile || !existsSync(err.logFile))
+        return;
+    const fullLog = join(process.cwd(), err.logFile);
+    if (options.includeTail ?? true) {
         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)}`);
+        console.error(lastLines(readFileSync(err.logFile, "utf-8"), LOG_TAIL_LINES));
+        console.error(`--- end ---\nFull log: ${fullLog}`);
+        return;
     }
+    console.error(`Full log: ${fullLog}`);
 }
 async function waitForReady(server, pid, options = {}) {
     const timeoutMs = options.timeoutMs ?? TIMEOUT_MS;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paleo/workspace",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Run multiple git-worktree dev environments side by side.",
   "keywords": [
     "workspace",