wizz-method 2.15.0 → 2.17.0

package/tools/hooks/wizz-arrumar.js

@@ -0,0 +1,418 @@
+// wizz-arrumar.js — arrumação da raiz do projeto com manifesto e desfazer.
+//
+// Fonte de verdade: wizz-method/tools/hooks/. Instalada em `_wizz/hooks/`.
+// É o padrão que deu certo no Spider (2026-10-02), agora repetível:
+// manifesto .tsv revisável, script de desfazer, referências atualizadas em
+// código/docs/memórias e testes rodando antes e depois. Diferença do Spider:
+// o desfazer também restaura os arquivos cujas referências foram reescritas
+// (lá o desfazer só revertia os moves e avisava que o resto ficava torto).
+//
+//   layout                   propõe o layout de pastas (só mostra)
+//   layout --gravar [t=dir]  grava `layout:` no config, cria pastas + README curto
+//   planejar                 monta o manifesto dos arquivos soltos (não move nada)
+//   aplicar <manifesto.tsv>  move, atualiza referências, gera desfazer, roda testes
+//   mover <origem> <destino> atalho de um arquivo (manifesto de uma linha + aplicar)
+//   desfazer <pasta-da-arrumacao>
+//
+// Opções de aplicar/mover: --testes "<comando>", --refs <dir,dir> (ex.: pasta
+// da auto-memória), --manter (não desfaz sozinho se os testes quebrarem).
+// Cada execução fica em `<arquivo>/arrumacao/<data>-<hora>/`.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const lib = require('./wizz-feature-lib.js');
+const layoutLib = require('./wizz-layout-lib.js');
+
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  '.next',
+  '.nuxt',
+  '.svelte-kit',
+  'dist',
+  'build',
+  'out',
+  'coverage',
+  '_wizz',
+  '.venv',
+  'venv',
+  '__pycache__',
+  '.turbo',
+  '.vercel',
+  '.cache',
+]);
+const TEXT_EXT = new Set([
+  '.md',
+  '.mdx',
+  '.txt',
+  '.js',
+  '.cjs',
+  '.mjs',
+  '.ts',
+  '.tsx',
+  '.jsx',
+  '.py',
+  '.sh',
+  '.bash',
+  '.zsh',
+  '.json',
+  '.yaml',
+  '.yml',
+  '.toml',
+  '.html',
+  '.css',
+  '.sql',
+  '.ini',
+  '.cfg',
+  '.env.example',
+]);
+const MAX_TEXT_BYTES = 1024 * 1024;
+
+function parseArgs(argv) {
+  const opts = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('--')) {
+        opts[key] = next;
+        i++;
+      } else opts[key] = true;
+    } else opts._.push(a);
+  }
+  return opts;
+}
+
+function stamp() {
+  const d = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${lib.today()}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+
+function archiveDir(root, layout) {
+  const dir = layout.arquivo && layoutLib.normalizeDir(layout.arquivo) !== '.' ? layoutLib.normalizeDir(layout.arquivo) : 'arquivo';
+  return path.join(root, dir, 'arrumacao');
+}
+
+function isInside(child, parent) {
+  const r = path.relative(parent, child);
+  return r !== '' && !r.startsWith('..') && !path.isAbsolute(r);
+}
+
+// ── layout ──────────────────────────────────────────────────────────────
+
+const README_BODY = (type, dir) =>
+  `# ${dir}\n\nPasta de ${layoutLib.LAYOUT_TYPES[type] || type}.\n\nDefinida em \`_wizz/bmm/config.yaml\` (bloco \`layout:\`). Arquivo novo deste tipo nasce aqui, nunca solto na raiz.\n`;
+
+function cmdLayout(root, opts) {
+  const config = lib.readConfig(root);
+  const { layout: proposed, loose } = layoutLib.proposeLayout(root);
+  if (!opts.gravar) {
+    const current = Object.keys(config.layout).length > 0 ? config.layout : null;
+    const shown = current || proposed;
+    const pairs = Object.entries(shown)
+      .map(([t, d]) => `${t}=${d}`)
+      .join(' ');
+    return {
+      ok: true,
+      line: current
+        ? `Layout atual: ${pairs}.`
+        : `Proposta de layout: ${pairs}. ${loose.length} arquivo(s) solto(s) na raiz. Grave com: layout --gravar ${pairs}`,
+    };
+  }
+  const given = opts._.slice(1).filter((a) => a.includes('='));
+  const layout = given.length > 0 ? Object.fromEntries(given.map((a) => a.split('=').map((s) => s.trim()))) : proposed;
+  lib.writeLayout(root, layout);
+  const created = [];
+  for (const [type, dir] of Object.entries(layout)) {
+    if (type === 'raiz_extra' || layoutLib.normalizeDir(dir) === '.') continue;
+    const abs = path.join(root, layoutLib.normalizeDir(dir));
+    if (!isInside(abs, root)) continue;
+    fs.mkdirSync(abs, { recursive: true });
+    const readme = path.join(abs, 'README.md');
+    if (!fs.existsSync(readme)) {
+      fs.writeFileSync(readme, README_BODY(type, layoutLib.normalizeDir(dir)));
+      created.push(layoutLib.normalizeDir(dir));
+    }
+  }
+  return {
+    ok: true,
+    line: `Layout gravado em _wizz/bmm/config.yaml: ${Object.entries(layout)
+      .map(([t, d]) => `${t}=${d}`)
+      .join(' ')}.${created.length > 0 ? ` README curto criado em: ${created.join(', ')}.` : ''}`,
+  };
+}
+
+// ── manifesto ───────────────────────────────────────────────────────────
+
+function readManifest(file) {
+  const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/).filter(Boolean);
+  return lines
+    .slice(lines[0] && lines[0].startsWith('origem\t') ? 1 : 0)
+    .map((l) => l.split('\t'))
+    .filter((cols) => cols.length >= 2 && cols[0] && cols[1])
+    .map(([origem, destino]) => ({ origem, destino }));
+}
+
+function writeManifest(file, moves) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, ['origem\tdestino', ...moves.map((m) => `${m.origem}\t${m.destino}`)].join('\n') + '\n');
+}
+
+function planMoves(root, layout) {
+  const moves = [];
+  const semDestino = [];
+  for (const e of fs.readdirSync(root, { withFileTypes: true })) {
+    if (!e.isFile() || layoutLib.isAllowedAtRoot(e.name, layout)) continue;
+    const dest = layoutLib.suggestDestination(e.name, layout);
+    if (dest) moves.push({ origem: e.name, destino: `${dest.dir}/${e.name}` });
+    else semDestino.push(e.name);
+  }
+  return { moves, semDestino };
+}
+
+function cmdPlanejar(root, opts) {
+  const config = lib.readConfig(root);
+  if (Object.keys(config.layout).length === 0) return { ok: false, code: 2, line: 'Sem layout no config: rode `layout --gravar` antes.' };
+  const { moves, semDestino } = planMoves(root, config.layout);
+  if (moves.length === 0)
+    return { ok: true, line: `Raiz já está arrumada.${semDestino.length > 0 ? ` Sem destino: ${semDestino.join(', ')}.` : ''}` };
+  const file =
+    typeof opts.saida === 'string' ? path.resolve(root, opts.saida) : path.join(archiveDir(root, config.layout), `plano-${stamp()}.tsv`);
+  writeManifest(file, moves);
+  return {
+    ok: true,
+    line:
+      `Manifesto com ${moves.length} move(s): ${path.relative(root, file)}. Revise e rode: aplicar ${path.relative(root, file)}` +
+      (semDestino.length > 0 ? `. Sem destino sugerido: ${semDestino.join(', ')}.` : '.'),
+  };
+}
+
+// ── referências ─────────────────────────────────────────────────────────
+
+function* walkText(dir, skipAbs) {
+  let entries = [];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const abs = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name) || skipAbs.some((s) => abs === s || isInside(abs, s))) continue;
+      yield* walkText(abs, skipAbs);
+    } else if (e.isFile()) {
+      const ext = e.name.endsWith('.env.example') ? '.env.example' : path.extname(e.name).toLowerCase();
+      if (!TEXT_EXT.has(ext)) continue;
+      try {
+        if (fs.statSync(abs).size <= MAX_TEXT_BYTES) yield abs;
+      } catch {
+        // some no meio do caminho: ignora
+      }
+    }
+  }
+}
+
+function escapeRe(s) {
+  return s.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+}
+
+/**
+ * Reescreve referências a `origem` (caminho relativo à raiz) para `destino`.
+ * Casa `origem` e `./origem` quando não colado a outro caminho; não toca um
+ * arquivo cuja pasta tem um irmão com o mesmo nome (a referência é local).
+ */
+function rewriteRefs(text, moves, fileDir) {
+  let next = text;
+  for (const { origem, destino } of moves) {
+    if (fs.existsSync(path.join(fileDir, path.basename(origem))) && fileDir !== '') continue;
+    const re = new RegExp(String.raw`(?<![\w/.-])(\./)?${escapeRe(origem)}(?![\w-])`, 'g');
+    next = next.replace(re, (_m, dot) => `${dot || ''}${destino}`);
+  }
+  return next;
+}
+
+// ── aplicar / desfazer ──────────────────────────────────────────────────
+
+function runTests(root, cmd) {
+  if (!cmd || cmd === true) return null;
+  const r = spawnSync(cmd, { cwd: root, shell: true, encoding: 'utf8', timeout: 10 * 60 * 1000 });
+  return { ok: r.status === 0, code: r.status, tail: `${r.stdout || ''}${r.stderr || ''}`.trim().split('\n').slice(-5).join('\n') };
+}
+
+function shQuote(s) {
+  return `'${String(s).replaceAll("'", String.raw`'\''`)}'`;
+}
+
+function writeUndoScript(runDir, root, moves, edits) {
+  const lines = [
+    '#!/usr/bin/env bash',
+    `# Desfaz a arrumação de ${path.basename(runDir)}: restaura os arquivos editados e devolve os moves.`,
+    'set -euo pipefail',
+    `cd ${shQuote(root)}`,
+    ...edits.map((e) => `cp -p ${shQuote(path.join(runDir, e.backup))} ${shQuote(e.original)}`),
+    ...moves
+      .toReversed()
+      .map((m) => `[[ -e ${shQuote(m.destino)} && ! -e ${shQuote(m.origem)} ]] && mv ${shQuote(m.destino)} ${shQuote(m.origem)}`),
+    'echo "Arrumação desfeita."',
+    '',
+  ];
+  const file = path.join(runDir, 'desfazer.sh');
+  fs.writeFileSync(file, lines.join('\n'));
+  fs.chmodSync(file, 0o755);
+  return file;
+}
+
+function undo(root, runDir) {
+  const moves = readManifest(path.join(runDir, 'manifesto.tsv'));
+  const editsFile = path.join(runDir, 'edicoes.tsv');
+  const edits = fs.existsSync(editsFile)
+    ? fs
+        .readFileSync(editsFile, 'utf8')
+        .split('\n')
+        .filter(Boolean)
+        .map((l) => {
+          const [original, backup] = l.split('\t');
+          return { original, backup };
+        })
+    : [];
+  for (const e of edits) fs.copyFileSync(path.join(runDir, e.backup), e.original);
+  for (const m of moves.toReversed()) {
+    const from = path.join(root, m.destino);
+    const to = path.join(root, m.origem);
+    if (fs.existsSync(from) && !fs.existsSync(to)) fs.renameSync(from, to);
+  }
+  return { moves: moves.length, edits: edits.length };
+}
+
+function validateMoves(root, moves) {
+  const problems = [];
+  for (const m of moves) {
+    const from = path.join(root, m.origem);
+    const to = path.join(root, m.destino);
+    if (!isInside(from, root) || !isInside(to, root)) problems.push(`${m.origem}: fora do projeto`);
+    else if (['_wizz', '.git'].includes(m.origem.split('/')[0])) problems.push(`${m.origem}: pasta protegida`);
+    else if (!fs.existsSync(from)) problems.push(`${m.origem}: não existe`);
+    else if (fs.existsSync(to)) problems.push(`${m.destino}: destino já existe`);
+  }
+  return problems;
+}
+
+function applyMoves(root, moves, opts) {
+  const config = lib.readConfig(root);
+  const problems = validateMoves(root, moves);
+  if (problems.length > 0) return { ok: false, code: 2, line: `Nada foi movido: ${problems.join('; ')}.` };
+
+  const runDir = path.join(archiveDir(root, config.layout), stamp());
+  fs.mkdirSync(runDir, { recursive: true });
+  writeManifest(path.join(runDir, 'manifesto.tsv'), moves);
+
+  const before = runTests(root, opts.testes);
+
+  // Referências: projeto inteiro + pastas extras (auto-memória, Cérebro).
+  const extra = typeof opts.refs === 'string' ? opts.refs.split(',').map((d) => path.resolve(root, d.trim())) : [];
+  const skip = [archiveDir(root, config.layout)];
+  const targets = new Set();
+  for (const base of [root, ...extra]) for (const f of walkText(base, skip)) targets.add(f);
+  const movedAbs = new Set(moves.map((m) => path.join(root, m.origem)));
+
+  // 1) Backup + reescrita ANTES de mover: o backup guarda o texto original.
+  const edits = [];
+  let n = 0;
+  for (const file of targets) {
+    const text = fs.readFileSync(file, 'utf8');
+    const dir = movedAbs.has(file) ? '' : path.dirname(file) === root ? '' : path.dirname(file);
+    const next = rewriteRefs(text, moves, dir);
+    if (next === text) continue;
+    const backup = path.join('antes', String(++n).padStart(4, '0') + '-' + path.basename(file));
+    fs.mkdirSync(path.join(runDir, 'antes'), { recursive: true });
+    fs.copyFileSync(file, path.join(runDir, backup));
+    // Arquivo que também muda de lugar: o desfazer restaura no caminho NOVO e
+    // só depois devolve o move; restaurar no antigo deixaria uma cópia órfã.
+    const moved = moves.find((m) => path.join(root, m.origem) === file);
+    edits.push({ original: moved ? path.join(root, moved.destino) : file, backup });
+    fs.writeFileSync(file, next);
+  }
+  fs.writeFileSync(
+    path.join(runDir, 'edicoes.tsv'),
+    edits.map((e) => `${e.original}\t${e.backup}`).join('\n') + (edits.length > 0 ? '\n' : ''),
+  );
+
+  // 2) Moves.
+  for (const m of moves) {
+    const to = path.join(root, m.destino);
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    fs.renameSync(path.join(root, m.origem), to);
+  }
+  const undoFile = writeUndoScript(runDir, root, moves, edits);
+  const after = runTests(root, opts.testes);
+  const relRun = path.relative(root, runDir);
+
+  if (before && after && before.ok && !after.ok && !opts.manter) {
+    undo(root, runDir);
+    return {
+      ok: false,
+      code: 1,
+      line: `Os testes passavam antes e quebraram depois: desfiz tudo. Últimas linhas: ${after.tail}. Registro em ${relRun}/.`,
+    };
+  }
+  const testes = before
+    ? ` Testes: antes ${before.ok ? 'ok' : `falhando (${before.code})`}, depois ${after.ok ? 'ok' : `falhando (${after.code})`}.`
+    : ' Sem comando de testes (--testes): confira à mão.';
+  return {
+    ok: !after || after.ok || !before?.ok,
+    code: 0,
+    line: `Movi ${moves.length} arquivo(s) e atualizei referências em ${edits.length}.${testes} Desfazer: ${path.relative(root, undoFile)}.`,
+  };
+}
+
+function cmdAplicar(root, opts) {
+  const file = opts._[1];
+  if (!file) return { ok: false, code: 2, line: 'Uso: aplicar <manifesto.tsv>.' };
+  const moves = readManifest(path.resolve(root, file));
+  if (moves.length === 0) return { ok: false, code: 2, line: 'Manifesto vazio: nada a fazer.' };
+  return applyMoves(root, moves, opts);
+}
+
+function cmdMover(root, opts) {
+  const [, origem, destino] = opts._;
+  if (!origem || !destino) return { ok: false, code: 2, line: 'Uso: mover <origem> <destino>.' };
+  const relOf = (p) => path.relative(root, path.resolve(root, p));
+  return applyMoves(root, [{ origem: relOf(origem), destino: relOf(destino) }], opts);
+}
+
+function cmdDesfazer(root, opts) {
+  const dir = opts._[1];
+  if (!dir) return { ok: false, code: 2, line: 'Uso: desfazer <pasta-da-arrumacao>.' };
+  const runDir = path.resolve(root, dir);
+  if (!fs.existsSync(path.join(runDir, 'manifesto.tsv'))) return { ok: false, code: 2, line: `Sem manifesto.tsv em ${dir}.` };
+  const r = undo(root, runDir);
+  return { ok: true, line: `Desfeito: ${r.moves} move(s) revertido(s), ${r.edits} arquivo(s) restaurado(s).` };
+}
+
+const COMMANDS = { layout: cmdLayout, planejar: cmdPlanejar, aplicar: cmdAplicar, mover: cmdMover, desfazer: cmdDesfazer };
+
+function run(argv) {
+  const opts = parseArgs(argv);
+  const command = COMMANDS[opts._[0]];
+  if (!command) return { ok: false, code: 2, line: `Comandos: ${Object.keys(COMMANDS).join(', ')}.` };
+  const cwd = typeof opts.cwd === 'string' ? path.resolve(opts.cwd) : process.cwd();
+  const root = lib.findWizzRoot(cwd);
+  if (!root) return { ok: true, code: 0, line: 'Não é projeto Wizz (sem _wizz/): nada a fazer.' };
+  try {
+    return command(root, opts);
+  } catch (error) {
+    return { ok: false, code: 1, line: `Falhou: ${error.message}` };
+  }
+}
+
+if (require.main === module) {
+  const result = run(process.argv.slice(2));
+  process.stdout.write(`${result.line}\n`);
+  process.exit(result.code ?? (result.ok ? 0 : 1));
+}
+
+module.exports = { run, rewriteRefs, readManifest, planMoves, undo };

