@paleo/workspace 0.21.0 → 0.22.0

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, 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/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

@@ -49,11 +49,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 +85,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,8 +123,13 @@ 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. */

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();
@@ -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({

package/package.json

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