@tablation/crew 0.25.0 → 0.26.0

package/crew.example.yaml

@@ -76,6 +76,12 @@ routes:
 
     worktreePrefix: "myproject-issue-"
 
+    # A repo may also be written as an object to name its worktree directory
+    # for this ship only (CREW-1504) — a template over {dir} {issue} {number}
+    # {key} {slug} {tag} {prefix} {role}. Outranks the repo's own
+    # `worktrees.name`, which outranks worktreePrefix; see docs/REPO_SPEC.md.
+    #   My Product: { dir: "/home/me/src/my-product", worktreeName: "{dir}-{issue}" }
+
     # Opt this route's ship into Host Passengers for this route's workspace
     # (ISSUE-644): `crew connect` syncs this onto that workspace's own Ships
     # row. Config-truth lives here, on the machine — never edit a Ships row

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { resolve as resolve4, dirname as dirname11, join as join20, basename as basename7 } from "path";
+import { resolve as resolve4, dirname as dirname11, join as join20, basename as basename8 } from "path";
 import { fileURLToPath } from "url";
 import { hostname as hostname2, homedir as homedir5 } from "os";
 import { spawnSync as spawnSync3 } from "child_process";
@@ -84,6 +84,27 @@ var TOP_LEVEL = /* @__PURE__ */ new Set([
 ]);
 var BRANCH_KEYS = /* @__PURE__ */ new Set(["base", "name", "push", "remote"]);
 var PLACEHOLDER = /\{(key|number|slug|role|prefix|tag)\}/g;