package/tools/hooks/wizz-artifact-guard.js

@@ -0,0 +1,160 @@
+// wizz-artifact-guard.js — PostToolUse hook (matcher: Write)
+//
+// Fonte de verdade: wizz-method/tools/hooks/. Instalar via `npm run sync:global`
+// ou pelo installer (registra em `.claude/settings.json` do projeto).
+//
+// Dois avisos, nunca bloqueio (o arquivo já foi escrito; o aviso entra como
+// contexto para o agente corrigir na hora):
+//
+//   1. Artefato fora do lugar: escrito na pasta de artefatos mas fora da
+//      subpasta da feature ativa, artefato de feature sem feature ativa, ou
+//      artefato tipado (`spec-x.md`...) com frontmatter faltando/errado.
+//   2. Arquivo solto na raiz: fora do `layout:` do config. Sugere o destino e
+//      o comando que move atualizando as referências.
+//
+// Fail-open: sem `_wizz/`, sem config, payload estranho ou qualquer erro =
+// silêncio e exit 0. Caso comum (arquivo dentro de uma pasta qualquer) custa
+// zero token.
+
+const path = require('node:path');
+
+let lib;
+let layoutLib;
+try {
+  lib = require('./wizz-feature-lib.js');
+  layoutLib = require('./wizz-layout-lib.js');
+} catch {
+  lib = null;
+}
+
+const HOOK_CMD = '_wizz/hooks';
+
+function isInside(child, parent) {
+  const r = path.relative(parent, child);
+  return r !== '' && !r.startsWith('..') && !path.isAbsolute(r);
+}
+
+/**
+ * Aviso para um arquivo dentro das pastas de artefato, ou ''.
+ * @param {string} file - caminho absoluto
+ * @param {string} content - conteúdo escrito (pode ser '')
+ * @param {ReturnType<typeof lib.resolveFeature>} state
+ */
+function artifactWarning(file, content, state) {
+  const dirs = lib.artifactDirs(state.root, state.config);
+  const base = [dirs.planning, dirs.implementation].find((d) => isInside(file, d));
+  if (!base) return '';
+
+  const parts = path.relative(base, file).split(path.sep);
+  const name = parts.at(-1);
+  const type = lib.artifactTypeOf(name);
+  const relFile = path.relative(state.root, file);
+  const slug = state.slug;
+  const msgs = [];
+
+  if (parts.length === 1) {
+    if (lib.PROJECT_WIDE.test(name)) return '';
+    if (slug) {
+      msgs.push(
+        `ARTEFATO FORA DA FEATURE: ${relFile} está na raiz das pastas de artefato, mas a feature ativa é "${slug}". ` +
+          `Mova para ${path.relative(state.root, path.join(base, slug, name))} agora (raiz é só para artefato de projeto inteiro: arquitetura, contexto).`,
+      );
+    } else if (type) {
+      msgs.push(
+        `ARTEFATO SEM FEATURE: ${relFile} é de feature, mas nenhuma está ativa. ` +
+          `Grave a feature a partir do pedido (node ${HOOK_CMD}/wizz-feature.js definir <slug>) e mova o arquivo para a subpasta dela.`,
+      );
+    }
+  } else if (slug && parts[0] !== slug) {
+    msgs.push(
+      `ARTEFATO EM OUTRA FEATURE: ${relFile} está em "${parts[0]}", mas a ativa é "${slug}". ` +
+        `Se o trabalho é de "${slug}", mova; se o assunto mudou, troque a feature (wizz-feature.js definir ${parts[0]}).`,
+    );
+  }
+
+  if (type) {
+    const problems = lib.frontmatterProblems(content, parts.length > 1 ? parts[0] : slug);
+    if (problems.length > 0) msgs.push(`FRONTMATTER de ${relFile}: ${problems.join('; ')}.`);
+  }
+  return msgs.join(' ');
+}
+
+/**
+ * Aviso para arquivo solto na raiz do projeto, ou ''.
+ * @param {string} file
+ * @param {ReturnType<typeof lib.resolveFeature>} state
+ */
+function rootWarning(file, state) {
+  if (path.dirname(file) !== state.root) return '';
+  const name = path.basename(file);
+  const layout = state.config.layout;
+  if (layoutLib.isAllowedAtRoot(name, layout)) return '';
+
+  if (!state.hasLayout) {
+    return (
+      `ARQUIVO SOLTO NA RAIZ: ${name}. O projeto ainda não tem layout de pastas. ` +
+      `Proponha um em UMA linha (node ${HOOK_CMD}/wizz-arrumar.js layout) e grave com \`layout --gravar\`; depois mova o arquivo.`
+    );
+  }
+  const dest = layoutLib.suggestDestination(name, layout);
+  if (!dest) {
+    return `ARQUIVO SOLTO NA RAIZ: ${name} fica fora do layout. Mova para a pasta do tipo dele, ou libere em \`layout.raiz_extra\` se pertence à raiz.`;
+  }
+  const target = `${dest.dir}/${name}`;
+  return (
+    `ARQUIVO SOLTO NA RAIZ: ${name} fica fora do layout (${dest.type} → ${dest.dir}/). ` +
+    `Mova agora, atualizando as referências: node ${HOOK_CMD}/wizz-arrumar.js mover ${name} ${target}`
+  );
+}
+
+/**
+ * Decide o aviso a partir do payload do PostToolUse. Pura o bastante para teste.
+ * @param {{tool_name?: string, tool_input?: {file_path?: string, content?: string}, cwd?: string}} payload
+ * @returns {string} '' quando não há o que dizer
+ */
+function buildWarning(payload) {
+  if (!lib || !payload || typeof payload !== 'object') return '';
+  if (payload.tool_name && payload.tool_name !== 'Write') return '';
+  const input = payload.tool_input || {};
+  if (typeof input.file_path !== 'string' || !input.file_path) return '';
+
+  const cwd = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd();
+  const file = path.resolve(cwd, input.file_path);
+  // O cwd da sessão manda; o diretório do arquivo é a reserva (sessão aberta fora do projeto).
+  let state = lib.resolveFeature(cwd);
+  if (!state.isWizz || !isInside(file, state.root)) state = lib.resolveFeature(path.dirname(file));
+  if (!state.isWizz || !state.config.exists) return '';
+  if (!isInside(file, state.root)) return '';
+  // Nada dentro de _wizz/ (engine instalada) ou de pastas ocultas é artefato.
+  const first = path.relative(state.root, file).split(path.sep)[0];
+  if (first === '_wizz' || first.startsWith('.')) return '';
+
+  return artifactWarning(file, typeof input.content === 'string' ? input.content : '', state) || rootWarning(file, state);
+}
+
+if (require.main === module) {
+  let raw = '';
+  const timer = setTimeout(() => finish(), 3000);
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => (raw += chunk));
+  process.stdin.on('end', () => {
+    clearTimeout(timer);
+    finish();
+  });
+
+  function finish() {
+    try {
+      const warning = buildWarning(JSON.parse(raw || '{}'));
+      if (warning) {
+        process.stdout.write(
+          JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: `📁 Wizz: ${warning}` } }),
+        );
+      }
+    } catch {
+      // aviso nunca derruba a ferramenta
+    }
+    process.exit(0);
+  }
+}
+
+module.exports = { buildWarning, artifactWarning, rootWarning };