@paleo/workspace 0.11.0

package/dist/slots.js

@@ -0,0 +1,164 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { allPorts, isValidPort } from "./ports.js";
+import { getWorktreeBranch } from "./worktree.js";
+const SLOTS_FILENAME = "slots.json";
+export function readSlots(mainWorktree, registryDir) {
+    const filePath = join(mainWorktree, registryDir, SLOTS_FILENAME);
+    if (!existsSync(filePath))
+        return { slots: {} };
+    return JSON.parse(readFileSync(filePath, "utf-8"));
+}
+export function writeSlots(mainWorktree, registryDir, registry) {
+    const filePath = join(mainWorktree, registryDir, SLOTS_FILENAME);
+    mkdirSync(join(mainWorktree, registryDir), { recursive: true });
+    writeFileSync(filePath, `${JSON.stringify(registry, undefined, 2)}\n`);
+}
+export function resolveAndRegisterSlot(input) {
+    const registry = readSlots(input.mainWorktree, input.registryDir);
+    const port = pickSlotPort(input, registry);
+    const existing = registry.slots[String(port)];
+    const owner = input.requestedOwner ?? existing?.owner;
+    const createdAt = existing?.createdAt ?? new Date().toISOString();
+    // Re-runs of `workspace setup` keep a previously finalized slot ready, unless `--force` is set —
+    // then we reset to pending so `workspace wait` blocks and `dev:up` refuses during the re-finalize.
+    const status = existing?.status === "ready" && !input.force ? "ready" : "pending";
+    const entry = {
+        worktree: input.currentWorktree,
+        createdAt,
+        status,
+    };
+    if (input.isMainWorktree)
+        entry.main = true;
+    if (owner !== undefined)
+        entry.owner = owner;
+    registry.slots[String(port)] = entry;
+    writeSlots(input.mainWorktree, input.registryDir, registry);
+    return { port, owner, status };
+}
+export function markSlotReady(mainWorktree, registryDir, slotPort) {
+    const registry = readSlots(mainWorktree, registryDir);
+    const entry = registry.slots[String(slotPort)];
+    if (!entry)
+        return;
+    entry.status = "ready";
+    delete entry.failure;
+    writeSlots(mainWorktree, registryDir, registry);
+}
+export function markSlotFailed(mainWorktree, registryDir, slotPort, message) {
+    const registry = readSlots(mainWorktree, registryDir);
+    const entry = registry.slots[String(slotPort)];
+    if (!entry)
+        return;
+    entry.status = "failed";
+    entry.failure = { at: new Date().toISOString(), message };
+    writeSlots(mainWorktree, registryDir, registry);
+}
+export function validateSlotAvailability(slotArg, ctx) {
+    if (slotArg === undefined)
+        return;
+    const port = Number(slotArg);
+    if (!isValidPort(port, ctx.scheme)) {
+        console.error(`Error: Slot must be a valid port: ${allPorts(ctx.scheme).join(", ")}.`);
+        process.exit(1);
+    }
+    const registry = readSlots(ctx.mainWorktree, ctx.registryDir);
+    const existing = registry.slots[String(port)];
+    if (existing && resolve(existing.worktree) !== resolve(ctx.currentWorktree)) {
+        const existingBranch = getWorktreeBranch(existing.worktree);
+        console.error(`Error: Slot ${port} is already taken by ${existing.worktree} (branch: ${existingBranch ?? "(detached)"}).`);
+        process.exit(1);
+    }
+}
+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.");
+        process.exit(1);
+    }
+    return slot;
+}
+export function handleSetOwner(input) {
+    if (input.isMainWorktree) {
+        console.error("Error: `workspace set-owner` must be run from a linked worktree.");
+        process.exit(1);
+    }
+    const registry = readSlots(input.mainWorktree, input.registryDir);
+    const resolvedCurrent = resolve(input.currentWorktree);
+    const entry = Object.entries(registry.slots).find(([, v]) => resolve(v.worktree) === resolvedCurrent);
+    if (!entry) {
+        console.error("Error: No slot found for this worktree in the registry.");
+        process.exit(1);
+    }
+    const [slotPort, slotData] = entry;
+    const updated = {
+        worktree: slotData.worktree,
+        createdAt: slotData.createdAt,
+        status: slotData.status,
+    };
+    if (slotData.failure)
+        updated.failure = slotData.failure;
+    if (input.newOwner !== undefined)
+        updated.owner = input.newOwner;
+    registry.slots[slotPort] = updated;
+    writeSlots(input.mainWorktree, input.registryDir, registry);
+    return { slotPort, owner: input.newOwner };
+}
+function pickSlotPort(args, registry) {
+    const resolvedCurrent = resolve(args.currentWorktree);
+    if (args.isMainWorktree)
+        return args.scheme.basePort;
+    if (args.slot !== undefined) {
+        const port = Number(args.slot);
+        if (!isValidPort(port, args.scheme)) {
+            console.error(`Error: Slot must be a valid port: ${allPorts(args.scheme).join(", ")}.`);
+            process.exit(1);
+        }
+        const existing = registry.slots[String(port)];
+        if (existing && resolve(existing.worktree) !== resolvedCurrent) {
+            const existingBranch = getWorktreeBranch(existing.worktree);
+            console.error(`Error: Slot ${port} is already taken by ${existing.worktree} (branch: ${existingBranch ?? "(detached)"}).`);
+            process.exit(1);
+        }
+        return port;
+    }
+    const existingEntry = Object.entries(registry.slots).find(([, v]) => resolve(v.worktree) === resolvedCurrent);
+    if (existingEntry)
+        return Number(existingEntry[0]);
+    for (const port of allPorts(args.scheme)) {
+        if (!registry.slots[String(port)])
+            return port;
+    }
+    console.error("Error: All slots are taken. Remove a workspace with `workspace remove` first.");
+    process.exit(1);
+}
+function lookupSlotForCwd(registryDir) {
+    const cwd = resolve(process.cwd());
+    // Reads slots.json relative to cwd's shared-dir symlink (so works in linked worktrees too).
+    const filePath = join(registryDir, SLOTS_FILENAME);
+    if (!existsSync(filePath))
+        return undefined;
+    const registry = JSON.parse(readFileSync(filePath, "utf-8"));
+    for (const [port, entry] of Object.entries(registry.slots)) {
+        if (resolve(entry.worktree) === cwd) {
+            const resolved = {
+                slot: Number(port),
+                worktree: entry.worktree,
+                owner: entry.owner,
+            };
+            if (entry.main)
+                resolved.main = true;
+            return resolved;
+        }
+    }
+    return undefined;
+}
+function synthesizeMainSlot(basePort) {
+    const gitCommonDir = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf-8" }).trim();
+    const mainWorktree = dirname(gitCommonDir);
+    const cwd = resolve(process.cwd());
+    if (resolve(mainWorktree) !== cwd)
+        return undefined;
+    return { slot: basePort, worktree: cwd, main: true };
+}

