@paleo/workspace 0.21.0 → 0.23.0

package/dist/helpers.js

@@ -81,8 +81,8 @@ export function copyAndPatchFile(ctx, relPath, source, patchFn, label, force, op
     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.");
+                console.error(`Error: config source ${source.path} not found. Bootstrap it first ` +
+                    "(`workspace setup`, or commit the template), or mark the entry as optional.");
                 process.exit(1);
             }
             ctx.log(`Warning: source ${source.path} not found, skipping (optional).`);

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, ConfigFileSource, ConfigFileSourceSpec, PurgeContext, } from "./workspace.js";
+export type { WorkspaceConfig, SetupContext, FinalizeResult, SummaryContext, PatchContext, ConfigFileEntry, ConfigFileSource, MainWorktreeConfigFileSource, NewWorktreeConfigFileSource, ContentConfigFileSource, 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/slots.d.ts

@@ -25,6 +25,9 @@ export interface SlotEntry {
     };
     /** `true` for the main-worktree entry. Absent on linked entries. */
     main?: boolean;
+    /** Opaque blob the consumer returns from `finalizeWorktree`, handed back to `purgeInfrastructure`
+     * so an orphan's infrastructure can be torn down by name after its worktree (and config) is gone. */
+    extra?: unknown;
 }
 export interface SlotsRegistry {
     slots: Record<string, SlotEntry>;
@@ -50,7 +53,7 @@ export declare function resolveAndRegisterSlot(input: RegisterSlotInput): {
     owner: string | undefined;
     status: SlotStatus;
 };
-export declare function markSlotReady(mainWorktree: string, registryDir: string, slotPort: number): void;
+export declare function markSlotReady(mainWorktree: string, registryDir: string, slotPort: number, extra?: unknown): void;
 export declare function markSlotFailed(mainWorktree: string, registryDir: string, slotPort: number, message: string): void;
 export declare function validateSlotAvailability(slotArg: string | undefined, ctx: {
     currentWorktree: string;

package/dist/slots.js

@@ -50,17 +50,21 @@ export function resolveAndRegisterSlot(input) {
         entry.main = true;
     if (owner !== undefined)
         entry.owner = owner;
+    if (existing?.extra !== undefined)
+        entry.extra = existing.extra;
     registry.slots[String(port)] = entry;
     writeSlots(input.mainWorktree, input.registryDir, registry);
     return { port, owner, status };
 }
-export function markSlotReady(mainWorktree, registryDir, slotPort) {
+export function markSlotReady(mainWorktree, registryDir, slotPort, extra) {
     const registry = readSlots(mainWorktree, registryDir);
     const entry = registry.slots[String(slotPort)];
     if (!entry)
         return;
     entry.status = "ready";
     delete entry.failure;
+    if (extra !== undefined)
+        entry.extra = extra;
     writeSlots(mainWorktree, registryDir, registry);
 }
 export function markSlotFailed(mainWorktree, registryDir, slotPort, message) {
@@ -116,6 +120,8 @@ export function handleSetOwner(input) {
     };
     if (slotData.failure)
         updated.failure = slotData.failure;
+    if (slotData.extra !== undefined)
+        updated.extra = slotData.extra;
     if (input.newOwner !== undefined)
         updated.owner = input.newOwner;
     registry.slots[slotPort] = updated;

package/dist/workspace.d.ts

@@ -1,3 +1,4 @@
+import { type ResolvedFileSource } from "./helpers.js";
 import { type SlotStatus } from "./slots.js";
 import { type WorktreeDirNameFn } from "./worktree.js";
 /** Configuration accepted by {@link runWorkspace}. */
@@ -32,7 +33,7 @@ export interface WorkspaceConfig {
      * Holds the setup log and dev-server logs.
      */
     runtimeDir: string;
-    /** Config files copied from the main worktree and patched per slot. */
+    /** Gitignored files seeded into each worktree (from main, a committed template, or content) and patched per slot. */
     configFiles: ConfigFileEntry[];
     /**
      * Runs before `configFiles` are copied. Use this to bootstrap source files the kernel expects
@@ -49,11 +50,19 @@ export interface WorkspaceConfig {
      *
      * Runs in a detached child whose stdout/stderr are already redirected to
      * `<runtimeDir>/logs/workspace-setup.log`. `console.log` and child-process `stdio: "inherit"` land there.
+     *
+     * May return `{ extra }` — an opaque blob persisted on the slot entry and handed back to
+     * {@link purgeInfrastructure}. Use it to record what infrastructure to tear down by name (e.g.
+     * container and volume names) so an orphaned worktree can still be cleaned up after its config is gone.
      */
-    finalizeWorktree: (ctx: SetupContext) => Promise<void> | void;
+    finalizeWorktree: (ctx: SetupContext) => Promise<FinalizeResult | undefined> | FinalizeResult | undefined;
     /**
-     * Destructive infrastructure teardown on `workspace remove` (e.g. `docker compose down -v` to
-     * wipe volumes). Runs after the dev-server stop. Best-effort; errors should be swallowed.
+     * Destructive infrastructure teardown (e.g. `docker compose down -v` to wipe volumes). Runs after
+     * the dev-server stop on `workspace remove`, and on `workspace prune` / removing an orphaned
+     * worktree. MUST be idempotent and tolerate already-absent infrastructure: it may run when the
+     * worktree directory is gone (`ctx.extra` carries the recorded teardown identifiers; `ctx.worktree`
+     * no longer exists), so branch on the worktree's presence and tear down by name in that case.
+     * Best-effort; errors should be swallowed.
      */
     purgeInfrastructure?: (ctx: PurgeContext) => Promise<void> | void;
     /** Builds the post-setup summary printed to stdout. */
@@ -77,6 +86,10 @@ export interface PreSetupContext {
     /** Writes to stdout and the setup log. */
     log: (msg: string) => void;
 }
+/** Return value of {@link WorkspaceConfig.finalizeWorktree}. */
+export interface FinalizeResult {
+    extra: unknown;
+}
 /** Context passed to {@link WorkspaceConfig.finalizeWorktree}. */
 export interface SetupContext {
     currentWorktree: string;
@@ -111,45 +124,46 @@ export interface SummaryContext {
 }
 /** Context passed to {@link WorkspaceConfig.purgeInfrastructure}. */
 export interface PurgeContext {
+    /** The target worktree. May no longer exist on disk when purging an orphan — check before
+     * running cwd-bound commands; tear down by name (from {@link extra}) in that case. */
     worktree: string;
     mainWorktree: string;
+    slot: number;
+    /** The blob the consumer returned from `finalizeWorktree`, if any. */
+    extra?: unknown;
     verbose: boolean;
 }
-/** 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. */
+/** One config file seeded from its source and patched per slot. */
 export interface ConfigFileEntry {
     /** Path relative to the worktree root. Written to the current worktree. */
     path: string;
+    /** Where the initial content comes from. */
+    source: ConfigFileSource;
+    /** Rewrites the source content per slot. Omit to copy the content verbatim. */
+    patch?: (content: string, ctx: PatchContext) => 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 `{ 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`. Ignored for `{ content }` sources.
+     * When `true`, a missing source file logs a warning and skips the entry instead of aborting.
+     * Applies to `mainWorktree` and `newWorktree` sources; ignored for `content`.
      */
     optional?: boolean;
 }
+/** Where a {@link ConfigFileEntry}'s initial content comes from. */
+export type ConfigFileSource = MainWorktreeConfigFileSource | NewWorktreeConfigFileSource | ContentConfigFileSource;
+/** Copies the gitignored file at the entry's `path` from the main worktree. */
+export interface MainWorktreeConfigFileSource {
+    kind: "mainWorktree";
+}
+/** Copies a committed template from the new worktree's own checkout. */
+export interface NewWorktreeConfigFileSource {
+    kind: "newWorktree";
+    /** Path of the template, relative to the worktree root (e.g. a committed `.example` file). */
+    path: string;
+}
+/** Uses the given content verbatim. The function form may be async. */
+export interface ContentConfigFileSource {
+    kind: "content";
+    content: string | (() => string | Promise<string>);
+}
 /** Context passed to {@link ConfigFileEntry.patch}. */
 export interface PatchContext {
     slot: number;
@@ -158,3 +172,4 @@ export interface PatchContext {
     currentWorktree: string;
 }
 export declare function runWorkspace(config: WorkspaceConfig): Promise<void>;
+export declare function resolveConfigSource(entry: ConfigFileEntry, ctx: PatchContext): Promise<ResolvedFileSource>;

package/dist/workspace.js

@@ -58,7 +58,7 @@ export async function runWorkspace(config) {
             runList(registryDir);
             return;
         case "prune":
-            await runPrune(registryDir);
+            await runPrune(config, registryDir, verbose);
             return;
     }
     const ctx = detectWorktree();
@@ -148,7 +148,7 @@ async function runSetup(command, ctx, run, config, registryDir) {
     }
     linkSharedDirectories(setupCtx, config.sharedDirs, verboseLog);
     linkWorkspaceRegistry(setupCtx, config.runtimeDir, verboseLog);
-    generateConfigFiles(setupCtx, config.configFiles, slot, ports, command.force, verboseLog);
+    await generateConfigFiles(setupCtx, config.configFiles, slot, ports, command.force, verboseLog);
     teeLog(config.printSummary({
         slot,
         branch,
@@ -223,8 +223,8 @@ async function runFinalize(command, config, registryDir) {
         verbose: false,
     };
     try {
-        await config.finalizeWorktree(setupContext);
-        markSlotReady(ctx.mainWorktree, registryDir, slot);
+        const result = await config.finalizeWorktree(setupContext);
+        markSlotReady(ctx.mainWorktree, registryDir, slot, result?.extra);
         appendLog("============================================================");
         appendLog(`READY: branch ${branch} (slot ${slot})`);
         appendLog("============================================================");
@@ -399,7 +399,7 @@ function hintLiveOrphans(liveOrphans) {
     console.log(`\nNote: ${liveOrphans.length} workspace(s) have a deleted worktree but a still-running ` +
         "dev-server. Run `workspace prune` to stop them and clean up.");
 }
-async function runPrune(registryDir) {
+async function runPrune(config, registryDir, verbose) {
     const ctx = detectWorktree();
     const registry = readSlots(ctx.mainWorktree, registryDir);
     const orphanPorts = findOrphanPorts(registry);
@@ -407,6 +407,13 @@ async function runPrune(registryDir) {
     for (const port of orphanPorts) {
         const entry = registry.slots[port];
         stoppedProcesses += await stopOrphanedDevServer(ctx.mainWorktree, registryDir, entry.worktree);
+        await runPurgeInfrastructure(config, {
+            worktree: entry.worktree,
+            mainWorktree: ctx.mainWorktree,
+            slot: Number(port),
+            extra: entry.extra,
+            verbose,
+        });
         delete registry.slots[port];
         const ownerSuffix = entry.owner ? `, owner ${entry.owner}` : "";
         console.log(`Pruned slot ${port} (${entry.worktree}${ownerSuffix}).`);
@@ -419,16 +426,18 @@ async function runPrune(registryDir) {
         return;
     }
     console.log(`Pruned ${orphanPorts.length} orphaned workspace(s).`);
-    if (stoppedProcesses > 0) {
-        console.log(`Stopped ${stoppedProcesses} orphaned process(es). Note: infrastructure managed by callback ` +
-            "servers (e.g. `docker compose`) is not torn down automatically — check for leftover containers.");
+    if (stoppedProcesses > 0)
+        console.log(`Stopped ${stoppedProcesses} orphaned process(es).`);
+    if (config.purgeInfrastructure === undefined) {
+        console.log("Note: infrastructure managed by callback servers (e.g. `docker compose`) is not torn down " +
+            "automatically — check for leftover containers.");
     }
 }
 /**
  * Stop a gone worktree's dev-server the only way left: its dir (and `dev-server.mjs`) is deleted, so
  * we can't shell out to `dev down` to run callback stop() — we kill the recorded spawn PIDs directly
- * and drop the dev-server entry. Returns the count of live PIDs stopped. Callback-managed infra is
- * not torn down (see `runPrune`'s caveat).
+ * and drop the dev-server entry. Returns the count of live PIDs stopped. The caller separately runs
+ * `purgeInfrastructure` (by name, from the slot's `extra`) to tear down callback-managed infra.
  */
 async function stopOrphanedDevServer(mainWorktree, registryDir, worktree) {
     const devEntry = findOwnEntry(mainWorktree, registryDir, worktree);
@@ -509,6 +518,13 @@ async function handleRemove(command, ctx, run, config, registryDir) {
     if (!existsSync(target.worktreePath)) {
         console.warn(`Warning: Worktree directory ${target.worktreePath} not found. Cleaning up registry only.`);
         await stopOrphanedDevServer(ctx.mainWorktree, registryDir, target.worktreePath);
+        await runPurgeInfrastructure(config, {
+            worktree: target.worktreePath,
+            mainWorktree: ctx.mainWorktree,
+            slot: Number(target.slotPort),
+            extra: registry.slots[target.slotPort]?.extra,
+            verbose: run.verbose,
+        });
         delete registry.slots[target.slotPort];
         writeSlots(ctx.mainWorktree, registryDir, registry);
         pruneGitWorktrees(ctx.mainWorktree);
@@ -526,13 +542,13 @@ async function handleRemove(command, ctx, run, config, registryDir) {
     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,
-        });
-    }
+    await runPurgeInfrastructure(config, {
+        worktree: target.worktreePath,
+        mainWorktree: ctx.mainWorktree,
+        slot: Number(target.slotPort),
+        extra: registry.slots[target.slotPort]?.extra,
+        verbose: run.verbose,
+    });
     delete registry.slots[target.slotPort];
     writeSlots(ctx.mainWorktree, registryDir, registry);
     removeDevServerEntryByWorktree(ctx.mainWorktree, registryDir, target.worktreePath);
@@ -546,6 +562,10 @@ async function handleRemove(command, ctx, run, config, registryDir) {
         console.log(`Now run: cd ${ctx.mainWorktree}`);
     }
 }
+async function runPurgeInfrastructure(config, ctx) {
+    if (config.purgeInfrastructure)
+        await config.purgeInfrastructure(ctx);
+}
 function handleSetOwnerMode(command, ctx, registryDir) {
     const newOwner = command.name;
     const { slotPort } = handleSetOwner({
@@ -681,7 +701,7 @@ function linkWorkspaceRegistry(ctx, runtimeDir, log, opts) {
     symlinkSync(relative(runtimeRoot, mainDir), link);
     log("Created workspace-registry symlink → main worktree.");
 }
-function generateConfigFiles(ctx, entries, slot, ports, force, log) {
+async function generateConfigFiles(ctx, entries, slot, ports, force, log) {
     for (const entry of entries) {
         const patchCtx = {
             slot,
@@ -689,16 +709,25 @@ function generateConfigFiles(ctx, entries, slot, ports, force, log) {
             mainWorktree: ctx.mainWorktree,
             currentWorktree: ctx.currentWorktree,
         };
-        copyAndPatchFile({ currentWorktree: ctx.currentWorktree, log }, entry.path, resolveConfigSource(entry, patchCtx), (content) => entry.patch(content, patchCtx), entry.path, force, entry.optional ?? false);
+        const { patch } = entry;
+        const patchFn = patch
+            ? (content) => patch(content, patchCtx)
+            : (content) => content;
+        copyAndPatchFile({ currentWorktree: ctx.currentWorktree, log }, entry.path, await resolveConfigSource(entry, patchCtx), patchFn, 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) };
+export async function resolveConfigSource(entry, ctx) {
+    const { source } = entry;
+    switch (source.kind) {
+        case "mainWorktree":
+            return { path: join(ctx.mainWorktree, entry.path) };
+        case "newWorktree":
+            return { path: join(ctx.currentWorktree, source.path) };
+        case "content":
+            return {
+                content: typeof source.content === "function" ? await source.content() : source.content,
+            };
+    }
 }
 function resolveRemoveTarget(command, ctx, registry) {
     if (command.branch === undefined) {

package/package.json

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