@marcomigozzi/trailhead 0.9.0 → 0.11.0

package/bin/lib/install-verify.js

@@ -0,0 +1,257 @@
+'use strict';
+// install-verify.js: post-install filesystem verification for both hosts.
+//
+// installClaude/installCodex place files and register hooks, but never
+// checked any of it landed. This module adds that check: given a spec
+// describing what an install is supposed to look like, it walks the
+// filesystem (and the host's hook registry file) and reports what's missing
+// or merely unverifiable (a registered hook target whose path depends on an
+// env var this process doesn't have set).
+//
+// Reads the filesystem only, never writes, and never throws: a stat/parse
+// error just counts as "missing" or an empty registry. It never reads
+// process.env or os.homedir() itself; the caller always passes both in
+// (spec.env, spec.home), so the tests stay hermetic.
+
+const fs = require('fs');
+const path = require('path');
+const { codexLayout } = require('./codex-projection.js');
+
+// --- fs probes, never throw --------------------------------------------------
+function isDir(p) {
+  try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+function isFile(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+
+// --- sharedCoreFiles ----------------------------------------------------------
+// The shared-core file list, single-sourced from _shared/load-first.md's own
+// numbered "Load first, in order" list: load-first.md itself, plus every
+// `../_shared/<name>.md` named on a numbered-list line, de-duplicated, in
+// order. Empty/unreadable text still yields ['load-first.md'].
+function sharedCoreFiles(loadFirstText) {
+  const names = ['load-first.md'];
+  const re = /^\d+\.\s+`\.\.\/_shared\/([\w.-]+\.md)`/gm;
+  let m;
+  while ((m = re.exec(loadFirstText || '')) !== null) {
+    if (!names.includes(m[1])) names.push(m[1]);
+  }
+  return names;
+}
+
+// --- hookScriptTokens ---------------------------------------------------------
+// Split a shell-like command into tokens (quotes stripped), then return every
+// token whose basename matches trailhead-<name>.js. A1: a quoted token that
+// itself contains whitespace (e.g. bash -c's payload) is re-tokenized
+// recursively, so an inner script path nested inside `bash -c '...'` is still
+// found as its own token.
+function tokenize(command) {
+  const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+  const tokens = [];
+  let m;
+  while ((m = re.exec(command)) !== null) {
+    tokens.push(m[1] !== undefined ? m[1] : (m[2] !== undefined ? m[2] : m[3]));
+  }
+  return tokens;
+}
+
+function hookScriptTokens(command) {
+  const found = [];
+  const visit = (cmd) => {
+    for (const token of tokenize(cmd)) {
+      if (/\s/.test(token)) {
+        visit(token);
+      } else if (/^trailhead-[\w-]+\.js$/.test(path.basename(token))) {
+        found.push(token);
+      }
+    }
+  };
+  visit(command || '');
+  return found;
+}
+
+// --- expandTarget --------------------------------------------------------------
+// Expand a `~`/`~/...` prefix (to `home`) and any `$VAR`/`${VAR}` references
+// (from `env`). The first undefined variable short-circuits to
+// { unresolved: varName }; an empty-string value counts as defined and is
+// substituted as-is. `~user/...` is intentionally NOT expanded (it stays
+// relative and later fails as a relative target).
+function expandTarget(token, { env, home }) {
+  let result = token;
+  if (result === '~' || result.startsWith('~/')) {
+    result = path.join(home, result.slice(1));
+  }
+  const re = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
+  let out = '';
+  let lastIndex = 0;
+  let match;
+  while ((match = re.exec(result)) !== null) {
+    const name = match[1] || match[2];
+    const val = env[name];
+    if (val === undefined) return { unresolved: name };
+    out += result.slice(lastIndex, match.index) + val;
+    lastIndex = match.index + match[0].length;
+  }
+  out += result.slice(lastIndex);
+  return { path: out };
+}
+
+// --- verifyInstall: individual checks -----------------------------------------
+function checkSkills(spec, missing) {
+  for (const name of spec.skillDirs) {
+    if (name === '_shared') continue;
+    const skillMd = path.join(spec.skillsRoot, name, 'SKILL.md');
+    if (!isDir(path.join(spec.skillsRoot, name)) || !isFile(skillMd)) {
+      missing.push(`skill ${name}/SKILL.md`);
+    }
+  }
+}
+
+function checkSharedCore(spec, missing) {
+  const sharedDir = path.join(spec.skillsRoot, '_shared');
+  for (const f of spec.sharedFiles) {
+    if (!isDir(sharedDir) || !isFile(path.join(sharedDir, f))) missing.push(`shared core _shared/${f}`);
+  }
+}
+
+function checkHookScripts(spec, missing) {
+  for (const f of spec.hookFiles) {
+    if (!isFile(path.join(spec.hooksDir, f))) missing.push(`hook script ${f}`);
+  }
+  for (const f of spec.hookLibFiles) {
+    if (!isFile(path.join(spec.hooksDir, 'lib', f))) missing.push(`hook lib lib/${f}`);
+  }
+}
+
+function readRegistry(registryFile) {
+  try { return JSON.parse(fs.readFileSync(registryFile, 'utf8')); } catch { return {}; }
+}
+
+// Registered hook targets + expected registration. Walks hooks.<event>[].hooks[]
+// .command in the registry file, expands each trailhead-* token, and sorts it
+// into `missing` (relative or non-existent) or `unverified` (undefined var).
+// Then, per A2, an expected hookFiles entry counts as registered when some
+// token expands to exactly hooksDir/<f>, OR an unresolved token's basename is
+// <f> (stays warning-only, never also missing).
+function checkRegisteredTargets(spec, missing, unverified) {
+  const registry = readRegistry(spec.registryFile);
+  const registryName = path.basename(spec.registryFile);
+  const events = (registry && typeof registry.hooks === 'object' && registry.hooks) ? registry.hooks : {};
+  const registeredExact = new Set();
+  const registeredViaUnresolved = new Set();
+
+  for (const [event, groups] of Object.entries(events)) {
+    for (const group of Array.isArray(groups) ? groups : []) {
+      for (const hook of Array.isArray(group.hooks) ? group.hooks : []) {
+        const command = typeof hook.command === 'string' ? hook.command : '';
+        for (const token of hookScriptTokens(command)) {
+          const expanded = expandTarget(token, { env: spec.env, home: spec.home });
+          if (expanded.unresolved) {
+            unverified.push(`${token} (${event}, ${registryName}: $${expanded.unresolved} undefined)`);
+            registeredViaUnresolved.add(path.basename(token));
+            continue;
+          }
+          if (!path.isAbsolute(expanded.path)) {
+            missing.push(`registered hook target ${token} is relative (${event}, ${registryName})`);
+            continue;
+          }
+          if (!isFile(expanded.path)) {
+            missing.push(`registered hook target ${expanded.path} (${event}, ${registryName})`);
+            continue;
+          }
+          for (const f of spec.hookFiles) {
+            if (expanded.path === path.join(spec.hooksDir, f)) registeredExact.add(f);
+          }
+        }
+      }
+    }
+  }
+
+  for (const f of spec.hookFiles) {
+    if (!registeredExact.has(f) && !registeredViaUnresolved.has(f)) {
+      missing.push(`hook registration ${f} (${registryName})`);
+    }
+  }
+}
+
+function checkAgents(spec, missing) {
+  let files = [];
+  if (isDir(spec.agentsDir)) {
+    try { files = fs.readdirSync(spec.agentsDir); } catch { files = []; }
+  }
+  const hasMatch = files.some((f) => spec.agentPattern.test(f) && isFile(path.join(spec.agentsDir, f)));
+  if (!hasMatch) missing.push(`agents: no trailhead-* agents in ${spec.agentsDir}`);
+}
+
+// --- verifyInstall --------------------------------------------------------------
+// spec = { skillsRoot, skillDirs, sharedFiles, hooksDir, hookFiles,
+//          hookLibFiles, registryFile, agentsDir, agentPattern, env, home }
+function verifyInstall(spec) {
+  const missing = [];
+  const unverified = [];
+  checkSkills(spec, missing);
+  checkSharedCore(spec, missing);
+  checkHookScripts(spec, missing);
+  checkRegisteredTargets(spec, missing, unverified);
+  checkAgents(spec, missing);
+  return { missing, unverified };
+}
+
+// --- spec builders ---------------------------------------------------------
+function claudeVerifySpec(configDir, { skillDirs, sharedFiles, hookFiles, hookLibFiles, env, home }) {
+  return {
+    skillsRoot: path.join(configDir, 'skills'),
+    skillDirs,
+    sharedFiles,
+    hooksDir: path.join(configDir, 'hooks'),
+    hookFiles,
+    hookLibFiles,
+    registryFile: path.join(configDir, 'settings.json'),
+    agentsDir: path.join(configDir, 'agents'),
+    agentPattern: /^trailhead-.*\.md$/,
+    env,
+    home,
+  };
+}
+
+function codexVerifySpec(configDir, { skillDirs, sharedFiles, hookFiles, hookLibFiles, env, home }) {
+  const L = codexLayout(configDir);
+  return {
+    skillsRoot: L.skillsRoot,
+    skillDirs,
+    sharedFiles,
+    hooksDir: L.hooksScriptsDir,
+    hookFiles,
+    hookLibFiles,
+    registryFile: L.hooksJson,
+    agentsDir: L.codexAgentsDir,
+    agentPattern: /^trailhead-.*\.toml$/,
+    env,
+    home,
+  };
+}
+
+// --- formatters --------------------------------------------------------------
+function formatVerifyFailure(hostLabel, configDir, { missing, unverified }) {
+  const lines = [`✗ trailhead install incomplete for ${hostLabel} → ${configDir}`];
+  for (const m of missing) lines.push(`  missing: ${m}`);
+  for (const u of unverified) lines.push(`  unverified: ${u}`);
+  lines.push('Re-run the installer to restore a missing file. For a stale or relative hook target, remove that entry from the registry file named above (or run --uninstall), then reinstall.');
+  return lines.join('\n');
+}
+
+function formatVerifyWarnings(unverified) {
+  return unverified.map((u) => `  ⚠ unverified hook target ${u}`);
+}
+
+module.exports = {
+  sharedCoreFiles,
+  hookScriptTokens,
+  expandTarget,
+  verifyInstall,
+  claudeVerifySpec,
+  codexVerifySpec,
+  formatVerifyFailure,
+  formatVerifyWarnings,
+};

package/bin/lib/install-verify.test.js

@@ -0,0 +1,379 @@
+#!/usr/bin/env node
+// Tests for install-verify.js. Run: node install-verify.test.js
+// No framework: plain asserts, mirrors the style of codex-projection.test.js.
+// Fixtures live under os.tmpdir(); every spec passes an explicit env/home,
+// never the real process.env/os.homedir(), so the tests stay hermetic.
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const {
+  sharedCoreFiles,
+  hookScriptTokens,
+  expandTarget,
+  verifyInstall,
+  claudeVerifySpec,
+  codexVerifySpec,
+  formatVerifyFailure,
+  formatVerifyWarnings,
+} = require('./install-verify.js');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const tmpDirs = [];
+function mktmp() {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'th-iv-'));
+  tmpDirs.push(d);
+  return d;
+}
+function write(p, content = '') {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, content);
+}
+
+// --- sharedCoreFiles -----------------------------------------------------------
+const loadFirstPath = path.join(__dirname, '../../plugins/trailhead/skills/_shared/load-first.md');
+const loadFirstSrc = fs.readFileSync(loadFirstPath, 'utf8');
+ok('sharedCoreFiles on the real load-first.md returns the 7 core names',
+  JSON.stringify(sharedCoreFiles(loadFirstSrc)) === JSON.stringify([
+    'load-first.md', 'principles.md', 'ticket-language.md', 'substrate.md',
+    'session-handoff.md', 'configuration.md', 'techniques.md',
+  ]));
+ok("sharedCoreFiles('') returns just load-first.md", JSON.stringify(sharedCoreFiles('')) === JSON.stringify(['load-first.md']));
+ok('sharedCoreFiles de-duplicates repeated entries', JSON.stringify(sharedCoreFiles(
+  '1. `../_shared/a.md`: x\n2. `../_shared/a.md`: x again\n3. `../_shared/b.md`: y\n'
+)) === JSON.stringify(['load-first.md', 'a.md', 'b.md']));
+
+// --- hookScriptTokens ----------------------------------------------------------
+ok('hookScriptTokens: node "<p>"', JSON.stringify(hookScriptTokens('node "/x/trailhead-a.js"')) === JSON.stringify(['/x/trailhead-a.js']));
+ok('hookScriptTokens: node <p>', JSON.stringify(hookScriptTokens('node /x/trailhead-a.js')) === JSON.stringify(['/x/trailhead-a.js']));
+ok('hookScriptTokens: node <p> --flag', JSON.stringify(hookScriptTokens('node /x/trailhead-a.js --flag')) === JSON.stringify(['/x/trailhead-a.js']));
+ok("hookScriptTokens: bash -c 'node <p>'", JSON.stringify(hookScriptTokens("bash -c 'node /x/trailhead-a.js'")) === JSON.stringify(['/x/trailhead-a.js']));
+ok("hookScriptTokens: /usr/bin/env node '<p>'", JSON.stringify(hookScriptTokens("/usr/bin/env node '/x/trailhead-a.js'")) === JSON.stringify(['/x/trailhead-a.js']));
+ok('hookScriptTokens: no trailhead script gives []', JSON.stringify(hookScriptTokens('node /x/other.js')) === JSON.stringify([]));
+ok('hookScriptTokens: trailhead-x.json does not match', JSON.stringify(hookScriptTokens('node /x/trailhead-x.json')) === JSON.stringify([]));
+ok('hookScriptTokens: my-trailhead-x.js does not match', JSON.stringify(hookScriptTokens('node /x/my-trailhead-x.js')) === JSON.stringify([]));
+
+// --- expandTarget ----------------------------------------------------------------
+const H = '/home/fixture-user';
+ok('expandTarget ~/a becomes home', expandTarget('~/a', { env: {}, home: H }).path === path.join(H, 'a'));
+ok('expandTarget ~ alone becomes home', expandTarget('~', { env: {}, home: H }).path === H);
+ok('expandTarget $A/x expands with A defined', expandTarget('$A/x', { env: { A: '/v' }, home: H }).path === '/v/x');
+ok('expandTarget ${A}/x expands with A defined', expandTarget('${A}/x', { env: { A: '/v' }, home: H }).path === '/v/x');
+ok('expandTarget undefined ${CLAUDE_PLUGIN_ROOT} is unresolved',
+  expandTarget('${CLAUDE_PLUGIN_ROOT}/x', { env: {}, home: H }).unresolved === 'CLAUDE_PLUGIN_ROOT');
+ok('expandTarget substitutes an empty-string variable', expandTarget('$A/x', { env: { A: '' }, home: H }).path === '/x');
+
+// --- verifyInstall: clean fixtures ----------------------------------------------
+function buildClaudeFixture() {
+  const configDir = mktmp();
+  const skillDirs = ['trailhead', '_shared', 'trailhead-work'];
+  const sharedFiles = ['load-first.md', 'substrate.md'];
+  const hookFiles = ['trailhead-commit-guard.js', 'trailhead-body-guard.js'];
+  const hookLibFiles = ['commit-message-check.js'];
+  write(path.join(configDir, 'skills', 'trailhead', 'SKILL.md'), 'x');
+  write(path.join(configDir, 'skills', 'trailhead-work', 'SKILL.md'), 'x');
+  write(path.join(configDir, 'skills', '_shared', 'load-first.md'), 'x');
+  write(path.join(configDir, 'skills', '_shared', 'substrate.md'), 'x');
+  write(path.join(configDir, 'hooks', 'trailhead-commit-guard.js'), 'x');
+  write(path.join(configDir, 'hooks', 'trailhead-body-guard.js'), 'x');
+  write(path.join(configDir, 'hooks', 'lib', 'commit-message-check.js'), 'x');
+  write(path.join(configDir, 'agents', 'trailhead-execute.md'), 'x');
+  const settings = {
+    hooks: {
+      PreToolUse: [{ matcher: 'Bash', hooks: [
+        { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-commit-guard.js')}"` },
+        { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-body-guard.js')}"` },
+      ] }],
+    },
+  };
+  write(path.join(configDir, 'settings.json'), JSON.stringify(settings, null, 2));
+  const spec = claudeVerifySpec(configDir, { skillDirs, sharedFiles, hookFiles, hookLibFiles, env: {}, home: H });
+  return { configDir, spec, skillDirs, sharedFiles, hookFiles, hookLibFiles };
+}
+
+function buildCodexFixture() {
+  const configDir = mktmp();
+  const skillDirs = ['trailhead', '_shared', 'trailhead-work'];
+  const sharedFiles = ['load-first.md', 'substrate.md'];
+  const hookFiles = ['trailhead-commit-guard.js', 'trailhead-body-guard.js'];
+  const hookLibFiles = ['commit-message-check.js'];
+  const hooksScriptsDir = path.join(configDir, 'skills', 'trailhead', 'hooks');
+  write(path.join(configDir, 'skills', 'trailhead', 'SKILL.md'), 'x');
+  write(path.join(configDir, 'skills', 'trailhead-work', 'SKILL.md'), 'x');
+  write(path.join(configDir, 'skills', '_shared', 'load-first.md'), 'x');
+  write(path.join(configDir, 'skills', '_shared', 'substrate.md'), 'x');
+  write(path.join(hooksScriptsDir, 'trailhead-commit-guard.js'), 'x');
+  write(path.join(hooksScriptsDir, 'trailhead-body-guard.js'), 'x');
+  write(path.join(hooksScriptsDir, 'lib', 'commit-message-check.js'), 'x');
+  write(path.join(configDir, 'agents', 'trailhead-execute.toml'), 'x');
+  const hooksJson = {
+    hooks: {
+      PreToolUse: [{ matcher: 'Bash', hooks: [
+        { type: 'command', command: `node "${path.join(hooksScriptsDir, 'trailhead-commit-guard.js')}"` },
+        { type: 'command', command: `node "${path.join(hooksScriptsDir, 'trailhead-body-guard.js')}"` },
+      ] }],
+    },
+  };
+  write(path.join(configDir, 'hooks.json'), JSON.stringify(hooksJson, null, 2));
+  const spec = codexVerifySpec(configDir, { skillDirs, sharedFiles, hookFiles, hookLibFiles, env: {}, home: H });
+  return { configDir, spec, skillDirs, sharedFiles, hookFiles, hookLibFiles, hooksScriptsDir };
+}
+
+{
+  const { spec } = buildClaudeFixture();
+  const r = verifyInstall(spec);
+  ok('verifyInstall claude clean fixture: no missing/unverified', r.missing.length === 0 && r.unverified.length === 0);
+}
+{
+  const { spec } = buildCodexFixture();
+  const r = verifyInstall(spec);
+  ok('verifyInstall codex clean fixture: no missing/unverified', r.missing.length === 0 && r.unverified.length === 0);
+}
+// The Codex spec never flags search-guard (it is never in hookFiles for Codex).
+{
+  const { spec } = buildCodexFixture();
+  const r = verifyInstall(spec);
+  ok('verifyInstall codex spec never names search-guard',
+    !r.missing.some((m) => m.includes('search-guard')) && !r.unverified.some((u) => u.includes('search-guard')));
+}
+
+// --- verifyInstall: one named `missing` entry each ------------------------------
+{
+  const { configDir, spec } = buildClaudeFixture();
+  fs.rmSync(path.join(configDir, 'hooks', 'trailhead-body-guard.js'));
+  const r = verifyInstall(spec);
+  ok('missing: a missing hook file', r.missing.includes('hook script trailhead-body-guard.js'));
+}
+{
+  const { configDir, spec } = buildClaudeFixture();
+  fs.rmSync(path.join(configDir, 'hooks', 'trailhead-body-guard.js'));
+  fs.mkdirSync(path.join(configDir, 'hooks', 'trailhead-body-guard.js'), { recursive: true });
+  const r = verifyInstall(spec);
+  ok('missing: a hook path that is a directory', r.missing.includes('hook script trailhead-body-guard.js'));
+}
+{
+  const { configDir, spec } = buildClaudeFixture();
+  fs.rmSync(path.join(configDir, 'hooks', 'lib', 'commit-message-check.js'));
+  const r = verifyInstall(spec);
+  ok('missing: a missing lib file', r.missing.includes('hook lib lib/commit-message-check.js'));
+}
+{
+  const { configDir, spec } = buildClaudeFixture();
+  write(path.join(configDir, 'settings.json'), JSON.stringify({
+    hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [
+      { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-commit-guard.js')}"` },
+    ] }] },
+  }));
+  const r = verifyInstall(spec);
+  ok('missing: an unregistered hook', r.missing.includes('hook registration trailhead-body-guard.js (settings.json)'));
+}
+{
+  const { configDir, spec } = buildClaudeFixture();
+  write(path.join(configDir, 'settings.json'), JSON.stringify({
+    hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [
+      { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-commit-guard.js')}"` },
+      { type: 'command', command: 'node "/other/dir/trailhead-body-guard.js"' },
+    ] }] },
+  }));
+  const r = verifyInstall(spec);
+  ok('missing: a lookalike registration at /other/dir/trailhead-commit-guard.js is still unregistered',
+    r.missing.includes('hook registration trailhead-body-guard.js (settings.json)') &&
+    r.missing.includes('registered hook target /other/dir/trailhead-body-guard.js (PreToolUse, settings.json)'));
+}
+{
+  const { configDir, spec } = buildClaudeFixture();
+  fs.rmSync(path.join(configDir, 'agents', 'trailhead-execute.md'));
+  write(path.join(configDir, 'agents', 'my-custom-agent.md'), 'x');
+  const r = verifyInstall(spec);
+  ok('missing: zero agents, with a non-trailhead agent present', r.missing.some((m) => m.startsWith('agents: no trailhead-* agents')));
+}
+{
+  const { configDir, spec } = buildClaudeFixture();
+  fs.rmSync(path.join(configDir, 'skills', 'trailhead-work', 'SKILL.md'));
+  const r = verifyInstall(spec);
+  ok('missing: a cluster with no SKILL.md', r.missing.includes('skill trailhead-work/SKILL.md'));
+}
+{
+  const { configDir, spec } = buildClaudeFixture();
+  fs.rmSync(path.join(configDir, 'skills', '_shared'), { recursive: true, force: true });
+  const r = verifyInstall(spec);
+  ok('missing: _shared missing', r.missing.includes('shared core _shared/load-first.md') && r.missing.includes('shared core _shared/substrate.md'));
+}
+{
+  const { configDir, spec } = buildClaudeFixture();
+  fs.rmSync(path.join(configDir, 'skills', '_shared', 'substrate.md'));
+  const r = verifyInstall(spec);
+  ok('missing: _shared present without substrate.md', r.missing.includes('shared core _shared/substrate.md') && !r.missing.includes('shared core _shared/load-first.md'));
+}
+{
+  const { configDir, spec } = buildClaudeFixture();
+  const dangling = path.join(configDir, 'hooks', 'trailhead-body-guard.js');
+  fs.rmSync(dangling);
+  fs.symlinkSync(path.join(configDir, 'nonexistent-target.js'), dangling);
+  const r = verifyInstall(spec);
+  ok('missing: a dangling symlink', r.missing.includes('hook script trailhead-body-guard.js'));
+}
+{
+  const { configDir, spec } = buildClaudeFixture();
+  write(path.join(configDir, 'settings.json'), JSON.stringify({
+    hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [
+      { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-commit-guard.js')}"` },
+      { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-body-guard.js')}"` },
+      { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-old-guard.js')}"` },
+    ] }] },
+  }));
+  const r = verifyInstall(spec);
+  ok('missing: a stale trailhead-old-guard.js registration',
+    r.missing.includes(`registered hook target ${path.join(configDir, 'hooks', 'trailhead-old-guard.js')} (PreToolUse, settings.json)`));
+}
+{
+  const { configDir, spec } = buildClaudeFixture();
+  write(path.join(configDir, 'settings.json'), JSON.stringify({
+    hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [
+      { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-commit-guard.js')}"` },
+      { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-body-guard.js')}"` },
+      { type: 'command', command: 'node hooks/trailhead-x-guard.js' },
+    ] }] },
+  }));
+  const r = verifyInstall(spec);
+  ok('missing: a relative target', r.missing.includes('registered hook target hooks/trailhead-x-guard.js is relative (PreToolUse, settings.json)'));
+}
+{
+  const { configDir, spec } = buildClaudeFixture();
+  write(path.join(configDir, 'settings.json'), JSON.stringify({
+    hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [
+      { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-commit-guard.js')}"` },
+      { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-body-guard.js')}"` },
+      { type: 'command', command: 'node "~/gone/trailhead-x-guard.js"' },
+    ] }] },
+  }));
+  const r = verifyInstall(spec);
+  ok('missing: a ~/gone/trailhead-x-guard.js target (expands under the fixture home, not found)',
+    r.missing.includes(`registered hook target ${path.join(H, 'gone', 'trailhead-x-guard.js')} (PreToolUse, settings.json)`));
+}
+{
+  const { configDir, spec } = buildClaudeFixture();
+  spec.env = { A: configDir };
+  write(path.join(configDir, 'settings.json'), JSON.stringify({
+    hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [
+      { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-commit-guard.js')}"` },
+      { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-body-guard.js')}"` },
+      { type: 'command', command: 'node "$A/trailhead-x-guard.js"' },
+    ] }] },
+  }));
+  const r = verifyInstall(spec);
+  ok('missing: a $A/trailhead-x-guard.js target with A defined but the file absent',
+    r.missing.includes(`registered hook target ${path.join(configDir, 'trailhead-x-guard.js')} (PreToolUse, settings.json)`));
+}
+{
+  const { configDir, spec } = buildClaudeFixture();
+  write(path.join(configDir, 'settings.json'), JSON.stringify({
+    hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [
+      { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-commit-guard.js')}"` },
+      { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-body-guard.js')}"` },
+      { type: 'command', command: `bash -c 'node "${path.join(configDir, 'hooks', 'trailhead-gone.js')}"'` },
+    ] }] },
+  }));
+  const r = verifyInstall(spec);
+  ok("missing: a script inside bash -c '...' whose file is gone",
+    r.missing.includes(`registered hook target ${path.join(configDir, 'hooks', 'trailhead-gone.js')} (PreToolUse, settings.json)`));
+}
+
+// --- verifyInstall: resolution cases ---------------------------------------------
+{
+  const { configDir, spec } = buildClaudeFixture();
+  spec.env = {};
+  write(path.join(configDir, 'settings.json'), JSON.stringify({
+    hooks: { SessionStart: [{ matcher: '', hooks: [
+      { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-commit-guard.js')}"` },
+      { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-body-guard.js')}"` },
+      { type: 'command', command: 'node "${CLAUDE_PLUGIN_ROOT}/hooks/trailhead-x.js"' },
+    ] }] },
+  }));
+  const r = verifyInstall(spec);
+  ok('resolution: undefined ${CLAUDE_PLUGIN_ROOT} gives missing: [] plus one unverified entry naming the variable',
+    r.missing.length === 0 && r.unverified.some((u) => u.includes('CLAUDE_PLUGIN_ROOT undefined')));
+}
+{
+  // ~/... and $A/... pointing at EXISTING fixture files both pass.
+  const { configDir, spec } = buildClaudeFixture();
+  const homeDir = mktmp();
+  spec.home = homeDir;
+  spec.env = { A: configDir };
+  write(path.join(homeDir, 'sub', 'trailhead-tilde.js'), 'x');
+  write(path.join(configDir, 'trailhead-dollar.js'), 'x');
+  write(path.join(configDir, 'settings.json'), JSON.stringify({
+    hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [
+      { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-commit-guard.js')}"` },
+      { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-body-guard.js')}"` },
+      { type: 'command', command: 'node "~/sub/trailhead-tilde.js"' },
+      { type: 'command', command: 'node "$A/trailhead-dollar.js"' },
+    ] }] },
+  }));
+  const r = verifyInstall(spec);
+  ok('resolution: ~/... and $A/... pointing at existing fixture files pass (no new missing/unverified)',
+    r.missing.length === 0 && r.unverified.length === 0);
+}
+{
+  // A non-trailhead hook with a missing target is ignored entirely.
+  const { configDir, spec } = buildClaudeFixture();
+  write(path.join(configDir, 'settings.json'), JSON.stringify({
+    hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [
+      { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-commit-guard.js')}"` },
+      { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-body-guard.js')}"` },
+      { type: 'command', command: 'node "/gone/other.js"' },
+    ] }] },
+  }));
+  const r = verifyInstall(spec);
+  ok('resolution: a non-trailhead hook with a missing target is ignored', r.missing.length === 0 && r.unverified.length === 0);
+}
+{
+  // Missing/malformed registry: no crash, every expected hook unregistered.
+  const { configDir, spec } = buildClaudeFixture();
+  fs.rmSync(path.join(configDir, 'settings.json'));
+  const r1 = verifyInstall(spec);
+  ok('resolution: a missing registry file does not crash and flags every hook unregistered',
+    r1.missing.includes('hook registration trailhead-commit-guard.js (settings.json)') &&
+    r1.missing.includes('hook registration trailhead-body-guard.js (settings.json)'));
+  write(path.join(configDir, 'settings.json'), '{not json');
+  const r2 = verifyInstall(spec);
+  ok('resolution: a malformed registry file does not crash and flags every hook unregistered',
+    r2.missing.includes('hook registration trailhead-commit-guard.js (settings.json)'));
+}
+
+// --- A2: unresolved expected registration stays warning-only ---------------------
+{
+  const { configDir, spec } = buildClaudeFixture();
+  fs.rmSync(path.join(configDir, 'hooks', 'trailhead-body-guard.js'));
+  write(path.join(configDir, 'settings.json'), JSON.stringify({
+    hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [
+      { type: 'command', command: `node "${path.join(configDir, 'hooks', 'trailhead-commit-guard.js')}"` },
+      { type: 'command', command: 'node "${CLAUDE_PLUGIN_ROOT}/hooks/trailhead-body-guard.js"' },
+    ] }] },
+  }));
+  const r = verifyInstall(spec);
+  ok('A2: an unresolved token whose basename matches the expected file stays unverified, not also missing',
+    !r.missing.includes('hook registration trailhead-body-guard.js (settings.json)') &&
+    r.unverified.some((u) => u.includes('CLAUDE_PLUGIN_ROOT undefined')));
+}
+
+// --- formatters --------------------------------------------------------------
+{
+  const out = formatVerifyFailure('Claude Code', '/c/dir', { missing: ['skill trailhead-work/SKILL.md'], unverified: ['/x/trailhead-y.js (PreToolUse, settings.json: $Y undefined)'] });
+  ok('formatVerifyFailure contains the host', out.includes('Claude Code'));
+  ok('formatVerifyFailure contains the dir', out.includes('/c/dir'));
+  ok('formatVerifyFailure contains the missing entry', out.includes('skill trailhead-work/SKILL.md'));
+  ok('formatVerifyFailure contains the unverified entry', out.includes('$Y undefined'));
+}
+ok('formatVerifyWarnings([]) is []', JSON.stringify(formatVerifyWarnings([])) === '[]');
+ok('formatVerifyWarnings has one line per entry', (() => {
+  const lines = formatVerifyWarnings(['a', 'b']);
+  return lines.length === 2 && lines[0].includes('⚠') && lines[0].includes('a') && lines[1].includes('b');
+})());
+
+// --- cleanup ---------------------------------------------------------------
+for (const d of tmpDirs) fs.rmSync(d, { recursive: true, force: true });
+
+console.log(`✓ install-verify: ${passed} assertions passed`);