dw-kit 1.3.4 → 1.3.5

package/src/commands/security-scan.mjs

@@ -0,0 +1,427 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { banner, log, info, warn, ok, err } from '../lib/ui.mjs';
+import chalk from 'chalk';
+import {
+  loadSnapshot,
+  snapshotInfo,
+  syncSnapshotForProject,
+  isStale,
+  isSchemaCompatible,
+  fetchOsvByName,
+} from '../lib/sc-sync.mjs';
+import {
+  scanProject,
+  severityRank,
+  worstSeverity,
+  parsePackageJson,
+  findPackageJson,
+  matchPackageByName,
+  matchNamespaceFixture,
+} from '../lib/sc-scanner.mjs';
+import { logEvent } from '../lib/telemetry.mjs';
+
+const TOOLKIT_ROOT = resolve(fileURLToPath(import.meta.url), '..', '..', '..');
+const NAMESPACE_FIXTURE_REL = '.dw/security/ioc-namespaces.json';
+
+export async function securityScanCommand(opts) {
+  const rootDir = process.cwd();
+  const mode = pickMode(opts);
+
+  if (mode === 'pre-install') {
+    return runPreInstallMode(rootDir, opts);
+  }
+
+  if (opts.json) {
+    return runJsonMode(rootDir, mode, opts);
+  }
+
+  banner('dw-kit Supply-Chain Scan');
+
+  if (mode === 'update-db' || opts.updateDb) {
+    info('Fetching fresh advisory snapshot from OSV.dev...');
+    try {
+      const start = Date.now();
+      const res = await syncSnapshotForProject(rootDir);
+      const elapsed = Date.now() - start;
+      ok(`Snapshot updated — ${res.advisoryCount} advisories for ${res.packageCount} packages (${elapsed}ms)`);
+      logEvent({ event: 'sc_guard', action: 'sync', advisories: res.advisoryCount, packages: res.packageCount, latency_ms: elapsed }, rootDir);
+    } catch (e) {
+      err(`Sync failed: ${e.message}`);
+      if (e.code === 'NO_LOCKFILE') warn('Run `npm install` first to create package-lock.json.');
+      process.exit(2);
+    }
+    if (mode === 'update-db') {
+      log('');
+      info('Snapshot ready. Run `dw security-scan` to scan project.');
+      return;
+    }
+    log('');
+  }
+
+  const info_ = snapshotInfo(rootDir);
+  if (!info_.exists) {
+    warn('No advisory snapshot found.');
+    log('Run `dw security-scan --update-db` to fetch from OSV.dev.');
+    log('Quick mode requires an existing snapshot.');
+    process.exit(1);
+  }
+
+  const ageDays = info_.age_days;
+  const ageLabel = ageDays === Infinity ? 'unknown' : `${ageDays.toFixed(1)} days old`;
+  log(chalk.bold('Snapshot'));
+  log(`  Source     : ${info_.source} (${info_.ecosystem})`);
+  log(`  Fetched    : ${info_.fetched_at || '?'} (${ageLabel})`);
+  log(`  Advisories : ${info_.advisory_count}  Packages scanned previously: ${info_.package_count}`);
+  if (!info_.schema_compatible) {
+    err(`  Schema mismatch — expected 1.0, got ${info_.schema_version || 'unknown'}`);
+    log('  Run `dw security-scan --update-db` to refresh.');
+    process.exit(2);
+  }
+  if (info_.stale) {
+    warn(`  Snapshot is stale (>7 days). Run \`dw security-scan --update-db\` to refresh.`);
+  }
+
+  log('');
+  log(chalk.bold('Scanning project lockfile...'));
+  const snap = loadSnapshot(rootDir);
+  const start = Date.now();
+  const result = scanProject(rootDir, snap);
+  const elapsed = Date.now() - start;
+
+  if (result.error === 'no_lockfile') {
+    err('No lockfile found (expected package-lock.json).');
+    process.exit(1);
+  }
+  if (result.error === 'no_snapshot') {
+    err('Snapshot data unavailable.');
+    process.exit(1);
+  }
+
+  log(`  Lockfile          : ${result.lockfile}`);
+  log(`  Packages scanned  : ${result.packages_scanned}`);
+  log(`  Elapsed           : ${elapsed}ms`);
+  log('');
+
+  if (result.matches.length === 0) {
+    ok('No advisory matches — clean.');
+    logEvent({ event: 'sc_guard', action: 'scan_run', matches: 0, packages: result.packages_scanned, outcome: 'clean', latency_ms: elapsed }, rootDir);
+    log('');
+    advisoryFooter();
+    return;
+  }
+
+  log(chalk.bold(`Matches (${result.matches.length})`));
+  const sorted = result.matches.slice().sort((a, b) => severityRank(b.severity) - severityRank(a.severity));
+  for (const m of sorted) {
+    const tag = severityTag(m.severity);
+    log(`  ${tag} ${m.package}@${m.version}`);
+    if (m.summary) log(chalk.dim(`      ${m.summary}`));
+    log(chalk.dim(`      advisory: ${m.advisory_id}`));
+    if (m.fix_versions.length) log(chalk.dim(`      fix:      ${m.fix_versions.join(', ')}`));
+  }
+  log('');
+
+  const worst = worstSeverity(result.matches);
+  const blockCount = result.matches.filter((m) => severityRank(m.severity) >= severityRank('high')).length;
+  const exitCode = blockCount > 0 ? 2 : 1;
+
+  logEvent(
+    {
+      event: 'sc_guard',
+      action: blockCount > 0 ? 'block' : 'allow',
+      matches: result.matches.length,
+      block_count: blockCount,
+      worst_severity: worst,
+      packages: result.packages_scanned,
+      latency_ms: elapsed,
+      snapshot_age_days: ageDays,
+    },
+    rootDir,
+  );
+
+  if (blockCount > 0) {
+    err(`${blockCount} HIGH+ severity match(es) — review before merging lockfile changes.`);
+  } else {
+    warn(`${result.matches.length} low/medium match(es) — review recommended.`);
+  }
+  log('');
+  advisoryFooter();
+  process.exit(exitCode);
+}
+
+function pickMode(opts) {
+  if (opts.preInstall) return 'pre-install';
+  if (opts.updateDb) return 'update-db';
+  return 'scan';
+}
+
+function loadNamespaceFixture(rootDir) {
+  // Prefer project-local fixture, fall back to toolkit-bundled
+  const candidates = [
+    join(rootDir, NAMESPACE_FIXTURE_REL),
+    join(TOOLKIT_ROOT, NAMESPACE_FIXTURE_REL),
+  ];
+  for (const p of candidates) {
+    if (existsSync(p)) {
+      try {
+        return { fixture: JSON.parse(readFileSync(p, 'utf-8')), path: p };
+      } catch {
+        // skip malformed
+      }
+    }
+  }
+  return { fixture: null, path: null };
+}
+
+async function runPreInstallMode(rootDir, opts) {
+  const useJson = !!opts.json;
+  const out = { mode: 'pre-install', ok: true, network_ok: false, packages: 0, osv_hits: [], namespace_hits: [] };
+
+  const pkgPath = findPackageJson(rootDir);
+  if (!pkgPath) {
+    if (useJson) {
+      out.ok = false;
+      out.error = { code: 'NO_PACKAGE_JSON', message: 'No package.json in current directory' };
+      process.stdout.write(JSON.stringify(out) + '\n');
+      process.exit(1);
+    }
+    err('No package.json in current directory.');
+    process.exit(1);
+  }
+
+  let packages;
+  try {
+    packages = parsePackageJson(pkgPath);
+  } catch (e) {
+    if (useJson) {
+      out.ok = false;
+      out.error = { code: 'PARSE_FAILED', message: e.message };
+      process.stdout.write(JSON.stringify(out) + '\n');
+      process.exit(1);
+    }
+    err(`Failed to parse package.json: ${e.message}`);
+    process.exit(1);
+  }
+
+  out.packages = packages.size;
+
+  if (!useJson) {
+    banner('dw-kit Pre-Install Scan');
+    log(chalk.bold('package.json'));
+    log(`  Path     : ${pkgPath}`);
+    log(`  Declared : ${packages.size} packages (across deps/devDeps/peerDeps/optionalDeps)`);
+    log('');
+  }
+
+  // 1. Namespace fixture (offline, fast)
+  const fixtureBundle = loadNamespaceFixture(rootDir);
+  if (fixtureBundle.fixture) {
+    const hits = matchNamespaceFixture(packages, fixtureBundle.fixture);
+    out.namespace_hits = hits;
+    out.fixture_path = fixtureBundle.path;
+    if (!useJson) {
+      log(chalk.bold('Namespace IoC fixture'));
+      log(`  Source   : ${fixtureBundle.path}`);
+      log(`  Entries  : ${(fixtureBundle.fixture.namespaces || []).length} active namespace pattern(s)`);
+      if (hits.length === 0) {
+        ok('  No matches against active namespace patterns');
+      } else {
+        log('');
+        for (const h of hits) {
+          log(`  ${severityTag(h.severity)} ${h.package} matches pattern "${h.namespace_pattern}"`);
+          if (h.reason) log(chalk.dim(`      ${h.reason}`));
+          if (h.guidance) log(chalk.yellow(`      guidance: ${h.guidance}`));
+          if (h.advisory_url) log(chalk.dim(`      advisory: ${h.advisory_url}`));
+        }
+      }
+      log('');
+    }
+  }
+
+  // 2. OSV.dev name-only queries (network, optional)
+  if (!opts.offline) {
+    if (!useJson) log(chalk.bold('OSV.dev name-only query (per declared package)'));
+    const osvErrors = [];
+    let queried = 0;
+    for (const [name] of packages) {
+      try {
+        const result = await fetchOsvByName(name, 'npm', { timeoutMs: 5000 });
+        queried++;
+        const vulns = (result && result.vulns) || [];
+        if (vulns.length > 0) {
+          const hits = matchPackageByName(name, vulns);
+          for (const h of hits) {
+            out.osv_hits.push({ package: name, declared_range: packages.get(name), ...h });
+          }
+        }
+      } catch (e) {
+        osvErrors.push({ package: name, error: e.message });
+      }
+    }
+    out.network_ok = queried > 0;
+    out.osv_queried = queried;
+    out.osv_errors = osvErrors;
+
+    if (!useJson) {
+      log(`  Queried  : ${queried}/${packages.size} packages (${osvErrors.length} errors)`);
+      if (out.osv_hits.length === 0) {
+        ok('  No active advisories for declared packages');
+      } else {
+        const grouped = groupBy(out.osv_hits, 'package');
+        log('');
+        for (const [pkg, hits] of Object.entries(grouped)) {
+          const worst = hits.reduce(
+            (acc, h) => (severityRank(h.severity) > severityRank(acc) ? h.severity : acc),
+            'unknown',
+          );
+          log(`  ${severityTag(worst)} ${pkg}@${packages.get(pkg)} — ${hits.length} active advisory(s)`);
+          for (const h of hits.slice(0, 3)) {
+            log(chalk.dim(`      ${h.advisory_id}: ${h.summary || '(no summary)'}`));
+            if (h.fix_versions && h.fix_versions.length) {
+              log(chalk.dim(`        fix: ${h.fix_versions.slice(0, 3).join(', ')}`));
+            }
+          }
+          if (hits.length > 3) log(chalk.dim(`      ... and ${hits.length - 3} more`));
+        }
+      }
+      log('');
+    }
+  } else if (!useJson) {
+    log(chalk.dim('  OSV.dev query: skipped (--offline)'));
+    log('');
+  }
+
+  // Summarize
+  const namespaceCrit = out.namespace_hits.length;
+  const osvHigh = out.osv_hits.filter((h) => severityRank(h.severity) >= severityRank('high')).length;
+  const exitCode = namespaceCrit > 0 ? 2 : (osvHigh > 0 ? 2 : (out.osv_hits.length > 0 ? 1 : 0));
+
+  logEvent(
+    {
+      event: 'sc_guard',
+      action: exitCode >= 2 ? 'block' : (exitCode === 1 ? 'allow' : 'scan_run'),
+      sub_mode: 'pre-install',
+      packages: packages.size,
+      namespace_hits: namespaceCrit,
+      osv_hits: out.osv_hits.length,
+      osv_high: osvHigh,
+      network_ok: out.network_ok,
+    },
+    rootDir,
+  );
+
+  if (useJson) {
+    out.summary = { namespace_hits: namespaceCrit, osv_hits: out.osv_hits.length, osv_high: osvHigh, exit_code: exitCode };
+    process.stdout.write(JSON.stringify(out) + '\n');
+    process.exit(exitCode);
+  }
+
+  log(chalk.bold('Summary'));
+  if (exitCode === 0) {
+    ok(`Clean — ${packages.size} packages scanned, no matches`);
+  } else if (exitCode === 1) {
+    warn(`${out.osv_hits.length} low/medium advisor(y/ies) found — review recommended`);
+  } else {
+    err(`${namespaceCrit} namespace match(es) + ${osvHigh} HIGH+ advisory(s) — rotate credentials if already installed`);
+  }
+  log('');
+  advisoryFooter();
+  process.exit(exitCode);
+}
+
+function groupBy(arr, key) {
+  const out = {};
+  for (const item of arr) {
+    const k = item[key];
+    if (!out[k]) out[k] = [];
+    out[k].push(item);
+  }
+  return out;
+}
+
+function severityTag(label) {
+  switch (label) {
+    case 'critical':
+      return chalk.red.bold('[CRITICAL]'.padEnd(12));
+    case 'high':
+      return chalk.red('[HIGH]    '.padEnd(12));
+    case 'medium':
+      return chalk.yellow('[MEDIUM]  '.padEnd(12));
+    case 'low':
+      return chalk.blue('[LOW]     '.padEnd(12));
+    default:
+      return chalk.dim('[?]       '.padEnd(12));
+  }
+}
+
+function advisoryFooter() {
+  info('ADVISORY OUTPUT — NOT a decision rule.');
+  log('  Threshold matrix in v14-evaluation-protocol.md is authoritative.');
+  log('  Use this scan as evidence-supplement only.');
+  log('  Public sunset commitment: 2026-08-12 (see ADR-0005).');
+}
+
+async function runJsonMode(rootDir, mode, opts) {
+  let out = { mode, ok: true };
+
+  if (mode === 'update-db' || opts.updateDb) {
+    try {
+      const start = Date.now();
+      const res = await syncSnapshotForProject(rootDir);
+      out.sync = { advisory_count: res.advisoryCount, package_count: res.packageCount, latency_ms: Date.now() - start };
+      logEvent({ event: 'sc_guard', action: 'sync', advisories: res.advisoryCount, packages: res.packageCount }, rootDir);
+    } catch (e) {
+      out.ok = false;
+      out.error = { code: e.code || 'SYNC_FAILED', message: e.message };
+      process.stdout.write(JSON.stringify(out) + '\n');
+      process.exit(2);
+    }
+    if (mode === 'update-db') {
+      process.stdout.write(JSON.stringify(out) + '\n');
+      return;
+    }
+  }
+
+  const info_ = snapshotInfo(rootDir);
+  out.snapshot = info_;
+  if (!info_.exists) {
+    out.ok = false;
+    out.error = { code: 'NO_SNAPSHOT', message: 'Run `dw security-scan --update-db`' };
+    process.stdout.write(JSON.stringify(out) + '\n');
+    process.exit(1);
+  }
+
+  const snap = loadSnapshot(rootDir);
+  const start = Date.now();
+  const result = scanProject(rootDir, snap);
+  out.scan = { ...result, elapsed_ms: Date.now() - start };
+
+  if (result.error) {
+    out.ok = false;
+    out.error = { code: result.error.toUpperCase(), message: result.error };
+    process.stdout.write(JSON.stringify(out) + '\n');
+    process.exit(1);
+  }
+
+  const worst = worstSeverity(result.matches);
+  const blockCount = result.matches.filter((m) => severityRank(m.severity) >= severityRank('high')).length;
+  out.summary = { matches: result.matches.length, block_count: blockCount, worst_severity: worst };
+
+  logEvent(
+    {
+      event: 'sc_guard',
+      action: blockCount > 0 ? 'block' : (result.matches.length > 0 ? 'allow' : 'scan_run'),
+      matches: result.matches.length,
+      block_count: blockCount,
+      worst_severity: worst,
+      packages: result.packages_scanned,
+      snapshot_age_days: info_.age_days,
+    },
+    rootDir,
+  );
+
+  process.stdout.write(JSON.stringify(out) + '\n');
+  process.exit(blockCount > 0 ? 2 : result.matches.length > 0 ? 1 : 0);
+}

