@bongos/core 1.19.120 → 1.19.122

package/scripts/gds/worktree.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+// scripts/gds/worktree.js — junction-safe worktree lifecycle (task 1002809).
+//
+// The trap this kills: a worktree OUTSIDE the repo root (C:/tmp/wt-N — used to
+// dodge OneDrive file locks) can't resolve node_modules by walking up, so
+// Windows builders hand-made junctions with `cmd //c mklink` from Git Bash —
+// which mangles quoted targets containing spaces (dead junction) — and then
+// `git worktree remove` FOLLOWED the junction and deleted the SHARED
+// node_modules of the main checkout. This helper creates junctions with
+// fs.symlinkSync(..., 'junction') (no shell, no quoting) and always removes the
+// junction BEFORE git worktree remove. Worktrees INSIDE the repo
+// (.claude/worktrees/<name>, the project default) need no junction at all.
+//
+// Usage:
+//   node scripts/gds/worktree.js add <task-id|name> [--path <dir> | --outside] [--base <ref>]
+//   node scripts/gds/worktree.js remove <name|path> [--force]
+//   node scripts/gds/worktree.js list
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { arg, hasFlag } = require('./cli-lib');
+
+// -- pure helpers (exported for tests/worktree_helper.mjs) --------------------
+
+// A numeric task id becomes the conventional task-<id>; an explicit name passes
+// through; anything with path separators or dot-traversal is rejected (null).
+function worktreeNameFor(raw) {
+  const s = String(raw == null ? '' : raw).trim();
+  if (!s || s === '.' || s === '..') return null;
+  if (/^\d+$/.test(s)) return `task-${s}`;
+  if (!/^[A-Za-z0-9._-]+$/.test(s)) return null;
+  return s;
+}
+
+// Is the worktree OUTSIDE the repo root? Inside the repo, node's resolution
+// walks up to the main checkout's node_modules; outside it can't. Pure string
+// compare (case-insensitive, both slash styles); callers pass absolute paths.
+function isOutsideRepo({ wtPath, repoRoot }) {
+  const norm = (p) => String(p).replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+  const wt = norm(wtPath);
+  const root = norm(repoRoot);
+  return !(wt === root || wt.startsWith(root + '/'));
+}
+
+// Only a win32 worktree outside the repo root gets a junction (the OneDrive
+// dodge); posix symlink semantics differ and aren't the trap this fixes.
+function needsJunction({ wtPath, repoRoot, platform }) {
+  if (platform !== 'win32') return false;
+  return isOutsideRepo({ wtPath, repoRoot });
+}
+
+// Ordered removal steps. The junction MUST go before git worktree remove (git
+// follows it into the shared node_modules); a REAL node_modules dir is left for
+// git to refuse — this tool never deletes real directories.
+function removalPlan({ nodeModulesState }) {
+  return nodeModulesState === 'junction'
+    ? ['unlink-junction', 'git-worktree-remove']
+    : ['git-worktree-remove'];
+}
+
+// -- CLI ----------------------------------------------------------------------
+
+function git(args, opts = {}) {
+  return execFileSync('git', args, { encoding: 'utf8', ...opts }).trim();
+}
+
+// Main checkout root from any worktree — same derivation as merge-lock.js.
+function mainWorktreeRoot() {
+  const common = git(['rev-parse', '--git-common-dir']);
+  const abs = path.isAbsolute(common) ? common : path.resolve(process.cwd(), common);
+  return path.dirname(abs);
+}
+
+function listWorktrees(root) {
+  const out = git(['worktree', 'list', '--porcelain'], { cwd: root });
+  return out.split('\n').filter((l) => l.startsWith('worktree ')).map((l) => l.slice('worktree '.length));
+}
+
+function nodeModulesState(wtPath) {
+  const p = path.join(wtPath, 'node_modules');
+  let st;
+  try { st = fs.lstatSync(p); } catch (_) { return 'absent'; }
+  return st.isSymbolicLink() ? 'junction' : 'real-dir';
+}
+
+function resolveWorktreePath(root, nameOrPath) {
+  const all = listWorktrees(root);
+  const norm = (p) => path.resolve(p).replace(/\\/g, '/').toLowerCase();
+  const byPath = all.find((w) => norm(w) === norm(nameOrPath));
+  if (byPath) return byPath;
+  // Case-insensitive, matching the filesystem (and the byPath compare above).
+  const byName = all.filter((w) => path.basename(w).toLowerCase() === String(nameOrPath).toLowerCase());
+  if (byName.length === 1) return byName[0];
+  if (byName.length > 1) {
+    console.error(`worktree: "${nameOrPath}" matches ${byName.length} worktrees — pass the full path:`);
+    for (const w of byName) console.error(`  ${w}`);
+    process.exit(2);
+  }
+  return null;
+}
+
+function cmdAdd(root, argv) {
+  const name = worktreeNameFor(argv[1]);
+  if (!name) {
+    console.error('worktree add: pass a task id (→ task-<id>) or a simple name (letters/digits/._-).');
+    process.exit(2);
+  }
+  const explicitPath = arg('--path', argv);
+  const outside = hasFlag('--outside', argv);
+  // --outside exists to dodge OneDrive file locks — a Windows problem. On posix
+  // an outside-repo worktree would just lose node_modules resolution (no
+  // junction is created there), so refuse rather than hand back a silently
+  // broken tree; the in-repo default works everywhere.
+  if (outside && process.platform !== 'win32') {
+    console.error('worktree add: --outside is a Windows OneDrive dodge; use the default in-repo location here');
+    console.error('  (an outside-repo worktree on this platform cannot resolve the shared node_modules).');
+    process.exit(2);
+  }
+  const wtPath = path.resolve(explicitPath
+    || (outside ? path.join('C:/tmp', name)
+                : path.join(root, '.claude', 'worktrees', name)));
+  // Default base origin/main so the branch starts current; best-effort fetch
+  // first (offline still works off the local ref).
+  const base = arg('--base', argv) || 'origin/main';
+  try { execFileSync('git', ['fetch', 'origin', 'main'], { cwd: root, stdio: 'ignore', timeout: 15000 }); } catch (_) { /* offline is fine */ }
+
+  console.log(`worktree add: ${wtPath}  (branch ${name}, base ${base})`);
+  try {
+    execFileSync('git', ['worktree', 'add', wtPath, '-b', name, base], { cwd: root, stdio: 'inherit' });
+  } catch (e) {
+    console.error(`worktree add failed — ${e.message}`);
+    console.error('  (a branch of that name may already exist: remove it or pick another name)');
+    process.exit(1);
+  }
+
+  if (needsJunction({ wtPath, repoRoot: root, platform: process.platform })) {
+    const target = path.join(root, 'node_modules');
+    if (!fs.existsSync(target)) {
+      console.error(`⚠ ${target} does not exist — run npm install in the MAIN checkout first`);
+      console.error('  (worktrees never get their own node_modules; they share the main one).');
+    } else {
+      // fs.symlinkSync with type 'junction' needs no shell and no elevation —
+      // this is the fix for the mangled `cmd //c mklink` quoting trap.
+      fs.symlinkSync(target, path.join(wtPath, 'node_modules'), 'junction');
+      console.log(`  node_modules junction → ${target}`);
+      console.log('  (remove this worktree with `node scripts/gds/worktree.js remove` — it unlinks the junction first;');
+      console.log('   a bare `git worktree remove` would follow the junction into the SHARED node_modules.)');
+    }
+  } else if (isOutsideRepo({ wtPath, repoRoot: root })) {
+    // Explicit --path outside the repo on posix: no junction is created here,
+    // so say plainly that node_modules won't resolve rather than fail later.
+    console.log('  ⚠ this worktree is outside the repo — node_modules will NOT resolve from here on this platform.');
+  }
+  console.log('');
+  console.log('Next:');
+  console.log(`  cd "${wtPath}"`);
+  console.log('  node scripts/gds/claim.js <task-id>   (worktree auto-detected)');
+}
+
+function cmdRemove(root, argv) {
+  const target = argv[1];
+  if (!target) {
+    console.error('usage: node scripts/gds/worktree.js remove <name|path> [--force]');
+    process.exit(2);
+  }
+  const wtPath = resolveWorktreePath(root, target);
+  if (!wtPath) {
+    console.error(`worktree remove: "${target}" is not a registered worktree (see: git worktree list).`);
+    process.exit(1);
+  }
+  if (path.resolve(wtPath).toLowerCase() === path.resolve(root).toLowerCase()) {
+    console.error('worktree remove: refusing to remove the MAIN checkout.');
+    process.exit(2);
+  }
+  const state = nodeModulesState(wtPath);
+  for (const step of removalPlan({ nodeModulesState: state })) {
+    if (step === 'unlink-junction') {
+      // rmdir on a junction removes the LINK only, never the target's contents.
+      fs.rmdirSync(path.join(wtPath, 'node_modules'));
+      console.log('  removed node_modules junction (link only — the shared node_modules is untouched)');
+    } else {
+      const args = ['worktree', 'remove', ...(hasFlag('--force', argv) ? ['--force'] : []), wtPath];
+      try {
+        execFileSync('git', args, { cwd: root, stdio: 'inherit' });
+        console.log(`worktree removed: ${wtPath}`);
+      } catch (e) {
+        // OneDrive briefly locks the dir; the failed attempt usually still
+        // DEREGISTERS the worktree — verify instead of fighting it with retries.
+        const still = listWorktrees(root).some((w) => path.resolve(w).toLowerCase() === path.resolve(wtPath).toLowerCase());
+        if (!still) {
+          console.log(`worktree deregistered: ${wtPath}`);
+          console.log('  (the directory husk is briefly locked — OneDrive — and deletes on its own later)');
+        } else {
+          console.error(`worktree remove failed — ${e.message}`);
+          // The worktree is still live but its junction is already unlinked —
+          // restore it so the tree stays usable (node_modules keeps resolving)
+          // instead of stranding the builder back at hand-rolled mklink.
+          if (state === 'junction') {
+            try {
+              fs.symlinkSync(path.join(root, 'node_modules'), path.join(wtPath, 'node_modules'), 'junction');
+              console.error('  node_modules junction restored — the worktree remains fully usable.');
+            } catch (restoreErr) {
+              console.error(`  could not restore the node_modules junction (${restoreErr.message}) —`);
+              console.error('  re-create it: node -e "require(\'fs\').symlinkSync(\'<main>/node_modules\', \'<wt>/node_modules\', \'junction\')"');
+            }
+          }
+          if (state === 'real-dir') {
+            console.error('  node_modules here is a REAL directory (not a junction) — if it and the other');
+            console.error('  untracked files are disposable, re-run with --force.');
+          } else {
+            console.error('  re-run with --force if the leftover untracked files are disposable.');
+          }
+          process.exit(1);
+        }
+      }
+    }
+  }
+  console.log(`  (branch "${path.basename(wtPath)}" left in place — the land/ship pipeline owns branch cleanup)`);
+}
+
+function cmdList(root) {
+  const all = listWorktrees(root);
+  for (const w of all) {
+    const isMain = path.resolve(w).toLowerCase() === path.resolve(root).toLowerCase();
+    const tag = isMain ? 'main checkout' : `node_modules: ${nodeModulesState(w)}`;
+    console.log(`${w}   [${tag}]`);
+  }
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0];
+  let root;
+  try {
+    root = mainWorktreeRoot();
+  } catch (e) {
+    console.error('worktree: not a git repo (cannot resolve the main checkout):', e.message);
+    process.exit(2);
+  }
+  if (cmd === 'add') return cmdAdd(root, argv);
+  if (cmd === 'remove') return cmdRemove(root, argv);
+  if (cmd === 'list') return cmdList(root);
+  console.error('usage: node scripts/gds/worktree.js add <task-id|name> [--path <dir> | --outside] [--base <ref>]');
+  console.error('       node scripts/gds/worktree.js remove <name|path> [--force]');
+  console.error('       node scripts/gds/worktree.js list');
+  process.exit(2);
+}
+
+if (require.main === module) main();
+
+module.exports = { worktreeNameFor, needsJunction, removalPlan, nodeModulesState };

