@marcomigozzi/trailhead 0.16.1 → 0.18.0

package/plugins/trailhead/hooks/lib/checkout-find.test.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+// Tests for templates/trailhead-checkout-find.js. Run: node checkout-find.test.js
+// No framework: plain asserts, same style as checkout-in.test.js.
+//
+// Layers covered:
+//   1. parseRemote / matches: pure URL handling.
+//   2. findCheckouts over temp roots: matching, walk rules, truncation, tiers.
+//   3. The CLI: statuses, default tiers under a temp HOME, usage errors.
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const scriptPath = path.resolve(__dirname, '..', '..', 'templates', 'trailhead-checkout-find.js');
+
+// require() must print nothing and must not exit.
+const probe = spawnSync(process.execPath, ['-e', `require(${JSON.stringify(scriptPath)}); process.stdout.write('alive')`], { encoding: 'utf8' });
+assert.strictEqual(probe.stdout, 'alive', 'require prints nothing and does not exit');
+const { parseRemote, parseRepoShape, matches, findCheckouts } = require(scriptPath);
+
+let passed = 1;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+const eq = (name, a, b) => { assert.deepStrictEqual(a, b, name); passed++; };
+
+// --- 1. pure helpers ---------------------------------------------------------------
+const GH = { host: 'github.com', path: 'o/r' };
+for (const u of [
+  'https://github.com/o/r.git', 'https://github.com/o/r', 'https://github.com/o/r/', 'ssh://git@github.com/o/r.git',
+  'git@github.com:o/r.git', 'git@github.com:o/r', 'github.com:o/r', 'https://user@GitHub.com/o/r.git', 'git://github.com/o/r.git',
+  '  git@github.com:o/r.git\n',
+]) eq(`parse ${u.trim()}`, parseRemote(u), GH);
+eq('port kept in the host', parseRemote('ssh://git@ghe.example.com:2222/o/r.git'), { host: 'ghe.example.com:2222', path: 'o/r' });
+eq('nested group path', parseRemote('git@gitlab.com:g/sub/r.git'), { host: 'gitlab.com', path: 'g/sub/r' });
+eq('local path is not a remote', parseRemote('/srv/git/r.git'), null);
+eq('relative path is not a remote', parseRemote('../r'), null);
+eq('empty is not a remote', parseRemote(''), null);
+
+ok('github path is case-insensitive', matches('git@github.com:Foo/Bar.git', 'github.com/foo/bar'));
+ok('host is case-insensitive', matches('https://GITHUB.com/o/r', 'github.com/o/r'));
+ok('bare owner/name matches any host', matches('git@gitlab.com:o/r.git', 'o/r'));
+ok('host mismatch rejects', !matches('git@gitlab.com:o/r.git', 'github.com/o/r'));
+ok('path case is exact off github', !matches('https://gitlab.com/O/r', 'gitlab.com/o/r') && matches('https://gitlab.com/o/r', 'gitlab.com/o/r'));
+ok('different repo rejects', !matches('https://github.com/o/other', 'github.com/o/r'));
+ok('wanted port must equal the remote port', matches('ssh://git@h.io:2222/o/r', 'h.io:2222/o/r') && !matches('ssh://git@h.io:2223/o/r', 'h.io:2222/o/r'));
+ok('port-less wanted host ignores the remote port', matches('ssh://git@h.io:2222/o/r', 'h.io/o/r'));
+eq('repo shape: a dotless host is a host', parseRepoShape('gitea/owner/name'), { host: 'gitea', path: 'owner/name' });
+eq('repo shape: two segments is no shape', parseRepoShape('owner/name'), null);
+ok('a parsed dotless host matches a scp remote', matches('git@gitea:owner/name.git', { host: 'gitea', path: 'owner/name' }));
+ok('a parsed dotless host rejects another host', !matches('git@forge:owner/name.git', { host: 'gitea', path: 'owner/name' }));
+ok('nested group matches', matches('git@gitlab.com:g/sub/r.git', 'gitlab.com/g/sub/r'));
+
+// --- 2. findCheckouts --------------------------------------------------------------
+const tmp = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'checkout-find-')));
+const git = (cwd, ...args) => {
+  const r = spawnSync('git', ['-C', cwd, ...args], { encoding: 'utf8' });
+  assert.strictEqual(r.status, 0, `git ${args.join(' ')}: ${r.stderr}`);
+};
+function makeRepo(dir, origin) {
+  fs.mkdirSync(dir, { recursive: true });
+  git(dir, 'init', '-q', '-b', 'main');
+  git(dir, '-c', 'user.name=t', '-c', 'user.email=t@t', 'commit', '-q', '--allow-empty', '-m', 'init');
+  if (origin) git(dir, 'remote', 'add', 'origin', origin);
+  return fs.realpathSync(dir);
+}
+const fresh = (name) => { const d = path.join(tmp, name); fs.mkdirSync(d, { recursive: true }); return fs.realpathSync(d); };
+const WANT = 'github.com/o/r';
+
+{
+  const root = fresh('basic');
+  const a = makeRepo(path.join(root, 'a'), 'git@github.com:O/R.git');
+  makeRepo(path.join(root, 'b'), 'https://github.com/o/other');
+  makeRepo(path.join(root, 'c'), null);
+  eq('lone match is found (case, .git, scp)', findCheckouts(WANT, { roots: [root] }), { status: 'found', path: a });
+  const https = makeRepo(path.join(root, 'deep', 'd'), 'https://github.com/o/r');
+  const r = findCheckouts(WANT, { roots: [root] });
+  eq('ssh and https both match: ambiguous, sorted', r, { status: 'ambiguous', candidates: [{ path: a, kind: 'main' }, { path: https, kind: 'main' }] });
+  eq('no match is none with the searched roots', findCheckouts('github.com/x/y', { roots: [root] }), { status: 'none', searched: [root] });
+}
+{
+  const root = fresh('nested');
+  const outer = makeRepo(path.join(root, 'outer'), 'https://github.com/o/other');
+  makeRepo(path.join(outer, 'inner'), 'https://github.com/o/r');
+  eq('a nested repo under a checkout is not descended', findCheckouts(WANT, { roots: [root] }).status, 'none');
+}
+{
+  const root = fresh('worktrees');
+  const main = makeRepo(path.join(root, 'main'), 'https://github.com/o/r');
+  git(main, 'worktree', 'add', '-q', '-b', 'wt', path.join(root, 'wt'));
+  const wt = fs.realpathSync(path.join(root, 'wt'));
+  eq('main + worktree is ambiguous with kinds', findCheckouts(WANT, { roots: [root] }),
+    { status: 'ambiguous', candidates: [{ path: main, kind: 'main' }, { path: wt, kind: 'linked' }].sort((x, y) => (x.path < y.path ? -1 : 1)) });
+  const lone = fresh('lone-wt');
+  const base = makeRepo(path.join(tmp, 'elsewhere-main'), 'https://github.com/o/r');
+  git(base, 'worktree', 'add', '-q', '-b', 'wt2', path.join(lone, 'wt'));
+  eq('a lone worktree is found', findCheckouts(WANT, { roots: [lone] }), { status: 'found', path: fs.realpathSync(path.join(lone, 'wt')) });
+}
+{
+  const root = fresh('overlap');
+  const a = makeRepo(path.join(root, 'sub', 'a'), 'https://github.com/o/r');
+  eq('overlapping roots never double-count', findCheckouts(WANT, { roots: [root, path.join(root, 'sub'), root] }), { status: 'found', path: a });
+  fs.symlinkSync(root, path.join(root, 'sub', 'loop'));
+  fs.symlinkSync(path.join(root, 'sub', 'a'), path.join(root, 'alias'));
+  eq('a symlink cycle and an alias never double-count', findCheckouts(WANT, { roots: [root] }), { status: 'found', path: a });
+}
+{
+  const root = fresh('skips');
+  makeRepo(path.join(root, 'node_modules', 'pkg'), 'https://github.com/o/r');
+  makeRepo(path.join(root, '.hidden', 'x'), 'https://github.com/o/r');
+  eq('node_modules and dot-dirs are skipped', findCheckouts(WANT, { roots: [root] }).status, 'none');
+}
+{
+  const root = fresh('depth');
+  const deep = makeRepo(path.join(root, 'l1', 'l2', 'l3', 'r'), 'https://github.com/o/r');
+  eq('depth 3 reaches the 3rd level below the root', findCheckouts(WANT, { roots: [root], depth: 3 }).status, 'none');
+  eq('depth 4 reaches the 4th level', findCheckouts(WANT, { roots: [root], depth: 4 }), { status: 'found', path: deep });
+  const near = makeRepo(path.join(root, 'n1', 'n2', 'n3'), 'https://github.com/o/r');
+  eq('default depth 3 reaches level 3', findCheckouts(WANT, { roots: [root] }), { status: 'found', path: near });
+}
+{
+  const root = fresh('nested-group');
+  const g = makeRepo(path.join(root, 'g'), 'git@gitlab.com:grp/sub/repo.git');
+  eq('a nested group/sub/repo remote is found', findCheckouts('gitlab.com/grp/sub/repo', { roots: [root] }), { status: 'found', path: g });
+  const p = makeRepo(path.join(root, 'p'), 'ssh://git@ghe.io:2222/o/r.git');
+  eq('port kept: wanted with the port matches', findCheckouts('ghe.io:2222/o/r', { roots: [root] }), { status: 'found', path: p });
+  eq('port kept: another port does not', findCheckouts('ghe.io:2223/o/r', { roots: [root] }).status, 'none');
+  eq('path case exact off github', findCheckouts('gitlab.com/GRP/sub/repo', { roots: [root] }).status, 'none');
+}
+{
+  const root = fresh('broken');
+  const a = makeRepo(path.join(root, 'ok'), 'https://github.com/o/r');
+  const bad = makeRepo(path.join(root, 'bad'), 'https://github.com/o/r');
+  fs.writeFileSync(path.join(bad, '.git', 'config'), '[remote "origin"\n\turl = ???\n');
+  eq('a broken config is skipped', findCheckouts(WANT, { roots: [root] }), { status: 'found', path: a });
+  eq('a checkout with no origin is skipped', findCheckouts(WANT, { roots: [fresh('noorigin')] }).status, 'none');
+}
+{
+  // Cap: injected origin reader keeps it deterministic.
+  const root = fresh('cap');
+  for (let i = 0; i < 6; i++) fs.mkdirSync(path.join(root, `d${i}`));
+  const hit = makeRepo(path.join(root, 'a-hit'), 'https://github.com/o/r');
+  const originOf = (dir) => (dir === hit ? 'https://github.com/o/r' : null);
+  eq('no cap hit: found', findCheckouts(WANT, { roots: [root], originOf }), { status: 'found', path: hit });
+  eq('cap hit with a lone match is ambiguous and truncated', findCheckouts(WANT, { roots: [root], originOf, cap: 3 }),
+    { status: 'ambiguous', candidates: [{ path: hit, kind: 'main' }], truncated: true });
+  eq('cap hit with no match is none and truncated', findCheckouts('github.com/x/y', { roots: [root], originOf, cap: 2 }),
+    { status: 'none', searched: [root], truncated: true });
+}
+{
+  const focused = fresh('tier-focused');
+  const home = fresh('tier-home');
+  const f = makeRepo(path.join(focused, 'f'), 'https://github.com/o/r');
+  makeRepo(path.join(home, 'h'), 'https://github.com/o/r');
+  eq('a focused-tier match wins over a home-tier one', findCheckouts(WANT, { tiers: [[focused], [home]] }), { status: 'found', path: f });
+  const empty = fresh('tier-empty');
+  const h2 = makeRepo(path.join(home, 'only-home'), 'https://github.com/o/solo');
+  eq('home tier is searched when the focused one is empty', findCheckouts('github.com/o/solo', { tiers: [[empty], [home]] }), { status: 'found', path: h2 });
+  eq('a cap on the focused tier does not starve the home tier', findCheckouts('github.com/o/solo', { tiers: [[focused], [home]], cap: 3 }).status, 'found');
+}
+
+// --- 3. CLI ------------------------------------------------------------------------
+const cli = (args, env = {}) => {
+  const r = spawnSync(process.execPath, [scriptPath, ...args], { encoding: 'utf8', env: { ...process.env, ...env } });
+  return { code: r.status, out: r.stdout.trim() ? JSON.parse(r.stdout.trim()) : null, err: r.stderr };
+};
+{
+  const root = fresh('cli');
+  const a = makeRepo(path.join(root, 'a'), 'https://github.com/o/r');
+  eq('cli found', cli(['--repo', WANT, '--roots', root]).out, { status: 'found', path: a });
+  const b = makeRepo(path.join(root, 'b'), 'git@github.com:o/r.git');
+  const amb = cli(['--repo', 'o/r', '--roots', root]);
+  eq('cli ambiguous (bare owner/name)', [amb.code, amb.out.status, amb.out.candidates.map((c) => c.path)], [0, 'ambiguous', [a, b]]);
+  eq('cli none', cli(['--repo', 'github.com/x/y', '--roots', root]).out, { status: 'none', searched: [root] });
+  eq('cli depth 0 sees only the roots', cli(['--repo', WANT, '--roots', root, '--depth', '0']).out.status, 'none');
+
+  // Default tiers under a temp HOME: a code folder wins, then $HOME itself.
+  const home = fresh('cli-home');
+  const inGit = makeRepo(path.join(home, 'Git', 'proj'), 'https://github.com/o/r');
+  makeRepo(path.join(home, 'stray', 'proj'), 'https://github.com/o/r');
+  const cwd = path.join(fresh('cli-cwd-parent'), 'cwd');
+  fs.mkdirSync(cwd);
+  eq('default tiers: the focused code folder wins', cli(['--repo', WANT, '--cwd', cwd], { HOME: home }).out, { status: 'found', path: inGit });
+  const home2 = fresh('cli-home2');
+  const stray = makeRepo(path.join(home2, 'stray', 'proj'), 'https://github.com/o/r');
+  eq('default tiers: falls back to $HOME', cli(['--repo', WANT, '--cwd', cwd], { HOME: home2 }).out, { status: 'found', path: stray });
+}
+{
+  const r = spawnSync(process.execPath, [scriptPath], { encoding: 'utf8' });
+  eq('missing --repo is a usage error', r.status, 2);
+  eq('a repo with no owner is a usage error', spawnSync(process.execPath, [scriptPath, '--repo', 'solo'], { encoding: 'utf8' }).status, 2);
+  eq('a bad --depth is a usage error', spawnSync(process.execPath, [scriptPath, '--repo', WANT, '--depth', 'x'], { encoding: 'utf8' }).status, 2);
+}
+
+fs.rmSync(tmp, { recursive: true, force: true });
+console.log(`checkout-find: ${passed} assertions passed`);

