hookstack-cli 0.1.3 → 0.1.5

package/bin/cli.mjs

@@ -1,162 +1,248 @@
 #!/usr/bin/env node
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs'
+import { homedir } from 'os'
 import { join } from 'path'
-
-const API_BASE = 'https://hookstack.vercel.app'
-const VERSION = '0.1.0'
-
-function parseArgs(argv) {
-  const args = argv.slice(2)
-  const result = { command: null, hooks: [], help: false, version: false }
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i]
-    if (arg === '--help' || arg === '-h') { result.help = true; continue }
-    if (arg === '--version' || arg === '-v') { result.version = true; continue }
-    if (arg.startsWith('--hooks=')) {
-      result.hooks = arg.slice('--hooks='.length).split(',').filter(Boolean)
-      continue
-    }
-    if (arg === '--hooks' && args[i + 1]) {
-      result.hooks = args[++i].split(',').filter(Boolean)
-      continue
-    }
-    if (!result.command) result.command = arg
-  }
-
-  return result
-}
-
-function mergeHooks(existing, incoming) {
-  const merged = JSON.parse(JSON.stringify(existing))
-  for (const [event, entries] of Object.entries(incoming)) {
-    merged[event] ??= []
-    for (const entry of entries) {
-      const found = merged[event].find(e => (e.matcher ?? '') === (entry.matcher ?? ''))
-      if (found) {
-        found.hooks.push(...entry.hooks)
-      } else {
-        merged[event].push({ ...entry, hooks: [...entry.hooks] })
-      }
-    }
-  }
-  return merged
-}
+import { fileURLToPath } from 'url'
+import * as p from '@clack/prompts'
+import pc from 'picocolors'
+import {
+  parseArgs,
+  resolveScopeRoot,
+  mergeHooks,
+  assertSafeTarget,
+  collectIncomingHooks,
+  buildSummaryRows,
+  buildSecurityRows,
+} from './core.mjs'
+
+const API_BASE = process.env.HOOKSTACK_API_BASE || 'https://hookstack.vercel.app'
+const REPO_URL = 'github.com/steve-magne/hookstack'
+const VERSION = '0.1.3'
 
 async function fetchHooks(slugs) {
-  const url = `${API_BASE}/api/hooks?slugs=${slugs.join(',')}`
+  const url = `${API_BASE}/api/hooks?slugs=${slugs.map(encodeURIComponent).join(',')}`
   const res = await fetch(url)
   if (!res.ok) {
-    const body = await res.text()
+    const body = await res.text().catch(() => '')
     throw new Error(`API error ${res.status}: ${body}`)
   }
   return res.json()
 }
 