package/src/bongos/serve-internal.js

@@ -162,7 +162,7 @@ function injectBrandingGlobal(html, brand = clientBranding(), mods = clientModul
 // fill cannot reach them, and a baked one would make every instance advertise
 // whichever instance happened to author the file (task 1002748, direction C5/C6).
 // Pure + exported for the test; both origins are injectable so it drives with zero I/O.
-function applyBrandTokens(html, brand = clientBranding(), origin = safePublicOrigin(), hallOrigin = safeBuildersOrigin(), sourceRepo = safeSourceRepoUrl()) {
+function applyBrandTokens(html, brand = clientBranding(), origin = safePublicOrigin(), hallOrigin = safeBuildersOrigin(), sourceRepo = safeSourceRepoUrl(), instanceBase = safeInstanceBase()) {
   const world = (brand.identity && brand.identity.worldName) || '';
   const product = (brand.identity && brand.identity.productName) || '';
   const tagline = (brand.copy && brand.copy.tagline) || '';
@@ -178,7 +178,8 @@ function applyBrandTokens(html, brand = clientBranding(), origin = safePublicOri
     // a pack that names no hall of its own resolves to its OWN apex — never to
     // whichever instance authored the file
     .split('{{buildersOrigin}}').join(esc(hallOrigin || origin || ''))
-    .split('{{sourceRepoUrl}}').join(esc(sourceRepo || ''));
+    .split('{{sourceRepoUrl}}').join(esc(sourceRepo || ''))
+    .split('{{instanceBase}}').join(esc(instanceBase || ''));
 }
 // Every token lands in HTML — as element text, or inside a double-quoted
 // attribute (href/content). Escaping is defence in depth, not a live fix: the
@@ -206,6 +207,14 @@ function safePublicOrigin() {
 function safeBuildersOrigin() {
   try { return branding().domains.buildersOrigin || ''; } catch { return ''; }
 }
+// The apex new projects get their auto-assigned <slug>.<apex> address under
+// (task 1002704) — same server-only `domains` source. Stamped into markup (a
+// <meta> content attribute, never a <script>) so the create wizard's address
+// preview matches what the server will actually assign instead of guessing
+// from location.hostname. Empty = no auto-assign; the wizard falls back.
+function safeInstanceBase() {
+  try { return branding().domains.instanceBase || ''; } catch { return ''; }
+}
 // The instance's own source repo, from the pack's `repo: {owner, name}` binding —
 // another server-only field (the branding contract keeps repo off clientBranding
 // alongside domains). A page that wants to link "read the source" must take it

package/src/module-api.js

@@ -667,8 +667,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.118 with no explicit bump. run 31835957309. (task 1002620)
 //   1.19.120 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.119 with no explicit bump. run 31836959112. (task 1002620)
+//   1.19.121 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.120 with no explicit bump. run 31838955115. (task 1002620)
+//   1.19.122 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.121 with no explicit bump. run 31840810826. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.120'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.122'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/api_msys_path_repair.mjs

@@ -0,0 +1,104 @@
+// tests/api_msys_path_repair.mjs
+//
+// Unit tests for repairMsysMangledPath (task 1002809). Git Bash (MSYS) rewrites
+// a leading-slash argument into a Windows path under the Git install root before
+// node ever sees it — `/tasks/123` arrives as `C:/Program Files/Git/tasks/123` —
+// unless the builder remembers MSYS_NO_PATHCONV=1. api.js undoes that mangling
+// itself so no builder needs the env prefix.
+//
+// Contract proved here:
+//   1. A path that already starts with '/' is returned untouched (the repair is
+//      a no-op everywhere the shell behaved).
+//   2. A mangled path is repaired by stripping the LONGEST ancestor of EXEPATH
+//      that prefixes it — EXEPATH is `<git-root>\bin` while the msys root that
+//      prefixes mangled args is `<git-root>`, so ancestor-walking is required.
+//   3. The drive root alone is never treated as the msys root (stripping `C:/`
+//      would "repair" any Windows path into nonsense).
+//   4. Non-win32, missing EXEPATH, and unrelated Windows paths pass through.
+//
+// Run:  node tests/api_msys_path_repair.mjs
+
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const { repairMsysMangledPath } = require('../scripts/gds/cli-lib.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try {
+    fn();
+    passed++;
+    console.log(`  ok  ${name}`);
+  } catch (err) {
+    failed++;
+    console.log(`  FAIL ${name}`);
+    console.log(`     ${err.message}`);
+  }
+}
+function eq(actual, expected, msg) {
+  if (actual !== expected) throw new Error(`${msg || 'mismatch'}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+}
+
+const GIT_BASH = { exepath: 'C:\\Program Files\\Git\\bin', platform: 'win32' };
+
+test('already-correct path is untouched', () => {
+  eq(repairMsysMangledPath('/api/gds/inbox', GIT_BASH), '/api/gds/inbox');
+  eq(repairMsysMangledPath('/tasks/1002809', GIT_BASH), '/tasks/1002809');
+});
+
+test('mangled path is repaired via EXEPATH ancestor (forward slashes)', () => {
+  eq(repairMsysMangledPath('C:/Program Files/Git/tasks/1002809', GIT_BASH), '/tasks/1002809');
+  eq(repairMsysMangledPath('C:/Program Files/Git/api/gds/inbox', GIT_BASH), '/api/gds/inbox');
+});
+
+test('mangled path with backslashes is repaired and normalized', () => {
+  eq(repairMsysMangledPath('C:\\Program Files\\Git\\claims', GIT_BASH), '/claims');
+});
+
+test('prefix match is case-insensitive (Windows paths are)', () => {
+  eq(repairMsysMangledPath('c:/program files/git/tasks/5', GIT_BASH), '/tasks/5');
+});
+
+test('longest matching ancestor wins (a legit /Git/... path survives)', () => {
+  // Original arg /Git/tasks/9 mangles to <root>/Git/tasks/9 — stripping the
+  // git root must give back /Git/tasks/9, not /tasks/9.
+  eq(repairMsysMangledPath('C:/Program Files/Git/Git/tasks/9', GIT_BASH), '/Git/tasks/9');
+});
+
+test('drive root alone is never stripped', () => {
+  // Root-level install: EXEPATH C:\Git\bin → msys root C:/Git is strippable...
+  eq(repairMsysMangledPath('C:/Git/tasks/7', { exepath: 'C:\\Git\\bin', platform: 'win32' }), '/tasks/7');
+  // ...but C:/ by itself is not a valid msys root — an unrelated Windows path
+  // must pass through unchanged, not get "repaired" into /tmp/x.json.
+  eq(repairMsysMangledPath('C:/tmp/x.json', GIT_BASH), 'C:/tmp/x.json');
+});
+
+test('non-win32 platform passes through', () => {
+  eq(repairMsysMangledPath('C:/Program Files/Git/tasks/1', { exepath: 'C:\\Program Files\\Git\\bin', platform: 'linux' }), 'C:/Program Files/Git/tasks/1');
+});
+
+test('missing EXEPATH passes through (empty = not a Git Bash shell)', () => {
+  eq(repairMsysMangledPath('C:/Program Files/Git/tasks/1', { exepath: '', platform: 'win32' }), 'C:/Program Files/Git/tasks/1');
+});
+
+test('empty/undefined input passes through', () => {
+  eq(repairMsysMangledPath('', GIT_BASH), '');
+  eq(repairMsysMangledPath(undefined, GIT_BASH), undefined);
+});
+
+// Static wiring check (the cli_exit_no_abort.mjs pattern): the pure helper being
+// correct is worthless if api.js stops applying it to its positional path arg —
+// that exact mutation survived every behavioural test here.
+test('api.js applies the repair to process.argv[3] (static)', () => {
+  const src = fs.readFileSync(fileURLToPath(new URL('../scripts/gds/api.js', import.meta.url)), 'utf8');
+  if (!/repairMsysMangledPath\(\s*process\.argv\[3\]\s*\)/.test(src)) {
+    throw new Error('api.js no longer wraps process.argv[3] in repairMsysMangledPath(...)');
+  }
+});
+
+console.log('');
+console.log(`api_msys_path_repair: ${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);