dw-kit 1.3.0 → 1.3.5

package/src/lib/cut-analysis.mjs

@@ -1,8 +1,17 @@
 // Cut Criteria Matrix — implements ADR-0001 v1.4 decision gate.
 // Consumes telemetry events, emits cut candidates with evidence.
 
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
 
+// Task doc thresholds — invalidation triggers for 3→2 file consolidation (ADR-0001)
+export const TASK_DOC_THRESHOLDS = {
+  trackingLinesWarn: 400,   // avg tracking.md lines → reopen 3→2 decision
+  extraFilesPctWarn: 30,    // % tasks with ≥3 md files → tasks re-growing structure
+};
+
 // Never-cut: skills that are the workflow's load-bearing verbs.
 export const CRITICAL_SKILLS = new Set([
   'dw:flow', 'dw:task-init', 'dw:commit', 'dw:handoff',
@@ -133,6 +142,76 @@ function evaluateHook(name, events, totalSessions) {
   return { name, type: 'hook', qualify, stats: s, reasons };
 }
 
+export function analyzeTaskDocs(rootDir = process.cwd()) {
+  const tasksDir = join(rootDir, '.dw', 'tasks');
+  if (!existsSync(tasksDir)) return null;
+
+  const entries = readdirSync(tasksDir).filter((name) => {
+    if (name === 'archive' || name === 'ACTIVE.md') return false;
+    try {
+      return statSync(join(tasksDir, name)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+
+  const tasks = [];
+  for (const name of entries) {
+    const dir = join(tasksDir, name);
+    let mdFiles;
+    try {
+      mdFiles = readdirSync(dir).filter((f) => f.endsWith('.md'));
+    } catch {
+      continue;
+    }
+    const hasSpec = mdFiles.includes('spec.md');
+    const hasTracking = mdFiles.includes('tracking.md');
+    const format = hasSpec && hasTracking ? 'v2' : mdFiles.some((f) => f.endsWith('-progress.md')) ? 'v1' : 'unknown';
+
+    let trackingLines = 0;
+    if (hasTracking) {
+      try {
+        trackingLines = readFileSync(join(dir, 'tracking.md'), 'utf8').split('\n').length;
+      } catch {
+        /* skip */
+      }
+    }
+
+    tasks.push({ name, format, mdFileCount: mdFiles.length, trackingLines });
+  }
+
+  const v2 = tasks.filter((t) => t.format === 'v2');
+  const avgTrackingLines =
+    v2.length > 0 ? Math.round(v2.reduce((s, t) => s + t.trackingLines, 0) / v2.length) : 0;
+  const maxTrackingLines = v2.length > 0 ? Math.max(...v2.map((t) => t.trackingLines)) : 0;
+  const extraFiles = tasks.filter((t) => t.mdFileCount >= 3);
+  const extraFilesPct = tasks.length > 0 ? Math.round((extraFiles.length / tasks.length) * 100) : 0;
+
+  const triggers = [];
+  if (avgTrackingLines > TASK_DOC_THRESHOLDS.trackingLinesWarn) {
+    triggers.push(
+      `avg_tracking_lines=${avgTrackingLines} > ${TASK_DOC_THRESHOLDS.trackingLinesWarn} — tracking.md phình → reopen 3→2 decision (ADR-0001)`
+    );
+  }
+  if (extraFilesPct > TASK_DOC_THRESHOLDS.extraFilesPctWarn) {
+    triggers.push(
+      `${extraFilesPct}% tasks have ≥3 md files > ${TASK_DOC_THRESHOLDS.extraFilesPctWarn}% — structure re-growing → reopen 3→2 decision (ADR-0001)`
+    );
+  }
+
+  return {
+    totalTasks: tasks.length,
+    v2Count: v2.length,
+    v1Count: tasks.filter((t) => t.format === 'v1').length,
+    avgTrackingLines,
+    maxTrackingLines,
+    extraFilesCount: extraFiles.length,
+    extraFilesPct,
+    triggers,
+    tasks,
+  };
+}
+
 export function analyze(events) {
   const totalSessions = uniqueSessions(events);
   const totalDays = coverageDays(events);

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

package/src/lib/sc-scanner.mjs

@@ -0,0 +1,272 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const LOCKFILE_NAMES = ['package-lock.json', 'npm-shrinkwrap.json'];
+
+export function findLockfile(rootDir = process.cwd()) {
+  for (const name of LOCKFILE_NAMES) {
+    const p = join(rootDir, name);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+export function parsePackageLockfile(filepath) {
+  const raw = readFileSync(filepath, 'utf-8');
+  const data = JSON.parse(raw);
+
+  const out = new Map();
+
+  if (data.packages && typeof data.packages === 'object') {
+    for (const [key, info] of Object.entries(data.packages)) {
+      if (!key || key === '') continue;
+      if (!info || !info.version) continue;
+
+      const name = info.name || key.replace(/^node_modules\//, '').replace(/.*\/node_modules\//, '');
+      if (!name) continue;
+      if (!out.has(name)) out.set(name, info.version);
+    }
+    return out;
+  }
+
+  if (data.dependencies && typeof data.dependencies === 'object') {
+    walkDeps(data.dependencies, out);
+  }
+
+  return out;
+}
+
+function walkDeps(deps, out) {
+  for (const [name, info] of Object.entries(deps)) {
+    if (info && info.version && !out.has(name)) {
+      out.set(name, info.version);
+    }
+    if (info && info.dependencies) walkDeps(info.dependencies, out);
+  }
+}
+
+export function compareVersions(a, b) {
+  const norm = (v) => String(v).split('-')[0].split('+')[0].split('.').map((s) => parseInt(s, 10) || 0);
+  const pa = norm(a);
+  const pb = norm(b);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x !== y) return x - y;
+  }
+  return 0;
+}
+
+export function versionInRange(version, range) {
+  if (!range || !range.events || !Array.isArray(range.events)) return false;
+
+  let affected = false;
+  let lastIntroduced = null;
+  let lastFixed = null;
+
+  const events = range.events.slice().sort((e1, e2) => {
+    const v1 = e1.introduced || e1.fixed || e1.last_affected || '0.0.0';
+    const v2 = e2.introduced || e2.fixed || e2.last_affected || '0.0.0';
+    return compareVersions(v1, v2);
+  });
+
+  for (const evt of events) {
+    if (evt.introduced !== undefined) lastIntroduced = evt.introduced;
+    if (evt.fixed !== undefined) lastFixed = evt.fixed;
+    if (evt.last_affected !== undefined) lastFixed = evt.last_affected;
+  }
+
+  if (lastIntroduced !== null && compareVersions(version, lastIntroduced) >= 0) {
+    affected = true;
+  }
+  if (affected && lastFixed !== null && compareVersions(version, lastFixed) >= 0) {
+    if (range.type === 'SEMVER' || range.type === 'ECOSYSTEM') affected = false;
+  }
+
+  return affected;
+}
+
+export function matchAdvisory(packageName, version, advisory) {
+  if (!advisory || !advisory.affected) return null;
+
+  for (const aff of advisory.affected) {
+    const affName = aff.package?.name || aff.package_name || aff.name;
+    if (affName !== packageName) continue;
+
+    if (Array.isArray(aff.versions) && aff.versions.includes(version)) {
+      return buildMatch(packageName, version, advisory, aff);
+    }
+
+    if (Array.isArray(aff.ranges)) {
+      for (const range of aff.ranges) {
+        if (versionInRange(version, range)) {
+          return buildMatch(packageName, version, advisory, aff);
+        }
+      }
+    }
+  }
+  return null;
+}
+
+function buildMatch(packageName, version, advisory, aff) {
+  const fixVersions = [];
+  if (Array.isArray(aff.ranges)) {
+    for (const range of aff.ranges) {
+      if (Array.isArray(range.events)) {
+        for (const evt of range.events) {
+          if (evt.fixed) fixVersions.push(evt.fixed);
+        }
+      }
+    }
+  }
+
+  const severity = pickSeverity(advisory);
+
+  return {
+    package: packageName,
+    version,
+    advisory_id: advisory.id,
+    summary: advisory.summary || '',
+    severity,
+    fix_versions: fixVersions,
+    references: (advisory.references || []).map((r) => r.url || r).filter(Boolean),
+  };
+}
+
+function pickSeverity(advisory) {
+  if (Array.isArray(advisory.severity) && advisory.severity.length > 0) {
+    const cvss = advisory.severity.find((s) => s.type && s.type.startsWith('CVSS'));
+    if (cvss && cvss.score) return cvssToLabel(cvss.score);
+  }
+  if (advisory.database_specific?.severity) return String(advisory.database_specific.severity).toLowerCase();
+  return 'unknown';
+}
+
+function cvssToLabel(score) {
+  if (typeof score === 'string') {
+    const m = score.match(/\d+(\.\d+)?/);
+    if (m) score = parseFloat(m[0]);
+  }
+  if (typeof score !== 'number') return 'unknown';
+  if (score >= 9.0) return 'critical';
+  if (score >= 7.0) return 'high';
+  if (score >= 4.0) return 'medium';
+  if (score > 0) return 'low';
+  return 'unknown';
+}
+
+export function scanProject(rootDir, snapshot) {
+  const result = {
+    lockfile: null,
+    packages_scanned: 0,
+    matches: [],
+    snapshot_meta: snapshot ? { fetched_at: snapshot.fetched_at, source: snapshot.source } : null,
+  };
+
+  const lockPath = findLockfile(rootDir);
+  if (!lockPath) {
+    result.error = 'no_lockfile';
+    return result;
+  }
+  result.lockfile = lockPath;
+
+  if (!snapshot || !Array.isArray(snapshot.advisories)) {
+    result.error = 'no_snapshot';
+    return result;
+  }
+
+  const packages = parsePackageLockfile(lockPath);
+  result.packages_scanned = packages.size;
+
+  for (const [name, version] of packages) {
+    for (const adv of snapshot.advisories) {
+      const m = matchAdvisory(name, version, adv);
+      if (m) result.matches.push(m);
+    }
+  }
+
+  return result;
+}
+
+export function severityRank(label) {
+  return { critical: 4, high: 3, medium: 2, low: 1, unknown: 0 }[label] || 0;
+}
+
+export function worstSeverity(matches) {
+  if (!matches || matches.length === 0) return null;
+  return matches.reduce((acc, m) => (severityRank(m.severity) > severityRank(acc) ? m.severity : acc), 'unknown');
+}
+
+// ── Pre-install scan helpers (package.json without lockfile) ────────────────
+
+export function parsePackageJson(filepath) {
+  const raw = readFileSync(filepath, 'utf-8');
+  const data = JSON.parse(raw);
+  const out = new Map();
+  for (const section of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+    if (data[section] && typeof data[section] === 'object') {
+      for (const [name, range] of Object.entries(data[section])) {
+        if (typeof range === 'string' && !out.has(name)) out.set(name, range);
+      }
+    }
+  }
+  return out;
+}
+
+export function findPackageJson(rootDir = process.cwd()) {
+  const p = join(rootDir, 'package.json');
+  return existsSync(p) ? p : null;
+}
+
+export function matchPackageByName(packageName, advisories) {
+  const hits = [];
+  for (const adv of advisories || []) {
+    if (!adv.affected) continue;
+    for (const aff of adv.affected) {
+      const affName = aff.package?.name || aff.package_name || aff.name;
+      if (affName !== packageName) continue;
+
+      const fixVersions = [];
+      if (Array.isArray(aff.ranges)) {
+        for (const range of aff.ranges) {
+          if (Array.isArray(range.events)) {
+            for (const evt of range.events) if (evt.fixed) fixVersions.push(evt.fixed);
+          }
+        }
+      }
+      hits.push({
+        advisory_id: adv.id,
+        summary: adv.summary || '',
+        severity: pickSeverity(adv),
+        fix_versions: fixVersions,
+        references: (adv.references || []).map((r) => r.url || r).filter(Boolean),
+      });
+      break;
+    }
+  }
+  return hits;
+}
+
+export function matchNamespaceFixture(packages, fixture) {
+  const now = new Date();
+  const hits = [];
+  for (const entry of fixture?.namespaces || []) {
+    if (entry.active_until && new Date(entry.active_until) < now) continue;
+    if (!entry.pattern) continue;
+
+    for (const [name] of packages) {
+      if (name.startsWith(entry.pattern) || name === entry.pattern) {
+        hits.push({
+          package: name,
+          namespace_pattern: entry.pattern,
+          reason: entry.reason,
+          advisory_url: entry.advisory,
+          active_until: entry.active_until,
+          guidance: entry.guidance,
+          severity: entry.severity || 'high',
+        });
+      }
+    }
+  }
+  return hits;
+}