@paleo/worktree-env 0.6.0 → 0.6.2

package/README.md

@@ -37,9 +37,12 @@ npm run setup-worktree -- --remove feat/42   # full teardown
 ## API
 
 ```ts
+import { fileURLToPath } from "node:url";
 import { runSetupWorktree, helpers } from "@paleo/worktree-env";
 
 await runSetupWorktree({
+  scriptPath: fileURLToPath(import.meta.url),
+  devServerScript: fileURLToPath(new URL("./dev-server.mjs", import.meta.url)),
   basePort: 8100,
   portNames: ["server", "frontend", "db"],
   sharedDirs: [".local", ".plans"],
@@ -77,6 +80,7 @@ await runDevServer({
   devLimit: 5,
   servers: [
     {
+      kind: "spawn",
       name: "dev",
       exec: { command: "npm", args: ["run", "dev"] },
       port: helpers.readPortFromEnvFile(".env", "PORT"),

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

@@ -60,8 +60,8 @@ function callbackServersOf(config) {
 async function start(config, mainWorktree, { evict }) {
     const ctx = { cwd: process.cwd() };
     await enforceCap(config, mainWorktree, evict);
-    await checkPortsFree(config.servers);
     checkNoLocalRegistryConflict(config, mainWorktree, ctx.cwd);
+    await checkPortsFree(config.servers);
     const spawnPids = {};
     const startedCallbacks = [];
     try {
@@ -126,6 +126,7 @@ async function rollbackStart(spawnPids, startedCallbacks, ctx) {
         }
     }
     for (const server of [...startedCallbacks].reverse()) {
+        console.log(`Stopping ${server.name}...`);
         try {
             await server.stop(ctx);
         }
@@ -205,6 +206,7 @@ async function stopLocal(config, mainWorktree) {
     }
     const callbacks = callbackServersOf(config);
     for (const server of [...callbacks].reverse()) {
+        console.log(`Stopping ${server.name}...`);
         try {
             await server.stop(ctx);
         }

package/dist/dev-servers-registry.js

@@ -59,6 +59,7 @@ export async function evictOldest(input) {
 }
 async function stopCallbacksForVictim(callbackServers, worktree) {
     for (const server of [...callbackServers].reverse()) {
+        console.log(`  ${server.name} (callback)`);
         try {
             await server.stop({ cwd: worktree });
         }

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/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`. */
@@ -38,13 +46,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 +53,13 @@ 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.finalizeWorktree}. */
 export interface SetupContext {
@@ -64,7 +72,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;

package/dist/setup-worktree.js

@@ -2,7 +2,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, symlinkSync, writeFileSync, } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { isFinalizeMode, isInfoMode, isRemoveMode, isSetOwnerMode, isSetupMode, isWaitMode, parseSetupArgs, printSetupHelp, validateSetupFlags, } from "./cli.js";
-import { removeDevServerEntryByWorktree } from "./dev-servers-registry.js";
+import { findOwnEntry, removeDevServerEntryByWorktree } from "./dev-servers-registry.js";
 import { ConfigError } from "./errors.js";
 import { copyAndPatchFile } from "./helpers.js";
 import { defaultComputePorts, isValidPort, resolvePortScheme } from "./ports.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,
@@ -123,6 +123,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],
@@ -287,7 +288,13 @@ async function handleRemove(args, ctx, run, config) {
         console.log(`Removed registry entry for branch "${target.branch}" (slot ${target.slotPort}${ownerSuffix}).`);
         return;
     }
-    stopTargetDevServer(config.devServerScript, target.worktreePath, verboseLog);
+    const targetEntry = findOwnEntry(ctx.mainWorktree, config.registryDir, target.worktreePath);
+    if (targetEntry) {
+        stopTargetDevServer(config.devServerScript, target.worktreePath, verboseLog);
+    }
+    else {
+        verboseLog(`No dev-server running in ${target.worktreePath}; skipping --stop.`);
+    }
     if (config.purgeInfrastructure) {
         await config.purgeInfrastructure({
             worktree: target.worktreePath,
@@ -339,11 +346,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) {

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.0",
+  "version": "0.6.2",
   "description": "Worktree-based concurrent local environment kernel.",
   "keywords": [
     "worktree",