@paleo/workspace 0.11.1 → 0.12.0

package/README.md

@@ -48,7 +48,7 @@ await runWorkspace({
   portNames: ["server", "frontend", "db"],
   sharedDirs: [".local", ".plans"],
   runtimeDir: ".local-wt",
-  registryDir: ".local/wt-registry",
+  registryDir: ".local/_workspace-registry",
   configFiles: [
     {
       path: ".env",
@@ -74,7 +74,7 @@ await runWorkspace({
 
 `branch` is resolved live from the worktree on each call (not persisted in the registry — `git checkout` makes any stored value stale). For detached HEAD or missing directory, it falls back to `"(detached)"`. `status` is the slot's finalize status: `"pending"` until `finalizeWorktree` succeeds, then `"ready"` (or `"failed"`).
 
-Setup runs in two phases: a fast foreground Part 1 creates the worktree and config, then a detached Part 2 runs `finalizeWorktree` and writes progress to `<runtimeDir>/wt-setup.log`. If Part 2 fails, `cd` into the worktree and run `workspace setup` — it is idempotent and retries the finalize step. To block until Part 2 finishes (CI, agent orchestration), run `workspace wait` from inside the worktree (or `workspace wait --slot 8110` from anywhere) — exits 0 on `READY`, 1 on `FAILED`.
+Setup runs in two phases: a fast foreground Part 1 creates the worktree and config, then a detached Part 2 runs `finalizeWorktree` and writes progress to `<runtimeDir>/logs/workspace-setup.log`. If Part 2 fails, `cd` into the worktree and run `workspace setup` — it is idempotent and retries the finalize step. To block until Part 2 finishes (CI, agent orchestration), run `workspace wait` from inside the worktree (or `workspace wait --slot 8110` from anywhere) — exits 0 on `READY`, 1 on `FAILED`.
 
 **Bootstrap the main worktree first.** Linked-worktree setup copies config sources from the main worktree, so the main must already have those files. Run `workspace setup` once on the main checkout. Use `preSetup` (with `isMainWorktree === true`) to seed sources from examples or templates. `configFiles` entries are required by default; mark `optional: true` for sources that may legitimately be missing.
 
@@ -86,7 +86,7 @@ import { runDevServer, helpers } from "@paleo/workspace";
 await runDevServer({
   basePort: 8100,
   runtimeDir: ".local-wt",
-  registryDir: ".local/wt-registry",
+  registryDir: ".local/_workspace-registry",
   devLimit: 5,
   servers: [
     {

package/dist/cli.js

@@ -170,24 +170,24 @@ export function printWorkspaceHelp() {
     console.log([
         "Usage: workspace <command> [options]",
         "",
-        "Manage worktree lifecycle: creation, local environment setup, and removal.",
+        "Manage workspaces: a git worktree plus its own dev setup (ports, config, database, dev server).",
         "",
         "Commands:",
         "  setup [<branch>] [-c|--new-branch] [--owner <name>] [-s|--slot <port>] [--force] [--wait]",
-        "      Set up the local environment. With <branch>, create a sibling worktree for it",
+        "      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).",
         "      Finalize runs in the background; add --wait to block until it reaches READY.",
         "  remove [<branch>] [--no-remote-check]",
-        "      Remove a worktree by branch, or the current one when omitted.",
+        "      Remove a workspace by branch, or the current one when omitted.",
         "  list",
-        "      List all registered worktrees (slot, status, branch, path, owner, created).",
+        "      List all registered workspaces (slot, status, branch, path, owner, created).",
         "  info [-s|--slot <port>]",
-        "      Print a worktree summary (ports, branch, readiness).",
+        "      Print a workspace summary (ports, branch, readiness).",
         "  wait [-s|--slot <port>]",
         "      Block until the background finalize reaches READY (exit 0) or FAILED (exit 1).",
         "  set-owner <name>",
-        "      Update the current linked worktree's slot owner (no rebuild).",
+        "      Update the current workspace's owner (no rebuild).",
         "",
         "Global options:",
         "  -v, --verbose   Show intermediate output.",

package/dist/dev-server.d.ts

@@ -8,7 +8,7 @@ export interface DevServerConfig {
     /** Per-worktree runtime directory, relative to the worktree root (e.g. `.local-wt`). */
     runtimeDir: string;
     /**
-     * Shared registry directory, relative to a worktree root (e.g. `.local/wt-registry`).
+     * Shared registry directory, relative to a worktree root (e.g. `.local/_workspace-registry`).
      * Holds `slots.json` and `dev-servers.json`. Must resolve to the same physical directory
      * across linked worktrees — typically via a symlink (e.g. `.local`).
      */

package/dist/dev-server.js

@@ -4,7 +4,7 @@ import { dirname, join } from "node:path";
 import { parseDevServerArgs, printDevServerHelp, validateDevServerFlags, } 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 } from "./helpers.js";
+import { detectCommonJsError, formatDuration, setupLogPath } from "./helpers.js";
 import { awaitAllReady, handleStartupFailure } from "./log-polling.js";
 import { canonicalCwd, detectPortConflicts, sweepStalePorts, waitForPortsFree, } from "./port-holder.js";
 import { isProcessAlive, stopProcessGroup } from "./process-control.js";
@@ -152,7 +152,7 @@ export function buildWorktreeReadyMessage(input) {
     const { slotPort, worktreePath, runtimeDir, entry, now } = input;
     if (!entry || entry.status === "ready")
         return { ok: true };
-    const logPath = join(worktreePath, runtimeDir, "wt-setup.log");
+    const logPath = setupLogPath(worktreePath, runtimeDir);
     if (entry.status === "pending") {
         const elapsed = formatDuration(now - Date.parse(entry.createdAt));
         return {
@@ -315,7 +315,7 @@ async function stopLocal(config, mainWorktree) {
 function defaultPrintSummary(slot, servers, runtimeDir) {
     console.log("\nDev servers started!");
     const ownerSuffix = slot.owner ? `, owner ${slot.owner}` : "";
-    console.log(`  Worktree: slot ${slot.slot}${ownerSuffix}`);
+    console.log(`  Workspace: slot ${slot.slot}${ownerSuffix}`);
     for (const { server, port, pid } of servers) {
         if (server.kind === "spawn") {
             const url = `http://localhost:${port}/`;

package/dist/helpers.d.ts

@@ -1,3 +1,4 @@
+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;
 /**

package/dist/helpers.js

@@ -1,5 +1,8 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+export function setupLogPath(worktreeRoot, runtimeDir) {
+    return join(worktreeRoot, runtimeDir, "logs", "workspace-setup.log");
+}
 export function patchEnvFile(content, patches) {
     const lines = content.trimEnd().split("\n");
     for (const [key, value] of Object.entries(patches)) {

package/dist/slots.js

@@ -74,7 +74,7 @@ export function validateSlotAvailability(slotArg, ctx) {
 export function resolveCurrentSlot(basePort, registryDir) {
     const slot = lookupSlotForCwd(registryDir) ?? synthesizeMainSlot(basePort);
     if (!slot) {
-        console.error("Error: No slot found for this worktree. Run `workspace setup` first.");
+        console.error("Error: No workspace here. Run `workspace setup` first.");
         process.exit(1);
     }
     return slot;

package/dist/workspace.d.ts

@@ -33,7 +33,7 @@ export interface WorkspaceConfig {
      */
     runtimeDir: string;
     /**
-     * Shared registry directory, relative to a worktree root (e.g. `.local/wt-registry`).
+     * Shared registry directory, relative to a worktree root (e.g. `.local/_workspace-registry`).
      * Holds `slots.json` and `dev-servers.json`. Must resolve to the same physical directory
      * across linked worktrees — typically via a symlink listed in `sharedDirs` (e.g. `.local`).
      */
@@ -54,7 +54,7 @@ export interface WorkspaceConfig {
      * installed deps, etc.).
      *
      * Runs in a detached child whose stdout/stderr are already redirected to
-     * `<runtimeDir>/wt-setup.log`. `console.log` and child-process `stdio: "inherit"` land there.
+     * `<runtimeDir>/logs/workspace-setup.log`. `console.log` and child-process `stdio: "inherit"` land there.
      */
     finalizeWorktree: (ctx: SetupContext) => Promise<void> | void;
     /**

package/dist/workspace.js

@@ -4,7 +4,7 @@ import { dirname, join, relative, resolve } from "node:path";
 import { parseWorkspaceArgs, printWorkspaceHelp } from "./cli.js";
 import { findOwnEntry, removeDevServerEntryByWorktree } from "./dev-servers-registry.js";
 import { ConfigError } from "./errors.js";
-import { copyAndPatchFile, formatDuration } 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";
@@ -86,9 +86,8 @@ async function runSetup(command, ctx, run, config) {
         force: command.force,
     });
     const ports = portsFn(slot);
-    const runtimeDir = join(setupCtx.currentWorktree, config.runtimeDir);
-    mkdirSync(runtimeDir, { recursive: true });
-    const logPath = join(runtimeDir, "wt-setup.log");
+    const logPath = setupLogPath(setupCtx.currentWorktree, config.runtimeDir);
+    mkdirSync(dirname(logPath), { recursive: true });
     // Truncate any prior log so `workspace setup` retries start with a clean record (the previous run's
     // FAILED: banner would otherwise linger and produce false positives for grep-based tooling).
     writeFileSync(logPath, "");
@@ -128,7 +127,7 @@ async function runSetup(command, ctx, run, config) {
         isMainWorktree: setupCtx.isMainWorktree,
         status,
     }));
-    teeLog(`WORKTREE_CREATED path=${setupCtx.currentWorktree} branch=${branch} slot=${slot}`);
+    teeLog(`WORKSPACE_CREATED path=${setupCtx.currentWorktree} branch=${branch} slot=${slot}`);
     if (status !== "ready") {
         teeLog(`Setup continuing in background. Tail: ${logPath}`);
         teeLog(`Block until ready: workspace wait --slot ${slot}`);
@@ -162,7 +161,7 @@ function refuseIfFinalizePending(ctx, registryDir, force) {
 async function runFinalize(command, config) {
     const slot = Number(command.slot);
     const ctx = detectWorktree();
-    const logPath = join(ctx.currentWorktree, config.runtimeDir, "wt-setup.log");
+    const logPath = setupLogPath(ctx.currentWorktree, config.runtimeDir);
     const appendLog = (message) => {
         appendFileSync(logPath, `${message}\n`);
     };
@@ -227,7 +226,7 @@ function printWorktreeInfo(config, slot, worktreeForLog, fallback) {
     const ports = resolvePortsFn(config)(slot);
     const owner = entry?.owner ?? fallback.owner;
     const status = entry?.status ?? "pending";
-    const setupLogPath = join(worktreeForLog, config.runtimeDir, "wt-setup.log");
+    const setupLog = setupLogPath(worktreeForLog, config.runtimeDir);
     const now = Date.now();
     const isMainWorktree = entry?.main ?? false;
     const targetWorktree = entry?.worktree ?? ctx.currentWorktree;
@@ -246,7 +245,7 @@ function printWorktreeInfo(config, slot, worktreeForLog, fallback) {
         const at = entry?.failure?.at ?? entry?.createdAt;
         const elapsed = at ? formatDuration(now - Date.parse(at)) : "?";
         const reason = entry?.failure?.message ?? "(no message)";
-        console.log(`Failure: ${reason} (${elapsed} ago, tail ${setupLogPath})`);
+        console.log(`Failure: ${reason} (${elapsed} ago, tail ${setupLog})`);
     }
     else if (status === "pending" && entry) {
         const elapsed = formatDuration(now - Date.parse(entry.createdAt));
@@ -293,7 +292,7 @@ function runList(config) {
     const ctx = detectWorktree();
     const entries = Object.entries(readSlots(ctx.mainWorktree, config.registryDir).slots).sort(([a], [b]) => Number(a) - Number(b));
     if (entries.length === 0) {
-        console.log("No worktrees registered.");
+        console.log("No workspaces registered.");
         return;
     }
     const rows = entries.map(([port, e]) => ({
@@ -310,7 +309,7 @@ function runList(config) {
         type: "TYPE",
         status: "STATUS",
         branch: "BRANCH",
-        worktree: "WORKTREE",
+        worktree: "PATH",
         owner: "OWNER",
         created: "CREATED",
     };
@@ -359,7 +358,7 @@ async function waitForSlot(slot, config, options = {}) {
             return;
         }
         if (entry.status === "failed") {
-            const logPath = join(entry.worktree, config.runtimeDir, "wt-setup.log");
+            const logPath = setupLogPath(entry.worktree, config.runtimeDir);
             console.error(`FAILED: ${entry.failure?.message ?? "(no message)"}`);
             console.error(`Full log: ${logPath}`);
             process.exit(1);
@@ -372,7 +371,7 @@ async function handleRemove(command, ctx, run, config) {
     const removeHere = command.branch === undefined;
     const registry = readSlots(ctx.mainWorktree, config.registryDir);
     const target = resolveRemoveTarget(command, ctx, registry);
-    // Refuse to remove while the detached finalize is still writing to slots.json / wt-setup.log:
+    // Refuse to remove while the detached finalize is still writing to slots.json / workspace-setup.log:
     // racing the two corrupts the registry and leaves the worktree directory orphaned.
     if (registry.slots[target.slotPort]?.status === "pending") {
         console.error(`Error: Setup is still in progress for slot ${target.slotPort}. ` +
@@ -411,7 +410,7 @@ async function handleRemove(command, ctx, run, config) {
         process.chdir(ctx.mainWorktree);
     }
     removeWorktree(target.worktreePath, run);
-    console.log(`Removed worktree for branch "${target.branch}" (slot ${target.slotPort}${ownerSuffix}). ` +
+    console.log(`Removed workspace for branch "${target.branch}" (slot ${target.slotPort}${ownerSuffix}). ` +
         `Branch "${target.branch}" kept.`);
     if (removeHere) {
         console.log(`Now run: cd ${ctx.mainWorktree}`);
@@ -505,7 +504,7 @@ function resolveRemoveTarget(command, ctx, registry) {
     const branch = command.branch;
     const entry = Object.entries(registry.slots).find(([, v]) => getWorktreeBranch(v.worktree) === branch);
     if (!entry) {
-        console.error(`Error: No worktree found for branch "${branch}" in the slot registry.`);
+        console.error(`Error: No workspace found for branch "${branch}" in the registry.`);
         process.exit(1);
     }
     const worktreePath = entry[1].worktree;

package/package.json

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