@marcomigozzi/trailhead 0.14.0 → 0.16.0

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

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// Tests for templates/trailhead-checkout-in.js. Run: node checkout-in.test.js
+// No framework: plain asserts, same style as uat-backfill.test.js.
+//
+// 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.
+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-in.js');
+const skillPath = path.resolve(__dirname, '..', '..', 'skills', 'trailhead-work', 'SKILL.md');
+const { encodeIn, decodeIn } = require(scriptPath);
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+const eq = (name, a, b) => { assert.deepStrictEqual(a, b, name); passed++; };
+
+const tmp = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'checkout-in-')));
+const sh = (cwd, ...args) => {
+  const r = spawnSync('git', ['-C', cwd, ...args], { encoding: 'utf8' });
+  assert.strictEqual(r.status, 0, `git ${args.join(' ')}: ${r.stderr}`);
+  return r.stdout;
+};
+function makeRepo(dir) {
+  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');
+  return fs.realpathSync(dir);
+}
+const run = (inArg, cwd) => {
+  const r = spawnSync(process.execPath, [scriptPath, '--in', inArg, '--cwd', cwd], { 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);
+
+// --- 1. pure helpers ---------------------------------------------------------------
+const odd = [
+  '/tmp/with space/repo',
+  "/tmp/it's/repo",
+  '/tmp/"dq"/repo',
+  '/tmp/-leading/repo',
+  '-dash-first',
+  '/tmp/uniè中文/repo',
+  "/tmp/a'b'c d/$HOME/`x`",
+];
+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('decode of garbage', decodeIn('!!!'), null);
+eq('decode of empty', decodeIn(''), null);
+
+// --- 2. CLI ------------------------------------------------------------------------
+const main = makeRepo(path.join(tmp, 'main repo'));
+const other = makeRepo(path.join(tmp, 'other'));
+const plain = path.join(tmp, 'plain');
+fs.mkdirSync(plain);
+
+{
+  const r = run(tokenOf(main), main);
+  eq('here in the root', [r.code, r.out.status, r.out.path], [0, 'here', main]);
+}
+{
+  fs.mkdirSync(path.join(main, 'sub'));
+  const r = run(tokenOf(main), path.join(main, 'sub'));
+  eq('here from a subdir of the same checkout', r.out.status, 'here');
+}
+{
+  const r = run(tokenOf(main), other);
+  eq('move from another repo', [r.code, r.out.status, r.out.path], [0, 'move', main]);
+  ok('move carries a cd', r.out.cd === `cd -- '${main}'`);
+}
+{
+  const r = run(tokenOf(main), plain);
+  eq('move from outside any repo', r.out.status, 'move');
+}
+{
+  const r = run(tokenOf(main), path.join(tmp, 'missing-cwd'));
+  eq('move from a cwd that does not exist', r.out.status, 'move');
+}
+
+// A worktree root is its own checkout: here only for itself.
+{
+  const wt = path.join(tmp, 'wt');
+  sh(main, 'worktree', 'add', '-q', '-b', 'wt-branch', wt);
+  const wtReal = fs.realpathSync(wt);
+  eq('worktree root is here for itself', run(tokenOf(wtReal), wtReal).out.status, 'here');
+  eq('worktree root is move from the main checkout', run(tokenOf(wtReal), main).out.status, 'move');
+  eq('main checkout is move from the worktree', run(tokenOf(main), wtReal).out.status, 'move');
+}
+
+// A symlinked path compares canonical.
+{
+  const link = path.join(tmp, 'link-to-main');
+  fs.symlinkSync(main, link);
+  const r = run(tokenOf(link), main);
+  eq('symlinked path is here by canonical compare', r.out.status, 'here');
+  eq('symlinked cwd is here too', run(tokenOf(main), link).out.status, 'here');
+}
+
+// invalid: never searches for another checkout.
+{
+  eq('relative path is invalid', run(tokenOf('relative/dir'), main).out.status, 'invalid');
+  eq('missing path is invalid', run(tokenOf(path.join(tmp, 'nope')), main).out.status, 'invalid');
+  eq('non-repo dir is invalid', run(tokenOf(plain), main).out.status, 'invalid');
+  eq('subdir of a repo is invalid (not a root)', run(tokenOf(path.join(main, 'sub')), other).out.status, 'invalid');
+  const bad = run('!!!', main);
+  eq('undecodable token is invalid', [bad.code, bad.out.status], [0, 'invalid']);
+  ok('invalid has a reason', typeof bad.out.reason === 'string' && bad.out.reason.length > 0);
+  ok('invalid has no cd', !('cd' in run(tokenOf(plain), main).out));
+}
+
+// usage errors
+{
+  const r = spawnSync(process.execPath, [scriptPath, '--cwd', main], { encoding: 'utf8' });
+  eq('missing --in is a usage error', r.status, 2);
+  const r2 = spawnSync(process.execPath, [scriptPath, '--in', tokenOf(main)], { encoding: 'utf8' });
+  eq('missing --cwd is a usage error', r2.status, 2);
+}
+
+// The cd field, run by a shell, lands in the path for every pathological case.
+{
+  let n = 0;
+  for (const p of odd) {
+    if (!path.isAbsolute(p)) continue;
+    const dir = path.join(tmp, `odd${n++}`, p.replace(/^\/tmp\//, '').replace(/\//g, '_'));
+    const real = makeRepo(dir);
+    const r = run(tokenOf(real), plain);
+    eq(`move for ${dir}`, r.out.status, 'move');
+    const cd = spawnSync('sh', ['-c', `${r.out.cd} && pwd -P`], { encoding: 'utf8', cwd: plain });
+    eq(`cd lands in ${dir}`, cd.stdout.trim(), real);
+  }
+  // A quote and a leading dash in the actual directory names.
+  for (const name of ["it's here", '-dash', 'sp ace "dq" $x `y`']) {
+    const real = makeRepo(path.join(tmp, 'pathological', name));
+    const r = run(tokenOf(real), plain);
+    const cd = spawnSync('sh', ['-c', `${r.out.cd} && pwd -P`], { encoding: 'utf8', cwd: plain });
+    eq(`cd lands in ${name}`, cd.stdout.trim(), real);
+  }
+}
+
+// --- 3. protocol contract: the move comes before anything else -----------------------
+{
+  const skill = fs.readFileSync(skillPath, 'utf8');
+  const move = skill.indexOf('## Move into the handed checkout');
+  ok('move section exists', move >= 0);
+  const load = skill.indexOf('## Load first');
+  const pre = skill.indexOf('## Preflight');
+  ok('move section sits before Load first', load > move);
+  ok('move section sits before the Preflight', pre > move);
+  const section = skill.slice(move, load);
+  ok('names the helper', section.includes('trailhead-checkout-in.js'));
+  ok('names the --in= word', section.includes('--in='));
+  ok('names work and resume', /`work`/.test(section) && /`resume`/.test(section));
+  ok('runs the cd field verbatim', /`cd` field[^.]*verbatim/.test(section));
+  ok('cd is its own Bash call', /own Bash call/.test(section));
+  ok('post-move re-check requires here', /re-run the helper/.test(section) && /`here`/.test(section));
+  ok('stops on invalid', /`invalid`[^.]*stop/.test(section));
+  ok('stops on a failed cd', /failed `cd`[^.]*stop|`cd` fails[^.]*stop|stop[^.]*`cd` fail/i.test(section));
+  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('Routing points at the move section', /Routing[\s\S]*Move into the handed checkout/.test(skill.slice(skill.indexOf('## Routing'))));
+}
+
+fs.rmSync(tmp, { recursive: true, force: true });
+console.log(`checkout-in: ${passed} assertions passed`);

package/plugins/trailhead/hooks/lib/commit-message-check.js

@@ -2,7 +2,7 @@
 // commit-message-check.js: the single source of truth for trailhead's commit
 // message rules, shared by two guardrails so they can never drift:
 //   - trailhead-commit-guard.js         (Claude Code PreToolUse(Bash) hook)
-//   - templates/trailhead-commit-msg    (host-independent git commit-msg hook,
+//   - templates/trailhead-commit-msg.cjs (host-independent git commit-msg hook logic,
 //     installed into .git/hooks at repo first-use so it runs on ANY host)
 // Two rules: NEVER a Co-Authored-By trailer; a Conventional Commits subject
 // (<type>(scope)?: subject) of at most 72 chars. Plus a conditional third rule:

package/plugins/trailhead/hooks/lib/commit-message-check.test.js

@@ -4,7 +4,8 @@
 //
 // Drives the SAME fixtures through two paths:
 //   1. checkCommitMessage() directly (the source of truth).
-//   2. the template hook (templates/trailhead-commit-msg) end-to-end via
+//   2. the template hook (templates/trailhead-commit-msg sh wrapper, which runs
+//      the sibling trailhead-commit-msg.cjs logic) end-to-end via
 //      execFileSync, feeding it the message as a temp file, run from a fresh
 //      mkdtemp cwd (so the template's own .trailhead/session-ticket lookup is
 //      independent of this repo's real marker).
@@ -60,7 +61,7 @@ function runTemplateHook(message, marker) {
   let allowed = true;
   let stderr = '';
   try {
-    execFileSync('node', [templatePath, tmpFile], { cwd: tmp, stdio: 'pipe' });
+    execFileSync('sh', [templatePath, tmpFile], { cwd: tmp, stdio: 'pipe' });
   } catch (e) {
     allowed = false;
     stderr = e.stderr ? e.stderr.toString() : '';

package/plugins/trailhead/hooks/lib/commit-msg-module-repo.test.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// Regression for #257: the git commit-msg hook must work in a repo whose root
+// package.json says "type": "module". The hook is installed by the sync script
+// into a fixture repo and exercised through real `git commit` calls.
+// Run: node commit-msg-module-repo.test.js
+const assert = require('assert');
+const { execFileSync, spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const syncScript = path.resolve(__dirname, '..', '..', 'templates', 'trailhead-commit-msg-sync.js');
+
+// Prefisso della riga che il wrapper stampa quando non può applicare le regole (#262).
+const INACTIVE = 'trailhead: commit-msg hook inactive (';
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+function gitEnv(extra) {
+  return Object.assign({}, process.env, {
+    GIT_CONFIG_GLOBAL: '/dev/null',
+    GIT_CONFIG_NOSYSTEM: '1',
+    GIT_AUTHOR_NAME: 'Trailhead Test',
+    GIT_AUTHOR_EMAIL: 'trailhead-test@example.com',
+    GIT_COMMITTER_NAME: 'Trailhead Test',
+    GIT_COMMITTER_EMAIL: 'trailhead-test@example.com',
+  }, extra || {});
+}
+
+// Repo fixture: package.json "type": "module" alla radice, hook installato dallo
+// script di sync, marker session-ticket = #1.
+function makeRepo() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-commit-msg-esm-'));
+  execFileSync('git', ['init', '-q'], { cwd: dir, env: gitEnv() });
+  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ type: 'module' }));
+  const out = execFileSync(process.execPath, [syncScript, '--repo', dir], { env: gitEnv(), encoding: 'utf8' });
+  assert.strictEqual(JSON.parse(out).status, 'installed');
+  fs.mkdirSync(path.join(dir, '.trailhead'));
+  fs.writeFileSync(path.join(dir, '.trailhead', 'session-ticket'), '#1 x\n');
+  return { dir, hooksDir: path.join(dir, '.git', 'hooks') };
+}
+
+function commit(dir, message) {
+  const r = spawnSync('git', ['commit', '--allow-empty', '-q', '-m', message], { cwd: dir, env: gitEnv(), encoding: 'utf8' });
+  return { status: r.status, stderr: r.stderr || '' };
+}
+
+// (a) commit convenzionale con Refs: #1 passa
+{
+  const { dir } = makeRepo();
+  const r = commit(dir, 'fix: thing\n\nRefs: #1');
+  ok('module repo: conventional commit with Refs passes', r.status === 0);
+  ok('module repo: clean commit stays silent', !r.stderr.includes('trailhead:'));
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// (b) senza trailer: rifiutato col messaggio di trailhead
+{
+  const { dir } = makeRepo();
+  const r = commit(dir, 'fix: thing');
+  ok('module repo: missing Refs is rejected with exit 1', r.status === 1);
+  ok('module repo: rejection carries trailhead message', r.stderr.includes('trailhead:') && r.stderr.includes('Refs: #1'));
+  ok('module repo: no ESM load error leaks', !r.stderr.includes('require is not defined'));
+  ok('module repo: a violation carries no inactive notice', !r.stderr.includes(INACTIVE));
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// (c) errori di avvio: mai bloccare un commit, ma segnalarlo su stderr (#262)
+{
+  const { dir, hooksDir } = makeRepo();
+  fs.rmSync(path.join(hooksDir, 'trailhead-commit-msg.cjs'));
+  const r = commit(dir, 'not conventional at all');
+  ok('module repo: missing .cjs lets the commit through', r.status === 0);
+  ok('module repo: missing .cjs prints the inactive notice',
+    r.stderr.includes(INACTIVE + 'trailhead-commit-msg.cjs missing or unreadable)'));
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+// .cjs presente ma illeggibile: da root chmod non toglie la lettura, quindi si salta.
+if (typeof process.getuid !== 'function' || process.getuid() !== 0) {
+  const { dir, hooksDir } = makeRepo();
+  fs.chmodSync(path.join(hooksDir, 'trailhead-commit-msg.cjs'), 0o000);
+  const r = commit(dir, 'not conventional at all');
+  ok('module repo: unreadable .cjs lets the commit through', r.status === 0);
+  ok('module repo: unreadable .cjs prints the inactive notice',
+    r.stderr.includes(INACTIVE + 'trailhead-commit-msg.cjs missing or unreadable)'));
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+{
+  const { dir, hooksDir } = makeRepo();
+  fs.writeFileSync(path.join(hooksDir, 'trailhead-commit-msg.cjs'), "throw new Error('boom at load');\n");
+  const r = commit(dir, 'not conventional at all');
+  ok('module repo: .cjs crashing at load lets the commit through', r.status === 0);
+  ok('module repo: .cjs crashing at load prints the inactive notice',
+    r.stderr.includes(INACTIVE + 'trailhead-commit-msg.cjs failed to run, exit '));
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+{
+  // node assente dal PATH: il wrapper deve uscire 0 anche con un messaggio che
+  // altrimenti sarebbe una violazione (controllo negativo con PATH normale).
+  const { dir, hooksDir } = makeRepo();
+  const msgFile = path.join(dir, 'MSG');
+  fs.writeFileSync(msgFile, 'not conventional at all\n');
+  const emptyBin = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-empty-bin-'));
+  const hook = path.join(hooksDir, 'commit-msg');
+  const withNode = spawnSync('/bin/sh', [hook, msgFile], { cwd: dir, env: gitEnv(), encoding: 'utf8' });
+  ok('wrapper control: violation exits 1 with node on PATH', withNode.status === 1);
+  const noNode = spawnSync('/bin/sh', [hook, msgFile], { cwd: dir, env: { PATH: emptyBin }, encoding: 'utf8' });
+  ok('wrapper: node absent from PATH exits 0', noNode.status === 0);
+  ok('wrapper: node absent from PATH prints the inactive notice',
+    (noNode.stderr || '').includes(INACTIVE + 'node not found on PATH)'));
+  fs.rmSync(emptyBin, { recursive: true, force: true });
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+console.log(`✓ commit-msg module repo (#257): ${passed} assertions passed`);

package/plugins/trailhead/hooks/lib/commit-msg-sync.test.js

@@ -16,7 +16,10 @@ const os = require('os');
 
 const scriptPath = path.resolve(__dirname, '..', '..', 'templates', 'trailhead-commit-msg-sync.js');
 const templatePath = path.resolve(__dirname, '..', '..', 'templates', 'trailhead-commit-msg');
+const cjsTemplatePath = path.resolve(__dirname, '..', '..', 'templates', 'trailhead-commit-msg.cjs');
 const oldFixturePath = path.join(__dirname, 'fixtures', 'commit-msg-a319156');
+// Hook JS monofile pre-#257 (extensionless CommonJS), da migrare al nuovo layout.
+const legacyJsFixturePath = path.join(__dirname, 'fixtures', 'commit-msg-legacy-js');
 
 const {
   resolveHooksTarget,
@@ -29,7 +32,10 @@ let passed = 0;
 const ok = (name, cond) => { assert.ok(cond, name); passed++; };
 
 const templateText = fs.readFileSync(templatePath, 'utf8');
+const cjsText = fs.readFileSync(cjsTemplatePath, 'utf8');
 const oldHookText = fs.readFileSync(oldFixturePath, 'utf8');
+const legacyJsText = fs.readFileSync(legacyJsFixturePath, 'utf8');
+const CJS_NAME = 'trailhead-commit-msg.cjs';
 
 function mktmp() {
   return fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-commit-msg-sync-test-'));
@@ -38,6 +44,9 @@ function mktmp() {
 // --- isTrailheadHook() unit cases -------------------------------------------
 ok('isTrailheadHook: current template is recognised', isTrailheadHook(templateText));
 ok('isTrailheadHook: old (a319156) hook is recognised', isTrailheadHook(oldHookText));
+ok('isTrailheadHook: legacy single-file JS hook is recognised', isTrailheadHook(legacyJsText));
+ok('isTrailheadHook: wrapper header is on a "#" line within the first 5', isTrailheadHook(templateText));
+ok('isTrailheadHook: wrapper is a sh script', templateText.startsWith('#!/bin/sh\n'));
 ok('isTrailheadHook: plain foreign script is not', !isTrailheadHook('#!/bin/sh\necho hi\n'));
 ok('isTrailheadHook: mention outside the first 5 lines, not line-start, is not',
   !isTrailheadHook('#!/bin/sh\necho hi\necho more\necho stuff\necho again\n# trailhead commit-msg hook (git). fake\n'));
@@ -55,13 +64,14 @@ function modeOf(p) { return fs.statSync(p).mode & 0o777; }
 // absent -> installed, 0755
 {
   const dir = mktmp();
-  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, fs });
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, cjsText, fs });
   const hookPath = path.join(dir, 'commit-msg');
   ok('syncCommitMsgHook: absent -> installed', result.status === 'installed');
   ok('syncCommitMsgHook: absent -> hook path returned', result.hook === hookPath);
   ok('syncCommitMsgHook: absent -> file written', fs.existsSync(hookPath));
   ok('syncCommitMsgHook: absent -> content matches template', fs.readFileSync(hookPath, 'utf8') === templateText);
   ok('syncCommitMsgHook: absent -> mode 0755', modeOf(hookPath) === 0o755);
+  ok('syncCommitMsgHook: absent -> .cjs written beside it', fs.readFileSync(path.join(dir, CJS_NAME), 'utf8') === cjsText);
   fs.rmSync(dir, { recursive: true, force: true });
 }
 
@@ -71,21 +81,77 @@ function modeOf(p) { return fs.statSync(p).mode & 0o777; }
   const hookPath = path.join(dir, 'commit-msg');
   fs.writeFileSync(hookPath, oldHookText);
   fs.chmodSync(hookPath, 0o755);
-  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, fs });
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, cjsText, fs });
   ok('syncCommitMsgHook: old -> upgraded', result.status === 'upgraded');
   ok('syncCommitMsgHook: old -> bytes now match template', fs.readFileSync(hookPath, 'utf8') === templateText);
   ok('syncCommitMsgHook: old -> mode 0755', modeOf(hookPath) === 0o755);
   fs.rmSync(dir, { recursive: true, force: true });
 }
 
+// legacy single-file JS hook -> upgraded to wrapper + .cjs
+{
+  const dir = mktmp();
+  const hookPath = path.join(dir, 'commit-msg');
+  fs.writeFileSync(hookPath, legacyJsText);
+  fs.chmodSync(hookPath, 0o755);
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, cjsText, hooksPathSet: false, fs });
+  ok('syncCommitMsgHook: legacy JS -> upgraded', result.status === 'upgraded');
+  ok('syncCommitMsgHook: legacy JS -> wrapper now matches template', fs.readFileSync(hookPath, 'utf8') === templateText);
+  ok('syncCommitMsgHook: legacy JS -> .cjs written', fs.readFileSync(path.join(dir, CJS_NAME), 'utf8') === cjsText);
+  ok('syncCommitMsgHook: legacy JS -> wrapper mode 0755', modeOf(hookPath) === 0o755);
+  const again = syncCommitMsgHook({ hooksDir: dir, templateText, cjsText, hooksPathSet: false, fs });
+  ok('syncCommitMsgHook: legacy JS -> second run is current', again.status === 'current');
+  ok('syncCommitMsgHook: legacy JS -> no temp files left', fs.readdirSync(dir).sort().join(',') === `commit-msg,${CJS_NAME}`);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// current wrapper but outdated .cjs -> upgraded, .cjs rewritten
+{
+  const dir = mktmp();
+  const hookPath = path.join(dir, 'commit-msg');
+  fs.writeFileSync(hookPath, templateText);
+  fs.chmodSync(hookPath, 0o755);
+  fs.writeFileSync(path.join(dir, CJS_NAME), '// stale\n');
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, cjsText, hooksPathSet: false, fs });
+  ok('syncCommitMsgHook: outdated .cjs -> upgraded', result.status === 'upgraded');
+  ok('syncCommitMsgHook: outdated .cjs -> rewritten', fs.readFileSync(path.join(dir, CJS_NAME), 'utf8') === cjsText);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// current wrapper but .cjs missing -> upgraded, .cjs restored
+{
+  const dir = mktmp();
+  const hookPath = path.join(dir, 'commit-msg');
+  fs.writeFileSync(hookPath, templateText);
+  fs.chmodSync(hookPath, 0o755);
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, cjsText, hooksPathSet: false, fs });
+  ok('syncCommitMsgHook: missing .cjs -> upgraded', result.status === 'upgraded');
+  ok('syncCommitMsgHook: missing .cjs -> restored', fs.readFileSync(path.join(dir, CJS_NAME), 'utf8') === cjsText);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// outdated wrapper (older sh wrapper text) + current .cjs -> upgraded wrapper
+{
+  const dir = mktmp();
+  const hookPath = path.join(dir, 'commit-msg');
+  fs.writeFileSync(hookPath, '#!/bin/sh\n# trailhead commit-msg hook (git). older wrapper\nexit 0\n');
+  fs.chmodSync(hookPath, 0o755);
+  fs.writeFileSync(path.join(dir, CJS_NAME), cjsText);
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, cjsText, hooksPathSet: false, fs });
+  ok('syncCommitMsgHook: outdated wrapper -> upgraded', result.status === 'upgraded');
+  ok('syncCommitMsgHook: outdated wrapper -> now matches template', fs.readFileSync(hookPath, 'utf8') === templateText);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
 // CRLF current -> current, untouched
 {
   const dir = mktmp();
   const hookPath = path.join(dir, 'commit-msg');
   const crlfTemplate = templateText.replace(/\n/g, '\r\n');
+  fs.writeFileSync(path.join(dir, CJS_NAME), cjsText);
   fs.writeFileSync(hookPath, crlfTemplate);
   fs.chmodSync(hookPath, 0o755);
-  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, fs });
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, cjsText, fs });
   ok('syncCommitMsgHook: CRLF current -> current', result.status === 'current');
   ok('syncCommitMsgHook: CRLF current -> untouched bytes', fs.readFileSync(hookPath, 'utf8') === crlfTemplate);
   fs.rmSync(dir, { recursive: true, force: true });
