@marcomigozzi/trailhead 0.10.0 → 0.11.0

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

@@ -5,7 +5,9 @@
 // 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
-//      execFileSync, feeding it the message as a temp file.
+//      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).
 // The two verdicts must always agree: that agreement is the anti-drift
 // guarantee that keeps the Claude Code hook and the git commit-msg hook from
 // ever diverging.
@@ -15,7 +17,7 @@ const path = require('path');
 const fs = require('fs');
 const os = require('os');
 
-const { checkCommitMessage } = require('./commit-message-check.js');
+const { checkCommitMessage, parseSessionTicket, hasRefsFor } = require('./commit-message-check.js');
 
 const templatePath = path.resolve(__dirname, '..', '..', 'templates', 'trailhead-commit-msg');
 
@@ -37,7 +39,7 @@ const FIXTURES = [
   { name: 'empty message', message: '', expectOk: true },
 ];
 
-// --- unit: checkCommitMessage() directly ---
+// --- unit: checkCommitMessage() directly (no ticket, no marker) ---
 for (const f of FIXTURES) {
   const verdict = checkCommitMessage(f.message);
   ok(`checkCommitMessage: ${f.name} -> ok=${f.expectOk}`, verdict.ok === f.expectOk);
@@ -46,22 +48,30 @@ for (const f of FIXTURES) {
   }
 }
 
-// --- end-to-end: drive the template hook on the SAME fixtures ---
-function runTemplateHook(message) {
-  const tmpFile = path.join(os.tmpdir(), `trailhead-commit-msg-test-${process.pid}-${Math.random().toString(36).slice(2)}.txt`);
+// --- end-to-end: drive the template hook on the SAME fixtures, no marker ---
+function runTemplateHook(message, marker) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-commit-msg-test-'));
+  const tmpFile = path.join(tmp, 'COMMIT_EDITMSG');
   fs.writeFileSync(tmpFile, message);
+  if (marker !== undefined) {
+    fs.mkdirSync(path.join(tmp, '.trailhead'));
+    fs.writeFileSync(path.join(tmp, '.trailhead', 'session-ticket'), marker);
+  }
+  let allowed = true;
+  let stderr = '';
   try {
-    execFileSync('node', [templatePath, tmpFile]);
-    return true; // exit 0 -> allow
-  } catch {
-    return false; // non-zero exit -> block
+    execFileSync('node', [templatePath, tmpFile], { cwd: tmp, stdio: 'pipe' });
+  } catch (e) {
+    allowed = false;
+    stderr = e.stderr ? e.stderr.toString() : '';
   } finally {
-    fs.rmSync(tmpFile, { force: true });
+    fs.rmSync(tmp, { recursive: true, force: true });
   }
+  return { allowed, stderr };
 }
 
 for (const f of FIXTURES) {
-  const allowed = runTemplateHook(f.message);
+  const { allowed } = runTemplateHook(f.message);
   const expected = checkCommitMessage(f.message).ok;
   ok(`template hook: ${f.name} -> allowed=${expected}`, allowed === expected);
 }
