@paleo/workspace 0.11.0

package/README.md

@@ -0,0 +1,113 @@
+# @paleo/workspace
+
+Run multiple local dev environments side by side, one per git worktree, with isolated ports, databases, and config files. Built for branches worked in parallel, by humans or AI agents.
+
+Each project writes two custom scripts on top, using these entry points:
+
+- `runWorkspace(config)` — worktree lifecycle (setup / remove / set-owner).
+- `runDevServer(config)` — background dev-server start / stop / list.
+
+## Setup
+
+The `workspace-guide` skill is a setup-time companion. Install the skill (globally or locally):
+
+```bash
+npx skills add https://github.com/paleo/alignfirst --skill workspace-guide
+```
+
+Then, in your project, ask your agent:
+
+```text
+Use your workspace-guide skill. Set up worktree-based local environments in this project.
+```
+
+The agent reads the skill, adapts the reference scripts to your stack, installs `@paleo/workspace` as a dev dependency, and wires the npm scripts. After that, you can uninstall the skill, it won't be used by your project anymore.
+
+## Workflow
+
+```sh
+npm run workspace -- setup feat/42 -c   # new branch + worktree + isolated env
+npm run dev:up                          # start dev server 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
+npm run dev:list                        # active dev-servers across all worktrees
+npm run dev:down                        # stop dev server (infrastructure stays up)
+npm run workspace -- remove feat/42     # full teardown
+```
+
+## API
+
+```ts
+import { fileURLToPath } from "node:url";
+import { runWorkspace, helpers } from "@paleo/workspace";
+
+await runWorkspace({
+  scriptPath: fileURLToPath(import.meta.url),
+  devServerScript: fileURLToPath(new URL("./dev-server.mjs", import.meta.url)),
+  basePort: 8100,
+  portNames: ["server", "frontend", "db"],
+  sharedDirs: [".local", ".plans"],
+  runtimeDir: ".local-wt",
+  registryDir: ".local/wt-registry",
+  configFiles: [
+    {
+      path: ".env",
+      patch: (content, { ports }) =>
+        helpers.patchEnvFile(content, {
+          PORT: String(ports.frontend),
+          SERVER_PORT: String(ports.server),
+        }),
+    },
+  ],
+  preSetup: ({ currentWorktree, isMainWorktree, log }) => {
+    // Idempotent. Bootstrap source files the kernel expects to find (e.g. seed `.env` from
+    // `.env.example` on the main worktree). MUST NOT mutate the main worktree from a linked
+    // worktree setup — bootstrap the main first via `workspace setup`.
+  },
+  finalizeWorktree: async ({ currentWorktree }) => {
+    // MUST be idempotent. Install deps, start containers, seed a database, etc.
+  },
+  printSummary: ({ slot, branch, owner, ports, isMainWorktree, status }) =>
+    `Type:   ${isMainWorktree ? "main" : "linked"}\nStatus: ${status}\nSlot:   ${slot}\nBranch: ${branch}${owner ? `\nOwner:  ${owner}` : ""}\nServer: :${ports.server}`,
+});
+```
+
+`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`.
+
+**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.
+
+`--evict` is best-effort: the cap check and the subsequent register are not atomic, so two concurrent `dev:up --evict` from different worktrees can both pass the check and end up at `devLimit + 1` live servers. The window is narrow; if it matters, `dev:list` + `dev:down` deterministically.
+
+```ts
+import { runDevServer, helpers } from "@paleo/workspace";
+
+await runDevServer({
+  basePort: 8100,
+  runtimeDir: ".local-wt",
+  registryDir: ".local/wt-registry",
+  devLimit: 5,
+  servers: [
+    {
+      kind: "spawn",
+      name: "dev",
+      exec: { command: "npm", args: ["run", "dev"] },
+      port: helpers.readPortFromEnvFile(".env", "PORT"),
+      detectSuccess: (log) => log.includes("Server is ready on port"),
+    },
+  ],
+  printSummary: ({ slot, servers }) =>
+    `Dev servers started in slot ${slot.slot}${slot.owner ? ` (${slot.owner})` : ""}: ${servers
+      .map((s) => `${s.server.name} :${s.port} (PID ${s.pid})`)
+      .join(", ")}`,
+});
+```
+
+## Build / test
+
+```sh
+npm install
+npm run build
+npm test
+```