package/plugins/trailhead/hooks/lib/checkout-in.test.js

@@ -5,7 +5,8 @@
 // Layers covered:
 //   1. The pure token helpers: encode / decode round-trip.
 //   2. The CLI against real temp git repos: invalid, here, move, the `cd` field.
-//   3. The protocol contract: the work skill moves before it loads or preflights.
+//   3. The remote fallback (#329): a missing path plus a repo in the token.
+//   4. The protocol contract: the work skill moves before it loads or preflights.
 const assert = require('assert');
 const { spawnSync } = require('child_process');
 const path = require('path');
@@ -26,17 +27,20 @@ const sh = (cwd, ...args) => {
   assert.strictEqual(r.status, 0, `git ${args.join(' ')}: ${r.stderr}`);
   return r.stdout;
 };
-function makeRepo(dir) {
+function makeRepo(dir, origin) {
   fs.mkdirSync(dir, { recursive: true });
   sh(dir, 'init', '-q', '-b', 'main');
   sh(dir, '-c', 'user.name=t', '-c', 'user.email=t@t', 'commit', '-q', '--allow-empty', '-m', 'init');
+  if (origin) sh(dir, 'remote', 'add', 'origin', origin);
   return fs.realpathSync(dir);
 }
-const run = (inArg, cwd) => {
-  const r = spawnSync(process.execPath, [scriptPath, '--in', inArg, '--cwd', cwd], { encoding: 'utf8' });
+const run = (inArg, cwd, roots) => {
+  const extra = roots ? ['--roots', roots.join(':')] : [];
+  const r = spawnSync(process.execPath, [scriptPath, '--in', inArg, '--cwd', cwd, ...extra], { encoding: 'utf8' });
   return { code: r.status, out: r.stdout.trim() ? JSON.parse(r.stdout.trim()) : null, err: r.stderr };
 };
-const tokenOf = (p) => encodeIn(p).slice('--in='.length);
+const fresh = (name) => { const d = path.join(tmp, name); fs.mkdirSync(d, { recursive: true }); return fs.realpathSync(d); };
+const tokenOf = (p, repo) => encodeIn(p, repo).slice('--in='.length);
 
 // --- 1. pure helpers ---------------------------------------------------------------
 const odd = [
@@ -51,11 +55,30 @@ const odd = [
 for (const p of odd) {
   const enc = encodeIn(p);
   ok(`token shape ${p}`, /^--in=[A-Za-z0-9_-]+$/.test(enc));
-  eq(`round-trip ${p}`, decodeIn(enc.slice(5)), p);
+  eq(`round-trip ${p}`, decodeIn(enc.slice(5)), { path: p, repo: null });
 }
 eq('decode of garbage', decodeIn('!!!'), null);
 eq('decode of empty', decodeIn(''), null);
 
+// Two-part token: path + host/owner/name.
+{
+  const enc = encodeIn('/w/with space/r', 'github.com/o/r');
+  ok('two-part shape', /^--in=[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(enc));
+  eq('two-part round-trip', decodeIn(enc.slice(5)), { path: '/w/with space/r', repo: 'github.com/o/r' });
+  eq('encodeIn without a repo stays one part', encodeIn('/r'), `--in=${Buffer.from('/r').toString('base64url')}`);
+  // An old helper (#312) only accepts [A-Za-z0-9_-]+: a two-part token is invalid there, so the rollout fails closed.
+  ok('an old helper shape check rejects a two-part token', !/^[A-Za-z0-9_-]+$/.test(enc.slice(5)));
+  const b = (s) => Buffer.from(s).toString('base64url');
+  eq('extra separator is malformed', decodeIn(`${b('/r')}.${b('github.com/o/r')}.${b('x')}`), null);
+  eq('invalid base64url in the path part', decodeIn(`!!.${b('github.com/o/r')}`), null);
+  eq('invalid base64url in the repo part', decodeIn(`${b('/r')}.!!`), null);
+  eq('empty repo part', decodeIn(`${b('/r')}.`), null);
+  eq('empty path part', decodeIn(`.${b('github.com/o/r')}`), null);
+  eq('a dotless host is a valid repo part', decodeIn(`${b('/r')}.${b('gitea/owner/name')}`), { path: '/r', repo: 'gitea/owner/name' });
+  eq('repo part without a host is malformed', decodeIn(`${b('/r')}.${b('owner/name')}`), null);
+  eq('repo part that is not host/path is malformed', decodeIn(`${b('/r')}.${b('justone')}`), null);
+}
+
 // --- 2. CLI ------------------------------------------------------------------------
 const main = makeRepo(path.join(tmp, 'main repo'));
 const other = makeRepo(path.join(tmp, 'other'));
@@ -145,7 +168,54 @@ fs.mkdirSync(plain);
   }
 }
 
-// --- 3. protocol contract: the move comes before anything else -----------------------
+// --- 3. remote fallback (#329): roots are always explicit, the real home is never scanned ---
+{
+  const REPO = 'github.com/o/r';
+  const gone = path.join(tmp, 'moved-away', 'r');
+  const roots = fresh('relocate-roots');
+  const found = makeRepo(path.join(roots, 'r'), 'git@github.com:o/r.git');
+  makeRepo(path.join(roots, 'unrelated'), 'https://github.com/o/other');
+
+  const mv = run(tokenOf(gone, REPO), other, [roots]);
+  eq('missing path + repo moves to the matching repo', [mv.code, mv.out.status, mv.out.path, mv.out.relocatedFrom], [0, 'move', found, gone]);
+  ok('the relocated move carries a cd', mv.out.cd === `cd -- '${found}'`);
+  const here = run(tokenOf(gone, REPO), found, [roots]);
+  eq('here when cwd is the found repo', [here.out.status, here.out.path, here.out.relocatedFrom], ['here', found, gone]);
+
+  const two = fresh('relocate-two');
+  const t1 = makeRepo(path.join(two, 'a'), 'https://github.com/o/r');
+  const t2 = makeRepo(path.join(two, 'b'), 'https://github.com/o/r');
+  const ch = run(tokenOf(gone, REPO), other, [two]);
+  eq('two matches -> choose', [ch.out.status, ch.out.path], ['choose', gone]);
+  eq('choose lists both candidates', ch.out.candidates, [{ path: t1, kind: 'main' }, { path: t2, kind: 'main' }]);
+  ok('choose has a reason and no cd', typeof ch.out.reason === 'string' && ch.out.reason.length > 0 && !('cd' in ch.out));
+
+  const none = run(tokenOf(gone, 'github.com/x/y'), other, [roots]);
+  eq('no match -> invalid', none.out.status, 'invalid');
+  ok('invalid names the repo', none.out.reason.includes('github.com/x/y'));
+  eq('one-part token with a missing path stays invalid', run(tokenOf(gone), other, [roots]).out.status, 'invalid');
+  fs.mkdirSync(path.join(found, 'sub'));
+  eq('an existing non-root path with a repo is invalid, no relocation', run(tokenOf(path.join(found, 'sub'), REPO), other, [roots]).out.status, 'invalid');
+  eq('a relative path with a repo is invalid without a search', run(tokenOf('rel/r', REPO), other, [roots]).out.status, 'invalid');
+  eq('an existing path ignores the repo', run(tokenOf(main, REPO), other, [roots]).out.path, main);
+  eq('no relocatedFrom on a plain move', 'relocatedFrom' in run(tokenOf(main, REPO), other, [roots]).out, false);
+  eq('a malformed two-part token is invalid', run(`${tokenOf(gone)}.!!`, other, [roots]).out.status, 'invalid');
+}
+
+// Dotless hosts (gitea, localhost): the repo part is read by shape, never by a dot heuristic.
+{
+  const exists = run(tokenOf(main, 'gitea/owner/name'), other, [fresh('dotless-unused')]);
+  eq('dotless-host token with an existing path moves', [exists.out.status, exists.out.path], ['move', main]);
+  eq('dotless-host token with an existing path is here in it', run(tokenOf(main, 'localhost/o/n'), main, [fresh('dotless-unused2')]).out.status, 'here');
+  const roots = fresh('dotless-roots');
+  const g = makeRepo(path.join(roots, 'n'), 'git@gitea:owner/name.git');
+  const gone = path.join(tmp, 'dotless-gone', 'n');
+  const r = run(tokenOf(gone, 'gitea/owner/name'), other, [roots]);
+  eq('dotless-host relocation moves with relocatedFrom', [r.out.status, r.out.path, r.out.relocatedFrom], ['move', g, gone]);
+  eq('another dotless host does not match', run(tokenOf(gone, 'forge/owner/name'), other, [roots]).out.status, 'invalid');
+}
+
+// --- 4. protocol contract: the move comes before anything else -----------------------
 {
   const skill = fs.readFileSync(skillPath, 'utf8');
   const move = skill.indexOf('## Move into the handed checkout');
@@ -166,6 +236,12 @@ fs.mkdirSync(plain);
   ok('stops when the post-check is not here', /could not move/.test(section));
   ok('stops when the helper is missing', /missing[^.]*stop|stop[^.]*missing/i.test(section));
   ok('never moves by hand', /by hand/.test(section));
+  ok('has a choose branch that asks', /`choose`/.test(section) && /AskUserQuestion/.test(section));
+  ok('choose never picks by hand', /never pick one by hand/.test(section));
+  ok('choose re-checks for here', /original `--in` token/.test(section) && /could not move/.test(section));
+  ok('relocatedFrom gets a result-oriented line', /`relocatedFrom`[^.]*moved/.test(section));
+  const subs = fs.readFileSync(path.resolve(__dirname, '..', '..', 'skills', '_shared', 'substrate-commands.md'), 'utf8');
+  ok('substrate documents the finder', /## Find a checkout by its remote/.test(subs) && subs.includes('trailhead-checkout-find.js'));
   ok('Routing points at the move section', /Routing[\s\S]*Move into the handed checkout/.test(skill.slice(skill.indexOf('## Routing'))));
 }
 

package/plugins/trailhead/hooks/lib/dashboard.test.js

@@ -407,6 +407,25 @@ function runMain(argv, t, extra = {}) {
   ok('create: a secret in the generated body aborts the create', guardHit.code === 1 && ghost.created.length === 0);
 }
 
+// --- --update-only: never opens a dashboard of its own (#330) -----------------
+{
+  const t = makeTracker({ dash: null, pinned: [] });
+  const r = runMain(['--repo', 'o/r', '--update-only'], t);
+  ok('update-only: no dashboard -> skip line, exit 0', r.code === 0 && r.out === 'skipped: no dashboard issue (update-only)\n');
+  ok('update-only: no dashboard -> no create, pin, label or write call', t.created.length === 0 && t.pins.length === 0 && t.labels.length === 0 && t.writes.length === 0 && !t.calls.some((c) => /^label create|^issue create|^issue edit|graphql/.test(c)));
+}
+{
+  const t = makeTracker();
+  const r = runMain(['--repo', 'o/r', '--update-only'], t);
+  ok('update-only: a dashboard present is rewritten as usual', r.code === 0 && t.writes.length === 1 && /^dashboard #33: 3 maps/.test(r.out) && !/skipped/.test(r.out));
+  ok('update-only: a dashboard present keeps the label ensure and creates nothing', t.labels.includes('trailhead:dashboard') && t.created.length === 0);
+}
+{
+  const t = makeTracker({ dups: { 'trailhead:dashboard': [{ number: 90, title: 'dup' }] } });
+  const r = runMain(['--repo', 'o/r', '--update-only'], t);
+  ok('update-only: duplicate dashboards still abort, never skipped', r.code === 1 && /ambiguous singleton/.test(r.out) && t.writes.length === 0);
+}
+
 // --- I2: a pin-check failure after the write is not an abort ------------------
 {
   const t = makeTracker({ failOn: /pinnedIssues/ });

package/plugins/trailhead/hooks/lib/gh-auth-preflight.js

@@ -0,0 +1,89 @@
+'use strict';
+// Preflight dell'auth di gh (SessionStart): segnala una volta, all'avvio, un
+// GH_TOKEN/GITHUB_TOKEN non valido nell'ambiente che oscura un login gh
+// funzionante. Pura: il runner è iniettabile (spawnSync shape), i test non
+// toccano mai la rete. Mai lancia: ogni errore o caso dubbio -> null.
+const { spawnSync } = require('child_process');
+
+// gh dà la precedenza a GH_TOKEN, poi GITHUB_TOKEN, poi al login salvato.
+const TOKEN_VARS = ['GH_TOKEN', 'GITHUB_TOKEN'];
+// SessionStart scatta di nuovo su resume e compact: li saltiamo (una volta sola).
+const SKIP_SOURCES = new Set(['resume', 'compact']);
+
+// Budget totale condiviso da tutti i probe: SessionStart non resta bloccato oltre.
+const BUDGET_MS = 5000;
+
+function defaultRun(env, timeoutMs = BUDGET_MS) {
+  try {
+    return spawnSync('gh', ['api', 'user', '-q', '.login'], {
+      env, timeout: timeoutMs, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8',
+    });
+  } catch (error) {
+    return { status: null, stdout: '', stderr: '', error };
+  }
+}
+
+function activeVar(env) {
+  return TOKEN_VARS.find((v) => typeof env[v] === 'string' && env[v] !== '') || null;
+}
+
+function isSuccess(r) {
+  return Boolean(r) && !r.error && r.status === 0;
+}
+// Solo un 401 esplicito conta come rifiuto: tutto il resto (rete, timeout,
+// gh assente) degrada in silenzio.
+function isAuthFailure(r) {
+  if (!r || r.error || r.status === 0 || r.status === null || r.status === undefined) return false;
+  return /HTTP 401|Bad credentials/.test(String(r.stderr || '')) || /"status":\s*"401"/.test(String(r.stdout || ''));
+}
+
+// gh non loggato: exit 4 o invito a "gh auth login" (non un errore di rete).
+function isNotLoggedIn(r) {
+  if (!r || r.error) return false;
+  return r.status === 4 || /gh auth login/.test(String(r.stderr || ''));
+}
+
+function notice(rejected, working) {
+  const vars = rejected.join(' and ');
+  const unset = rejected.map((v) => `${v}=`).join(' ');
+  if (working === null) {
+    return `GitHub rejects the ${vars} set in this environment (HTTP 401) and there is no working \`gh\` login. `
+      + `Tell the user to remove ${rejected.length > 1 ? 'them' : 'it'} from their shell profile and run \`gh auth login\`.`;
+  }
+  const what = working === 'stored' ? 'the working `gh` login' : `the valid ${working}`;
+  return `GitHub rejects the ${vars} set in this environment (HTTP 401); it overrides ${what}, so \`gh\` calls fail. `
+    + `Tell the user to remove ${rejected.length > 1 ? 'them' : rejected[0]} from their shell profile and restart; `
+    + `until then run \`gh\` as \`${unset} gh ...\`.`;
+}
+
+function check({ env, run, source, now } = {}) {
+  try {
+    if (SKIP_SOURCES.has(source)) return null;
+    const base = env || process.env;
+    if (!activeVar(base)) return null;
+    const runner = run || defaultRun;
+    let cur = { ...base };
+    const rejected = [];
+    const clock = now || Date.now;
+    const start = clock();
+    for (;;) {
+      const remaining = BUDGET_MS - (clock() - start);
+      if (remaining <= 0) return null;
+      const r = runner(cur, remaining);
+      if (isSuccess(r)) {
+        return rejected.length ? notice(rejected, activeVar(cur) || 'stored') : null;
+      }
+      const active = activeVar(cur);
+      // dopo un 401 confermato, senza altre variabili da togliere, anche "non
+      // loggato" vale "nessun login funzionante"; rete/timeout restano silenziosi
+      if (!active && rejected.length && (isAuthFailure(r) || isNotLoggedIn(r))) return notice(rejected, null);
+      if (!isAuthFailure(r) || !active) return null;
+      rejected.push(active);
+      cur = { ...cur, [active]: '' };
+    }
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { check, defaultRun };

package/plugins/trailhead/hooks/lib/gh-auth-preflight.test.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+// Test per lib/gh-auth-preflight.js. Run: node gh-auth-preflight.test.js
+// Nessun framework: assert semplici, runner iniettato (mai la rete).
+const assert = require('assert');
+const path = require('path');
+const { check } = require(path.join(__dirname, 'gh-auth-preflight.js'));
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const AUTH_ERR = { status: 1, stdout: '{"message":"Bad credentials","status":"401"}', stderr: 'gh: Bad credentials (HTTP 401)' };
+const GOOD = { status: 0, stdout: 'octo\n', stderr: '' };
+
+// Runner che modella la precedenza di gh: GH_TOKEN, poi GITHUB_TOKEN, poi il login salvato.
+// valid: { GH_TOKEN, GITHUB_TOKEN, stored } = true/false.
+function model(valid, failure) {
+  const calls = [];
+  const run = (env) => {
+    calls.push(env);
+    const v = env.GH_TOKEN ? valid.GH_TOKEN : env.GITHUB_TOKEN ? valid.GITHUB_TOKEN : valid.stored;
+    if (v === 'other') return failure;
+    return v ? GOOD : AUTH_ERR;
+  };
+  run.calls = calls;
+  return run;
+}
+
+// nessuna variabile token -> null, runner mai chiamato
+{
+  const run = model({ stored: false });
+  ok('no token var: null', check({ env: { PATH: 'x' }, run }) === null);
+  ok('no token var: runner not called', run.calls.length === 0);
+}
+// variabile vuota = non impostata
+{
+  const run = model({ stored: false });
+  ok('empty var counts as unset', check({ env: { GH_TOKEN: '', GITHUB_TOKEN: '' }, run }) === null && run.calls.length === 0);
+}
+// token d'ambiente valido -> null
+ok('env token works: null', check({ env: { GITHUB_TOKEN: 'good' }, run: model({ GITHUB_TOKEN: true }) }) === null);
+
+// token rifiutato, login salvato valido -> notice (variante ii)
+{
+  const run = model({ GITHUB_TOKEN: false, stored: true });
+  const n = check({ env: { GITHUB_TOKEN: 'bad' }, run });
+  ok('rejected + stored ok: notice', typeof n === 'string' && n.includes('GITHUB_TOKEN') && n.includes('overrides the working `gh` login'));
+  ok('rejected + stored ok: workaround', n.includes('GITHUB_TOKEN= gh'));
+  ok('notice never has the token value', !n.includes('bad'));
+  ok('stripped call used', run.calls.length === 2 && run.calls[1].GITHUB_TOKEN === '');
+}
+// rifiuto riconosciuto anche solo da stdout 401 o solo da stderr
+for (const [label, res] of [
+  ['stdout only', { status: 1, stdout: '{"status": "401"}', stderr: '' }],
+  ['stderr only', { status: 1, stdout: '', stderr: 'gh: Bad credentials (HTTP 401)' }],
+]) {
+  const calls = [];
+  const run = (env) => { calls.push(env); return env.GITHUB_TOKEN ? res : GOOD; };
+  ok(`auth failure detected: ${label}`, check({ env: { GITHUB_TOKEN: 'bad' }, run }) !== null);
+}
+// token rifiutato e nessun login funzionante -> variante iii
+{
+  const n = check({ env: { GITHUB_TOKEN: 'bad' }, run: model({ GITHUB_TOKEN: false, stored: false }) });
+  ok('nothing works: notice', n.includes('no working `gh` login') && n.includes('gh auth login'));
+  ok('nothing works: no workaround', !n.includes('GITHUB_TOKEN= gh') && !n.includes('overrides'));
+}
+// errori non di auth -> null
+for (const [label, res] of [
+  ['network', { status: 1, stdout: '', stderr: 'error connecting to api.github.com' }],
+  ['timeout', { status: null, stdout: '', stderr: '', error: Object.assign(new Error('t'), { code: 'ETIMEDOUT' }) }],
+  ['ENOENT', { status: null, stdout: '', stderr: '', error: Object.assign(new Error('x'), { code: 'ENOENT' }) }],
+  ['throws', null],
+]) {
+  const run = () => { if (res === null) throw new Error('boom'); return res; };
+  ok(`non-auth failure: ${label} -> null`, check({ env: { GITHUB_TOKEN: 'bad' }, run }) === null);
+}
+// entrambe le variabili: GH_TOKEN rifiutato, GITHUB_TOKEN valido
+{
+  const n = check({ env: { GH_TOKEN: 'bad', GITHUB_TOKEN: 'good' }, run: model({ GH_TOKEN: false, GITHUB_TOKEN: true, stored: false }) });
+  ok('both set: names only GH_TOKEN', n.includes('GH_TOKEN') && !n.includes('GH_TOKEN, GITHUB_TOKEN'));
+  ok('both set: says GITHUB_TOKEN works', n.includes('valid GITHUB_TOKEN') && n.includes('GH_TOKEN= gh'));
+}
+// entrambe rifiutate, login salvato valido
+{
+  const n = check({ env: { GH_TOKEN: 'bad', GITHUB_TOKEN: 'bad2' }, run: model({ GH_TOKEN: false, GITHUB_TOKEN: false, stored: true }) });
+  ok('both rejected: names both', n.includes('GH_TOKEN') && n.includes('GITHUB_TOKEN') && n.includes('GH_TOKEN= GITHUB_TOKEN= gh'));
+  ok('both rejected: no token values', !n.includes('bad'));
+}
+// W1: token rifiutato (401 confermato), login salvato assente (exit 4) -> variante iii
+{
+  const NOLOGIN = { status: 4, stdout: '', stderr: 'To get started with GitHub CLI, please run:  gh auth login' };
+  const run = (env) => (env.GITHUB_TOKEN ? AUTH_ERR : NOLOGIN);
+  const n = check({ env: { GITHUB_TOKEN: 'bad' }, run });
+  ok('bad token + no stored login (exit 4): nothing works', typeof n === 'string' && n.includes('no working `gh` login'));
+  const run2 = (env) => (env.GITHUB_TOKEN ? AUTH_ERR : { status: 1, stdout: '', stderr: 'please run: gh auth login' });
+  ok('bad token + "gh auth login" in stderr: nothing works', /no working/.test(check({ env: { GITHUB_TOKEN: 'bad' }, run: run2 })));
+  // il primo probe (prima di un 401) non usa questa regola: exit 4 senza rifiuto -> null
+  ok('first probe exit 4: null', check({ env: { GITHUB_TOKEN: 'x' }, run: () => NOLOGIN }) === null);
+}
+// W1: token rifiutato, probe del login salvato in errore di rete -> null
+{
+  const run = (env) => (env.GITHUB_TOKEN ? AUTH_ERR : { status: 1, stdout: '', stderr: 'error connecting to api.github.com' });
+  ok('bad token + stored network error: null', check({ env: { GITHUB_TOKEN: 'bad' }, run }) === null);
+  const run2 = (env) => (env.GITHUB_TOKEN ? AUTH_ERR : { status: null, stdout: '', stderr: '', error: new Error('t') });
+  ok('bad token + stored timeout: null', check({ env: { GITHUB_TOKEN: 'bad' }, run: run2 }) === null);
+}
+// I1: budget totale condiviso fra i probe
+{
+  const mk = (step) => {
+    let t = 1000;
+    const timeouts = [];
+    const run = (env, timeoutMs) => { timeouts.push(timeoutMs); t += step; return env.GH_TOKEN || env.GITHUB_TOKEN ? AUTH_ERR : GOOD; };
+    return { run, now: () => t, timeouts };
+  };
+  const a = mk(2000);
+  const n = check({ env: { GH_TOKEN: 'b1', GITHUB_TOKEN: 'b2' }, run: a.run, now: a.now });
+  ok('budget: timeouts decrease and stay bounded', a.timeouts.length === 3 && a.timeouts[0] <= 5000 && a.timeouts[1] < a.timeouts[0] && a.timeouts[2] < a.timeouts[1] && a.timeouts[2] > 0);
+  ok('budget: notice still produced within budget', typeof n === 'string');
+  const b = mk(3000);
+  ok('budget exhausted: null', check({ env: { GH_TOKEN: 'b1', GITHUB_TOKEN: 'b2' }, run: b.run, now: b.now }) === null && b.timeouts.length === 2);
+}
+// source
+for (const source of ['resume', 'compact']) {
+  const run = model({ GITHUB_TOKEN: false, stored: true });
+  ok(`source ${source}: skipped`, check({ env: { GITHUB_TOKEN: 'bad' }, run, source }) === null && run.calls.length === 0);
+}
+for (const source of ['startup', 'clear', undefined, 'weird']) {
+  const run = model({ GITHUB_TOKEN: false, stored: true });
+  ok(`source ${source}: checked`, check({ env: { GITHUB_TOKEN: 'bad' }, run, source }) !== null);
+}
+ok('no em-dash in notices', !/—/.test(check({ env: { GITHUB_TOKEN: 'bad' }, run: model({ GITHUB_TOKEN: false, stored: true }) })));
+
+console.log(`gh-auth-preflight: ${passed} passed`);

package/plugins/trailhead/hooks/lib/git-env-mod.test.js

@@ -0,0 +1,55 @@
+// Mod side of #349: git spawns go through `env -u <repo-location vars> git ...`
+// (the mod's process.run cannot delete env), and the name list matches the template's.
+// The mod file is TypeScript: loaded through Node's type stripping (Node >= 22.18);
+// skipped on an older Node, where the source checks below still run.
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const { GIT_LOCATION_VARS } = require('../../templates/trailhead-git-env.js');
+
+const modDir = path.join(__dirname, '..', 'mod');
+let passed = 0;
+const t = (name, fn) => { fn(); passed++; console.log('ok -', name); };
+
+let mod = null;
+try { mod = require(path.join(modDir, 'git-env.ts')); } catch { /* no type stripping */ }
+
+if (mod) {
+  t('the mod name list equals the template list', () => {
+    assert.deepStrictEqual([...mod.GIT_LOCATION_VARS], [...GIT_LOCATION_VARS]);
+  });
+  t('gitArgv starts with the env -u wrapper and ends with git args', () => {
+    const argv = mod.gitArgv('-C', '/r', 'status');
+    const gitAt = argv.indexOf('git');
+    assert.strictEqual(argv[0], 'env');
+    assert.deepStrictEqual(argv.slice(gitAt), ['git', '-C', '/r', 'status']);
+    const pairs = argv.slice(1, gitAt);
+    assert.deepStrictEqual(pairs.filter((_, i) => i % 2 === 0), GIT_LOCATION_VARS.map(() => '-u'));
+    assert.deepStrictEqual(pairs.filter((_, i) => i % 2 === 1), [...GIT_LOCATION_VARS]);
+  });
+  t('scrubGitEnv wraps a gh argv the same way', () => {
+    const argv = mod.scrubGitEnv(['gh', 'api', 'graphql']);
+    assert.strictEqual(argv[0], 'env');
+    assert.deepStrictEqual(argv.slice(-3), ['gh', 'api', 'graphql']);
+  });
+  t('the wrapper really drops GIT_DIR (env -u, run for real)', () => {
+    const { spawnSync } = require('child_process');
+    const argv = mod.scrubGitEnv([process.execPath, '-p', "'GIT_DIR' in process.env"]);
+    const r = spawnSync(argv[0], argv.slice(1), { encoding: 'utf8', env: { ...process.env, GIT_DIR: '/x' } });
+    assert.strictEqual(r.stdout.trim(), 'false');
+  });
+}
+
+t('no mod file spawns git without the wrapper', () => {
+  for (const f of fs.readdirSync(modDir).filter((n) => /\.tsx?$/.test(n) && n !== 'git-env.ts')) {
+    const src = fs.readFileSync(path.join(modDir, f), 'utf8');
+    assert.ok(!/\[\s*'git'/.test(src), `${f} builds a raw git argv; use gitArgv()`);
+  }
+});
+
+t('map-pane gh calls are wrapped', () => {
+  const src = fs.readFileSync(path.join(modDir, 'map-pane.tsx'), 'utf8');
+  assert.ok(src.includes("scrubGitEnv(['gh', ...args])"));
+});
+
+console.log(`${passed} passed${mod ? '' : ' (type stripping unavailable: wrapper checks skipped)'}`);