+var WORKTREE_PLACEHOLDERS = ["dir", "issue", "number", "key", "slug", "role", "prefix", "tag"];
+function worktreeNameProblem(template) {
+  const valid = `Valid placeholders: ${WORKTREE_PLACEHOLDERS.map((p) => `{${p}}`).join(" ")}.`;
+  if (template.trim() === "") return `must be a non-empty string. ${valid}`;
+  if (/[/\\]/.test(template)) {
+    return "must not contain a path separator \u2014 a worktree is cut beside the checkout, not inside a directory of its own";
+  }
+  const stripped = template.replace(/\{([^{}]*)\}/g, (_m, name) => {
+    if (!WORKTREE_PLACEHOLDERS.includes(name)) return "\0";
+    return "";
+  });
+  if (stripped.includes("\0")) {
+    const bad = [...template.matchAll(/\{([^{}]*)\}/g)].map((m) => m[1] ?? "").filter((n) => !WORKTREE_PLACEHOLDERS.includes(n));
+    return `names unknown placeholder ${bad.map((b) => `{${b}}`).join(", ")}. ${valid}`;
+  }
+  if (/[{}]/.test(stripped)) return `has an unbalanced brace. ${valid}`;
+  if (!/\{(issue|number|key|slug|tag)\}/.test(template)) {
+    return "names no per-ticket placeholder \u2014 every ticket would get the same worktree. Use at least one of {issue} {number} {key} {slug} {tag}.";
+  }
+  return null;
+}
 var RELEASE_KEYS = /* @__PURE__ */ new Set([
   "mode",
   "ship",
@@ -132,7 +153,7 @@ function parseRepoConfig(text, file) {
   rejectUnknown(raw.release?.ci, CI_KEYS, "release.ci", file);
   rejectUnknown(raw.release?.verify, VERIFY_KEYS, "release.verify", file);
   rejectUnknown(raw.branch, BRANCH_KEYS, "branch", file);
-  rejectUnknown(raw.worktrees, /* @__PURE__ */ new Set(["copy", "prefix"]), "worktrees", file);
+  rejectUnknown(raw.worktrees, /* @__PURE__ */ new Set(["copy", "prefix", "name"]), "worktrees", file);
   rejectUnknown(raw.docs, /* @__PURE__ */ new Set(["triagePolicy", "designGuide"]), "docs", file);
   if (raw.version === void 0) throw new RepoConfigError(`${file}: version is required`);
   if (raw.version !== SPEC_VERSION) {
@@ -167,7 +188,13 @@ function parseRepoConfig(text, file) {
       `${file}: worktrees.prefix ("${prefixRaw}") must not contain a path separator \u2014 a worktree is cut beside the checkout, not inside a directory of its own`
     );
   }
+  const nameRaw = raw.worktrees?.name;
+  if (nameRaw !== void 0) {
+    const problem = typeof nameRaw === "string" ? worktreeNameProblem(nameRaw) : "must be a string";
+    if (problem) throw new RepoConfigError(`${file}: worktrees.name ("${String(nameRaw)}") ${problem}`);
+  }
   const worktrees2 = {
+    ...nameRaw !== void 0 ? { name: String(nameRaw) } : {},
     copy: (copyRaw ?? []).map((c) => String(c)),
     // Empty means "not declared" here; the effective config fills it in, since
     // only that layer knows the ship's setting and the checkout's directory.
@@ -358,6 +385,10 @@ function renderBranchName(template, ctx) {
     }
   });
 }
+function renderWorktreeName(template, ctx) {
+  const issue = (ctx.tag ?? ctx.key).toLowerCase();
+  return renderBranchName(template.replace(/\{dir\}/g, ctx.dir).replace(/\{issue\}/g, issue), ctx);
+}
 function defaultWorktreePrefix(dir) {
   const name = basename(dir.replace(/[/\\]+$/, ""));
   return name ? `${name}-issue-` : "issue-";
@@ -389,6 +420,10 @@ function resolveRepoConfig(repo, ship, dir) {
     provenance[key] = "default";
     return fallback;
   };
+  if (ship?.worktrees?.nameOverride) {
+    if (repo?.worktrees.name) shadowed.push("worktrees.name");
+    provenance["worktrees.name"] = "ship";
+  } else if (repo?.worktrees.name) provenance["worktrees.name"] = "repo";
   const hooks = {};
   const labels = {};
   for (const h of HOOK_NAMES) {
@@ -424,7 +459,8 @@ function resolveRepoConfig(repo, ship, dir) {
         repo?.worktrees.prefix || void 0,
         ship?.worktrees?.prefix,
         defaultWorktreePrefix(dir)
-      )
+      ),
+      ...ship?.worktrees?.nameOverride || repo?.worktrees.name ? { name: ship?.worktrees?.nameOverride || repo?.worktrees.name } : {}
     },
     docs: repo?.docs ?? {},
     branch: {
@@ -525,7 +561,8 @@ function effectiveBranchTemplate(cfg, prefix) {
   if (cfg.provenance["branch.name"] !== "default") return cfg.branch.name;
   return prefix ? "{prefix}-{number}" : "issue-{number}";
 }
-function effectiveWorktreeDirName(cfg, dir, branchName, number) {
+function effectiveWorktreeDirName(cfg, dir, branchName, number, renderName) {
+  if (cfg.worktrees.name && renderName) return renderName(cfg.worktrees.name);
   if (cfg.provenance["worktrees.prefix"] !== "default") return `${cfg.worktrees.prefix}${number}`;
   return `${basename(dir.replace(/[/\\]+$/, ""))}-${branchName}`;
 }
@@ -623,7 +660,12 @@ var ROUTE_KEYS = /* @__PURE__ */ new Set([
   "promptSet",
   "hostPassengers"
 ]);
-var REPO_ENTRY_KEYS = /* @__PURE__ */ new Set(["dir", "hooks", "labels", "release", "branch", "hostPassengers"]);
+function parseWorktreeName(v, where, file) {
+  const problem = typeof v === "string" ? worktreeNameProblem(v) : "must be a string";
+  if (problem) throw new ConfigError(`${file}: ${where}.worktreeName ("${String(v)}") ${problem}`);
+  return String(v);
+}
+var REPO_ENTRY_KEYS = /* @__PURE__ */ new Set(["dir", "hooks", "labels", "release", "branch", "hostPassengers", "worktreeName"]);
 var BRANCH_OVERRIDE_KEYS = /* @__PURE__ */ new Set(["base", "name", "push", "remote"]);
 var RELEASE_OVERRIDE_KEYS = /* @__PURE__ */ new Set([
   "mode",
@@ -959,7 +1001,7 @@ function parseOneRoute(c, where, file, base, stateDir, raw, missing, crewHome) {
         const e = entry;
         rejectUnknownKeys(e, REPO_ENTRY_KEYS, `${where}.repos.${name}`, file);
         repoDirs[name] = expand(String(missing.req(e.dir, `${where}.repos.${name}.dir`) || ""), base);
-        if (e.hooks || e.labels || e.release || e.branch || e.hostPassengers !== void 0) {
+        if (e.hooks || e.labels || e.release || e.branch || e.hostPassengers !== void 0 || e.worktreeName !== void 0) {
           repoOverrides[name] = {
             hooks: e.hooks,
             labels: e.labels,
@@ -969,7 +1011,8 @@ function parseOneRoute(c, where, file, base, stateDir, raw, missing, crewHome) {
             // shape as one that never had the key, and existing callers
             // compare this literally.
             ...e.branch ? { branch: parseBranchOverride(e.branch, `${where}.repos.${name}`, file) } : {},
-            ...e.hostPassengers !== void 0 ? { hostPassengers: e.hostPassengers === true } : {}
+            ...e.hostPassengers !== void 0 ? { hostPassengers: e.hostPassengers === true } : {},
+            ...e.worktreeName !== void 0 ? { worktreeName: parseWorktreeName(e.worktreeName, `${where}.repos.${name}`, file) } : {}
           };
         }
       } else {
@@ -4661,6 +4704,7 @@ ${waiting.map((t) => `| ${displayKey2(t)} | ${t.status} | ${blockers(t, i)} |`).
 }
 
 // src/ticket-branch.ts
+import { basename as basename4 } from "path";
 function branchRenderer(t, role) {
   const { tag, prefix } = ticketBranchContext(t);
   return (template) => renderBranchName(template, { key: t.issue_id, title: t.title ?? void 0, role, tag, prefix });
@@ -4669,7 +4713,15 @@ function worktreeForTicket(dir, cfg, t, role) {
   const { prefix } = ticketBranchContext(t);
   const branchName = branchRenderer(t, role)(effectiveBranchTemplate(cfg, prefix));
   const number = t.issue_id.replace(/^\D+/, "");
-  return effectiveWorktreeDirName(cfg, dir, branchName, number);
+  const { tag } = ticketBranchContext(t);
+  return effectiveWorktreeDirName(cfg, dir, branchName, number, (template) => renderWorktreeName(template, {
+    dir: basename4(dir.replace(/[/\\]+$/, "")),
+    key: t.issue_id,
+    title: t.title ?? void 0,
+    role,
+    tag,
+    prefix
+  }));
 }
 function branchTemplates(cfg, t) {
   const { prefix } = ticketBranchContext(t);
@@ -4985,7 +5037,9 @@ function writeDigest(o, d, role, stateDir) {
     const repoFor = (dir) => {
       const hit = repoCache.get(dir);
       if (hit) return hit;
-      const cfg = resolveRepoConfig(loadRepoConfig(dir), void 0, dir);
+      const target = reposOf(o.route).find((r) => r.dir === dir);
+      const nameOverride = target ? o.route.repoOverrides[target.name]?.worktreeName : void 0;
+      const cfg = resolveRepoConfig(loadRepoConfig(dir), nameOverride ? { worktrees: { nameOverride } } : void 0, dir);
       repoCache.set(dir, cfg);
       return cfg;
     };
@@ -5350,7 +5404,7 @@ import { join as join7, dirname as dirname5 } from "path";
 import { createHash as createHash2 } from "crypto";
 
 // src/environment.ts
-import { basename as basename4 } from "path";
+import { basename as basename5 } from "path";
 var API_KEY_VAR = "CREW_API_KEY";
 function authorshipBullets(a, contract) {
   if (!a) return [];
@@ -5401,8 +5455,16 @@ function repoSection(r, key, heading) {
   const repo = r.config;
   const branchTemplate = effectiveBranchTemplate(repo, repoPrefix(repo));
   const branchName = branchExample(repo, key);
-  const worktreeName = effectiveWorktreeDirName(repo, r.dir, branchName, key.replace(/^\D+/, ""));
-  const worktreePattern = repo.provenance["worktrees.prefix"] !== "default" ? `${repo.worktrees.prefix}<number>` : `${basename4(r.dir.replace(/[/\\]+$/, ""))}-<branch>`;
+  const checkoutName = basename5(r.dir.replace(/[/\\]+$/, ""));
+  const worktreeName = effectiveWorktreeDirName(
+    repo,
+    r.dir,
+    branchName,
+    key.replace(/^\D+/, ""),
+    // The example ticket has no tag of its own, so `{issue}` is the key.
+    (template) => renderWorktreeName(template, { dir: checkoutName, key, title: "Fix the widget", role: "dev", prefix: repoPrefix(repo) })
+  );
+  const worktreePattern = repo.worktrees.name ?? (repo.provenance["worktrees.prefix"] !== "default" ? `${repo.worktrees.prefix}<number>` : `${checkoutName}-<branch>`);
   const lines = [
     "",
     heading,
@@ -6375,7 +6437,8 @@ async function guardRunHandoff(route, ship, tracker, role, workingId, log) {
     const cfg = resolveRepoConfig(loadRepoConfig(target.dir), {
       hooks: { ...route.hooks, ...o?.hooks },
       labels: { ...route.labels, ...o?.labels },
-      branch: { ...route.branch, ...o?.branch }
+      branch: { ...route.branch, ...o?.branch },
+      worktrees: { nameOverride: o?.worktreeName }
     }, target.dir);
     if (role === "qa") {
       await retireRunWorktree(tracker, target.dir, cfg, t, role, seatId, ship.name, log);
@@ -9032,7 +9095,7 @@ async function showLogEntry(route, entryId, opts = {}) {
 
 // src/repos-cmd.ts
 import { homedir as homedir3 } from "os";
-import { basename as basename5, resolve as resolve3 } from "path";
+import { basename as basename6, resolve as resolve3 } from "path";
 import { isMap, isSeq, parseDocument, stringify as stringify2 } from "yaml";
 var ReposError = class extends Error {
 };
@@ -9104,7 +9167,7 @@ function configuredRepos(text, route, base) {
     });
   }
   const dir = m.get("dir");
-  return dir ? [{ name: basename5(String(dir)), dir: expandDir(String(dir), base) }] : [];
+  return dir ? [{ name: basename6(String(dir)), dir: expandDir(String(dir), base) }] : [];
 }
 function planRepoAdd(i) {
   const doc = parseDocument(i.text);
@@ -9116,7 +9179,7 @@ function planRepoAdd(i) {
     throw new ReposError(`${target} is already configured on route ${i.route}`);
   }
   const matched = matchRepoName(i.origin, i.resolved);
-  const name = matched ?? i.name ?? normalizeRemote(i.origin)?.split("/").pop() ?? basename5(target);
+  const name = matched ?? i.name ?? normalizeRemote(i.origin)?.split("/").pop() ?? basename6(target);
   let warning;
   if (!matched) {
     const known = Object.values(i.resolved?.repoNames ?? {});
@@ -9280,14 +9343,14 @@ function schedulerInstalled(plan, exists, crontab) {
 
 // src/worktree-sweep.ts
 import { existsSync as existsSync15 } from "fs";
-import { basename as basename6 } from "path";
+import { basename as basename7 } from "path";
 function planWorktreeSweep(target, tickets, contract) {
   const terminal = new Set(contract.statuses.resolved.filter((s) => s !== contract.statuses.verified));
   const verified = contract.statuses.verified;
   const byNumber = new Map(tickets.map((t) => [t.issue_id.replace(/^\D+/, ""), t]));
   const actions = [];
   for (const w of worktrees(target.dir)) {
-    const m = /(?:^|-)(\d+)$/.exec(basename6(w.path));
+    const m = /(?:^|-)(\d+)$/.exec(basename7(w.path));
     if (!m) continue;
     const ticket = byNumber.get(m[1]);
     if (!ticket) continue;
@@ -10490,7 +10553,8 @@ async function buildEnvironment(route, ship, ticket) {
       config: resolveRepoConfig(loadRepoConfig(t.dir), {
         hooks: { ...route.hooks, ...o?.hooks },
         labels: { ...route.labels, ...o?.labels },
-        branch: { ...route.branch, ...o?.branch }
+        branch: { ...route.branch, ...o?.branch },
+        worktrees: { nameOverride: o?.worktreeName }
       }, t.dir)
     };
   });
@@ -11085,7 +11149,7 @@ ${changed2.map((c) => `  - ${c}
           // that declares its own `worktrees.prefix` shadows either, and
           // `doctor` reports that the way it reports every other shadowed
           // setting.
-          worktrees: { prefix: shipWorktreePrefixFor(c) ?? await areaWorktreePrefix(c, id) }
+          worktrees: { prefix: shipWorktreePrefixFor(c) ?? await areaWorktreePrefix(c, id), nameOverride: o?.worktreeName }
         }, t.dir)
       };
     }));
@@ -11142,7 +11206,7 @@ ${changed2.map((c) => `  - ${c}
         labels: { ...c.labels, ...o?.labels },
         release: mergeRouteRelease(c.release, o?.release),
         branch: { ...c.branch, ...o?.branch },
-        worktrees: { prefix: shipWorktreePrefixFor(c) }
+        worktrees: { prefix: shipWorktreePrefixFor(c), nameOverride: o?.worktreeName }
       }, target.dir);
       const problems = validateEffective(repo);
       for (const p of problems) remit.warn(`${scope}: ${p}`);
@@ -13195,7 +13259,7 @@ Signed in as ${result.identity.email} \u2014 minted an API key in workspace "${r
               // `synthesis-tabl-123`. `worktreePrefix` above is kept for
               // config-provenance display; this is the field that actually
               // describes where a worktree lands by default.
-              worktreeDirPattern: r.config.provenance["worktrees.prefix"] !== "default" ? `${r.config.worktrees.prefix}<number>` : `${basename7(r.dir.replace(/[/\\]+$/, ""))}-<branch>`,
+              worktreeDirPattern: r.config.worktrees.name ?? (r.config.provenance["worktrees.prefix"] !== "default" ? `${r.config.worktrees.prefix}<number>` : `${basename8(r.dir.replace(/[/\\]+$/, ""))}-<branch>`),
               worktreeParent: resolvePath(r.dir, "..")
             })),
             waiting: waiting ? { ticket: waiting.ticket, since: waiting.since, streak: fairness.streak() } : null
@@ -13294,10 +13358,10 @@ routes:            ${cfg.routes.map((c) => c.route).join(", ")}
       );
       for (const r of await resolvedRepos(route)) {
         const { config } = r;
-        const worktreePattern = config.provenance["worktrees.prefix"] !== "default" ? `${config.worktrees.prefix}<number>` : `${basename7(r.dir.replace(/[/\\]+$/, ""))}-${effectiveBranchTemplate(config, void 0)}`;
+        const worktreePattern = config.worktrees.name ?? (config.provenance["worktrees.prefix"] !== "default" ? `${config.worktrees.prefix}<number>` : `${basename8(r.dir.replace(/[/\\]+$/, ""))}-${effectiveBranchTemplate(config, void 0)}`);
         process.stdout.write(
           `${`repo ${r.name}:`.padEnd(19)}${r.dir}
-                   worktrees at ../${worktreePattern} (${config.provenance["worktrees.prefix"] ?? "default"}), branch ${config.branch.name}
+                   worktrees at ../${worktreePattern} (${config.provenance["worktrees.name"] ?? config.provenance["worktrees.prefix"] ?? "default"}), branch ${config.branch.name}
                    requires ${config.platform} \u2014 ${satisfies(host, config.platform) ? "OK" : "MISMATCH"}
 `
         );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tablation/crew",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "A standing team of headless agents that picks work off a Tablation board, does it on a machine you control, and reports back.",
   "type": "module",
   "license": "MIT",