@paleo/workspace 0.15.1 → 0.16.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                             # foreground: stream logs from startup, CTRL+C stops; attaches if already running (CTRL+C then detaches)
+npm run dev                             # foreground: stream logs, CTRL+C stops; attaches if already running
 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

@@ -287,7 +287,7 @@ export function printDevHelp() {
         "",
         "Commands:",
         "  dev               Start in the foreground, streaming logs from startup; CTRL+C stops it.",
-        "                    If one is already running here, attach to its logs instead",
+        "                    If one is already running here, attach to its logs instead.",
         "  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.",

package/dist/dev-server.d.ts

@@ -1,3 +1,4 @@
+import { StartupError } from "./errors.js";
 import type { CallbackServer, ServerContext, ServerDescriptor, SpawnServer } from "./server-descriptor.js";
 import { type ResolvedSlot, type SlotEntry } from "./slots.js";
 export type { CallbackServer, ServerContext, ServerDescriptor, SpawnServer };
@@ -33,6 +34,12 @@ export interface DevServerSummaryContext {
     }[];
 }
 export declare function runDevServer(config: DevServerConfig): Promise<void>;
+/**
+ * Wraps an error thrown by a callback server's `start()` into a {@link StartupError}, so a failing
+ * callback (e.g. `docker compose up -d`) gets the same clean rollback-and-report path as a spawn
+ * server instead of surfacing as a raw unhandled-rejection stack trace.
+ */
+export declare function toCallbackStartupError(name: string, err: unknown): StartupError;
 /**
  * Poll the foreground's own spawn PIDs; when none remain alive, the servers were stopped from
  * outside this process (`dev down`, `down --all`, eviction, or a manual kill). Fires `onStopped`

package/dist/dev-server.js

@@ -207,6 +207,16 @@ async function spawnWithRollback(config, ctx, state, isAborted = () => false, on
     }
     return !isAborted();
 }
+/**
+ * Wraps an error thrown by a callback server's `start()` into a {@link StartupError}, so a failing
+ * callback (e.g. `docker compose up -d`) gets the same clean rollback-and-report path as a spawn
+ * server instead of surfacing as a raw unhandled-rejection stack trace.
+ */
+export function toCallbackStartupError(name, err) {
+    if (err instanceof StartupError)
+        return err;
+    return new StartupError(name, err instanceof Error ? err.message : String(err));
+}
 async function spawnAndAwait(config, ctx, state, onSpawned) {
     for (const server of config.servers) {
         console.log(`Starting ${server.name} dev server...`);
@@ -214,7 +224,12 @@ async function spawnAndAwait(config, ctx, state, onSpawned) {
             state.spawnPids[server.name] = spawnServer(server, config.runtimeDir, ctx.cwd);
         }
         else {
-            await server.start(ctx);
+            try {
+                await server.start(ctx);
+            }
+            catch (err) {
+                throw toCallbackStartupError(server.name, err);
+            }
             state.startedCallbacks.push(server);
         }
     }

package/dist/helpers.d.ts

@@ -14,10 +14,15 @@ export declare function readPortFromEnvFile(file: string, varName: string): numb
 export declare function readPortFromJsonFile(file: string, jsonPath: string): number;
 export interface CopyAndPatchCtx {
     currentWorktree: string;
-    mainWorktree: string;
     log: (msg: string) => void;
 }
-export declare function copyAndPatchFile(ctx: CopyAndPatchCtx, relPath: string, patchFn: (content: string) => string, label: string, force: boolean, optional?: boolean): void;
+/** Resolved initial-content source for {@link copyAndPatchFile}. `path` is absolute. */
+export type ResolvedFileSource = {
+    path: string;
+} | {
+    content: string;
+};
+export declare function copyAndPatchFile(ctx: CopyAndPatchCtx, relPath: string, source: ResolvedFileSource, patchFn: (content: string) => string, label: string, force: boolean, optional?: boolean): void;
 /**
  * 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

package/dist/helpers.js

@@ -67,24 +67,29 @@ export function readPortFromJsonFile(file, jsonPath) {
     }
     return toPort(String(cur), file);
 }
-export function copyAndPatchFile(ctx, relPath, patchFn, label, force, optional = false) {
+export function copyAndPatchFile(ctx, relPath, source, 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);
+    let content;
+    if ("content" in source) {
+        content = source.content;
+    }
+    else {
+        if (!existsSync(source.path)) {
+            if (!optional) {
+                console.error(`Error: source ${source.path} not found. Bootstrap the main worktree first ` +
+                    "(`workspace setup`), provide a `source`, or mark the entry as optional.");
+                process.exit(1);
+            }
+            ctx.log(`Warning: source ${source.path} not found, skipping (optional).`);
+            return;
         }
-        ctx.log(`Warning: ${relPath} not found in main worktree, skipping (optional).`);
-        return;
+        content = readFileSync(source.path, "utf-8");
     }
-    const content = readFileSync(sourcePath, "utf-8");
     const patched = patchFn(content);
     mkdirSync(dirname(targetPath), { recursive: true });
     writeFileSync(targetPath, patched);

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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 type { WorkspaceConfig, SetupContext, SummaryContext, PatchContext, ConfigFileEntry, ConfigFileSource, ConfigFileSourceSpec, 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";

package/dist/workspace.d.ts

@@ -121,16 +121,38 @@ export interface PurgeContext {
     mainWorktree: string;
     verbose: boolean;
 }
-/** One config file copied from the main worktree and patched per slot. */
+/** A `{ path }` (relative to the main worktree) or `{ content }` (verbatim) initial source. */
+export type ConfigFileSourceSpec = {
+    path: string;
+} | {
+    content: string;
+};
+/**
+ * Overrides where a {@link ConfigFileEntry}'s initial content comes from. Defaults to reading
+ * `entry.path` from the main worktree.
+ *
+ * - `{ path }` — read this path (relative to the main worktree) instead of `entry.path`,
+ *   e.g. seed from a committed example: `{ path: "packages/api/.env.local.example" }`.
+ * - `{ content }` — use this string as the initial content verbatim.
+ * - a callback returning either of the above, resolved per worktree with the same
+ *   {@link PatchContext} the `patch` callback receives.
+ */
+export type ConfigFileSource = ConfigFileSourceSpec | ((ctx: PatchContext) => ConfigFileSourceSpec);
+/** One config file seeded from its source (the main worktree by default) and patched per slot. */
 export interface ConfigFileEntry {
-    /** Path relative to the worktree root. Same path is read from main and written to current. */
+    /** Path relative to the worktree root. Written to the current worktree. */
     path: string;
+    /**
+     * Overrides the initial content's source. Defaults to reading `path` from the main worktree.
+     * Use this to seed from a committed example or supplied content instead. See {@link ConfigFileSource}.
+     */
+    source?: ConfigFileSource;
     /** Returns the patched content given the source content and the slot's ports. */
     patch: (content: string, ctx: PatchContext) => string;
     /**
-     * When `true`, a missing source on the main worktree logs a warning and skips the entry.
+     * When `true`, a missing `{ path }` source logs a warning and skips the entry.
      * Default: required (missing source aborts setup). Bootstrap the main worktree first via
-     * `workspace setup`, or seed sources in `preSetup`.
+     * `workspace setup`, or seed sources in `preSetup`. Ignored for `{ content }` sources.
      */
     optional?: boolean;
 }

package/dist/workspace.js

@@ -4,7 +4,7 @@ import { dirname, join, relative, resolve } from "node:path";
 import { parseWorkspaceArgs, printWorkspaceHelp } from "./cli.js";
 import { findOwnEntry, liveWorktrees, readDevServers, removeDevServerEntryByWorktree, } from "./dev-servers-registry.js";
 import { ConfigError } from "./errors.js";
-import { copyAndPatchFile, formatDuration, setupLogPath } from "./helpers.js";
+import { copyAndPatchFile, formatDuration, setupLogPath, } from "./helpers.js";
 import { isProcessAlive } from "./process-control.js";
 import { defaultComputePorts, isValidPort, resolvePortScheme } from "./ports.js";
 import { handleSetOwner, markSlotFailed, markSlotReady, readSlots, resolveAndRegisterSlot, resolveCurrentSlot, validateSlotAvailability, writeSlots, } from "./slots.js";
@@ -478,14 +478,23 @@ function linkSharedDirectories(ctx, dirs, log) {
 }
 function generateConfigFiles(ctx, entries, slot, ports, force, log) {
     for (const entry of entries) {
-        copyAndPatchFile({ currentWorktree: ctx.currentWorktree, mainWorktree: ctx.mainWorktree, log }, entry.path, (content) => entry.patch(content, {
+        const patchCtx = {
             slot,
             ports,
             mainWorktree: ctx.mainWorktree,
             currentWorktree: ctx.currentWorktree,
-        }), entry.path, force, entry.optional ?? false);
+        };
+        copyAndPatchFile({ currentWorktree: ctx.currentWorktree, log }, entry.path, resolveConfigSource(entry, patchCtx), (content) => entry.patch(content, patchCtx), entry.path, force, entry.optional ?? false);
     }
 }
+function resolveConfigSource(entry, ctx) {
+    const spec = typeof entry.source === "function" ? entry.source(ctx) : entry.source;
+    if (spec === undefined)
+        return { path: join(ctx.mainWorktree, entry.path) };
+    if ("content" in spec)
+        return { content: spec.content };
+    return { path: join(ctx.mainWorktree, spec.path) };
+}
 function resolveRemoveTarget(command, ctx, registry) {
     if (command.branch === undefined) {
         if (ctx.isMainWorktree) {

package/package.json

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