@@ -96,8 +162,9 @@ function modeOf(p) { return fs.statSync(p).mode & 0o777; }
   const dir = mktmp();
   const hookPath = path.join(dir, 'commit-msg');
   fs.writeFileSync(hookPath, templateText);
+  fs.writeFileSync(path.join(dir, CJS_NAME), cjsText);
   fs.chmodSync(hookPath, 0o644);
-  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, fs });
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, cjsText, fs });
   ok('syncCommitMsgHook: current 0644 -> status current', result.status === 'current');
   ok('syncCommitMsgHook: current 0644 -> mode fixed to 0755', modeOf(hookPath) === 0o755);
   fs.rmSync(dir, { recursive: true, force: true });
@@ -110,10 +177,11 @@ function modeOf(p) { return fs.statSync(p).mode & 0o777; }
   const foreign = '#!/bin/sh\necho hi\n';
   fs.writeFileSync(hookPath, foreign);
   fs.chmodSync(hookPath, 0o755);
-  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, fs });
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, cjsText, fs });
   ok('syncCommitMsgHook: foreign shell -> foreign', result.status === 'foreign');
   ok('syncCommitMsgHook: foreign shell -> bytes untouched', fs.readFileSync(hookPath, 'utf8') === foreign);
   ok('syncCommitMsgHook: foreign shell -> mode untouched', modeOf(hookPath) === 0o755);
