@paleo/worktree-env 0.6.1 → 0.6.2

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

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