package/dist/workspace.d.ts

@@ -0,0 +1,144 @@
+import { type SlotStatus } from "./slots.js";
+import { type WorktreeDirNameFn } from "./worktree.js";
+/** Configuration accepted by {@link runWorkspace}. */
+export interface WorkspaceConfig {
+    /**
+     * Absolute path to the wrapper script that calls `runWorkspace`. The package re-spawns this
+     * file as a detached child for the finalize phase, so it must point at a runnable Node entrypoint
+     * — typically `fileURLToPath(import.meta.url)` from your `workspace.mjs`.
+     */
+    scriptPath: string;
+    /**
+     * Absolute path to your dev-server script (the file that calls `runDevServer`). On
+     * `workspace remove`, the kernel shells out to `node <devServerScript> --stop` with
+     * `cwd: <target worktree>`. Typically
+     * `fileURLToPath(new URL('./dev-server.mjs', import.meta.url))` from your `workspace.mjs`.
+     */
+    devServerScript: string;
+    /** Anchor port for the slot range. Slots are derived from this value. */
+    basePort: number;
+    /** Distance between consecutive slots. Defaults to `10`. */
+    portStep?: number;
+    /** Maximum number of slots. Defaults to `19`. */
+    maxSlotCount?: number;
+    /** Custom port computation; takes precedence over `portNames`. */
+    ports?: (slot: number) => Record<string, number>;
+    /** Named offsets `[name0, name1, ...]` mapped to `slot+0`, `slot+1`, ... Required if `ports` is omitted. */
+    portNames?: string[];
+    /** Directories symlinked from the main worktree. */
+    sharedDirs: string[];
+    /**
+     * Per-worktree runtime directory, relative to the worktree root (e.g. `.local-wt`).
+     * Holds the setup log and dev-server logs.
+     */
+    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 listed in `sharedDirs` (e.g. `.local`).
+     */
+    registryDir: string;
+    /** Config files copied from the main worktree and patched per slot. */
+    configFiles: ConfigFileEntry[];
+    /**
+     * Runs before `configFiles` are copied. Use this to bootstrap source files the kernel expects
+     * to find (e.g. seed `config.json` from `config.example.json` on the main worktree, decrypt
+     * an env file). MUST be idempotent. On a linked-worktree setup, MUST NOT mutate the main
+     * worktree — bootstrap the main worktree first via `workspace setup`.
+     */
+    preSetup?: (ctx: PreSetupContext) => Promise<void> | void;
+    /**
+     * MUST be idempotent. After a failure, the user re-runs `workspace setup` from inside
+     * the worktree — this callback will be invoked again with the same context. Re-runs must not
+     * error on pre-existing state (created directories, started containers, ran migrations,
+     * 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.
+     */
+    finalizeWorktree: (ctx: SetupContext) => Promise<void> | void;
+    /**
+     * 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.
+     */
+    purgeInfrastructure?: (ctx: PurgeContext) => Promise<void> | void;
+    /** Builds the post-setup summary printed to stdout. */
+    printSummary: (ctx: SummaryContext) => string;
+    /**
+     * Optional override for the worktree directory basename. Receives `{ branch, repoName }` and
+     * returns the basename (e.g. `myrepo-feat-ABC-123`). Defaults to {@link defaultWorktreeDirName},
+     * which strips a recognizable ticket suffix and caps the slug at 22 chars. The kernel handles
+     * deduplication (`-2`, `-3`…) when the resulting directory already exists.
+     */
+    worktreeDirName?: WorktreeDirNameFn;
+}
+/** Context passed to {@link WorkspaceConfig.preSetup}. */
+export interface PreSetupContext {
+    currentWorktree: string;
+    mainWorktree: string;
+    /** `true` when running on the main worktree (i.e. `workspace setup` from the main checkout). */
+    isMainWorktree: boolean;
+    /** Mirrors `--force`. Hooks may use it to overwrite previously bootstrapped files. */
+    force: boolean;
+    /** Writes to stdout and the setup log. */
+    log: (msg: string) => void;
+}
+/** Context passed to {@link WorkspaceConfig.finalizeWorktree}. */
+export interface SetupContext {
+    currentWorktree: string;
+    mainWorktree: string;
+    /** `true` when finalizing the main worktree. Gate "copy from main" steps with `!isMainWorktree`. */
+    isMainWorktree: boolean;
+    slot: number;
+    /** Live-resolved branch of `currentWorktree`. `"(detached)"` for detached HEAD. */
+    branch: string;
+    owner?: string;
+    ports: Record<string, number>;
+    force: boolean;
+    verbose: boolean;
+}
+/**
+ * Context passed to {@link WorkspaceConfig.printSummary}.
+ *
+ * Called after worktree creation; the dev-server is not running yet.
+ */
+export interface SummaryContext {
+    slot: number;
+    /** Live-resolved branch of `currentWorktree`. `"(detached)"` for detached HEAD. */
+    branch: string;
+    owner?: string;
+    ports: Record<string, number>;
+    currentWorktree: string;
+    mainWorktree: string;
+    /** `true` when the summary describes the main worktree (slot = `basePort`). */
+    isMainWorktree: boolean;
+    /** Slot finalize status. `"pending"` until `finalizeWorktree` succeeds, then `"ready"`. */
+    status: SlotStatus;
+}
+/** Context passed to {@link WorkspaceConfig.purgeInfrastructure}. */
+export interface PurgeContext {
+    worktree: string;
+    mainWorktree: string;
+    verbose: boolean;
+}
+/** One config file copied from the main worktree and patched per slot. */
+export interface ConfigFileEntry {
+    /** Path relative to the worktree root. Same path is read from main and written to current. */
+    path: string;
+    /** Returns the patched content given the source content and the slot's ports. */
+    patch: (content: string, ctx: PatchContext) => string;
+    /**
+     * When `true`, a missing source on the main worktree 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`.
+     */
+    optional?: boolean;
+}
+/** Context passed to {@link ConfigFileEntry.patch}. */
+export interface PatchContext {
+    slot: number;
+    ports: Record<string, number>;
+    mainWorktree: string;
+    currentWorktree: string;
+}
+export declare function runWorkspace(config: WorkspaceConfig): Promise<void>;