+  ok('syncCommitMsgHook: foreign shell -> no .cjs written', !fs.existsSync(path.join(dir, CJS_NAME)));
   fs.rmSync(dir, { recursive: true, force: true });
 }
 
@@ -124,7 +192,7 @@ function modeOf(p) { return fs.statSync(p).mode & 0o777; }
   const foreign = '#!/bin/sh\necho "trailhead commit-msg hook (git). not really"\nexit 0\n';
   fs.writeFileSync(hookPath, foreign);
   fs.chmodSync(hookPath, 0o755);
-  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, fs });
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, cjsText, fs });
   ok('syncCommitMsgHook: foreign wrapper mentioning phrase -> foreign', result.status === 'foreign');
   ok('syncCommitMsgHook: foreign wrapper -> bytes untouched', fs.readFileSync(hookPath, 'utf8') === foreign);
   fs.rmSync(dir, { recursive: true, force: true });
@@ -138,10 +206,11 @@ function modeOf(p) { return fs.statSync(p).mode & 0o777; }
   const targetContent = '#!/bin/sh\necho real\n';
   fs.writeFileSync(targetPath, targetContent);
   fs.symlinkSync(targetPath, hookPath);
-  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, fs });
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, cjsText, fs });
   ok('syncCommitMsgHook: symlink -> foreign', result.status === 'foreign');
   ok('syncCommitMsgHook: symlink -> still a symlink', fs.lstatSync(hookPath).isSymbolicLink());
   ok('syncCommitMsgHook: symlink target untouched', fs.readFileSync(targetPath, 'utf8') === targetContent);
