@paleo/workspace 0.20.0 → 0.22.0

package/README.md

@@ -26,7 +26,8 @@ The agent reads the skill, adapts the reference scripts to your stack, installs
 ## Workflow
 
 ```sh
-npm run workspace -- setup feat/42 -c   # new branch + worktree + isolated env
+npm run workspace -- setup feat/42 -c        # new branch + worktree + isolated env
+npm run workspace -- setup feat/42 -c --go   # …then drop into a shell there (exit to return)
 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

package/dist/cli.d.ts

@@ -7,6 +7,7 @@ export type WorkspaceCommand = {
     slot?: string;
     force: boolean;
     wait: boolean;
+    go: boolean;
 } | {
     kind: "remove";
     branch?: string;

package/dist/cli.js

@@ -53,6 +53,7 @@ function parseSetup(tokens) {
             slot: { type: "string", short: "s" },
             force: { type: "boolean" },
             wait: { type: "boolean" },
+            go: { type: "boolean" },
             verbose: { type: "boolean", short: "v" },
         },
         allowPositionals: true,
@@ -60,12 +61,16 @@ function parseSetup(tokens) {
     });
     const branch = takeOptionalPositional(positionals, "setup");
     const newBranch = values["new-branch"] ?? false;
+    const go = values.go ?? false;
     if (newBranch && branch === undefined) {
         throw new ConfigError("`workspace setup <branch> -c` requires a branch name.");
     }
     if (values.from !== undefined && !newBranch) {
         throw new ConfigError("`--from` requires `-c`/`--new-branch`.");
     }
+    if (go && branch === undefined) {
+        throw new ConfigError("`--go` requires a branch (the worktree to enter).");
+    }
     return {
         command: {
             kind: "setup",
@@ -76,6 +81,7 @@ function parseSetup(tokens) {
             slot: values.slot,
             force: values.force ?? false,
             wait: values.wait ?? false,
+            go,
         },
         verbose: values.verbose ?? false,
     };
@@ -196,12 +202,14 @@ export function printWorkspaceHelp() {
         "Manage workspaces: a git worktree plus its own dev setup (ports, config, database, dev server).",
         "",
         "Commands:",
-        "  setup [<branch>] [-c|--new-branch] [--from <ref>] [--owner <name>] [-s|--slot <port>] [--force] [--wait]",
+        "  setup [<branch>] [-c|--new-branch] [--from <ref>] [--owner <name>] [-s|--slot <port>] [--force] [--wait] [--go]",
         "      Set up the workspace. With <branch>, create a sibling worktree for it",
         "      (add -c to create the branch first). Without, set up the current worktree",
         "      (idempotent; bootstrap and retry path).",
         "      With -c, the new branch starts at the current worktree's HEAD, or at <ref> with --from.",
         "      Finalize runs in the background; add --wait to block until it reaches READY.",
+        "      With --go, drop into an interactive shell in the new worktree (exit to return);",
+        "      combine with --wait to enter only once it is READY. Requires a branch and $SHELL.",
         "  remove [<branch>] [--force]",
         "      Remove a workspace by branch, or the current one when omitted.",
         "      Refuses on uncommitted changes unless --force.",

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();
@@ -71,13 +71,29 @@ export async function runWorkspace(config) {
             handleSetOwnerMode(command, ctx, registryDir);
             return;
         case "setup": {
-            const { slot } = await runSetup(command, ctx, run, config, registryDir);
+            const { slot, worktree } = await runSetup(command, ctx, run, config, registryDir);
             if (command.wait)
                 await waitForSlot(slot, config, registryDir, { printSummary: false });
+            if (command.go)
+                enterWorktree(worktree);
             return;
         }
     }
 }
+/**
+ * `--go`: open an interactive shell in the freshly set-up worktree (exit to return). Falls back to
+ * printing a `cd` hint when there is no `$SHELL` or stdin is not a tty (scripts, pipes) — dropping
+ * into an interactive shell there would hang.
+ */
+function enterWorktree(worktree) {
+    const shell = process.env.SHELL;
+    if (shell === undefined || !process.stdin.isTTY) {
+        console.log(`Now run: cd ${worktree}`);
+        return;
+    }
+    console.error(`Entering ${worktree} (exit to return).`);
+    spawnSync(shell, [], { cwd: worktree, stdio: "inherit" });
+}
 async function runSetup(command, ctx, run, config, registryDir) {
     const scheme = resolvePortScheme(config);
     const portsFn = resolvePortsFn(config);
@@ -158,7 +174,7 @@ async function runSetup(command, ctx, run, config, registryDir) {
     });
     child.unref();
     closeSync(logFd);
-    return { slot };
+    return { slot, worktree: setupCtx.currentWorktree };
 }
 function refuseIfFinalizePending(ctx, registryDir, force) {
     if (force)
@@ -207,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("============================================================");
@@ -383,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);
@@ -391,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}).`);
@@ -403,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);
@@ -493,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);
@@ -510,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);
@@ -530,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.20.0",
+  "version": "0.22.0",
   "description": "Run multiple git-worktree dev environments side by side.",
   "keywords": [
     "workspace",