wizz-method 2.0.0 → 2.1.1

package/tools/installer/core/hash-cache.js

@@ -0,0 +1,156 @@
+/**
+ * Persistent hash cache (audit item 23, 2026-09-11; hardened 2026-09-11
+ * fase 3 review — bug 13 + the item 23 gaps: version field, ctime in the
+ * key, and actual pruning).
+ *
+ * The files-manifest.csv hashing pass is I/O-bound: every installed file is
+ * read and SHA256-hashed on every install/update, even though almost all of
+ * them are unchanged between runs. The in-process memo in fs-native.js
+ * (path:size:mtimeMs) only helps within one run; this module persists the
+ * mapping across runs so the next update hashes only the delta.
+ *
+ * Format: `_wizz/_config/hash-cache.json` is
+ * `{ "_v": 1, "algo": "sha256", "files": { relPath: { size, mtimeMs, ctimeMs, hash } } }`.
+ * A hit requires size AND mtimeMs AND ctimeMs to all match the current
+ * stat — ctime can't be set by a user-level copy (only the kernel bumps it,
+ * on a metadata or content change), so a `cp -p` or `rsync --times` that
+ * preserves mtime alone still forces a miss, because writing to a new
+ * inode necessarily bumps ctime. size+mtime alone would have missed
+ * exactly that case (a file copied over the installed one, same mtime,
+ * different content).
+ *
+ * Any mismatch on `_v` or `algo`, or a malformed/non-object JSON payload,
+ * is treated as a cold start (empty cache) — never a hard error. This also
+ * covers a future format change: bumping `_v` invalidates every existing
+ * cache file instead of trying to read the old shape.
+ *
+ * Known limitation: two edits to the same file within the same filesystem
+ * timestamp granularity (1s on some filesystems/platforms) that happen to
+ * land on the same size can still collide (same size+mtimeMs+ctimeMs,
+ * different content) and be reported as unchanged — this is the same trust
+ * level files-manifest.csv already accepts elsewhere (mtime as a proxy for
+ * content). `wizz doctor` rehashes every file without consulting this
+ * cache, so it remains the way to force a full, cache-free verification.
+ *
+ * Fail-open by design: a missing, corrupt, or stale (wrong `_v`/`algo`)
+ * cache is a cache miss, never an error — the file just gets hashed the
+ * old way. User-modified files are the caller's concern: the cache stores
+ * what the file looked like at last install, so a drifted file's NEW stat
+ * mismatches the cache and forces a fresh hash (its cached entry is then
+ * refreshed by the writer, which is correct — the manifest must record the
+ * current hash).
+ */
+const path = require('node:path');
+const fs = require('../fs-native');
+
+const CACHE_FILE = 'hash-cache.json';
+const CACHE_VERSION = 1;
+const CACHE_ALGO = 'sha256';
+
+/**
+ * Load the previous run's cache. Returns an empty Map on any failure
+ * (missing file, corrupt JSON, wrong shape, version/algo mismatch) —
+ * fail-open.
+ * @param {string} cfgDir - _wizz/_config directory
+ * @returns {Promise<Map<string, {size: number, mtimeMs: number, ctimeMs: number, hash: string}>>}
+ */
+async function loadHashCache(cfgDir) {
+  const map = new Map();
+  try {
+    const raw = await fs.readFile(path.join(cfgDir, CACHE_FILE), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (
+      parsed &&
+      typeof parsed === 'object' &&
+      parsed._v === CACHE_VERSION &&
+      parsed.algo === CACHE_ALGO &&
+      parsed.files &&
+      typeof parsed.files === 'object'
+    ) {
+      for (const [relPath, entry] of Object.entries(parsed.files)) {
+        if (
+          entry &&
+          typeof entry === 'object' &&
+          typeof entry.size === 'number' &&
+          typeof entry.mtimeMs === 'number' &&
+          typeof entry.ctimeMs === 'number' &&
+          typeof entry.hash === 'string'
+        ) {
+          map.set(relPath, entry);
+        }
+      }
+    }
+  } catch {
+    // Missing, corrupt, or wrong-version cache = cold start. Never fatal.
+  }
+  return map;
+}
+
+/**
+ * Look up a file's cached hash. Only hits when size AND mtimeMs AND
+ * ctimeMs all match the current stat — a partial match must be treated as
+ * a miss because any of the three could be the only signal that content
+ * changed (see the ctime rationale in the module header).
+ * @param {Map} cache - From loadHashCache
+ * @param {string} relPath - Path relative to _wizz/ (same key space as the CSV)
+ * @param {{size: number, mtimeMs: number, ctimeMs: number}} stat - Current file stat
+ * @returns {string|null} Cached hash, or null on miss
+ */
+function getCachedHash(cache, relPath, stat) {
+  const entry = cache.get(relPath);
+  if (!entry) return null;
+  if (entry.size !== stat.size || entry.mtimeMs !== stat.mtimeMs || entry.ctimeMs !== stat.ctimeMs) return null;
+  return entry.hash;
+}
+
+/**
+ * Build the cache to persist from the files just hashed, pruned to the
+ * files actually present in the manifest just written: a relPath that
+ * isn't in `currentPaths` (removed module, renamed/deleted file) is
+ * dropped, so the cache can't grow forever with entries for files that no
+ * longer exist.
+ * @param {Map} previousCache - Cache from the previous run (source for
+ *   files that weren't re-hashed this run but are still installed)
+ * @param {Array<{relPath: string, size: number, mtimeMs: number, ctimeMs: number, hash: string}>} hashed - This run's fresh entries (cache misses)
+ * @param {Iterable<string>} currentPaths - Every relPath written to files-manifest.csv this run
+ * @returns {Object} Plain object ready for JSON.stringify
+ */
+function buildHashCache(previousCache, hashed, currentPaths) {
+  const files = {};
+  const freshByPath = new Map(hashed.map((h) => [h.relPath, h]));
+  for (const relPath of currentPaths) {
+    const fresh = freshByPath.get(relPath);
+    if (fresh) {
+      files[relPath] = { size: fresh.size, mtimeMs: fresh.mtimeMs, ctimeMs: fresh.ctimeMs, hash: fresh.hash };
+      continue;
+    }
+    const prev = previousCache.get(relPath);
+    if (prev) files[relPath] = prev;
+  }
+  return { _v: CACHE_VERSION, algo: CACHE_ALGO, files };
+}
+
+/**
+ * Persist the cache atomically next to the files-manifest.csv. Best-effort:
+ * a failed write means the next run is a cold start, never an install error.
+ * @param {string} cfgDir - _wizz/_config directory
+ * @param {Object} data - From buildHashCache
+ * @returns {Promise<void>}
+ */
+async function saveHashCache(cfgDir, data) {
+  try {
+    await fs.writeFile(path.join(cfgDir, CACHE_FILE), JSON.stringify(data) + '\n', 'utf8');
+  } catch {
+    // Best-effort: cache loss is a perf regression, not a correctness one.
+  }
+}
+
+module.exports = {
+  loadHashCache,
+  getCachedHash,
+  buildHashCache,
+  saveHashCache,
+  CACHE_FILE,
+  CACHE_VERSION,
+  CACHE_ALGO,
+};

package/tools/installer/core/help-catalog.js

@@ -78,7 +78,10 @@ async function mergeModuleHelpCatalogs(wizzDir, _agentEntries = [], { trackFile
 
   // Get all installed module directories
   const entries = await fs.readdir(wizzDir, { withFileTypes: true });
-  const nonModuleDirs = new Set(['_config', '_memory', 'memory', 'docs', 'scripts', 'custom']);
+  // 'hooks' (RT-C1, tools/hooks/* copied here by Installer#_installHooks) is
+  // infra, not a module — keep it out of the module scan (same reasoning as
+  // module-config-writer.js's identical exclusion set).
+  const nonModuleDirs = new Set(['_config', '_memory', 'memory', 'docs', 'scripts', 'custom', 'hooks']);
   const installedModules = entries.filter((entry) => entry.isDirectory() && !nonModuleDirs.has(entry.name)).map((entry) => entry.name);
 
   // Add core module to scan (it's installed at root level as _config, but we check src/core-skills)

package/tools/installer/core/hooks-settings.js

@@ -0,0 +1,178 @@
+// hooks-settings.js — merge PURO dos hooks do Wizz Method em `.claude/settings.json`
+// de um projeto alvo. Sem I/O de disco aqui de propósito: o installer lê/escreve o
+// arquivo (core/installer.js), este módulo só computa o objeto resultante — o que o
+// torna testável sem tocar disco (RT-C1, auditoria 2026-09-11).
+//
+// Contrato do merge:
+//   - NÃO destrutivo: toda chave existente do settings.json (permissions, env,
+//     model, hooks de outros eventos/matchers) é preservada.
+//   - Idempotente: rodar 2x com os mesmos hookEntries não duplica nada
+//     (comparação pelo `command` completo).
+//   - Update seguro: uma entrada ANTIGA nossa no mesmo evento/matcher
+//     (reconhecida pelo path `_wizz/hooks/` + basename do hook) é substituída
+//     pela nova, sem mexer em hooks de terceiros que dividem o mesmo evento.
+//
+// filterHooksRegisteredGlobally (decisão do dono, 2026-09-11): quando um hook
+// nosso já está registrado no settings.json GLOBAL do usuário (~/.claude/),
+// o installer pula o registro no projeto para não rodar o mesmo hook 2x.
+
+const HOOKS_DIR = '_wizz/hooks';
+
+// Definição canônica dos hooks e onde cada um se registra em settings.json.
+// event/matcher/timeout replicam 1:1 o que tools/hooks/README.md documenta e
+// o que já roda hoje na máquina do mantenedor (npm run sync:global + registro
+// manual em ~/.claude/settings.json) — nenhum formato novo foi inventado.
+const HOOK_DEFS = [
+  { id: 'session-rules.js', event: 'SessionStart', kind: 'node' },
+  { id: 'wizz-router-enforce.js', event: 'UserPromptSubmit', kind: 'node' },
+  { id: 'security-defensive-context.js', event: 'PreToolUse', matcher: 'Skill', kind: 'node' },
+  // rtk é opcional (item 4 da decisão RT-C1): só entra em hookEntries quando
+  // `rtkOnPath` é true — ver buildHookEntries abaixo.
+  { id: 'rtk-rewrite.sh', event: 'PreToolUse', matcher: 'Bash', kind: 'shell', requires: 'rtk' },
+  { id: 'wizz-decision-trace.js', event: 'Stop', kind: 'node' },
+];
+
+const DEFAULT_TIMEOUT = 5;
+
+function commandFor(def) {
+  const target = `$CLAUDE_PROJECT_DIR/${HOOKS_DIR}/${def.id}`;
+  return def.kind === 'shell' ? `"${target}"` : `node "${target}"`;
+}
+
+/**
+ * Monta as entradas de hook a registrar em settings.json, a partir dos
+ * arquivos de fato copiados para `_wizz/hooks/`. Filtra `rtk-rewrite.sh`
+ * quando `rtkOnPath` é false — rtk é opcional (item 4, RT-C1).
+ * @param {string[]} installedHookFiles - basenames copiados para _wizz/hooks/
+ * @param {{rtkOnPath?: boolean}} [options]
+ * @returns {Array<{event: string, matcher?: string, id: string, command: string, timeout: number}>}
+ */
+function buildHookEntries(installedHookFiles, { rtkOnPath = false } = {}) {
+  const installed = new Set(installedHookFiles || []);
+  return HOOK_DEFS.filter((def) => installed.has(def.id) && (def.requires !== 'rtk' || rtkOnPath)).map((def) => ({
+    event: def.event,
+    matcher: def.matcher,
+    id: def.id,
+    command: commandFor(def),
+    timeout: DEFAULT_TIMEOUT,
+  }));
+}
+
+/**
+ * Remove de `hookEntries` toda entrada cujo hook (basename, ex.
+ * "rtk-rewrite.sh") já esteja registrado no MESMO evento do settings.json
+ * GLOBAL do usuário (`~/.claude/settings.json`) — decisão do dono
+ * (2026-09-11): evita rodar o mesmo hook 2x (global + projeto) numa máquina
+ * onde o mantenedor já registrou os hooks do Wizz globalmente. Compara pelo
+ * basename dentro do `command` (qualquer matcher no evento conta — um hook
+ * global sem matcher já cobre o Bash inteiro, por exemplo), não por igualdade
+ * exata do comando, porque o path do comando global (`~/.claude/hooks/...`)
+ * nunca é igual ao path do comando do projeto (`_wizz/hooks/...`).
+ * @param {Array<{event: string, matcher?: string, id: string, command: string, timeout?: number}>} hookEntries
+ * @param {object} globalSettings - conteúdo de ~/.claude/settings.json (ou {}/null/undefined)
+ * @returns {{entries: Array, skipped: string[]}}
+ */
+function filterHooksRegisteredGlobally(hookEntries, globalSettings) {
+  const entries = hookEntries || [];
+  const globalHooks = globalSettings && typeof globalSettings === 'object' ? globalSettings.hooks : null;
+  if (!globalHooks || typeof globalHooks !== 'object') {
+    return { entries: [...entries], skipped: [] };
+  }
+
+  const isRegisteredGlobally = (event, id) => {
+    const blocks = Array.isArray(globalHooks[event]) ? globalHooks[event] : [];
+    return blocks.some(
+      (block) => Array.isArray(block.hooks) && block.hooks.some((h) => h && typeof h.command === 'string' && h.command.includes(id)),
+    );
+  };
+
+  const skipped = [];
+  const kept = entries.filter((entry) => {
+    if (isRegisteredGlobally(entry.event, entry.id)) {
+      skipped.push(entry.id);
+      return false;
+    }
+    return true;
+  });
+
+  return { entries: kept, skipped };
+}
+
+function cloneJson(value) {
+  if (value === undefined || value === null) return {};
+  return structuredClone(value);
+}
+
+/**
+ * Um comando é "nosso" quando referencia `_wizz/hooks/<id>` — usado tanto
+ * para reconhecer uma entrada antiga a substituir (update) quanto para nunca
+ * confundir com um hook de terceiro que por acaso caia no mesmo evento.
+ * @param {string} command
+ * @param {string} id - basename do hook (ex.: "session-rules.js")
+ * @returns {boolean}
+ */
+function isOurHookCommand(command, id) {
+  return typeof command === 'string' && command.includes(`${HOOKS_DIR}/`) && command.includes(id);
+}
+
+/**
+ * Merge não destrutivo e idempotente de `hookEntries` num `settings.json` já
+ * existente (ou {} quando o projeto ainda não tem um). Função pura — nenhuma
+ * leitura/escrita de arquivo acontece aqui.
+ * @param {object} existingSettings - conteúdo atual de .claude/settings.json (ou {})
+ * @param {Array<{event: string, matcher?: string, id: string, command: string, timeout?: number}>} hookEntries
+ * @returns {object} newSettings
+ */
+function mergeHooksIntoSettings(existingSettings, hookEntries) {
+  const settings = cloneJson(existingSettings);
+  const hooks = cloneJson(settings.hooks);
+
+  for (const entry of hookEntries || []) {
+    const { event, matcher, id, command, timeout } = entry;
+    const blocks = Array.isArray(hooks[event]) ? hooks[event] : [];
+    const sameMatcher = (block) => (matcher ? block.matcher === matcher : block.matcher === undefined);
+
+    // 1) Já presente, idêntico — nada a fazer (idempotência).
+    const alreadyPresent = blocks.some(
+      (block) => sameMatcher(block) && Array.isArray(block.hooks) && block.hooks.some((h) => h && h.command === command),
+    );
+    if (alreadyPresent) {
+      hooks[event] = blocks;
+      continue;
+    }
+
+    // 2) Versão antiga NOSSA no mesmo evento/matcher — substitui em vez de duplicar.
+    const staleIndex = blocks.findIndex(
+      (block) => sameMatcher(block) && Array.isArray(block.hooks) && block.hooks.some((h) => isOurHookCommand(h && h.command, id)),
+    );
+
+    if (staleIndex !== -1) {
+      const staleBlock = blocks[staleIndex];
+      const newBlocks = [...blocks];
+      newBlocks[staleIndex] = {
+        ...staleBlock,
+        hooks: staleBlock.hooks.map((h) => (isOurHookCommand(h && h.command, id) ? { type: 'command', command, timeout } : h)),
+      };
+      hooks[event] = newBlocks;
+      continue;
+    }
+
+    // 3) Nada nosso ainda neste evento/matcher — adiciona um bloco novo,
+    // preservando qualquer bloco de terceiro já presente no mesmo evento.
+    const newBlock = matcher
+      ? { matcher, hooks: [{ type: 'command', command, timeout }] }
+      : { hooks: [{ type: 'command', command, timeout }] };
+    hooks[event] = [...blocks, newBlock];
+  }
+
+  return { ...settings, hooks };
+}
+
+module.exports = {
+  HOOKS_DIR,
+  HOOK_DEFS,
+  buildHookEntries,
+  filterHooksRegisteredGlobally,
+  mergeHooksIntoSettings,
+  isOurHookCommand,
+};