@paleo/worktree-env 0.6.2 → 0.7.1

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/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/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

@@ -39,11 +39,21 @@ 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
      * 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;
     /**
@@ -61,6 +71,17 @@ export interface SetupWorktreeConfig {
      */
     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 {
     currentWorktree: string;
@@ -97,8 +118,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

@@ -88,6 +88,7 @@ async function runSetup(args, ctx, run, config) {
         scheme,
         branch,
         requestedOwner: args.owner,
+        isMainWorktree: setupCtx.isMainWorktree,
     });
     const ports = portsFn(slot);
     const runtimeDir = join(setupCtx.currentWorktree, config.runtimeDir);
@@ -111,6 +112,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({
@@ -199,8 +209,7 @@ function printWorktreeInfo(config, slot, worktreeForLog, fallback) {
     const ports = resolvePortsFn(config)(slot);
     const branch = entry?.branch ?? fallback.branch;
     const owner = entry?.owner ?? fallback.owner;
-    // Main worktree has no slot entry by design — treat it as ready when the registry has no row.
-    const slotStatus = entry?.status ?? (ctx.isMainWorktree ? "ready" : "pending");
+    const slotStatus = entry?.status ?? "pending";
     const logHint = ` (tail ${join(worktreeForLog, config.runtimeDir, "wt-setup.log")})`;
     const display = slotStatus === "ready"
         ? "ready"
@@ -377,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/slots.d.ts

@@ -30,6 +30,8 @@ export interface RegisterSlotInput {
     scheme: PortScheme;
     branch: string;
     requestedOwner?: string;
+    /** When `true`, the slot is forced to `scheme.basePort` regardless of `slot` arg. */
+    isMainWorktree: boolean;
 }
 export declare function resolveAndRegisterSlot(input: RegisterSlotInput): {
     port: number;

package/dist/slots.js

@@ -104,6 +104,8 @@ export function handleSetOwner(input) {
 }
 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)) {

package/dist/worktree.js

@@ -17,12 +17,7 @@ export function enforceWorktreeMode(args, ctx) {
             process.exit(1);
         }
     }
-    else if (args.here) {
-        if (ctx.isMainWorktree) {
-            console.error("Error: --here must be run from a linked worktree, not from the main worktree.");
-            process.exit(1);
-        }
-    }
+    // --here runs in any worktree: linked worktree (retry path) or main (initial bootstrap).
 }
 export function useExistingBranch(branch, ctx, run, dirNameFn = defaultWorktreeDirName) {
     if (!branchExists(branch)) {

package/package.json

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