@marcomigozzi/trailhead 0.13.0 → 0.15.0

package/plugins/trailhead/templates/trailhead-commit-msg

@@ -1,104 +1,40 @@
-#!/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 rules as plugins/trailhead/hooks/lib/commit-message-check.js. That
-// lib's test drives this hook end-to-end so the 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).
-//
-// Note: a merge/revert/fixup message already fails the conventional-subject
-// rule below, so it needs no special case; `git commit --amend` keeps whatever
-// trailer the original message carried; `git commit --no-verify` bypasses this
-// hook entirely, as before.
-
-const fs = require('fs');
-const path = require('path');
-
-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';
-const REFS_LINE = /^\s*refs\s*:(.*)$/i;
-
-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 '';
+#!/bin/sh
+# trailhead commit-msg hook (git). Thin sh wrapper around the CommonJS logic in
+# trailhead-commit-msg.cjs beside it (#257: an extensionless node script would
+# inherit the "type" of the user repo's package.json, so "type": "module" broke it).
+#
+# Never blocks a commit on a startup failure: node missing, the .cjs missing or
+# unreadable, or node crashing at load all exit 0, but print a one-line "inactive"
+# notice on stderr so the failure is not silent. Only the .cjs's dedicated
+# rule-violation code (3) becomes exit 1, which makes git abort the commit.
+
+# Avviso unico su stderr, stesso formato per tutti i casi.
+inactive() {
+  echo "trailhead: commit-msg hook inactive ($1); commit rules not enforced." >&2
 }
 
