@paleo/worktree-env 0.6.1 → 0.7.0

package/README.md

@@ -58,6 +58,11 @@ await runSetupWorktree({
         }),
     },
   ],
+  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 `setup-worktree --here`.
+  },
   finalizeWorktree: async ({ currentWorktree }) => {
     // MUST be idempotent. Install deps, start containers, seed a database, etc.
   },
@@ -68,6 +73,8 @@ await runSetupWorktree({
 
 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 `setup-worktree --here` — it is idempotent and retries the finalize step. To block until Part 2 finishes (CI, agent orchestration), run `setup-worktree --wait` from inside the worktree (or `setup-worktree --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 `setup-worktree --here` 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

package/dist/cli.js

@@ -2,15 +2,15 @@ import { parseArgs } from "node:util";
 import { ConfigError } from "./errors.js";
 const SETUP_OPTIONS = {
     help: { type: "boolean", short: "h", description: "Show this help message" },
-    use: {
+    create: {
         type: "string",
         arg: "branch",
-        description: "Create a worktree for an existing branch, then set up the local environment",
+        description: "Create a new branch + worktree, then set up the local environment. If the branch already exists, appends a numeric suffix (-2, -3, ...)",
     },
-    create: {
+    use: {
         type: "string",
         arg: "branch",
-        description: "Create a new branch + worktree, then set up the local environment. If the branch already exists, appends a numeric suffix (-2, -3, ...)",
+        description: "Create a worktree for an existing branch, then set up the local environment",
     },
     here: {
         type: "boolean",

package/dist/dev-server.js

@@ -5,6 +5,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 } from "./helpers.js";
 import { awaitAllReady, handleStartupFailure } from "./log-polling.js";
 import { isProcessAlive, stopProcessGroup } from "./process-control.js";
 import { resolveCurrentSlot } from "./slots.js";
@@ -80,7 +81,7 @@ async function start(config, mainWorktree, { evict }) {
             name: s.name,
             logFile: logFileFor(config.runtimeDir, s.name),
             detectSuccess: s.detectSuccess,
-            detectError: s.detectError,
+            detectError: s.detectError ?? detectCommonJsError,
         }));
         const pollPids = spawnEntries.map((s) => spawnPids[s.name]);
         await awaitAllReady(pollables, pollPids);

package/dist/helpers.d.ts

@@ -15,4 +15,11 @@ export interface CopyAndPatchCtx {
     mainWorktree: string;
     log: (msg: string) => void;
 }
-export declare function copyAndPatchFile(ctx: CopyAndPatchCtx, relPath: string, patchFn: (content: string) => string, label: string, force: boolean, required?: boolean): void;
+export declare function copyAndPatchFile(ctx: CopyAndPatchCtx, relPath: string, patchFn: (content: string) => string, label: string, force: boolean, optional?: boolean): void;
+/**
+ * Detects common fatal JS startup failures in a log buffer. Returns a short marker string
+ * naming the matched pattern, or `false` when none match. Used as the default `detectError`
+ * for spawn servers that don't supply one. A custom `detectError` can compose with this:
+ * `detectError: (log) => myDetector(log) || helpers.detectCommonJsError(log)`.
+ */
+export declare function detectCommonJsError(log: string): string | false;

package/dist/helpers.js

@@ -59,7 +59,7 @@ export function readPortFromJsonFile(file, jsonPath) {
     }
     return toPort(String(cur), file);
 }
-export function copyAndPatchFile(ctx, relPath, patchFn, label, force, required = false) {
+export function copyAndPatchFile(ctx, relPath, patchFn, label, force, optional = false) {
     const targetPath = join(ctx.currentWorktree, relPath);
     const sourcePath = join(ctx.mainWorktree, relPath);
     const alreadyExists = existsSync(targetPath);
@@ -68,11 +68,12 @@ export function copyAndPatchFile(ctx, relPath, patchFn, label, force, required =
         return;
     }
     if (!existsSync(sourcePath)) {
-        if (required) {
-            console.error(`Error: ${relPath} not found in main worktree (required).`);
+        if (!optional) {
+            console.error(`Error: ${relPath} not found in main worktree. Bootstrap the main worktree first ` +
+                "(setup-worktree --here), or mark the entry as optional.");
             process.exit(1);
         }
-        ctx.log(`Warning: ${relPath} not found in main worktree, skipping.`);
+        ctx.log(`Warning: ${relPath} not found in main worktree, skipping (optional).`);
         return;
     }
     const content = readFileSync(sourcePath, "utf-8");
@@ -81,6 +82,25 @@ export function copyAndPatchFile(ctx, relPath, patchFn, label, force, required =
     writeFileSync(targetPath, patched);
     ctx.log(`${alreadyExists ? "Overwritten" : "Created"} ${label}.`);
 }
+/**
+ * Detects common fatal JS startup failures in a log buffer. Returns a short marker string
+ * naming the matched pattern, or `false` when none match. Used as the default `detectError`
+ * for spawn servers that don't supply one. A custom `detectError` can compose with this:
+ * `detectError: (log) => myDetector(log) || helpers.detectCommonJsError(log)`.
+ */
+export function detectCommonJsError(log) {
+    if (log.includes("[nodemon] app crashed"))
+        return "[nodemon] app crashed";
+    if (/^Node\.js v/m.test(log))
+        return "Node.js v";
+    if (log.includes("Error: Cannot find module "))
+        return "Error: Cannot find module";
+    if (/^SyntaxError: /m.test(log))
+        return "SyntaxError";
+    if (log.includes("UnhandledPromiseRejection"))
+        return "UnhandledPromiseRejection";
+    return false;
+}
 function toPort(raw, file) {
     const port = Number(raw);
     if (!Number.isFinite(port)) {

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { runSetupWorktree } from "./setup-worktree.js";
+export { defaultWorktreeDirName } from "./worktree.js";
+export type { WorktreeDirNameFn } from "./worktree.js";
 export type { SetupWorktreeConfig, SetupContext, SummaryContext, PatchContext, ConfigFileEntry, PurgeContext, } from "./setup-worktree.js";
 export { runDevServer } from "./dev-server.js";
 export type { DevServerConfig, DevServerSummaryContext, ServerDescriptor, ServerContext, SpawnServer, CallbackServer, } from "./dev-server.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { runSetupWorktree } from "./setup-worktree.js";
+export { defaultWorktreeDirName } from "./worktree.js";
 export { runDevServer } from "./dev-server.js";
 import * as helpers from "./helpers.js";
 export { helpers };

package/dist/server-descriptor.d.ts

@@ -22,7 +22,11 @@ export interface SpawnServer {
     port: number;
     /** Returns `true` once the log content indicates the server is ready. */
     detectSuccess: (logContent: string) => boolean;
-    /** Returns a non-empty marker string when the log content indicates a fatal error, or `false`. */
+    /**
+     * Returns a non-empty marker string when the log content indicates a fatal error, or `false`.
+     * When omitted, `helpers.detectCommonJsError` is used as a default. To disable detection,
+     * pass `() => false`.
+     */
     detectError?: (logContent: string) => string | false;
 }
 /**

package/dist/setup-worktree.d.ts

@@ -1,3 +1,4 @@
+import { type WorktreeDirNameFn } from "./worktree.js";
 /** Configuration accepted by {@link runSetupWorktree}. */
 export interface SetupWorktreeConfig {
     /**
@@ -6,6 +7,13 @@ export interface SetupWorktreeConfig {
      * — typically `fileURLToPath(import.meta.url)` from your `setup-worktree.mjs`.
      */
     scriptPath: string;
+    /**
+     * Absolute path to your dev-server script (the file that calls `runDevServer`). On `--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
+     * `setup-worktree.mjs`.
+     */
+    devServerScript: string;
     /** Anchor port for the slot range. Slots are derived from this value. */
     basePort: number;
     /** Distance between consecutive slots. Defaults to `10`. */
@@ -31,6 +39,13 @@ export interface SetupWorktreeConfig {
     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 `setup-worktree --here`.
+     */
+    preSetup?: (ctx: PreSetupContext) => Promise<void> | void;
     /**
      * MUST be idempotent. After a failure, the user re-runs `setup-worktree --here` from inside
      * the worktree — this callback will be invoked again with the same context. Re-runs must not
@@ -38,13 +53,6 @@ export interface SetupWorktreeConfig {
      * installed deps, etc.).
      */
     finalizeWorktree: (ctx: SetupContext) => Promise<void> | void;
-    /**
-     * Absolute path to your dev-server script (the file that calls `runDevServer`). On `--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
-     * `setup-worktree.mjs`.
-     */
-    devServerScript: string;
     /**
      * Destructive infrastructure teardown on `--remove` (e.g. `docker compose down -v` to wipe
      * volumes). Runs after the dev-server stop. Best-effort; errors should be swallowed.
@@ -52,6 +60,24 @@ export interface SetupWorktreeConfig {
     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 SetupWorktreeConfig.preSetup}. */
+export interface PreSetupContext {
+    currentWorktree: string;
+    mainWorktree: string;
+    /** `true` when running on the main worktree (i.e. `--here` 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 SetupWorktreeConfig.finalizeWorktree}. */
 export interface SetupContext {
@@ -64,7 +90,11 @@ export interface SetupContext {
     force: boolean;
     verbose: boolean;
 }
-/** Context passed to {@link SetupWorktreeConfig.printSummary}. */
+/**
+ * Context passed to {@link SetupWorktreeConfig.printSummary}.
+ *
+ * Called after worktree creation; the dev-server is not running yet.
+ */
 export interface SummaryContext {
     slot: number;
     branch: string;
@@ -85,8 +115,12 @@ export interface ConfigFileEntry {
     path: string;
     /** Returns the patched content given the source content and the slot's ports. */
     patch: (content: string, ctx: PatchContext) => string;
-    /** When `true`, abort if the source file is missing in the main worktree. Defaults to `false`. */
-    required?: boolean;
+    /**
+     * 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
+     * `setup-worktree --here`, or seed sources in `preSetup`.
+     */
+    optional?: boolean;
 }
 /** Context passed to {@link ConfigFileEntry.patch}. */
 export interface PatchContext {

package/dist/setup-worktree.js

@@ -78,7 +78,7 @@ async function runSetup(args, ctx, run, config) {
         registryDir: config.registryDir,
         scheme,
     });
-    const setupCtx = ensureWorktree(args, ctx, run);
+    const setupCtx = ensureWorktree(args, ctx, run, config.worktreeDirName);
     const branch = getCurrentBranch(setupCtx.currentWorktree);
     const { port: slot, owner } = resolveAndRegisterSlot({
         slot: args.slot,
@@ -111,6 +111,15 @@ async function runSetup(args, ctx, run, config) {
     verboseLog(`Using slot ${slot} (${Object.entries(ports)
         .map(([k, v]) => `${k}: ${v}`)
         .join(", ")})`);
+    if (config.preSetup) {
+        await config.preSetup({
+            currentWorktree: setupCtx.currentWorktree,
+            mainWorktree: setupCtx.mainWorktree,
+            isMainWorktree: setupCtx.isMainWorktree,
+            force: args.force ?? false,
+            log: teeLog,
+        });
+    }
     linkSharedDirectories(setupCtx, config.sharedDirs, verboseLog);
     generateConfigFiles(setupCtx, config.configFiles, slot, ports, args.force ?? false, verboseLog);
     teeLog(config.printSummary({
@@ -123,6 +132,7 @@ async function runSetup(args, ctx, run, config) {
     }));
     teeLog(`WORKTREE_CREATED path=${setupCtx.currentWorktree} branch=${branch} slot=${slot}`);
     teeLog(`Setup continuing in background. Tail: ${logPath}`);
+    teeLog(`Block until ready: setup-worktree --wait --slot ${slot}`);
     const child = spawn(process.execPath, [config.scriptPath, "--__finalize", String(slot)], {
         detached: true,
         stdio: ["ignore", logFd, logFd],
@@ -345,11 +355,11 @@ function handleSetOwnerMode(args, ctx, config) {
     }
     console.log(`Owner for slot ${slotPort}: ${newOwner ?? "(none)"}`);
 }
-function ensureWorktree(args, ctx, run) {
+function ensureWorktree(args, ctx, run, dirNameFn) {
     if (args.use)
-        return useExistingBranch(args.use, ctx, run);
+        return useExistingBranch(args.use, ctx, run, dirNameFn);
     if (args.create)
-        return createBranch(args.create, ctx, run);
+        return createBranch(args.create, ctx, run, dirNameFn);
     return ctx;
 }
 function linkSharedDirectories(ctx, dirs, log) {
@@ -376,7 +386,7 @@ function generateConfigFiles(ctx, entries, slot, ports, force, log) {
             ports,
             mainWorktree: ctx.mainWorktree,
             currentWorktree: ctx.currentWorktree,
-        }), entry.path, force, entry.required ?? false);
+        }), entry.path, force, entry.optional ?? false);
     }
 }
 function resolveRemoveTarget(args, ctx, registry, removeHere) {

package/dist/worktree.d.ts

@@ -12,9 +12,20 @@ export declare function enforceWorktreeMode(args: {
     create?: string;
     here?: boolean;
 }, ctx: WorktreeContext): void;
-export declare function useExistingBranch(branch: string, ctx: WorktreeContext, run: RunCtx): WorktreeContext;
-export declare function createBranch(requestedBranch: string, ctx: WorktreeContext, run: RunCtx): WorktreeContext;
+export declare function useExistingBranch(branch: string, ctx: WorktreeContext, run: RunCtx, dirNameFn?: WorktreeDirNameFn): WorktreeContext;
+export declare function createBranch(requestedBranch: string, ctx: WorktreeContext, run: RunCtx, dirNameFn?: WorktreeDirNameFn): WorktreeContext;
 export declare function verifyBranchAbsentFromRemote(branch: string, run: RunCtx): void;
 export declare function getCurrentBranch(worktreePath: string): string;
 export declare function removeWorktree(worktreePath: string, run: RunCtx): void;
-export declare function computeWorktreePath(mainWorktree: string, branch: string): string;
+/** Pure function that produces the basename of a worktree directory from a branch. */
+export type WorktreeDirNameFn = (opts: {
+    branch: string;
+    repoName: string;
+}) => string;
+/**
+ * Default {@link WorktreeDirNameFn}. Strips a recognizable ticket suffix from the last branch
+ * segment (`feat/ABC-123-extra` → `feat-ABC-123`), caps the result at 22 chars, and strips
+ * trailing dashes. Falls back to the full sanitized branch when no ticket pattern is found.
+ */
+export declare const defaultWorktreeDirName: WorktreeDirNameFn;
+export declare function computeWorktreePath(mainWorktree: string, branch: string, dirNameFn?: WorktreeDirNameFn): string;

package/dist/worktree.js

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 export function detectWorktree() {
     const currentWorktree = execFileSync("git", ["rev-parse", "--show-toplevel"], {
@@ -23,16 +24,16 @@ export function enforceWorktreeMode(args, ctx) {
         }
     }
 }
-export function useExistingBranch(branch, ctx, run) {
+export function useExistingBranch(branch, ctx, run, dirNameFn = defaultWorktreeDirName) {
     if (!branchExists(branch)) {
         console.error(`Error: Branch "${branch}" does not exist locally or on the remote.`);
         process.exit(1);
     }
-    const worktreePath = computeWorktreePath(ctx.mainWorktree, branch);
+    const worktreePath = dedupeWorktreePath(computeWorktreePath(ctx.mainWorktree, branch, dirNameFn));
     execFileSync("git", ["worktree", "add", worktreePath, branch], { stdio: stdioFor(run) });
     return { ...ctx, currentWorktree: worktreePath, isMainWorktree: false };
 }
-export function createBranch(requestedBranch, ctx, run) {
+export function createBranch(requestedBranch, ctx, run, dirNameFn = defaultWorktreeDirName) {
     let finalBranch = requestedBranch;
     if (branchExists(finalBranch)) {
         let suffix = 2;
@@ -42,7 +43,7 @@ export function createBranch(requestedBranch, ctx, run) {
         finalBranch = `${requestedBranch}-${suffix}`;
         console.warn(`Warning: Branch "${requestedBranch}" already exists; using "${finalBranch}" instead.`);
     }
-    const worktreePath = computeWorktreePath(ctx.mainWorktree, finalBranch);
+    const worktreePath = dedupeWorktreePath(computeWorktreePath(ctx.mainWorktree, finalBranch, dirNameFn));
     execFileSync("git", ["worktree", "add", "-b", finalBranch, worktreePath], {
         stdio: stdioFor(run),
     });
@@ -67,10 +68,39 @@ export function getCurrentBranch(worktreePath) {
 export function removeWorktree(worktreePath, run) {
     execFileSync("git", ["worktree", "remove", "--force", worktreePath], { stdio: stdioFor(run) });
 }
-export function computeWorktreePath(mainWorktree, branch) {
+/**
+ * Default {@link WorktreeDirNameFn}. Strips a recognizable ticket suffix from the last branch
+ * segment (`feat/ABC-123-extra` → `feat-ABC-123`), caps the result at 22 chars, and strips
+ * trailing dashes. Falls back to the full sanitized branch when no ticket pattern is found.
+ */
+export const defaultWorktreeDirName = ({ branch, repoName }) => {
+    return `${repoName}-${shortenBranchSegment(branch)}`;
+};
+function shortenBranchSegment(branch) {
+    const parts = branch.split("/");
+    const last = parts[parts.length - 1] ?? "";
+    const match = last.match(/^([A-Za-z]+-\d+|\d+)/);
+    if (match) {
+        parts[parts.length - 1] = match[1];
+    }
+    let result = parts.join("-");
+    if (result.length > 22) {
+        result = result.slice(0, 22);
+    }
+    return result.replace(/-+$/, "");
+}
+export function computeWorktreePath(mainWorktree, branch, dirNameFn = defaultWorktreeDirName) {
     const repoName = basename(mainWorktree);
-    const sanitized = branch.replaceAll("/", "-");
-    return join(dirname(mainWorktree), `${repoName}-${sanitized}`);
+    return join(dirname(mainWorktree), dirNameFn({ branch, repoName }));
+}
+function dedupeWorktreePath(candidate) {
+    if (!existsSync(candidate))
+        return candidate;
+    let suffix = 2;
+    while (existsSync(`${candidate}-${suffix}`)) {
+        ++suffix;
+    }
+    return `${candidate}-${suffix}`;
 }
 function branchExists(branch) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paleo/worktree-env",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Worktree-based concurrent local environment kernel.",
   "keywords": [
     "worktree",