hookstack-cli 0.1.18 → 0.1.20

package/README.md

@@ -24,7 +24,9 @@ npx hookstack-cli@latest install --hooks=<slug1>,<slug2>,...
 Options:
   --hooks <slugs>   Comma-separated hook slugs (required)
   --global, -g      Install into ~/.claude instead of ./.claude
-  --scope <s>       "project" (default) or "global"
+  --copilot         Install into ./.claude with paths adapted for GitHub Copilot
+  --scope <s>       "project" (default), "global", or "copilot"
+  --with-tests      Also install vitest unit tests into tests/hooks/ (project scope only)
   --yes, -y         Skip prompts (non-interactive / CI)
   --version, -v     Print version
   --help, -h        Show help
@@ -46,6 +48,9 @@ Skips all prompts — useful in CI or dotfile bootstrap scripts.
 ```bash
 # CI bootstrap
 npx hookstack-cli@latest install --hooks=secret-detection,git-push-guard --yes --scope=project
+
+# CI bootstrap with unit tests (avoids SonarQube gating on new files without tests)
+npx hookstack-cli@latest install --hooks=secret-detection,git-push-guard --yes --with-tests
 ```
 
 ---
@@ -56,6 +61,7 @@ For each hook the CLI:
 
 - Writes the `.mjs` script to `.claude/hooks/` (or `~/.claude/hooks/` for global scope)
 - Patches `.claude/settings.json` to register the hook on the right lifecycle event
+- Optionally writes vitest unit tests to `tests/hooks/` when `--with-tests` is passed (or confirmed interactively)
 
 No new dependencies are added to your project. Hooks are plain Node.js scripts — no SDK, no agent modification.
 

package/bin/cli.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from 'fs'
+import { join as pathJoin } from 'path'
 import { homedir } from 'os'
 import { join, dirname } from 'path'
 import { fileURLToPath } from 'url'
@@ -11,8 +12,8 @@ import {
   mergeHooks,
   assertSafeTarget,
   collectIncomingHooks,
-  buildSummaryRows,
   buildSecurityRows,
+  doInstallTests,
 } from './core.mjs'
 
 const API_BASE = process.env.HOOKSTACK_API_BASE || 'https://hookstack.vercel.app'
@@ -71,29 +72,36 @@ function capCell(on, width) {
   return on ? pc.yellow(text) : pc.dim(text)
 }
 
-const SNYK_COLOR = { high: pc.red, medium: pc.yellow, low: pc.cyan, safe: pc.green, unknown: pc.dim }
+const VERDICT_COLOR = { high: pc.red, medium: pc.yellow, low: pc.cyan, safe: pc.green, unknown: pc.dim }
 
 export function securityPanel(rows) {
-  const W = { name: 28, cap: 8, snyk: 10 }
+  const W = { name: 24, benefit: 34, cap: 7, snyk: 9, codeql: 8 }
   const header = pc.dim(
-    ''.padEnd(W.name) + 'Shell'.padEnd(W.cap) + 'Net'.padEnd(W.cap) +
-    'Writes'.padEnd(W.cap) + 'Snyk',
+    ''.padEnd(W.name) +
+    ''.padEnd(W.benefit) +
+    'Shell'.padEnd(W.cap) +
+    'Net'.padEnd(W.cap) +
+    'Writes'.padEnd(W.cap) +
+    'Snyk'.padEnd(W.snyk) +
+    'CodeQL',
   )
-  const body = rows.map(r =>
-    truncPad(r.name, W.name) +
-    capCell(r.shell, W.cap) +
-    capCell(r.network, W.cap) +
-    capCell(r.fsWrite, W.cap) +
-    (SNYK_COLOR[r.snyk.level] ?? pc.dim)(truncPad(r.snyk.label, W.snyk)),
-  )
-  const anyUnknown = rows.some(r => r.snyk.level === 'unknown')
+  const body = rows.flatMap(r => {
+    const benefitText = r.benefit ? truncPad(r.benefit, W.benefit) : ''.padEnd(W.benefit)
+    const row = truncPad(r.name, W.name) +
+      pc.dim(benefitText) +
+      capCell(r.shell, W.cap) +
+      capCell(r.network, W.cap) +
+      capCell(r.fsWrite, W.cap) +
+      (VERDICT_COLOR[r.snyk.level] ?? pc.dim)(truncPad(r.snyk.label, W.snyk)) +
+      (VERDICT_COLOR[r.codeql.level] ?? pc.dim)(r.codeql.label)
+    return [row]
+  })
   const footer = [
     '',
     pc.dim('Shell = runs commands · Net = network access · Writes = filesystem writes'),
-    anyUnknown ? pc.dim('Snyk "—" = not scanned yet') : null,
     pc.dim(`Details: ${API_BASE}/hook/<slug>`),
-  ].filter(v => v !== null).join('\n')
-  return [header, ...body, footer].join('\n')
+  ].join('\n')
+  return [header, '', ...body, footer].join('\n')
 }
 
 // ── install ───────────────────────────────────────────────────────────────────