package/src/commands/upgrade.mjs

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { header, ok, warn, err, info, log, dry } from '../lib/ui.mjs';
 import { loadConfig, writeConfig, getToolkitVersions } from '../lib/config.mjs';
 import { diffDirs, copyDir, copyFile } from '../lib/copy.mjs';
+import { ensureDwGitignore, ensureClaudeGitignore } from '../lib/gitignore.mjs';
 
 const TOOLKIT_ROOT = resolve(fileURLToPath(import.meta.url), '..', '..', '..');
 
@@ -57,6 +58,7 @@ export async function upgradeCommand(opts) {
 
   upgradeScripts(projectDir, opts);
   upgradeConfigSchema(projectDir, opts);
+  upgradeScopedGitignores(projectDir, opts);
 
   if (!opts.dryRun && totalChanges > 0) {
     updateVersionTracking(configPath, projectConfig, toolkitVersions);
@@ -169,6 +171,7 @@ function mergeSettingsJson(projectDir, opts) {
 
   if (opts.dryRun) {
     dry('merge .claude/settings.json');
+    dry('post-merge: wire supply-chain-scan.sh hook if missing (idempotent)');
     return;
   }
 
@@ -181,6 +184,57 @@ function mergeSettingsJson(projectDir, opts) {
   } catch (e) {
     warn(`settings.json merge failed: ${e.message}`);
   }
+
+  // Post-merge: explicitly install supply-chain-scan hook (ADR-0005, idempotent).
+  // deepMerge replaces arrays, so user's PostToolUse array may not contain the new
+  // hook entry. We must add it explicitly. Respects existing wiring.
+  installSupplyChainHookOnUpgrade(projectDir, opts);
+}
+
+function upgradeScopedGitignores(projectDir, opts) {
+  info('Scoped .gitignore (.dw/, .claude/)');
+  if (opts.dryRun) {
+    dry('refresh .dw/.gitignore + .claude/.gitignore managed blocks');
+    return;
+  }
+  try {
+    const dwR = ensureDwGitignore(projectDir);
+    if (dwR.action === 'noop') log('  .dw/.gitignore: up to date');
+    else ok(`.dw/.gitignore: ${dwR.action}`);
+
+    if (existsSync(join(projectDir, '.claude'))) {
+      const cR = ensureClaudeGitignore(projectDir);
+      if (cR.action === 'noop') log('  .claude/.gitignore: up to date');
+      else ok(`.claude/.gitignore: ${cR.action}`);
+    }
+  } catch (e) {
+    warn(`Scoped gitignore: ${e.message}`);
+  }
+}
+
+function installSupplyChainHookOnUpgrade(projectDir, opts) {
+  if (opts.dryRun) return;
+  try {
+    const configPath = join(projectDir, '.dw', 'config', 'dw.config.yml');
+    if (existsSync(configPath)) {
+      const cfg = readFileSync(configPath, 'utf-8');
+      if (/depth:\s*quick/i.test(cfg) && !/roles:\s*\[?\s*dev\s*,/i.test(cfg)) {
+        // Heuristic: solo preset → skip per ADR-0005 TW5
+        log('  Supply-chain hook: skipped (solo-style preset detected)');
+        log('  Enable later: `dw security-scan --install-hook`');
+        return;
+      }
+    }
+  } catch { /* fall through */ }
+
+  // Defer import (avoid loading at module top) for clean test isolation
+  import('../lib/sc-install.mjs').then((m) => {
+    const result = m.installHookInProject(projectDir);
+    if (result.ok && result.action === 'added') {
+      ok('Supply-chain guard hook wired (ADR-0005 — opt-in available since v1.3.5)');
+      log('  First scan: `dw security-scan --update-db`');
+    }
+  }).catch(() => { /* silent — installation is best-effort */ });
 }
 
 function deepMerge(base, override) {

package/src/lib/gitignore.mjs

@@ -0,0 +1,86 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+const MARKER_START = '# >>> dw-kit managed >>>';
+const MARKER_END = '# <<< dw-kit managed <<<';
+
+const DW_GITIGNORE_BLOCK = [
+  MARKER_START,
+  '# dw-kit framework files — regenerated by `dw init` / `dw upgrade`.',
+  '# Do NOT commit. Update dw-kit regularly via `dw upgrade`.',
+  'adapters/',
+  'core/',
+  'security/',
+  '',
+  '# Config directory: ignore framework files, keep user dw.config.yml tracked',
+  'config/*',
+  '!config/dw.config.yml',
+  '!config/.gitignore',
+  'config/dw.config.local.yml',
+  '',
+  '# Local-only telemetry (machine-specific, has session hashes)',
+  'metrics/',
+  MARKER_END,
+];
+
+const CLAUDE_GITIGNORE_BLOCK = [
+  MARKER_START,
+  '# dw-kit framework files — regenerated by `dw init` / `dw upgrade`.',
+  '# Do NOT commit. Update dw-kit regularly via `dw upgrade`.',
+  'agents/',
+  'hooks/',
+  'rules/',
+  'skills/',
+  'templates/',
+  '',
+  '# Local-only override (also in root .gitignore for safety)',
+  'settings.local.json',
+  MARKER_END,
+];
+
+function ensureDir(filepath) {
+  const dir = dirname(filepath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+function applyManagedBlock(content, blockLines) {
+  const block = blockLines.join('\n') + '\n';
+  if (!content) return block;
+
+  // If markers already present, replace block in-place (idempotent + upgrade-friendly)
+  const startIdx = content.indexOf(MARKER_START);
+  const endIdx = content.indexOf(MARKER_END);
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const before = content.slice(0, startIdx);
+    const after = content.slice(endIdx + MARKER_END.length);
+    return (before + block + after).replace(/\n{3,}/g, '\n\n');
+  }
+
+  // Markers not present — append block
+  const sep = content.endsWith('\n') ? '\n' : '\n\n';
+  return content + sep + block;
+}
+
+function writeGitignore(targetPath, blockLines) {
+  ensureDir(targetPath);
+  const current = existsSync(targetPath) ? readFileSync(targetPath, 'utf-8') : '';
+  const updated = applyManagedBlock(current, blockLines);
+  if (updated === current) return { action: 'noop', path: targetPath };
+  writeFileSync(targetPath, updated, 'utf-8');
+  return { action: current ? 'updated' : 'created', path: targetPath };
+}
+
+export function ensureDwGitignore(projectDir = process.cwd()) {
+  return writeGitignore(join(projectDir, '.dw', '.gitignore'), DW_GITIGNORE_BLOCK);
+}
+
+export function ensureClaudeGitignore(projectDir = process.cwd()) {
+  return writeGitignore(join(projectDir, '.claude', '.gitignore'), CLAUDE_GITIGNORE_BLOCK);
+}
+
+export function ensureBothGitignores(projectDir = process.cwd()) {
+  return {
+    dw: ensureDwGitignore(projectDir),
+    claude: ensureClaudeGitignore(projectDir),
+  };
+}

package/src/lib/sc-install.mjs

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const HOOK_COMMAND = 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/supply-chain-scan.sh"';
+const MATCHER = 'Write|Edit';
+
+export function settingsPath(rootDir = process.cwd()) {
+  return join(rootDir, '.claude', 'settings.json');
+}
+
+export function isHookWired(settings) {
+  if (!settings?.hooks?.PostToolUse) return false;
+  for (const group of settings.hooks.PostToolUse) {
+    if (group.matcher !== MATCHER && !(group.matcher || '').split('|').includes('Write')) continue;
+    if (!Array.isArray(group.hooks)) continue;
+    for (const h of group.hooks) {
+      if (h.command && h.command.includes('supply-chain-scan.sh')) return true;
+    }
+  }
+  return false;
+}
+
+export function wireHook(settings) {
+  settings.hooks = settings.hooks || {};
+  settings.hooks.PostToolUse = settings.hooks.PostToolUse || [];
+
+  let group = settings.hooks.PostToolUse.find((g) => g.matcher === MATCHER);
+  if (!group) {
+    group = { matcher: MATCHER, hooks: [] };
+    settings.hooks.PostToolUse.push(group);
+  }
+  group.hooks = group.hooks || [];
+
+  for (const h of group.hooks) {
+    if (h.command && h.command.includes('supply-chain-scan.sh')) {
+      return { action: 'noop', reason: 'already wired' };
+    }
+  }
+
+  group.hooks.push({ type: 'command', command: HOOK_COMMAND });
+  return { action: 'added' };
+}
+
+export function unwireHook(settings) {
+  if (!settings?.hooks?.PostToolUse) return { action: 'noop', reason: 'no PostToolUse' };
+
+  let removed = 0;
+  for (const group of settings.hooks.PostToolUse) {
+    if (!Array.isArray(group.hooks)) continue;
+    const before = group.hooks.length;
+    group.hooks = group.hooks.filter((h) => !(h.command && h.command.includes('supply-chain-scan.sh')));
+    removed += before - group.hooks.length;
+  }
+  return removed > 0 ? { action: 'removed', count: removed } : { action: 'noop', reason: 'not wired' };
+}
+
+export function installHookInProject(rootDir = process.cwd()) {
+  const p = settingsPath(rootDir);
+  if (!existsSync(p)) {
+    return { ok: false, error: 'settings.json not found — run `dw init` first', path: p };
+  }
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(p, 'utf-8'));
+  } catch (e) {
+    return { ok: false, error: `failed to parse settings.json: ${e.message}`, path: p };
+  }
+
+  const result = wireHook(settings);
+  if (result.action === 'added') {
+    writeFileSync(p, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+  }
+  return { ok: true, ...result, path: p };
+}
+
+export function uninstallHookFromProject(rootDir = process.cwd()) {
+  const p = settingsPath(rootDir);
+  if (!existsSync(p)) {
+    return { ok: false, error: 'settings.json not found', path: p };
+  }
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(p, 'utf-8'));
+  } catch (e) {
+    return { ok: false, error: `failed to parse settings.json: ${e.message}`, path: p };
+  }
+
+  const result = unwireHook(settings);
+  if (result.action === 'removed') {
+    writeFileSync(p, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+  }
+  return { ok: true, ...result, path: p };
+}