@@ -78,6 +88,86 @@ ok('no-strip: #-leading subject blocks with the conventional code',
 ok('default strip: #-leading line is a comment -> empty subject -> allow',
   checkCommitMessage(hashSubject).ok === true);
 ok('template hook: #-leading message is file-semantics (comment) -> allow',
-  runTemplateHook(hashSubject) === true);
+  runTemplateHook(hashSubject).allowed === true);
+
+// --- parseSessionTicket unit cases ---
+ok('parseSessionTicket: normal marker', parseSessionTicket('#184 Enforce the Refs trailer\n') === 184);
+ok('parseSessionTicket: number only', parseSessionTicket('#184') === 184);
+ok('parseSessionTicket: empty text', parseSessionTicket('') === null);
+ok('parseSessionTicket: missing hash', parseSessionTicket('184 Title') === null);
+ok('parseSessionTicket: non-numeric', parseSessionTicket('#abc') === null);
+ok('parseSessionTicket: zero', parseSessionTicket('#0 Title') === null);
+ok('parseSessionTicket: trailing junk glued to number', parseSessionTicket('#184x Title') === null);
+ok('parseSessionTicket: BOM stripped', parseSessionTicket('#184 Title') === 184);
+ok('parseSessionTicket: CRLF stripped', parseSessionTicket('#184 Title\r\nsecond line') === 184);
+
+// --- Refs / ticket fixtures: [marker, message, expectOk, expectCode?] ---
+const REFS_FIXTURES = [
+  { name: 'refs matches marker', marker: '#184 Title\n', message: 'feat: x\n\nRefs: #184', expectOk: true },
+  { name: 'refs multi list matches', marker: '#184 Title\n', message: 'feat: x\n\nRefs: #12, #184', expectOk: true },
+  { name: 'lowercase refs matches', marker: '#184 Title\n', message: 'feat: x\n\nrefs: #184', expectOk: true },
+  { name: 'no refs at all', marker: '#184 Title\n', message: 'feat: x', expectOk: false, code: 'REFS_TRAILER_MISSING' },
+  { name: 'refs wrong ticket', marker: '#184 Title\n', message: 'feat: x\n\nRefs: #183', expectOk: false, code: 'REFS_TRAILER_MISSING' },
+  { name: 'refs prefix-only mismatch (18 vs 184)', marker: '#184 Title\n', message: 'feat: x\n\nRefs: #18', expectOk: false, code: 'REFS_TRAILER_MISSING' },
+  { name: 'marker itself truncated (#18) with refs #184', marker: '#18 Title\n', message: 'feat: x\n\nRefs: #184', expectOk: false, code: 'REFS_TRAILER_MISSING' },
+  { name: 'refs suffix junk rejected (#184abc)', marker: '#184 Title\n', message: 'feat: x\n\nRefs: #184abc', expectOk: false, code: 'REFS_TRAILER_MISSING' },
+  { name: 'refs only inside a comment line', marker: '#184 Title\n', message: 'feat: x\n\n# Refs: #184', expectOk: false, code: 'REFS_TRAILER_MISSING' },
+  {
+    name: 'refs only after the scissors line',
+    marker: '#184 Title\n',
+    message: 'feat: x\n\n# ------------------------ >8 ------------------------\nRefs: #184',
+    expectOk: false,
+    code: 'REFS_TRAILER_MISSING',
+  },
+  { name: 'empty message with active marker still requires refs', marker: '#184 Title\n', message: '', expectOk: false, code: 'REFS_TRAILER_MISSING' },
+  { name: 'no marker: refs rule off, plain conventional commit ok', marker: undefined, message: 'feat: x', expectOk: true },
+  { name: 'malformed marker (no hash): rule off', marker: '184 Title\n', message: 'feat: x', expectOk: true },
+  { name: 'malformed marker (non-numeric): rule off', marker: '#abc\n', message: 'feat: x', expectOk: true },
+  { name: 'malformed marker (empty file): rule off', marker: '', message: 'feat: x', expectOk: true },
+  { name: 'malformed marker (#0): rule off', marker: '#0 Title\n', message: 'feat: x', expectOk: true },
+  {
+    name: 'precedence: non-conventional subject without refs -> conventional code wins',
+    marker: '#184 Title\n',
+    message: 'wip stuff',
+    expectOk: false,
+    code: 'CONVENTIONAL_COMMITS_VIOLATION',
+  },
+];
+
+for (const f of REFS_FIXTURES) {
+  const ticket = parseSessionTicket(f.marker === undefined ? '' : f.marker);
+  const verdict = checkCommitMessage(f.message, { ticket });
+  ok(`checkCommitMessage(ticket): ${f.name} -> ok=${f.expectOk}`, verdict.ok === f.expectOk);
+  if (!f.expectOk && f.code) {
+    ok(`checkCommitMessage(ticket): ${f.name} -> code=${f.code}`, verdict.code === f.code);
+  }
+
+  const { allowed, stderr } = runTemplateHook(f.message, f.marker);
+  ok(`template hook(ticket): ${f.name} -> allowed=${f.expectOk}`, allowed === f.expectOk);
+  if (!f.expectOk && f.code === 'REFS_TRAILER_MISSING') {
+    ok(`template hook(ticket): ${f.name} -> stderr matches lib reason`,
+      stderr.trim() === verdict.reason);
+  }
+}
+
+// --- extra API asserts from the plan ---
+ok('checkCommitMessage: string ticket disables the rule (never blocks)',
+  checkCommitMessage('feat: x', { ticket: '184' }).ok === true);
+ok('checkCommitMessage: numeric ticket + stripComments:false still finds Refs',
+  checkCommitMessage('feat: x\n\nRefs: #184', { ticket: 184, stripComments: false }).ok === true);
+
+// --- template stderr content check for the missing-refs case ---
+{
+  const { stderr } = runTemplateHook('feat: x', '#184 Title\n');
+  ok('template stderr mentions Refs: #184', stderr.includes('Refs: #184'));
+}
+
+// --- hasRefsFor unit checks ---
+ok('hasRefsFor: direct match', hasRefsFor('Refs: #184', 184) === true);
+ok('hasRefsFor: no match', hasRefsFor('Refs: #18', 184) === false);
+ok('hasRefsFor: a "# Refs:" comment line never counts',
+  hasRefsFor('# Refs: #184', 184) === false);
+ok('hasRefsFor: a Refs line in a multi-line body counts',
+  hasRefsFor('feat: x\n\nbody\n\nRefs: #184', 184) === true);
 
 console.log(`✓ commit-message-check: ${passed} assertions passed`);

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

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+// Tests for templates/trailhead-commit-msg-sync.js. Run: node commit-msg-sync.test.js
+// No framework: plain asserts, mirrors the style of commit-message-check.test.js.
+//
+// Covers three layers:
+//   1. isTrailheadHook() / normalize() unit cases.
+//   2. syncCommitMsgHook() unit cases against mkdtemp hook dirs (fs seam left
+//      as the real fs; each case gets its own scratch dir).
+//   3. resolveHooksTarget() with a stubbed runGit (no shelling out).
+//   4. End-to-end: execFileSync the script itself against real git repos.
+const assert = require('assert');
+const { execFileSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+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 oldFixturePath = path.join(__dirname, 'fixtures', 'commit-msg-a319156');
+
+const {
+  resolveHooksTarget,
+  isTrailheadHook,
+  normalize,
+  syncCommitMsgHook,
+} = require(scriptPath);
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const templateText = fs.readFileSync(templatePath, 'utf8');
+const oldHookText = fs.readFileSync(oldFixturePath, 'utf8');
+
+function mktmp() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-commit-msg-sync-test-'));
+}
+
+// --- isTrailheadHook() unit cases -------------------------------------------
+ok('isTrailheadHook: current template is recognised', isTrailheadHook(templateText));
+ok('isTrailheadHook: old (a319156) hook is recognised', isTrailheadHook(oldHookText));
+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'));
+ok('isTrailheadHook: mention inside an echo on line 2 is not',
+  !isTrailheadHook('#!/bin/sh\necho "trailhead commit-msg hook (git)."\n'));
+ok('isTrailheadHook: empty text is not', !isTrailheadHook(''));
+
+// --- normalize() unit cases --------------------------------------------------
+ok('normalize: CRLF becomes LF', normalize('a\r\nb\r\n') === 'a\nb\n');
+ok('normalize: LF-only text is unchanged', normalize('a\nb\n') === 'a\nb\n');
+
+// --- syncCommitMsgHook() unit cases ------------------------------------------
+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 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);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// old -> upgraded, bytes === template, 0755
+{
+  const dir = mktmp();
+  const hookPath = path.join(dir, 'commit-msg');
+  fs.writeFileSync(hookPath, oldHookText);
+  fs.chmodSync(hookPath, 0o755);
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, 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 });
+}
+
+// CRLF current -> current, untouched
+{
+  const dir = mktmp();
+  const hookPath = path.join(dir, 'commit-msg');
+  const crlfTemplate = templateText.replace(/\n/g, '\r\n');
+  fs.writeFileSync(hookPath, crlfTemplate);
+  fs.chmodSync(hookPath, 0o755);
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, 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 });
+}
+
+// current but mode 0644 -> current, mode fixed to 0755
+{
+  const dir = mktmp();
+  const hookPath = path.join(dir, 'commit-msg');
+  fs.writeFileSync(hookPath, templateText);
+  fs.chmodSync(hookPath, 0o644);
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, 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 });
+}
+
+// foreign shell script -> foreign, untouched
+{
+  const dir = mktmp();
+  const hookPath = path.join(dir, 'commit-msg');
+  const foreign = '#!/bin/sh\necho hi\n';
+  fs.writeFileSync(hookPath, foreign);
+  fs.chmodSync(hookPath, 0o755);
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, 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);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// foreign wrapper mentioning the phrase in an echo on line 2 -> foreign
+{
+  const dir = mktmp();
+  const hookPath = path.join(dir, 'commit-msg');
+  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 });
+  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 });
+}
+
+// symlink -> foreign, target untouched
+{
+  const dir = mktmp();
+  const hookPath = path.join(dir, 'commit-msg');
+  const targetPath = path.join(dir, 'real-hook.sh');
+  const targetContent = '#!/bin/sh\necho real\n';
+  fs.writeFileSync(targetPath, targetContent);
+  fs.symlinkSync(targetPath, hookPath);
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, 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);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// absent + hooksPathSet -> skipped, nothing created
+{
+  const dir = mktmp();
+  const hookPath = path.join(dir, 'commit-msg');
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: true, fs });
+  ok('syncCommitMsgHook: absent + hooksPathSet -> skipped', result.status === 'skipped');
+  ok('syncCommitMsgHook: absent + hooksPathSet -> nothing created', !fs.existsSync(hookPath));
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// --- resolveHooksTarget() with a stubbed runGit ------------------------------
+{
+  const stubThrow = () => { throw new Error('not a git repo'); };
+  const result = resolveHooksTarget({ repoDir: '/nonexistent-repo-dir', runGit: stubThrow });
+  ok('resolveHooksTarget: no-repo -> skip', result.skip === 'no-repo');
+}
+{
+  let calls = 0;
+  const runGit = (args) => {
+    calls++;
+    if (args[0] === 'rev-parse' && args[1] === '--git-dir') return '.git';
+    if (args[0] === 'rev-parse' && args[1] === '--git-path') return '.git/hooks';
+    if (args[0] === 'config') throw new Error('not set');
+    throw new Error('unexpected args: ' + args.join(' '));
+  };
+  const result = resolveHooksTarget({ repoDir: '/some/repo', runGit });
+  ok('resolveHooksTarget: hooksDir resolved against repoDir', result.hooksDir === path.resolve('/some/repo', '.git/hooks'));
+  ok('resolveHooksTarget: hooksPathSet false when core.hooksPath unset', result.hooksPathSet === false);
+  ok('resolveHooksTarget: runGit called', calls >= 2);
+}
+{
+  const runGit = (args) => {
+    if (args[0] === 'rev-parse' && args[1] === '--git-dir') return '.git';
+    if (args[0] === 'rev-parse' && args[1] === '--git-path') return '.git/hooks';
+    if (args[0] === 'config') return '.githooks';
+    throw new Error('unexpected args: ' + args.join(' '));
+  };
+  const result = resolveHooksTarget({ repoDir: '/some/repo', runGit });
+  ok('resolveHooksTarget: hooksPathSet true when core.hooksPath set', result.hooksPathSet === true);
+}
+
+console.log(`✓ commit-msg-sync (unit): ${passed} assertions passed`);
+
+// --- end-to-end: drive the script itself against real git repos -------------
+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 || {});
+}
+
+function runScript(args, opts) {
+  const out = execFileSync(process.execPath, [scriptPath].concat(args), Object.assign({ encoding: 'utf8' }, opts));
+  return out;
+}
+
+function assertSingleJsonLine(out, label) {
+  const lines = out.split('\n').filter((l) => l.length > 0);
+  ok(`${label}: stdout is exactly one line`, lines.length === 1);
+  let parsed;
+  assert.doesNotThrow(() => { parsed = JSON.parse(lines[0]); }, `${label}: stdout line is valid JSON`);
+  passed++;
+  ok(`${label}: JSON has exactly [status, hook, message] keys`,
+    Object.keys(parsed).sort().join(',') === 'hook,message,status');
+  return parsed;
+}
+
+// fresh repo: installed, then current on a second run
+{
+  const dir = mktmp();
+  execFileSync('git', ['init', '-q'], { cwd: dir, env: gitEnv() });
+  const out1 = runScript(['--repo', dir], { env: gitEnv() });
+  const parsed1 = assertSingleJsonLine(out1, 'e2e fresh repo (1st run)');
+  ok('e2e fresh repo: status installed', parsed1.status === 'installed');
+  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);
+
+  const out2 = runScript(['--repo', dir], { env: gitEnv() });
+  const parsed2 = assertSingleJsonLine(out2, 'e2e fresh repo (2nd run)');
+  ok('e2e fresh repo (2nd run): status current', parsed2.status === 'current');
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// seeded old hook -> upgraded
+{
+  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, oldHookText);
+  fs.chmodSync(hookPath, 0o755);
+  const out = runScript(['--repo', dir], { env: gitEnv() });
+  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);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// seeded foreign hook -> untouched
+{
+  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');
+  const foreign = '#!/bin/sh\necho "custom hook"\n';
+  fs.writeFileSync(hookPath, foreign);
+  fs.chmodSync(hookPath, 0o755);
+  const out = runScript(['--repo', dir], { env: gitEnv() });
+  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);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// core.hooksPath = .githooks, absent -> skipped, nothing created anywhere
+{
+  const dir = mktmp();
+  execFileSync('git', ['init', '-q'], { cwd: dir, env: gitEnv() });
+  execFileSync('git', ['config', 'core.hooksPath', '.githooks'], { cwd: dir, env: gitEnv() });
+  const out = runScript(['--repo', dir], { env: gitEnv() });
+  const parsed = assertSingleJsonLine(out, 'e2e core.hooksPath absent');
+  ok('e2e core.hooksPath absent: status skipped', parsed.status === 'skipped');
+  ok('e2e core.hooksPath absent: .githooks/commit-msg not created', !fs.existsSync(path.join(dir, '.githooks', 'commit-msg')));
+  ok('e2e core.hooksPath absent: .git/hooks/commit-msg not created', !fs.existsSync(path.join(dir, '.git', 'hooks', 'commit-msg')));
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// core.hooksPath = .githooks, old hook there -> upgraded there
+{
+  const dir = mktmp();
+  execFileSync('git', ['init', '-q'], { cwd: dir, env: gitEnv() });
+  execFileSync('git', ['config', 'core.hooksPath', '.githooks'], { cwd: dir, env: gitEnv() });
+  const githooksDir = path.join(dir, '.githooks');
+  fs.mkdirSync(githooksDir, { recursive: true });
+  const hookPath = path.join(githooksDir, 'commit-msg');
+  fs.writeFileSync(hookPath, oldHookText);
+  fs.chmodSync(hookPath, 0o755);
+  const out = runScript(['--repo', dir], { env: gitEnv() });
+  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);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// core.hooksPath = .githooks, foreign hook there -> untouched
+{
+  const dir = mktmp();
+  execFileSync('git', ['init', '-q'], { cwd: dir, env: gitEnv() });
+  execFileSync('git', ['config', 'core.hooksPath', '.githooks'], { cwd: dir, env: gitEnv() });
+  const githooksDir = path.join(dir, '.githooks');
+  fs.mkdirSync(githooksDir, { recursive: true });
+  const hookPath = path.join(githooksDir, 'commit-msg');
+  const foreign = '#!/bin/sh\necho "custom"\n';
+  fs.writeFileSync(hookPath, foreign);
+  fs.chmodSync(hookPath, 0o755);
+  const out = runScript(['--repo', dir], { env: gitEnv() });
+  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);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// linked worktree -> hook lands in the main repo's .git/hooks
+{
+  const dir = mktmp();
+  execFileSync('git', ['init', '-q'], { cwd: dir, env: gitEnv() });
+  execFileSync('git', ['-c', 'user.name=t', '-c', 'user.email=t@t',
+    'commit', '--allow-empty', '-m', 'chore: init', '--no-verify'], { cwd: dir, env: gitEnv() });
+  const worktreeDir = path.join(dir, '..', path.basename(dir) + '-wt');
+  execFileSync('git', ['worktree', 'add', worktreeDir, '-b', 'trailhead-wt'], { cwd: dir, env: gitEnv(), stdio: 'pipe' });
+  try {
+    const out = runScript(['--repo', worktreeDir], { env: gitEnv() });
+    const parsed = assertSingleJsonLine(out, 'e2e linked worktree');
+    ok('e2e linked worktree: status installed', parsed.status === 'installed');
+    const mainHookPath = path.join(dir, '.git', 'hooks', 'commit-msg');
+    ok('e2e linked worktree: hook lands in the main repo .git/hooks', fs.existsSync(mainHookPath));
+    ok('e2e linked worktree: reported hook path is the main repo one', parsed.hook === mainHookPath);
+  } finally {
+    try { execFileSync('git', ['worktree', 'remove', '--force', worktreeDir], { cwd: dir, env: gitEnv(), stdio: 'pipe' }); } catch { /* best effort cleanup */ }
+    fs.rmSync(worktreeDir, { recursive: true, force: true });
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// non-repo tmp dir -> skipped, exit 0
+{
+  const dir = mktmp();
+  const out = runScript(['--repo', dir], { env: gitEnv() });
+  const parsed = assertSingleJsonLine(out, 'e2e non-repo dir');
+  ok('e2e non-repo dir: status skipped', parsed.status === 'skipped');
+  ok('e2e non-repo dir: hook is null', parsed.hook === null);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// --bogus -> exit 2
+{
+  const dir = mktmp();
+  let exitCode = null;
+  try {
+    execFileSync(process.execPath, [scriptPath, '--bogus'], { cwd: dir, env: gitEnv(), stdio: 'pipe' });
+  } catch (e) {
+    exitCode = e.status;
+  }
+  ok('e2e --bogus: exits 2', exitCode === 2);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// --repo without a value -> exit 2
+{
+  const dir = mktmp();
+  let exitCode = null;
+  try {
+    execFileSync(process.execPath, [scriptPath, '--repo'], { cwd: dir, env: gitEnv(), stdio: 'pipe' });
+  } catch (e) {
+    exitCode = e.status;
+  }
+  ok('e2e --repo without value: exits 2', exitCode === 2);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+console.log(`✓ commit-msg-sync (e2e): ${passed} assertions passed`);

package/plugins/trailhead/hooks/lib/fixtures/commit-msg-a319156

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead commit-msg hook (git). Host-independent guardrail: installed into
+// .git/hooks/commit-msg at repo first-use so trailhead's commit discipline is
+// enforced on EVERY `git commit`, whatever agent host drives it (Codex has no
+// hook bus; this git hook is how the commit-guard survives there). Decision #16.
+//
+// Self-contained by design: detached from the trailhead install, it inlines the
+// same two rules as plugins/trailhead/hooks/lib/commit-message-check.js. That
+// lib's test drives this hook end-to-end so the two copies cannot drift.
+//
+// git passes the commit-message file path as argv[2]. On a violation: print the
+// reason to stderr and exit 1 (git aborts the commit). Otherwise exit 0.
+// Crash-safe: any unexpected error exits 0 (never wedge a commit).
+
+const fs = require('fs');
+
+const TYPES = 'feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert';
+const CONVENTIONAL = new RegExp(`^(${TYPES})(\\([^)]+\\))?!?:\\s.+`);
+const CO_AUTHORED = /co-authored-by\s*:/i;
+const SCISSORS = '# ------------------------ >8';
+
+function messageRegion(raw) {
+  const text = String(raw == null ? '' : raw);
+  const i = text.indexOf(SCISSORS);
+  return i === -1 ? text : text.slice(0, i);
+}
+function subjectOf(raw) {
+  for (const line of messageRegion(raw).split('\n')) {
+    if (line.trim() === '' || line.startsWith('#')) continue;
+    return line.trim();
+  }
+  return '';
+}
+
+try {
+  const file = process.argv[2];
+  const raw = file ? fs.readFileSync(file, 'utf8') : '';
+  const region = messageRegion(raw);
+
+  if (CO_AUTHORED.test(region)) {
+    process.stderr.write('trailhead: do not add a Co-Authored-By trailer to commits. Remove it and commit again.\n');
+    process.exit(1);
+  }
+  const subject = subjectOf(raw);
+  if (subject && !CONVENTIONAL.test(subject)) {
+    process.stderr.write(`trailhead: commit subject must be Conventional Commits: <type>(<scope>)?: <subject>. Valid types: ${TYPES.replace(/\|/g, ', ')}.\n`);
+    process.exit(1);
+  }
+  if (subject.length > 72) {
+    process.stderr.write('trailhead: commit subject must be 72 characters or less.\n');
+    process.exit(1);
+  }
+} catch {
+  process.exit(0); // never wedge a commit on an unexpected error
+}
+process.exit(0);

package/plugins/trailhead/hooks/trailhead-secret-read-guard.js

@@ -44,6 +44,11 @@
 // are shared with trailhead-search-guard.js via lib/shell-scan.js, so the two
 // guards can never drift into two divergent tokenizers again.
 //
+// #180 fix: `docker`/`podman` `--env-file .env` (or `--env-file=.env`) was a
+// false positive: the container RUNTIME reads that file, not the agent. Only
+// that flag's value is exempted, and only for docker/podman verbs; see
+// ENV_FILE_EXEMPT_VERBS below.
+//
 // Deliberately best-effort on the Bash leg, like the sibling guards: not a
 // full shell parser. It does not care about `cd` shape at all (that is
 // trailhead-search-guard.js's job) — it only asks "does any token here
@@ -94,6 +99,18 @@ function isSecretPathArg(t) {
 // every tool's flag surface, just the common file-value shapes.
 const VALUE_FLAGS = new Set(['-f', '--file']);
 
+// #180: `docker run --env-file .env img` / `docker compose --env-file
+// .env.prod up` / `podman run --env-file=.env img` are false positives. The
+// CONTAINER RUNTIME reads that file directly to populate the container's
+// environment; its contents never pass through the agent, so it is not a
+// secret READ by the agent (unlike a bare `cat .env`, which is). Scoped
+// narrowly: only the value of `--env-file` is exempt, and only for these
+// verbs; every other flag/positional in the same statement (image name,
+// `-v`, trailing `cat .env`, etc.) is still scanned exactly as before.
+const ENV_FILE_EXEMPT_VERBS = new Set(['docker', 'podman', 'docker-compose', 'podman-compose']);
+const ENV_FILE_EXEMPT_FLAGS = new Set(['--env-file']);
+const NO_EXEMPT_FLAGS = new Set();
+
 // The pattern-first search verbs (grep/rg/ag/sed/awk), shared with
 // trailhead-search-guard.js. Their first positional is a PATTERN, not a file
 // operand, so it must be skipped before scanning for a secret FILE argument
@@ -119,8 +136,11 @@ function stripTrailingPunct(t) {
 // Scan one already-tokenized statement's argument tokens (verb NOT stripped)
 // for a secret path used as a plain positional, an option value
 // (`--file=.env`, `-f .env`, glued `-f.env`), or a `<` (or glued `<file`)
-// redirect target. Returns the offending token or null.
-function scanTokensForSecretPath(tokens) {
+// redirect target. Returns the offending token or null. `exemptFlags` (#180)
+// names flags whose value must be skipped entirely rather than scanned, in
+// both the `--flag=value` and spaced `--flag value` forms.
+function scanTokensForSecretPath(tokens, exemptFlags) {
+  const exempt = exemptFlags || NO_EXEMPT_FLAGS;
   for (let i = 0; i < tokens.length; i++) {
     const t = stripTrailingPunct(tokens[i]);
     if (!t) continue;
@@ -143,10 +163,15 @@ function scanTokensForSecretPath(tokens) {
       // `--flag=value` form.
       const eq = t.indexOf('=');
       if (eq > 0) {
+        const flagName = t.slice(0, eq);
+        if (exempt.has(flagName)) continue; // #180: value never scanned
         const val = t.slice(eq + 1);
         if (isSecretPathArg(val)) return val;
         continue;
       }
+      // #180: exempt flag's separate-token value is skipped entirely, not
+      // scanned as a plain positional on the next loop iteration.
+      if (exempt.has(t)) { i++; continue; }
       // `-f value` / `--file value` (separate-token value).
       if (VALUE_FLAGS.has(t)) {
         const next = i + 1 < tokens.length ? stripTrailingPunct(tokens[i + 1]) : null;
@@ -214,7 +239,11 @@ function scanStatementForSecretPath(stmt) {
   if (SEARCH_VERBS.has(bin)) {
     return scanArgsSkippingPattern(tokens.slice(1), SEARCH_VERB_CONFIG[bin], isSecretPathArg);
   }
-  return scanTokensForSecretPath(tokens);
+  // #180: docker/podman (incl. `docker compose` as a subcommand, and the
+  // standalone docker-compose/podman-compose binaries) get --env-file's value
+  // exempted; every other verb keeps today's behaviour unchanged.
+  const exempt = ENV_FILE_EXEMPT_VERBS.has(bin) ? ENV_FILE_EXEMPT_FLAGS : NO_EXEMPT_FLAGS;
+  return scanTokensForSecretPath(tokens, exempt);
 }
 
 // Walk the command's top-level statements (quote-aware; `|`, `;`, `&&`,