@@ -184,12 +192,10 @@ async function interactiveInstall(slugs, args) {
   scope = scopeResult
 
   const dirs = resolveScopeRoot(scope, { cwd: process.cwd(), home: homedir() })
-  const summaryRows = buildSummaryRows(hooks, { root: dirs.root })
   const secRows = buildSecurityRows(hooks)
 
-  // Panels
-  p.note(summaryPanel(summaryRows), 'Installation Summary')
-  p.note(securityPanel(secRows), 'Security Assessment')
+  // Panel
+  p.note(securityPanel(secRows), 'Installation Summary')
 
   // Confirm
   const scopeLabel = scope === 'global' ? '~/.claude' : scope === 'copilot' ? './.claude (Copilot mode)' : './.claude'
@@ -210,12 +216,32 @@ async function interactiveInstall(slugs, args) {
   }
   spin2.stop(`Installed ${pc.bold(String(result.hookCount))} hook${result.hookCount === 1 ? '' : 's'}`)
 
+  // Unit tests prompt (project/copilot scope only)
+  let testResult = null
+  const hooksWithTests = hooks.filter(h => h.test_snippet)
+  if (scope !== 'global' && hooksWithTests.length > 0) {
+    const wantTests = await p.confirm({
+      message: `Install unit tests for ${plural(hooksWithTests.length, 'hook')} into ${pc.cyan('tests/hooks/')}? ${pc.dim('(vitest — helps SonarQube gating)')}`,
+      initialValue: true,
+    })
+    if (!p.isCancel(wantTests) && wantTests) {
+      try {
+        testResult = doInstallTests(hooks, process.cwd(), { mkdirSync, writeFileSync, join: pathJoin })
+      } catch (e) {
+        p.log.warn(`Could not write tests: ${e.message}`)
+      }
+    }
+  }
+
   // Result panel
   const resultLines = [
     pc.green(`✓ ${dirs.settingsPath}`),
     result.scriptCount > 0
       ? pc.green(`✓ ${result.scriptCount} script${result.scriptCount === 1 ? '' : 's'} written to ${dirs.hooksDir}`)
       : null,
+    testResult?.testCount > 0
+      ? pc.green(`✓ ${testResult.testCount} test file${testResult.testCount === 1 ? '' : 's'} written to tests/hooks/`)
+      : null,
     '',
     `Browse more hooks  ${pc.cyan(`${API_BASE}/#catalogue`)}`,
     `⭐  Star us         ${pc.cyan(REPO_URL)}`,
@@ -246,6 +272,15 @@ async function directInstall(slugs, args) {
   const log = { warn: m => console.warn(`  ! ${m}`) }
   const result = doInstall(hooks, dirs, args.scope, log)
   console.log(`  ✓ ${dirs.settingsPath}`)
+  if (args.withTests && args.scope !== 'global') {
+    try {
+      const testResult = doInstallTests(hooks, process.cwd(), { mkdirSync, writeFileSync, join: pathJoin })
+      if (testResult.testCount > 0)
+        console.log(`  ✓ ${testResult.testCount} test file${testResult.testCount === 1 ? '' : 's'} written to tests/hooks/`)
+    } catch (e) {
+      console.warn(`  ! Could not write tests: ${e.message}`)
+    }
+  }
   console.log(`\n✅ ${plural(result.hookCount, 'hook')} installed · star us → ${REPO_URL}`)
   console.log('   Restart Claude Code to activate.\n')
 }
@@ -262,6 +297,7 @@ const HELP = `
     --global, -g      Install into ~/.claude instead of ./.claude
     --copilot         Install into ./.claude with paths adapted for GitHub Copilot
     --scope <s>       "project" (default), "global", or "copilot"
+    --with-tests      Also install vitest unit tests into tests/hooks/ (project scope only)
     --yes, -y         Skip prompts (non-interactive install)
     --version, -v     Show version
     --help, -h        Show this help

package/bin/core.mjs

@@ -27,6 +27,7 @@ export function parseArgs(argv) {
     version: false,
     scope: 'project',
     yes: false,
+    withTests: false,
   }
 
   for (let i = 0; i < args.length; i++) {
@@ -34,6 +35,7 @@ export function parseArgs(argv) {
     if (arg === '--help' || arg === '-h') { result.help = true; continue }
     if (arg === '--version' || arg === '-v') { result.version = true; continue }
     if (arg === '--yes' || arg === '-y') { result.yes = true; continue }
+    if (arg === '--with-tests') { result.withTests = true; continue }
     if (arg === '--global' || arg === '-g') { result.scope = 'global'; continue }
     if (arg === '--project') { result.scope = 'project'; continue }
     if (arg === '--copilot') { result.scope = 'copilot'; continue }
@@ -159,6 +161,16 @@ export function snykVerdict(snyk) {
   return { label: 'Safe', level: 'safe' }
 }
 
+// Maps a stored CodeQL scan to a short verdict label.
+export function codeqlVerdict(codeql) {
+  if (!codeql || typeof codeql !== 'object') return { label: '—', level: 'unknown' }
+  const { critical = 0, high = 0, medium = 0, low = 0 } = codeql
+  if (critical > 0 || high > 0) return { label: 'High Risk', level: 'high' }
+  if (medium > 0) return { label: 'Med Risk', level: 'medium' }
+  if (low > 0) return { label: 'Low Risk', level: 'low' }
+  return { label: 'Safe', level: 'safe' }
+}
+
 export function shortRepo(url) {
   if (!url) return null
   return String(url)
@@ -167,6 +179,21 @@ export function shortRepo(url) {
     .replace(/\/$/, '')
 }
 
+// Writes test files for installed hooks into <projectRoot>/tests/hooks/.
+// Only hooks that have a test_snippet are written; others are silently skipped.
+export function doInstallTests(hooks, projectRoot, { mkdirSync, writeFileSync, join }) {
+  const testsDir = join(projectRoot, 'tests', 'hooks')
+  mkdirSync(testsDir, { recursive: true })
+  let testCount = 0
+  for (const hook of hooks) {
+    if (!hook.test_snippet) continue
+    const dest = join(testsDir, `${hook.slug}.test.mjs`)
+    writeFileSync(dest, hook.test_snippet, 'utf8')
+    testCount++
+  }
+  return { testCount }
+}
+
 // Display rows for the "Installation Summary" panel.
 export function buildSummaryRows(hooks, { root }) {
   return hooks.map(h => {
@@ -184,12 +211,14 @@ export function buildSummaryRows(hooks, { root }) {
   })
 }
 
-// Display rows for the "Security" panel: local static capabilities + Snyk verdict.
+// Display rows for the "Installation Summary" panel: description + static capabilities + verdicts.
 export function buildSecurityRows(hooks) {
   return hooks.map(h => ({
     slug: h.slug,
     name: h.name ?? h.slug,
+    benefit: h.benefit ?? null,
     ...analyzeSecurity(h.code_snippet),
     snyk: snykVerdict(h.security?.snyk),
+    codeql: codeqlVerdict(h.security?.codeql),
   }))
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hookstack-cli",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "CLI installer for the Hookstack catalogue of Claude Code hooks",
   "type": "module",
   "bin": {