-// Mirrors parseSessionTicket() in commit-message-check.js: parses the first
-// line of a .trailhead/session-ticket marker (`#<n> <title>`).
-function parseSessionTicket(text) {
-  const raw = String(text == null ? '' : text).replace(/^/, '');
-  const firstLine = raw.split('\n')[0].replace(/\r$/, '');
-  const m = firstLine.match(/^#([1-9]\d*)(?:\s|$)/);
-  return m ? Number(m[1]) : null;
-}
-
-// Mirrors hasRefsFor() in commit-message-check.js.
-function hasRefsFor(message, n) {
-  const target = new RegExp('#' + n + '(?![\\w])');
-  for (const line of messageRegion(message).split('\n')) {
-    if (line.trim().startsWith('#')) continue;
-    const m = line.match(REFS_LINE);
-    if (m && target.test(m[1])) return true;
-  }
-  return false;
-}
-
-// Reads the session-ticket marker at the worktree top-level. git runs
-// commit-msg from the worktree top-level (linked worktrees included), so
-// process.cwd() is the right root here. Its own try/catch: a read error
-// (marker absent, unreadable, etc.) must never skip the other rules below,
-// it just leaves the Refs rule off.
-function readTicket() {
-  try {
-    const markerPath = path.join(process.cwd(), '.trailhead', 'session-ticket');
-    return parseSessionTicket(fs.readFileSync(markerPath, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-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);
-  }
-
-  const ticket = readTicket();
-  if (Number.isInteger(ticket) && ticket > 0 && !hasRefsFor(raw, ticket)) {
-    process.stderr.write(`trailhead: this commit is on ticket #${ticket} (per .trailhead/session-ticket) but has no "Refs: #${ticket}" trailer. Add "Refs: #${ticket}" as the last line of the message and commit again. If this commit is not part of ticket #${ticket}, remove the stale .trailhead/session-ticket marker first.\n`);
-    process.exit(1);
-  }
-} catch {
-  process.exit(0); // never wedge a commit on an unexpected error
-}
-process.exit(0);
+case $0 in
+  */*) dir=${0%/*} ;;
+  *) dir=. ;;
+esac
+cjs="$dir/trailhead-commit-msg.cjs"
+
+if [ ! -r "$cjs" ]; then
+  inactive "trailhead-commit-msg.cjs missing or unreadable"
+  exit 0
+fi
+if ! command -v node >/dev/null 2>&1; then
+  inactive "node not found on PATH"
+  exit 0
+fi
+
+node "$cjs" "$@"
+code=$?
+case $code in
+  0) exit 0 ;;
+  3) exit 1 ;;
+  *)
+    inactive "trailhead-commit-msg.cjs failed to run, exit $code"
+    exit 0
+    ;;
+esac

package/plugins/trailhead/templates/trailhead-commit-msg-sync.js

@@ -2,10 +2,13 @@
 'use strict';
 // trailhead commit-msg hook sync (self-contained, ships in templates/ so it
 // reaches every install channel: bin/trailhead.js copies templates/ wholesale
-// for Claude/npm and Codex alike). Installs the sibling template
-// trailhead-commit-msg into the repo's git hooks dir, upgrades it in place
-// when an OLDER trailhead hook is already there (recognised by its own
-// header line, never by trusting the filename), and never touches a foreign
+// for Claude/npm and Codex alike). Installs the sibling templates into the
+// repo's git hooks dir: trailhead-commit-msg (a small sh wrapper, installed as
+// commit-msg) and trailhead-commit-msg.cjs (the logic, installed beside it; a
+// .cjs is always CommonJS, so a "type": "module" repo cannot break it, #257).
+// Upgrades in place when an OLDER trailhead hook (the legacy single-file JS
+// one, or an outdated wrapper/.cjs) is already there, recognised by its own
+// header line, never by trusting the filename, and never touches a foreign
 // (non-trailhead) hook. #185.
 //
 // CLI: node trailhead-commit-msg-sync.js [--repo <dir>]  (default cwd)
@@ -21,13 +24,17 @@ const path = require('path');
 const crypto = require('crypto');
 const { execFileSync } = require('child_process');
 
-// La prima riga riconosciuta di ogni versione dell'hook trailhead: basta che
-// una delle prime 5 righe (trim) inizi con questa stringa.
-const TRAILHEAD_MARK = '// trailhead commit-msg hook (git).';
+// Nome del file di logica installato accanto al wrapper commit-msg.
+const CJS_NAME = 'trailhead-commit-msg.cjs';
+
+// La riga riconosciuta di ogni versione dell'hook trailhead: basta che una
+// delle prime 5 righe (trim) inizi con una di queste stringhe. La prima è
+// l'hook JS monofile legacy, la seconda il wrapper sh (layout #257).
+const TRAILHEAD_MARKS = ['// trailhead commit-msg hook (git).', '# trailhead commit-msg hook (git).'];
 
 function isTrailheadHook(text) {
   const lines = String(text == null ? '' : text).split('\n').slice(0, 5);
-  return lines.some((line) => line.trim().startsWith(TRAILHEAD_MARK));
+  return lines.some((line) => TRAILHEAD_MARKS.some((mark) => line.trim().startsWith(mark)));
 }
 
 // Uniforma i fine riga per il confronto di contenuto: CRLF -> LF, non tocca
@@ -65,10 +72,36 @@ function resolveHooksTarget({ repoDir, runGit = defaultRunGit }) {
   return { hooksDir, hooksPathSet };
 }
 
-// Applica la sincronizzazione vera e propria dentro hooksDir. fs è iniettato
-// per testabilità (default: il modulo fs reale).
-function syncCommitMsgHook({ hooksDir, templateText, hooksPathSet, fs: fsMod = fs }) {
+// Scrittura atomica: temp file unico nella stessa dir, poi rename sul
+// destinazione (mai un truncate in place).
+function writeAtomic(fsMod, hooksDir, finalPath, text) {
+  const tmpPath = path.join(hooksDir, `.commit-msg.trailhead-${process.pid}-${crypto.randomBytes(4).toString('hex')}`);
+  try {
+    fsMod.writeFileSync(tmpPath, text);
+    fsMod.chmodSync(tmpPath, 0o755);
+    fsMod.renameSync(tmpPath, finalPath);
+  } catch (err) {
+    try { fsMod.unlinkSync(tmpPath); } catch { /* best effort cleanup */ }
+    throw err;
+  }
+}
+
+// true se il file esiste, non è un symlink e ha esattamente il contenuto atteso.
+function matchesTemplate(fsMod, filePath, text) {
+  try {
+    if (fsMod.lstatSync(filePath).isSymbolicLink()) return false;
+    return normalize(fsMod.readFileSync(filePath, 'utf8')) === normalize(text);
+  } catch {
+    return false;
+  }
+}
+
+// Applica la sincronizzazione vera e propria dentro hooksDir. templateText è il
+// wrapper sh (installato come commit-msg), cjsText la logica (installata come
+// trailhead-commit-msg.cjs). fs è iniettato per testabilità.
+function syncCommitMsgHook({ hooksDir, templateText, cjsText, hooksPathSet, fs: fsMod = fs }) {
   const hookPath = path.join(hooksDir, 'commit-msg');
+  const cjsPath = path.join(hooksDir, CJS_NAME);
 
   if (!fsMod.existsSync(hookPath)) {
     if (hooksPathSet) {
@@ -79,8 +112,9 @@ function syncCommitMsgHook({ hooksDir, templateText, hooksPathSet, fs: fsMod = f
       };
     }
     fsMod.mkdirSync(hooksDir, { recursive: true });
-    fsMod.writeFileSync(hookPath, templateText);
-    fsMod.chmodSync(hookPath, 0o755);
+    // Prima la logica, poi il wrapper: mai un wrapper senza il suo script.
+    writeAtomic(fsMod, hooksDir, cjsPath, cjsText);
+    writeAtomic(fsMod, hooksDir, hookPath, templateText);
     return { status: 'installed', hook: hookPath, message: 'installed the trailhead commit-msg hook.' };
   }
 
@@ -94,22 +128,18 @@ function syncCommitMsgHook({ hooksDir, templateText, hooksPathSet, fs: fsMod = f
     return { status: 'foreign', hook: hookPath, message: 'a foreign commit-msg hook is present; left untouched.' };
   }
 
-  if (normalize(existingText) === normalize(templateText)) {
+  const wrapperCurrent = normalize(existingText) === normalize(templateText);
+  const cjsCurrent = matchesTemplate(fsMod, cjsPath, cjsText);
+
+  if (wrapperCurrent && cjsCurrent) {
     if ((stat.mode & 0o777) !== 0o755) fsMod.chmodSync(hookPath, 0o755);
     return { status: 'current', hook: hookPath, message: 'the trailhead commit-msg hook is already current.' };
   }
 
-  // Upgrade atomico: scrive su un temp file unico nella stessa dir, poi rename
-  // sopra l'hook esistente (mai un truncate in place).
-  const tmpPath = path.join(hooksDir, `.commit-msg.trailhead-${process.pid}-${crypto.randomBytes(4).toString('hex')}`);
-  try {
-    fsMod.writeFileSync(tmpPath, templateText);
-    fsMod.chmodSync(tmpPath, 0o755);
-    fsMod.renameSync(tmpPath, hookPath);
-  } catch (err) {
-    try { fsMod.unlinkSync(tmpPath); } catch { /* best effort cleanup */ }
-    throw err;
-  }
+  // Upgrade: logica per prima, wrapper per ultimo (mai un wrapper senza script).
+  if (!cjsCurrent) writeAtomic(fsMod, hooksDir, cjsPath, cjsText);
+  if (!wrapperCurrent) writeAtomic(fsMod, hooksDir, hookPath, templateText);
+  else if ((stat.mode & 0o777) !== 0o755) fsMod.chmodSync(hookPath, 0o755);
   return { status: 'upgraded', hook: hookPath, message: 'upgraded the trailhead commit-msg hook to the current template.' };
 }
 
@@ -153,7 +183,8 @@ function main(argv, { cwd, stdout } = {}) {
     hooksDirForError = target.hooksDir;
     const templatePath = path.join(__dirname, 'trailhead-commit-msg');
     const templateText = fs.readFileSync(templatePath, 'utf8');
-    const result = syncCommitMsgHook({ hooksDir: target.hooksDir, templateText, hooksPathSet: target.hooksPathSet, fs });
+    const cjsText = fs.readFileSync(path.join(__dirname, CJS_NAME), 'utf8');
+    const result = syncCommitMsgHook({ hooksDir: target.hooksDir, templateText, cjsText, hooksPathSet: target.hooksPathSet, fs });
     writeResult(out, result);
     return 0;
   } catch (err) {
@@ -163,7 +194,7 @@ function main(argv, { cwd, stdout } = {}) {
   }
 }
 
-module.exports = { resolveHooksTarget, isTrailheadHook, normalize, syncCommitMsgHook, parseArgs, main };
+module.exports = { CJS_NAME, resolveHooksTarget, isTrailheadHook, normalize, syncCommitMsgHook, parseArgs, main };
 
 if (require.main === module) {
   const code = main(process.argv.slice(2), { cwd: process.cwd(), stdout: process.stdout });

package/plugins/trailhead/templates/trailhead-commit-msg.cjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead commit-msg hook logic (git, CommonJS). Host-independent guardrail:
+// installed beside the sh wrapper .git/hooks/commit-msg (which calls it) 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.
+//
+// The .cjs extension is deliberate (#257): Node takes the module format of an
+// extensionless file from the nearest package.json "type", and under .git/hooks/
+// that is the user repo's, so a "type": "module" repo would load this as ESM and
+// fail on require(). A .cjs file is always CommonJS.
+//
+// Self-contained by design: detached from the trailhead install, it inlines the
+// same rules as plugins/trailhead/hooks/lib/commit-message-check.js. That
+// lib's test drives this hook end-to-end so the copies cannot drift.
+//
+// git passes the commit-message file path as argv[2] (the wrapper forwards it).
+// On a violation: print the reason to stderr and exit VIOLATION (3); the wrapper
+// maps exactly that code to exit 1 (git aborts the commit); any code other than
+// 0 or 3 (a crash at load) is reported as the one-line "inactive" notice on
+// stderr and exits 0. Otherwise exit 0. Crash-safe: any unexpected error exits
+// 0 (never wedge a commit).
+//
+// Note: a merge/revert/fixup message already fails the conventional-subject
+// rule below, so it needs no special case; `git commit --amend` keeps whatever
+// trailer the original message carried; `git commit --no-verify` bypasses this
+// hook entirely, as before.
+
+const fs = require('fs');
+const path = require('path');
+
+const VIOLATION = 3; // codice dedicato, mappato a 1 dal wrapper sh
+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';
+const REFS_LINE = /^\s*refs\s*:(.*)$/i;
+
+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 '';
+}
+
+// Mirrors parseSessionTicket() in commit-message-check.js: parses the first
+// line of a .trailhead/session-ticket marker (`#<n> <title>`).
+function parseSessionTicket(text) {
+  const raw = String(text == null ? '' : text).replace(/^/, '');
+  const firstLine = raw.split('\n')[0].replace(/\r$/, '');
+  const m = firstLine.match(/^#([1-9]\d*)(?:\s|$)/);
+  return m ? Number(m[1]) : null;
+}
+
+// Mirrors hasRefsFor() in commit-message-check.js.
+function hasRefsFor(message, n) {
+  const target = new RegExp('#' + n + '(?![\\w])');
+  for (const line of messageRegion(message).split('\n')) {
+    if (line.trim().startsWith('#')) continue;
+    const m = line.match(REFS_LINE);
+    if (m && target.test(m[1])) return true;
+  }
+  return false;
+}
+
+// Reads the session-ticket marker at the worktree top-level. git runs
+// commit-msg from the worktree top-level (linked worktrees included), so
+// process.cwd() is the right root here. Its own try/catch: a read error
+// (marker absent, unreadable, etc.) must never skip the other rules below,
+// it just leaves the Refs rule off.
+function readTicket() {
+  try {
+    const markerPath = path.join(process.cwd(), '.trailhead', 'session-ticket');
+    return parseSessionTicket(fs.readFileSync(markerPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+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(VIOLATION);
+  }
+  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(VIOLATION);
+  }
+  if (subject.length > 72) {
+    process.stderr.write('trailhead: commit subject must be 72 characters or less.\n');
+    process.exit(VIOLATION);
+  }
+
+  const ticket = readTicket();
+  if (Number.isInteger(ticket) && ticket > 0 && !hasRefsFor(raw, ticket)) {
+    process.stderr.write(`trailhead: this commit is on ticket #${ticket} (per .trailhead/session-ticket) but has no "Refs: #${ticket}" trailer. Add "Refs: #${ticket}" as the last line of the message and commit again. If this commit is not part of ticket #${ticket}, remove the stale .trailhead/session-ticket marker first.\n`);
+    process.exit(VIOLATION);
+  }
+} catch {
+  process.exit(0); // never wedge a commit on an unexpected error
+}
+process.exit(0);