dw-kit 1.3.4 → 1.3.6

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,90 @@
+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);
+    // Collapse multiple consecutive blanks AND normalize trailing whitespace
+    // so re-running the helper is byte-identical (required by smoke idempotency test).
+    return (before + block + after)
+      .replace(/\n{3,}/g, '\n\n')
+      .replace(/\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/npm-registry.mjs

@@ -0,0 +1,159 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+const REGISTRY_BASE = 'https://registry.npmjs.org';
+const FETCH_TIMEOUT_MS = 5000;
+const CACHE_REL = '.dw/security/npm-registry-cache.jsonl';
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour per ADR-0006
+
+export function cachePath(rootDir = process.cwd()) {
+  return join(rootDir, CACHE_REL);
+}
+
+function ensureCacheDir(rootDir) {
+  const dir = dirname(cachePath(rootDir));
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+export function loadCache(rootDir = process.cwd()) {
+  const p = cachePath(rootDir);
+  if (!existsSync(p)) return new Map();
+  const map = new Map();
+  try {
+    const lines = readFileSync(p, 'utf-8').split('\n').filter(Boolean);
+    for (const line of lines) {
+      try {
+        const e = JSON.parse(line);
+        if (e && e.key) map.set(e.key, e);
+      } catch {
+        // skip malformed line
+      }
+    }
+  } catch {
+    // unreadable cache → ignore
+  }
+  return map;
+}
+
+export function cacheGet(rootDir, key, ttlMs = CACHE_TTL_MS) {
+  const map = loadCache(rootDir);
+  const entry = map.get(key);
+  if (!entry) return null;
+  if (ttlMs <= 0) return null;
+  if (Date.now() - entry.cached_at > ttlMs) return null;
+  return entry.value;
+}
+
+export function cachePut(rootDir, key, value) {
+  ensureCacheDir(rootDir);
+  const line = JSON.stringify({ key, cached_at: Date.now(), value }) + '\n';
+  appendFileSync(cachePath(rootDir), line, 'utf-8');
+}
+
+export function pruneCache(rootDir, ttlMs = CACHE_TTL_MS) {
+  const p = cachePath(rootDir);
+  if (!existsSync(p)) return;
+  const map = loadCache(rootDir);
+  const now = Date.now();
+  const fresh = [];
+  for (const e of map.values()) {
+    if (now - e.cached_at <= ttlMs) fresh.push(e);
+  }
+  ensureCacheDir(rootDir);
+  writeFileSync(p, fresh.map((e) => JSON.stringify(e)).join('\n') + (fresh.length ? '\n' : ''), 'utf-8');
+}
+
+async function fetchJson(url, { timeoutMs = FETCH_TIMEOUT_MS } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      headers: { accept: 'application/json' },
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      const err = new Error(`npm registry HTTP ${res.status}`);
+      err.status = res.status;
+      throw err;
+    }
+    return await res.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Fetch the full registry document for a package. Cached.
+ * Returns the raw npm registry response or null on hard failure.
+ */
+export async function fetchPackageMetadata(packageName, rootDir = process.cwd(), { useCache = true } = {}) {
+  const key = `pkg:${packageName}`;
+  if (useCache) {
+    const cached = cacheGet(rootDir, key);
+    if (cached) return cached;
+  }
+  try {
+    const data = await fetchJson(`${REGISTRY_BASE}/${encodeURIComponent(packageName).replace('%40', '@')}`);
+    cachePut(rootDir, key, data);
+    return data;
+  } catch (e) {
+    if (e.status === 404) return null;
+    throw e;
+  }
+}
+
+/**
+ * Extract the signals needed by the heuristic scorer (ADR-0006 pillar 3).
+ * Pure function — call after fetchPackageMetadata returned a document.
+ */
+export function extractSignals(metadata, version) {
+  if (!metadata) return null;
+  const timeMap = metadata.time || {};
+  const publishIso = timeMap[version] || null;
+  const publishedAt = publishIso ? new Date(publishIso).getTime() : null;
+  const ageHours = publishedAt ? (Date.now() - publishedAt) / (1000 * 60 * 60) : null;
+
+  // Last modified time on the package as a whole — proxy for maintainer activity
+  const modifiedIso = timeMap.modified || null;
+  const modifiedAt = modifiedIso ? new Date(modifiedIso).getTime() : null;
+
+  // Maintainer set
+  const maintainers = Array.isArray(metadata.maintainers)
+    ? metadata.maintainers.map((m) => (typeof m === 'string' ? m : m.name)).filter(Boolean)
+    : [];
+
+  // Latest version on dist-tags
+  const latestVersion = metadata['dist-tags']?.latest || null;
+
+  return {
+    package: metadata.name,
+    version,
+    publish_iso: publishIso,
+    publish_age_hours: ageHours,
+    latest_version: latestVersion,
+    modified_iso: modifiedIso,
+    package_modified_age_days: modifiedAt ? (Date.now() - modifiedAt) / (1000 * 60 * 60 * 24) : null,
+    maintainer_count: maintainers.length,
+    maintainers,
+  };
+}
+
+/**
+ * Lightweight popularity probe via downloads API. Cached separately.
+ * Returns weekly downloads count or null on failure.
+ */
+export async function fetchWeeklyDownloads(packageName, rootDir = process.cwd(), { useCache = true } = {}) {
+  const key = `dl:${packageName}`;
+  if (useCache) {
+    const cached = cacheGet(rootDir, key);
+    if (cached) return cached;
+  }
+  try {
+    const data = await fetchJson(`https://api.npmjs.org/downloads/point/last-week/${encodeURIComponent(packageName).replace('%40', '@')}`);
+    const count = typeof data?.downloads === 'number' ? data.downloads : null;
+    cachePut(rootDir, key, count);
+    return count;
+  } catch {
+    return null;
+  }
+}

package/src/lib/sc-heuristic.mjs

@@ -0,0 +1,263 @@
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parsePackageLockfile, findLockfile, compareVersions } from './sc-scanner.mjs';
+
+const DEFAULT_THRESHOLD = 50;
+const DEFAULT_WEEKLY_DOWNLOADS_MIN = 10000;
+const DEFAULT_RECENT_PUBLISH_HOURS = 72;
+
+// Top-500 popular npm packages (small bundled list for typo-squat detection).
+// Source: npm download counts, December 2025 snapshot. Pruned to common surface.
+// Not exhaustive — typo-squat is one signal of many.
+const POPULAR_PACKAGES = new Set([
+  'react', 'react-dom', 'vue', 'angular', 'svelte', 'next', 'nuxt',
+  'lodash', 'axios', 'express', 'fastify', 'koa', 'hapi',
+  'typescript', 'eslint', 'prettier', 'webpack', 'vite', 'rollup', 'esbuild',
+  'jest', 'mocha', 'vitest', 'playwright', 'cypress', 'puppeteer',
+  'chalk', 'commander', 'yargs', 'inquirer', 'enquirer',
+  'tailwindcss', 'postcss', 'sass', 'less',
+  'tanstack', '@tanstack/react-query', '@tanstack/react-router', '@tanstack/react-table',
+  'redux', '@reduxjs/toolkit', 'zustand', 'jotai', 'recoil',
+  'graphql', 'apollo-client', '@apollo/client', 'urql',
+  'rxjs', 'immer', 'lodash-es', 'date-fns', 'moment', 'dayjs', 'luxon',
+  'cors', 'helmet', 'jsonwebtoken', 'bcrypt', 'argon2',
+  'mongoose', 'prisma', '@prisma/client', 'sequelize', 'typeorm', 'knex',
+  'pg', 'mysql', 'mysql2', 'sqlite3', 'better-sqlite3',
+  'redis', 'ioredis',
+  'dotenv', 'uuid', 'nanoid', 'pino', 'winston', 'debug',
+  'zod', 'yup', 'joi', 'ajv',
+  'sharp', 'jimp', 'multer',
+  'socket.io', 'ws', 'engine.io',
+  'pm2', 'nodemon', 'concurrently', 'cross-env',
+  'firebase', 'firebase-admin', '@supabase/supabase-js',
+  'stripe', '@stripe/stripe-js',
+]);
+
+export function loadHeuristicConfig(rootDir = process.cwd()) {
+  // Read .dw/config/dw.config.yml security.heuristic.* if present.
+  // Cheap inline YAML probe — no js-yaml dep here. Caller may pass overrides.
+  try {
+    const cfgPath = join(rootDir, '.dw/config/dw.config.yml');
+    if (!existsSync(cfgPath)) return defaultConfig();
+    const raw = readFileSync(cfgPath, 'utf-8');
+    const threshold = matchYamlNumber(raw, 'risk_threshold');
+    const weekly = matchYamlNumber(raw, 'weekly_downloads_min');
+    const recent = matchYamlNumber(raw, 'recent_publish_hours');
+    return {
+      risk_threshold: threshold ?? DEFAULT_THRESHOLD,
+      weekly_downloads_min: weekly ?? DEFAULT_WEEKLY_DOWNLOADS_MIN,
+      recent_publish_hours: recent ?? DEFAULT_RECENT_PUBLISH_HOURS,
+    };
+  } catch {
+    return defaultConfig();
+  }
+}
+
+function defaultConfig() {
+  return {
+    risk_threshold: DEFAULT_THRESHOLD,
+    weekly_downloads_min: DEFAULT_WEEKLY_DOWNLOADS_MIN,
+    recent_publish_hours: DEFAULT_RECENT_PUBLISH_HOURS,
+  };
+}
+
+function matchYamlNumber(yamlText, key) {
+  // Scoped inside security.heuristic.*
+  // Avoid full YAML parser dep; brittle but enough for top-level integer keys.
+  const re = new RegExp(`heuristic:[\\s\\S]*?\\b${key}\\s*:\\s*(\\d+)`, 'm');
+  const m = yamlText.match(re);
+  return m ? parseInt(m[1], 10) : null;
+}
+
+/**
+ * List packages introduced or version-bumped since the last committed lockfile.
+ *
+ * Strategy:
+ *   1. If git available and HEAD has a previous lockfile → diff against HEAD
+ *   2. Otherwise → return ALL packages in current lockfile (cold-start path,
+ *      caller can cap how many to actually probe)
+ *
+ * Returns Array<{ name, version, change: 'added' | 'bumped', from?: string }>.
+ */
+export function diffLockfilePackages(rootDir = process.cwd()) {
+  const lockPath = findLockfile(rootDir);
+  if (!lockPath) return [];
+  const currentPkgs = parsePackageLockfile(lockPath);
+
+  let previousPkgs = null;
+  try {
+    // Best-effort: read previous lockfile content from git HEAD
+    const lockRelPath = lockPath.startsWith(rootDir + '\\') || lockPath.startsWith(rootDir + '/')
+      ? lockPath.slice(rootDir.length + 1).replace(/\\/g, '/')
+      : 'package-lock.json';
+    const previousContent = execSync(`git show HEAD:${lockRelPath}`, {
+      cwd: rootDir,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    previousPkgs = parsePackageLockfileContent(previousContent);
+  } catch {
+    // No git, or HEAD has no lockfile → cold start
+    previousPkgs = null;
+  }
+
+  const out = [];
+  if (!previousPkgs) {
+    // Cold start: caller decides how to handle a full lockfile
+    for (const [name, version] of currentPkgs) {
+      out.push({ name, version, change: 'cold-start' });
+    }
+    return out;
+  }
+
+  for (const [name, version] of currentPkgs) {
+    if (!previousPkgs.has(name)) {
+      out.push({ name, version, change: 'added' });
+    } else {
+      const prev = previousPkgs.get(name);
+      if (prev !== version) {
+        out.push({ name, version, change: 'bumped', from: prev });
+      }
+    }
+  }
+  return out;
+}
+
+function parsePackageLockfileContent(content) {
+  const lock = JSON.parse(content);
+  const packages = new Map();
+  if (lock.packages) {
+    for (const [k, v] of Object.entries(lock.packages)) {
+      if (!k || !v?.version) continue;
+      const name = k.startsWith('node_modules/') ? k.slice('node_modules/'.length) : k.split('node_modules/').pop();
+      if (!name || name === '') continue;
+      packages.set(name, v.version);
+    }
+  } else if (lock.dependencies) {
+    function walk(deps) {
+      for (const [n, v] of Object.entries(deps)) {
+        if (v?.version) packages.set(n, v.version);
+        if (v?.dependencies) walk(v.dependencies);
+      }
+    }
+    walk(lock.dependencies);
+  }
+  return packages;
+}
+
+/**
+ * Score one package's signals into a risk number + reason breakdown.
+ *
+ * Returns { score, reasons: [{signal, weight, detail}], blocking: bool }
+ *
+ * Signals (per ADR-0006):
+ *   - very_recent_publish (<24h)        +50
+ *   - recent_publish (<72h)             +30
+ *   - popular_package (downloads≥10k)   +20
+ *   - maintainer_change_recent (<30d)   +40
+ *   - major_version_jump                +15
+ *   - typo_squat (Lev=1 of popular)     +60
+ */
+export function scoreSignals(signals, weeklyDownloads, config = defaultConfig(), context = {}) {
+  if (!signals) return { score: 0, reasons: [] };
+  const reasons = [];
+  let score = 0;
+
+  const age = signals.publish_age_hours;
+  if (age !== null && age !== undefined) {
+    if (age < 24) {
+      score += 50;
+      reasons.push({ signal: 'very_recent_publish', weight: 50, detail: `${age.toFixed(1)}h since publish` });
+    } else if (age < config.recent_publish_hours) {
+      score += 30;
+      reasons.push({ signal: 'recent_publish', weight: 30, detail: `${age.toFixed(1)}h since publish (threshold ${config.recent_publish_hours}h)` });
+    }
+  }
+
+  if (typeof weeklyDownloads === 'number' && weeklyDownloads >= config.weekly_downloads_min) {
+    score += 20;
+    reasons.push({ signal: 'popular_package', weight: 20, detail: `${weeklyDownloads.toLocaleString()} weekly downloads` });
+  }
+
+  // Maintainer-change proxy: package-level "modified" time within 30d
+  if (signals.package_modified_age_days !== null && signals.package_modified_age_days !== undefined) {
+    if (signals.package_modified_age_days < 30) {
+      score += 40;
+      reasons.push({
+        signal: 'maintainer_change_recent',
+        weight: 40,
+        detail: `package modified ${signals.package_modified_age_days.toFixed(1)}d ago — possible maintainer/token change`,
+      });
+    }
+  }
+
+  // Major-version-jump (caller passes context.from from diff)
+  if (context.change === 'bumped' && context.from && signals.version) {
+    try {
+      const fromMajor = parseInt(context.from.match(/\d+/)?.[0] || '0', 10);
+      const toMajor = parseInt(signals.version.match(/\d+/)?.[0] || '0', 10);
+      if (toMajor - fromMajor >= 1) {
+        score += 15;
+        reasons.push({
+          signal: 'major_version_jump',
+          weight: 15,
+          detail: `bumped from ${context.from} to ${signals.version}`,
+        });
+      }
+    } catch {
+      // skip
+    }
+  }
+
+  // Typo-squat detection (offline, bundled popular list)
+  const ts = detectTypoSquat(signals.package);
+  if (ts) {
+    score += 60;
+    reasons.push({ signal: 'typo_squat', weight: 60, detail: `name within Lev=1 of popular "${ts}"` });
+  }
+
+  return { score, reasons };
+}
+
+function detectTypoSquat(name) {
+  if (!name) return null;
+  if (POPULAR_PACKAGES.has(name)) return null;
+  // Strip scope for comparison; typo-squats often target unscoped popular names
+  const bare = name.includes('/') ? name.split('/').pop() : name;
+  for (const pop of POPULAR_PACKAGES) {
+    const popBare = pop.includes('/') ? pop.split('/').pop() : pop;
+    if (Math.abs(bare.length - popBare.length) > 2) continue;
+    if (levenshtein(bare, popBare) === 1) return pop;
+  }
+  return null;
+}
+
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (!a.length) return b.length;
+  if (!b.length) return a.length;
+  const prev = new Array(b.length + 1);
+  const curr = new Array(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    for (let j = 0; j <= b.length; j++) prev[j] = curr[j];
+  }
+  return prev[b.length];
+}
+
+export function formatHeuristicHit(pkg, version, change, scoring) {
+  const lines = [];
+  const tag = scoring.score >= 80 ? '[HIGH-RISK]' : scoring.score >= 50 ? '[REVIEW]' : '[INFO]';
+  const changeLabel = change === 'bumped' ? `bumped to ${version}` : change === 'added' ? `added@${version}` : `${version}`;
+  lines.push(`${tag} ${pkg} ${changeLabel} — risk_score: ${scoring.score}`);
+  for (const r of scoring.reasons) {
+    lines.push(`  · ${r.signal} (+${r.weight}): ${r.detail}`);
+  }
+  return lines.join('\n');
+}

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 };
+}