-async function install(slugs, root) {
-  console.log(`\nFetching ${slugs.length} hook${slugs.length > 1 ? 's' : ''}…`)
+// ── panel rendering ────────────────────────────────────────────────────────
 
-  let data
-  try {
-    data = await fetchHooks(slugs)
-  } catch (e) {
-    console.error(`\n✗ Failed to fetch hooks: ${e.message}`)
-    process.exit(1)
-  }
+// Truncate to a visible width then pad — operate on PLAIN text only. Color is
+// applied afterwards so ANSI codes never throw off column alignment.
+function truncPad(value, width) {
+  const s = String(value ?? '')
+  return (s.length > width ? s.slice(0, width - 1) + '…' : s).padEnd(width)
+}
 
-  const { hooks } = data
-  const notFound = slugs.filter(s => !hooks.find(h => h.slug === s))
-  if (notFound.length > 0) {
-    console.warn(`  ! Unknown slugs (skipped): ${notFound.join(', ')}`)
-  }
-  if (hooks.length === 0) {
-    console.error('\n✗ No hooks to install.')
-    process.exit(1)
+export function summaryPanel(rows) {
+  const lines = []
+  for (const r of rows) {
+    lines.push(pc.cyan(r.path ?? `${r.name} (settings only)`))
+    const meta = [
+      r.category,
+      r.events.join(', ') + (r.blocking ? pc.yellow(' · can block') : ''),
+      r.matcher ? `matcher: ${r.matcher}` : null,
+    ].filter(Boolean).join(pc.dim(' · '))
+    lines.push('  ' + pc.dim(meta))
+    if (r.source) lines.push('  ' + pc.dim(`source: ${r.source}`))
   }
+  return lines.join('\n')
+}
 
-  const claudeDir = join(root, '.claude')
-  const settingsPath = join(claudeDir, 'settings.json')
-  const hooksDir = join(claudeDir, 'hooks')
+// Boolean capability cell: pad the plain "yes"/"no" first, then colorize.
+function capCell(on, width) {
+  const text = (on ? 'yes' : 'no').padEnd(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 }
+
+export function securityPanel(rows) {
+  const W = { name: 26, cap: 8, snyk: 10 }
+  const header = pc.dim(
+    ''.padEnd(W.name) + 'Shell'.padEnd(W.cap) + 'Net'.padEnd(W.cap) +
+    'Writes'.padEnd(W.cap) + 'Snyk'.padEnd(W.snyk),
+  )
+  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 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')
+}
 
-  mkdirSync(claudeDir, { recursive: true })
-  mkdirSync(hooksDir, { recursive: true })
+// ── install ──────────────────────────────────────────────────────────────
+
+function doInstall(hooks, dirs, scope, log) {
+  mkdirSync(dirs.claudeDir, { recursive: true })
+  mkdirSync(dirs.hooksDir, { recursive: true })
 
   let settings = {}
-  if (existsSync(settingsPath)) {
+  if (existsSync(dirs.settingsPath)) {
     try {
-      settings = JSON.parse(readFileSync(settingsPath, 'utf8'))
-      console.log('  Found existing settings.json — merging…')
+      settings = JSON.parse(readFileSync(dirs.settingsPath, 'utf8'))
     } catch {
-      console.warn('  ! Could not parse settings.json — starting fresh')
-    }
-  }
-
-  const incomingHooks = {}
-  for (const hook of hooks) {
-    const fragment = hook.config?.hooks
-    if (!fragment) continue
-    for (const [event, entries] of Object.entries(fragment)) {
-      incomingHooks[event] ??= []
-      incomingHooks[event].push(...entries)
+      log.warn('Could not parse existing settings.json — starting fresh')
     }
   }
 
-  settings.hooks = mergeHooks(settings.hooks ?? {}, incomingHooks)
-  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n')
-  console.log('  ✓ .claude/settings.json updated')
+  const incoming = collectIncomingHooks(hooks, { scope, globalRoot: dirs.root })
+  settings.hooks = mergeHooks(settings.hooks ?? {}, incoming)
+  writeFileSync(dirs.settingsPath, JSON.stringify(settings, null, 2) + '\n')
 
   let scriptCount = 0
   for (const hook of hooks) {
     if (!hook.script_path || !hook.code_snippet) continue
-    const dest = join(root, hook.script_path)
+    assertSafeTarget(dirs.root, hook.script_path)
+    const dest = join(dirs.root, hook.script_path)
     mkdirSync(join(dest, '..'), { recursive: true })
     writeFileSync(dest, hook.code_snippet, 'utf8')
     scriptCount++
-    console.log(`  ✓ ${hook.script_path}`)
   }
 
-  console.log(`\n✅ Installed ${hooks.length} hook${hooks.length > 1 ? 's' : ''}${scriptCount > 0 ? ` + ${scriptCount} script${scriptCount > 1 ? 's' : ''}` : ''}.`)
-  console.log('   Restart Claude Code to activate.\n')
+  return { hookCount: hooks.length, scriptCount }
 }
 
-async function main() {
-  const { command, hooks, help, version } = parseArgs(process.argv)
+// ── flows ──────────────────────────────────────────────────────────────────
 
-  if (version) {
-    console.log(VERSION)
-    return
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`
+
+async function interactiveInstall(slugs, args) {
+  p.intro(pc.bgCyan(pc.black(' hookstack-cli ')))
+
+  const s = p.spinner()
+  s.start(`Fetching ${plural(slugs.length, 'hook')}`)
+  let data
+  try {
+    data = await fetchHooks(slugs)
+  } catch (e) {
+    s.stop(pc.red('Fetch failed'))
+    p.cancel(e.message)
+    process.exit(1)
+  }
+  const { hooks } = data
+  const notFound = slugs.filter(slug => !hooks.find(h => h.slug === slug))
+  s.stop(`Fetched ${plural(hooks.length, 'hook')}`)
+  if (notFound.length) p.log.warn(`Unknown slugs skipped: ${notFound.join(', ')}`)
+  if (hooks.length === 0) {
+    p.cancel('No hooks to install.')
+    process.exit(1)
+  }
+
+  const scope = await p.select({
+    message: 'Installation scope',
+    initialValue: args.scope,
+    options: [
+      { value: 'project', label: 'Project', hint: './.claude — committed with your project' },
+      { value: 'global', label: 'Global', hint: '~/.claude — every project on this machine' },
+    ],
+  })
+  if (p.isCancel(scope)) { p.cancel('Cancelled.'); process.exit(0) }
+
+  const dirs = resolveScopeRoot(scope, { cwd: process.cwd(), home: homedir() })
+
+  p.note(summaryPanel(buildSummaryRows(hooks, { root: dirs.root })), 'Installation Summary')
+  p.note(securityPanel(buildSecurityRows(hooks)), 'Security')
+
+  const ok = await p.confirm({ message: `Install ${plural(hooks.length, 'hook')} into ${scope === 'global' ? '~/.claude' : './.claude'}?` })
+  if (p.isCancel(ok) || !ok) { p.cancel('Cancelled.'); process.exit(0) }
+
+  const s2 = p.spinner()
+  s2.start('Installing')
+  let result
+  try {
+    result = doInstall(hooks, dirs, scope, p.log)
+  } catch (e) {
+    s2.stop(pc.red('Install failed'))
+    p.cancel(e.message)
+    process.exit(1)
   }
+  s2.stop(`Wrote ${plural(result.scriptCount, 'script')} + patched settings.json`)
 
-  if (help || (!command && hooks.length === 0)) {
-    console.log(`
+  p.log.info(`⭐  star us → ${pc.cyan(REPO_URL)}`)
+  p.outro(pc.green(`✓ Installed ${plural(result.hookCount, 'hook')} — restart Claude Code to activate.`))
+}
+
+async function directInstall(slugs, args) {
+  console.log(`\nFetching ${plural(slugs.length, 'hook')}…`)
+  let data
+  try {
+    data = await fetchHooks(slugs)
+  } catch (e) {
+    console.error(`\n✗ Failed: ${e.message}`)
+    process.exit(1)
+  }
+  const { hooks } = data
+  const notFound = slugs.filter(slug => !hooks.find(h => h.slug === slug))
+  if (notFound.length) console.warn(`  ! Unknown slugs (skipped): ${notFound.join(', ')}`)
+  if (hooks.length === 0) {
+    console.error('\n✗ No hooks to install.')
+    process.exit(1)
+  }
+  const dirs = resolveScopeRoot(args.scope, { cwd: process.cwd(), home: homedir() })
+  const log = { warn: m => console.warn(`  ! ${m}`) }
+  const result = doInstall(hooks, dirs, args.scope, log)
+  console.log(`  ✓ ${dirs.settingsPath}`)
+  console.log(`\n✅ ${plural(result.hookCount, 'hook')} installed · star us → ${REPO_URL}`)
+  console.log('   Restart Claude Code to activate.\n')
+}
+
+const HELP = `
   hookstack — Claude Code hook installer
 
   Usage:
-    npx hookstack-cli-cli install --hooks=<slug1>,<slug2>,...
+    npx hookstack-cli@latest install --hooks=<slug1>,<slug2>,...
 
   Options:
     --hooks <slugs>   Comma-separated list of hook slugs
+    --global, -g      Install into ~/.claude instead of ./.claude
+    --scope <s>       "project" (default) or "global"
+    --yes, -y         Skip prompts (non-interactive install)
     --version, -v     Show version
     --help, -h        Show this help
 
-  Browse hooks at https://hookstack.vercel.app
-`)
-    return
+  Runs interactively in a terminal; falls back to a direct install when piped
+  or when --yes is passed. Browse hooks at https://hookstack.vercel.app
+`
+
+async function main() {
+  const args = parseArgs(process.argv)
+
+  if (args.version) { console.log(VERSION); return }
+  if (args.help || (!args.command && args.hooks.length === 0)) { console.log(HELP); return }
+
+  const command = args.command ?? 'install'
+  if (command !== 'install') {
+    console.error(`✗ Unknown command: ${command}`)
+    console.error('  Run --help for usage.')
+    process.exit(1)
   }
 
-  if (command === 'install' || command === null) {
-    if (hooks.length === 0) {
-      console.error('✗ No hooks specified. Use --hooks=<slug1>,<slug2>')
-      console.error('  Browse hooks at https://hookstack.vercel.app')
-      process.exit(1)
-    }
-    await install(hooks, process.cwd())
-    return
+  if (args.hooks.length === 0) {
+    console.error('✗ No hooks specified. Use --hooks=<slug1>,<slug2>')
+    console.error('  Browse hooks at https://hookstack.vercel.app')
+    process.exit(1)
   }
 
-  console.error(`✗ Unknown command: ${command}`)
-  console.error('  Run --help for usage.')
-  process.exit(1)
+  const interactive = Boolean(process.stdout.isTTY) && !args.yes
+  if (interactive) await interactiveInstall(args.hooks, args)
+  else await directInstall(args.hooks, args)
 }
 
-main()
+/* v8 ignore next 3 */
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main()
+}

package/bin/core.mjs

@@ -0,0 +1,191 @@
+// Pure, dependency-free logic for the hookstack CLI.
+// Everything here is side-effect free and unit-tested in isolation; the
+// interactive I/O (clack/picocolors, fs, fetch) lives in cli.mjs. This mirrors
+// the project's "pure run() + thin I/O guard" hook convention.
+import { join, resolve, relative, isAbsolute } from 'path'
+
+const BLOCKING_EVENTS = new Set([
+  'PreToolUse',
+  'UserPromptSubmit',
+  'PreCompact',
+  'PermissionRequest',
+])
+
+// Matches $CLAUDE_PROJECT_DIR and ${CLAUDE_PROJECT_DIR}.
+export const PROJECT_DIR_RE = /\$\{?CLAUDE_PROJECT_DIR\}?/g
+
+function splitList(raw) {
+  return raw.split(',').map(s => s.trim()).filter(Boolean)
+}
+
+export function parseArgs(argv) {
+  const args = argv.slice(2)
+  const result = {
+    command: null,
+    hooks: [],
+    help: false,
+    version: false,
+    scope: 'project',
+    yes: false,
+  }
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    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 === '--global' || arg === '-g') { result.scope = 'global'; continue }
+    if (arg === '--project') { result.scope = 'project'; continue }
+    if (arg.startsWith('--scope=')) {
+      const v = arg.slice('--scope='.length)
+      if (v === 'global' || v === 'project') result.scope = v
+      continue
+    }
+    if (arg.startsWith('--hooks=')) { result.hooks = splitList(arg.slice('--hooks='.length)); continue }
+    if (arg === '--hooks' && args[i + 1]) { result.hooks = splitList(args[++i]); continue }
+    if (!result.command) result.command = arg
+  }
+
+  return result
+}
+
+// Resolves where .claude/ lives for a given scope. Project → cwd; global → home.
+export function resolveScopeRoot(scope, { cwd, home }) {
+  const root = scope === 'global' ? home : cwd
+  const claudeDir = join(root, '.claude')
+  return {
+    scope,
+    root,
+    claudeDir,
+    hooksDir: join(claudeDir, 'hooks'),
+    settingsPath: join(claudeDir, 'settings.json'),
+  }
+}
+
+// Rejects target paths that would escape destDir, even if the registry JSON was
+// tampered with. Adapted from hyperframes' installer.assertSafeTarget.
+export function assertSafeTarget(destDir, target) {
+  if (isAbsolute(target)) {
+    throw new Error(`Unsafe path "${target}": absolute paths are not allowed.`)
+  }
+  if (/(^|[/\\])\.\.([/\\]|$)/.test(target)) {
+    throw new Error(`Unsafe path "${target}": ".." segments are not allowed.`)
+  }
+  if (/^[A-Za-z]:[/\\]/.test(target)) {
+    throw new Error(`Unsafe path "${target}": Windows drive letters are not allowed.`)
+  }
+  const resolved = resolve(destDir, target)
+  const rel = relative(resolve(destDir), resolved)
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`Unsafe path "${target}": resolves outside ${destDir}.`)
+  }
+}
+
+// Merges incoming settings.json hook fragments into existing ones, grouping by
+// event then by matcher (no overwrite). Same contract as src/lib/mergeConfig.
+export function mergeHooks(existing, incoming) {
+  const merged = structuredClone(existing)
+  for (const [event, entries] of Object.entries(incoming)) {
+    merged[event] ??= []
+    for (const entry of entries) {
+      const found = merged[event].find(e => (e.matcher ?? '') === (entry.matcher ?? ''))
+      if (found) found.hooks.push(...entry.hooks)
+      else merged[event].push({ ...entry, hooks: [...entry.hooks] })
+    }
+  }
+  return merged
+}
+
+// Gathers the hook fragments from an API hook list into a single event→entries
+// map. For global scope, rewrites $CLAUDE_PROJECT_DIR to the absolute global
+// root so commands resolve outside any project.
+export function collectIncomingHooks(hooks, { scope = 'project', globalRoot } = {}) {
+  const incoming = {}
+  for (const hook of hooks) {
+    const fragment = hook.config?.hooks
+    if (!fragment) continue
+    for (const [event, entries] of Object.entries(fragment)) {
+      incoming[event] ??= []
+      for (const entry of entries) {
+        const rewrite = scope === 'global' && globalRoot
+        incoming[event].push({
+          ...entry,
+          hooks: entry.hooks.map(h =>
+            rewrite && typeof h.command === 'string'
+              ? { ...h, command: h.command.replace(PROJECT_DIR_RE, globalRoot) }
+              : h,
+          ),
+        })
+      }
+    }
+  }
+  return incoming
+}
+
+export function isBlockingEvent(event) {
+  return BLOCKING_EVENTS.has(event)
+}
+
+// Honest static read of what a hook's code does — no external service.
+export function analyzeSecurity(codeSnippet) {
+  const code = codeSnippet ?? ''
+  const has = (...patterns) => patterns.some(re => re.test(code))
+  return {
+    shell: has(/\b(execSync|execFileSync|execFile|exec|spawnSync|spawn|fork)\s*\(/, /child_process/),
+    network: has(
+      /\bfetch\s*\(/,
+      /['"]node:(https?|net|dgram|dns)['"]/,
+      /\brequire\(\s*['"](https?|net|dgram|dns)['"]\s*\)/,
+      /\bfrom\s+['"](node:)?https?['"]/,
+    ),
+    fsWrite: has(
+      /\b(writeFileSync|writeFile|appendFileSync|appendFile|rmSync|unlinkSync|unlink|mkdirSync|renameSync|rename|rmdirSync|cpSync)\s*\(/,
+    ),
+  }
+}
+
+// Maps a stored Snyk scan ({high, medium, low}) to a short verdict label.
+// Returns the "unknown" placeholder when no scan data is available yet.
+export function snykVerdict(snyk) {
+  if (!snyk || typeof snyk !== 'object') return { label: '—', level: 'unknown' }
+  const { high = 0, medium = 0, low = 0 } = snyk
+  if (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)
+    .replace(/^https?:\/\/github\.com\//, '')
+    .replace(/\.git$/, '')
+    .replace(/\/$/, '')
+}
+
+// Display rows for the "Installation Summary" panel.
+export function buildSummaryRows(hooks, { root }) {
+  return hooks.map(h => {
+    const events = h.config?.hooks ? Object.keys(h.config.hooks) : []
+    return {
+      slug: h.slug,
+      name: h.name ?? h.slug,
+      path: h.script_path ? join(root, h.script_path) : null,
+      category: h.category ?? null,
+      events,
+      blocking: events.some(isBlockingEvent),
+      matcher: h.trigger ?? null,
+      source: shortRepo(h.community_examples?.[0]?.repo),
+    }
+  })
+}
+
+// Display rows for the "Security" panel: local static capabilities + Snyk verdict.
+export function buildSecurityRows(hooks) {
+  return hooks.map(h => ({
+    slug: h.slug,
+    name: h.name ?? h.slug,
+    ...analyzeSecurity(h.code_snippet),
+    snyk: snykVerdict(h.security?.snyk),
+  }))
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hookstack-cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "CLI installer for the Hookstack catalogue of Claude Code hooks",
   "type": "module",
   "bin": {
@@ -12,6 +12,10 @@
   "engines": {
     "node": ">=18"
   },
+  "dependencies": {
+    "@clack/prompts": "^1.0.0",
+    "picocolors": "^1.1.1"
+  },
   "keywords": [
     "claude-code",
     "hooks",