+  ok('syncCommitMsgHook: symlink -> no .cjs written', !fs.existsSync(path.join(dir, CJS_NAME)));
   fs.rmSync(dir, { recursive: true, force: true });
 }
 
@@ -149,9 +218,9 @@ function modeOf(p) { return fs.statSync(p).mode & 0o777; }
 {
   const dir = mktmp();
   const hookPath = path.join(dir, 'commit-msg');
-  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: true, fs });
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: true, cjsText, fs });
   ok('syncCommitMsgHook: absent + hooksPathSet -> skipped', result.status === 'skipped');
-  ok('syncCommitMsgHook: absent + hooksPathSet -> nothing created', !fs.existsSync(hookPath));
+  ok('syncCommitMsgHook: absent + hooksPathSet -> nothing created', !fs.existsSync(hookPath) && !fs.existsSync(path.join(dir, CJS_NAME)));
   fs.rmSync(dir, { recursive: true, force: true });
 }
 
@@ -226,6 +295,7 @@ function assertSingleJsonLine(out, label) {
   const hookPath = path.join(dir, '.git', 'hooks', 'commit-msg');
   ok('e2e fresh repo: hook file exists', fs.existsSync(hookPath));
   ok('e2e fresh repo: hook is executable', (modeOf(hookPath) & 0o111) !== 0);
+  ok('e2e fresh repo: .cjs installed beside it', fs.readFileSync(path.join(dir, '.git', 'hooks', CJS_NAME), 'utf8') === cjsText);
 
   const out2 = runScript(['--repo', dir], { env: gitEnv() });
   const parsed2 = assertSingleJsonLine(out2, 'e2e fresh repo (2nd run)');
@@ -246,6 +316,24 @@ function assertSingleJsonLine(out, label) {
   const parsed = assertSingleJsonLine(out, 'e2e seeded old hook');
   ok('e2e seeded old hook: status upgraded', parsed.status === 'upgraded');
   ok('e2e seeded old hook: content now matches template', fs.readFileSync(hookPath, 'utf8') === templateText);
+  ok('e2e seeded old hook: .cjs installed', fs.readFileSync(path.join(hooksDir, CJS_NAME), 'utf8') === cjsText);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// seeded legacy single-file JS hook -> upgraded to wrapper + .cjs
+{
+  const dir = mktmp();
+  execFileSync('git', ['init', '-q'], { cwd: dir, env: gitEnv() });
+  const hooksDir = path.join(dir, '.git', 'hooks');
+  fs.mkdirSync(hooksDir, { recursive: true });
+  const hookPath = path.join(hooksDir, 'commit-msg');
+  fs.writeFileSync(hookPath, legacyJsText);
+  fs.chmodSync(hookPath, 0o755);
+  const out = runScript(['--repo', dir], { env: gitEnv() });
+  const parsed = assertSingleJsonLine(out, 'e2e seeded legacy JS hook');
+  ok('e2e seeded legacy JS hook: status upgraded', parsed.status === 'upgraded');
+  ok('e2e seeded legacy JS hook: wrapper installed', fs.readFileSync(hookPath, 'utf8') === templateText);
+  ok('e2e seeded legacy JS hook: .cjs installed', fs.readFileSync(path.join(hooksDir, CJS_NAME), 'utf8') === cjsText);
   fs.rmSync(dir, { recursive: true, force: true });
 }
 
@@ -263,6 +351,7 @@ function assertSingleJsonLine(out, label) {
   const parsed = assertSingleJsonLine(out, 'e2e seeded foreign hook');
   ok('e2e seeded foreign hook: status foreign', parsed.status === 'foreign');
   ok('e2e seeded foreign hook: bytes untouched', fs.readFileSync(hookPath, 'utf8') === foreign);
+  ok('e2e seeded foreign hook: no .cjs written', !fs.existsSync(path.join(hooksDir, CJS_NAME)));
   fs.rmSync(dir, { recursive: true, force: true });
 }
 
@@ -293,6 +382,7 @@ function assertSingleJsonLine(out, label) {
   const parsed = assertSingleJsonLine(out, 'e2e core.hooksPath old hook');
   ok('e2e core.hooksPath old hook: status upgraded', parsed.status === 'upgraded');
   ok('e2e core.hooksPath old hook: upgraded in .githooks', fs.readFileSync(hookPath, 'utf8') === templateText);
+  ok('e2e core.hooksPath old hook: .cjs lands in .githooks', fs.readFileSync(path.join(githooksDir, CJS_NAME), 'utf8') === cjsText);
   fs.rmSync(dir, { recursive: true, force: true });
 }
 
@@ -311,6 +401,7 @@ function assertSingleJsonLine(out, label) {
   const parsed = assertSingleJsonLine(out, 'e2e core.hooksPath foreign hook');
   ok('e2e core.hooksPath foreign hook: status foreign', parsed.status === 'foreign');
   ok('e2e core.hooksPath foreign hook: untouched', fs.readFileSync(hookPath, 'utf8') === foreign);
+  ok('e2e core.hooksPath foreign hook: no .cjs written', !fs.existsSync(path.join(githooksDir, CJS_NAME)));
   fs.rmSync(dir, { recursive: true, force: true });
 }