package/dist/cli.d.ts

@@ -0,0 +1,47 @@
+export type WorkspaceCommand = {
+    kind: "setup";
+    branch?: string;
+    newBranch: boolean;
+    owner?: string;
+    slot?: string;
+    force: boolean;
+    wait: boolean;
+} | {
+    kind: "remove";
+    branch?: string;
+    noRemoteCheck: boolean;
+} | {
+    kind: "list";
+} | {
+    kind: "info";
+    slot?: string;
+} | {
+    kind: "wait";
+    slot?: string;
+} | {
+    kind: "set-owner";
+    name: string;
+} | {
+    kind: "finalize";
+    slot: string;
+    force: boolean;
+} | {
+    kind: "help";
+};
+export interface ParsedWorkspaceArgs {
+    command: WorkspaceCommand;
+    verbose: boolean;
+}
+export declare function parseWorkspaceArgs(argv?: string[]): ParsedWorkspaceArgs;
+export declare function printWorkspaceHelp(): void;
+export interface DevServerArgs {
+    help?: boolean;
+    stop?: boolean;
+    list?: boolean;
+    all?: boolean;
+    evict?: boolean;
+    restart?: boolean;
+}
+export declare function parseDevServerArgs(argv?: string[]): DevServerArgs;
+export declare function printDevServerHelp(): void;
+export declare function validateDevServerFlags(args: DevServerArgs): void;

package/dist/cli.js

@@ -0,0 +1,235 @@
+import { parseArgs } from "node:util";
+import { ConfigError } from "./errors.js";
+const DEV_SERVER_OPTIONS = {
+    help: { type: "boolean", short: "h", description: "Show this help message" },
+    stop: { type: "boolean", description: "Stop dev servers in the current worktree" },
+    list: { type: "boolean", description: "List active dev-servers across all worktrees" },
+    all: { type: "boolean", description: "Apply --stop to every active dev-server" },
+    evict: { type: "boolean", description: "Evict the oldest dev-server when the cap is reached" },
+    restart: {
+        type: "boolean",
+        description: "If a dev-server is already running in this worktree, stop it first, then start",
+    },
+};
+export function parseWorkspaceArgs(argv = process.argv.slice(2)) {
+    const [subcommand, ...tokens] = argv;
+    if (subcommand === undefined || subcommand === "--help" || subcommand === "-h") {
+        return { command: { kind: "help" }, verbose: false };
+    }
+    try {
+        return parseSubcommand(subcommand, tokens);
+    }
+    catch (err) {
+        if (err instanceof ConfigError)
+            throw err;
+        throw new ConfigError(`Error: ${err.message}`);
+    }
+}
+function parseSubcommand(subcommand, tokens) {
+    switch (subcommand) {
+        case "setup":
+            return parseSetup(tokens);
+        case "remove":
+            return parseRemove(tokens);
+        case "list":
+            return parseList(tokens);
+        case "info":
+            return parseInfo(tokens);
+        case "wait":
+            return parseWait(tokens);
+        case "set-owner":
+            return parseSetOwner(tokens);
+        case "__finalize":
+            return parseFinalize(tokens);
+        default:
+            throw new ConfigError(`Error: Unknown command "${subcommand}". Run \`workspace --help\`.`);
+    }
+}
+function parseSetup(tokens) {
+    const { values, positionals } = parseArgs({
+        args: tokens,
+        options: {
+            "new-branch": { type: "boolean", short: "c" },
+            owner: { type: "string" },
+            slot: { type: "string", short: "s" },
+            force: { type: "boolean" },
+            wait: { type: "boolean" },
+            verbose: { type: "boolean", short: "v" },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+    const branch = takeOptionalPositional(positionals, "setup");
+    const newBranch = values["new-branch"] ?? false;
+    if (newBranch && branch === undefined) {
+        throw new ConfigError("Error: `workspace setup <branch> -c` requires a branch name.");
+    }
+    return {
+        command: {
+            kind: "setup",
+            branch,
+            newBranch,
+            owner: values.owner,
+            slot: values.slot,
+            force: values.force ?? false,
+            wait: values.wait ?? false,
+        },
+        verbose: values.verbose ?? false,
+    };
+}
+function parseRemove(tokens) {
+    const { values, positionals } = parseArgs({
+        args: tokens,
+        options: {
+            "no-remote-check": { type: "boolean" },
+            verbose: { type: "boolean", short: "v" },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+    const branch = takeOptionalPositional(positionals, "remove");
+    return {
+        command: { kind: "remove", branch, noRemoteCheck: values["no-remote-check"] ?? false },
+        verbose: values.verbose ?? false,
+    };
+}
+function parseList(tokens) {
+    const { values, positionals } = parseArgs({
+        args: tokens,
+        options: { verbose: { type: "boolean", short: "v" } },
+        allowPositionals: true,
+        strict: true,
+    });
+    rejectPositionals(positionals, "list");
+    return { command: { kind: "list" }, verbose: values.verbose ?? false };
+}
+function parseInfo(tokens) {
+    const { values, positionals } = parseArgs({
+        args: tokens,
+        options: {
+            slot: { type: "string", short: "s" },
+            verbose: { type: "boolean", short: "v" },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+    rejectPositionals(positionals, "info");
+    return { command: { kind: "info", slot: values.slot }, verbose: values.verbose ?? false };
+}
+function parseWait(tokens) {
+    const { values, positionals } = parseArgs({
+        args: tokens,
+        options: {
+            slot: { type: "string", short: "s" },
+            verbose: { type: "boolean", short: "v" },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+    rejectPositionals(positionals, "wait");
+    return { command: { kind: "wait", slot: values.slot }, verbose: values.verbose ?? false };
+}
+function parseSetOwner(tokens) {
+    const { values, positionals } = parseArgs({
+        args: tokens,
+        options: { verbose: { type: "boolean", short: "v" } },
+        allowPositionals: true,
+        strict: true,
+    });
+    const name = takeRequiredPositional(positionals, "set-owner", "name");
+    return { command: { kind: "set-owner", name }, verbose: values.verbose ?? false };
+}
+function parseFinalize(tokens) {
+    const { values, positionals } = parseArgs({
+        args: tokens,
+        options: { force: { type: "boolean" } },
+        allowPositionals: true,
+        strict: true,
+    });
+    const slot = takeRequiredPositional(positionals, "__finalize", "slot");
+    return { command: { kind: "finalize", slot, force: values.force ?? false }, verbose: false };
+}
+function takeOptionalPositional(positionals, command) {
+    if (positionals.length > 1) {
+        throw new ConfigError(`Error: \`workspace ${command}\` accepts at most one positional argument.`);
+    }
+    return positionals[0];
+}
+function takeRequiredPositional(positionals, command, label) {
+    if (positionals.length !== 1) {
+        throw new ConfigError(`Error: \`workspace ${command}\` requires exactly one ${label}.`);
+    }
+    return positionals[0];
+}
+function rejectPositionals(positionals, command) {
+    if (positionals.length > 0) {
+        throw new ConfigError(`Error: \`workspace ${command}\` takes no positional arguments.`);
+    }
+}
+export function printWorkspaceHelp() {
+    console.log([
+        "Usage: workspace <command> [options]",
+        "",
+        "Manage worktree lifecycle: creation, local environment setup, and removal.",
+        "",
+        "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",
+        "      (add -c to create the branch first). Without, set up the current worktree",
+        "      (idempotent; bootstrap and retry path).",
+        "  remove [<branch>] [--no-remote-check]",
+        "      Remove a worktree by branch, or the current one when omitted.",
+        "  list",
+        "      List all registered worktrees (slot, status, branch, path, owner, created).",
+        "  info [-s|--slot <port>]",
+        "      Print a worktree 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).",
+        "",
+        "Global options:",
+        "  -v, --verbose   Show intermediate output.",
+    ].join("\n"));
+}
+export function parseDevServerArgs(argv) {
+    return parseOptions(argv, DEV_SERVER_OPTIONS);
+}
+export function printDevServerHelp() {
+    console.log(formatHelp("dev-server [options]", "Start, stop, or list background dev-server processes.", DEV_SERVER_OPTIONS));
+}
+export function validateDevServerFlags(args) {
+    if (args.all && !args.stop) {
+        throw new ConfigError("Error: --all requires --stop.");
+    }
+    if (args.list && (args.stop || args.all)) {
+        throw new ConfigError("Error: --list is mutually exclusive with --stop and --all.");
+    }
+    if (args.evict && (args.stop || args.list || args.all)) {
+        const conflict = args.stop ? "--stop" : args.list ? "--list" : "--all";
+        throw new ConfigError(`Error: --evict cannot be combined with ${conflict}.`);
+    }
+    if (args.restart && (args.stop || args.list || args.all)) {
+        const conflict = args.stop ? "--stop" : args.list ? "--list" : "--all";
+        throw new ConfigError(`Error: --restart cannot be combined with ${conflict}.`);
+    }
+}
+function parseOptions(argv, options) {
+    const cfg = { options: options, strict: true };
+    if (argv)
+        cfg.args = argv;
+    const { values } = parseArgs(cfg);
+    return values;
+}
+function formatHelp(usage, intro, options) {
+    const lines = [`Usage: ${usage}`, "", intro, ""];
+    for (const [name, opt] of Object.entries(options)) {
+        if (opt.description === "")
+            continue;
+        const shortFlag = opt.short ? `-${opt.short}, ` : "";
+        const argSuffix = opt.arg ? ` <${opt.arg}>` : "";
+        const flag = `${shortFlag}--${name}${argSuffix}`;
+        lines.push(`  ${flag.padEnd(28)} ${opt.description}`);
+    }
+    return lines.join("\n");
+}

package/dist/dev-server.d.ts

@@ -0,0 +1,52 @@
+import type { CallbackServer, ServerContext, ServerDescriptor, SpawnServer } from "./server-descriptor.js";
+import { type ResolvedSlot, type SlotEntry } from "./slots.js";
+export type { CallbackServer, ServerContext, ServerDescriptor, SpawnServer };
+/** Configuration accepted by {@link runDevServer}. */
+export interface DevServerConfig {
+    /** Anchor port for the slot range. Used to synthesize the main worktree's slot. */
+    basePort: number;
+    /** 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`).
+     * Holds `slots.json` and `dev-servers.json`. Must resolve to the same physical directory
+     * across linked worktrees — typically via a symlink (e.g. `.local`).
+     */
+    registryDir: string;
+    /** Maximum concurrent dev-servers across all worktrees. Omit for no limit. */
+    devLimit?: number;
+    /** One entry per server to start. Started in array order; stopped in reverse order. */
+    servers: ServerDescriptor[];
+    /** Builds the post-start summary printed to stdout. Defaults to a generic layout. */
+    printSummary?: (ctx: DevServerSummaryContext) => string;
+}
+/**
+ * Context passed to {@link DevServerConfig.printSummary}. `port` and `pid` are present only for
+ * `kind: "spawn"` servers; callback servers expose neither.
+ */
+export interface DevServerSummaryContext {
+    slot: ResolvedSlot;
+    servers: {
+        server: ServerDescriptor;
+        port?: number;
+        pid?: number;
+    }[];
+}
+export declare function runDevServer(config: DevServerConfig): Promise<void>;
+export type WorktreeReadyCheck = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Pure builder for the `dev:up` worktree-readiness gate. Returns `ok` when the slot is `ready`
+ * or absent (synthesized main); otherwise returns the user-facing error message.
+ */
+export declare function buildWorktreeReadyMessage(input: {
+    slotPort: number;
+    worktreePath: string;
+    runtimeDir: string;
+    entry: SlotEntry | undefined;
+    now: number;
+}): WorktreeReadyCheck;