wizz-method 1.19.0 → 2.1.0

package/tools/installer/core/doctor.js

@@ -0,0 +1,648 @@
+// doctor.js — diagnóstico do projeto Wizz (`wizz doctor`, item 17 da
+// auditoria 2026-09-11). Fecha os achados RT-M3 (drift silencioso entre
+// _wizz/ e o pacote) e RT-M4 (cadeia de tools quebrada sem sinal):
+// um comando que verifica, com saída legível, os 6 pontos que o dia a dia
+// do Wizz Method depende:
+//
+//   1. hooks   — arquivos em `_wizz/hooks/` + registro em `.claude/settings.json`
+//   2. rtk     — binário no PATH + versão (piso do hook: 0.23.0)
+//   3. jq      — binário no PATH (o hook rtk-rewrite.sh precisa dele)
+//   4. python  — informativo: `python3` é OPCIONAL desde o item 29 (só as
+//               skills BMAD com scripts próprios usam); reusa python-check.js
+//   5. drift   — hashes do files-manifest.csv vs os arquivos instalados em _wizz/
+//   6. resolved — snapshots de `_wizz/_resolved/` contra o hash das entradas
+//                 que os geraram (`.index.json`)
+//
+// Forma dos resultados: cada check devolve
+//   { check, status: 'ok'|'warn'|'error', detail }
+// e o agregador devolve { results, exitCode } seguindo a convenção do repo
+// (0 = ok/warn, 1 = error). Toda detecção de ambiente é INJETÁVEL: os
+// checkers (hasCommand, runVersion, pythonDetect, ...) chegam por `deps`
+// — os testes rodam sem rtk/jq/python instalados e sem rede.
+
+const path = require('node:path');
+const { HOOK_DEFS, isOurHookCommand } = require('./hooks-settings');
+const { classifyPython, PYTHON_ONLY_SKILLS } = require('./python-check');
+
+// Piso de versão do rtk que o hook rtk-rewrite.sh exige para `rtk rewrite`
+// (o registry pin do CLI é mais alto, 0.45.0, e é aplicado pelo detectClis
+// no install; aqui reportamos o piso que quebra o hook hoje).
+const RTK_HOOK_FLOOR = '0.23.0';
+
+const CHECKS = ['hooks', 'rtk', 'jq', 'python', 'drift', 'resolved'];
+
+/**
+ * Versão numérica comparável a partir de texto de `rtk --version` etc.
+ * (mesmo formato "x.y.z" que cli-config.js#extractVersion usa).
+ * @param {string} text
+ * @returns {string|null}
+ */
+function extractVersion(text) {
+  const m = String(text || '').match(/\d+\.\d+\.\d+/);
+  return m ? m[0] : null;
+}
+
+/**
+ * Compara "x.y.z" por segmento numérico (a<b negativo, igual 0, a>b positivo).
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function compareSemver(a, b) {
+  const pa = String(a)
+    .split('.')
+    .map((n) => Number(n) || 0);
+  const pb = String(b)
+    .split('.')
+    .map((n) => Number(n) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const diff = (pa[i] || 0) - (pb[i] || 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+/**
+ * Lê CSV de uma linha só respeitando aspas duplas com vírgula/aspas dentro
+ * (suficiente pros manifests que o próprio installer escreve). Não suporta
+ * aspas escapadas embutidas — os manifests não geram esse caso.
+ * @param {string} line
+ * @returns {string[]}
+ */
+function parseCsvLine(line) {
+  const fields = [];
+  let current = '';
+  let inQuotes = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (inQuotes) {
+      if (ch === '"') {
+        if (line[i + 1] === '"') {
+          current += '"';
+          i++;
+        } else {
+          inQuotes = false;
+        }
+      } else {
+        current += ch;
+      }
+    } else if (ch === '"') {
+      inQuotes = true;
+    } else if (ch === ',') {
+      fields.push(current);
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  fields.push(current);
+  return fields;
+}
+
+/**
+ * Checagem de hooks: para cada HOOK_DEF canônico, o arquivo existe em
+ * `_wizz/hooks/` e (para o settings) há uma entrada nossa no evento certo
+ * de `.claude/settings.json`? Hooks com `requires: 'rtk'` (rtk-rewrite.sh)
+ * degradam para warn quando o arquivo não existe — o installer também os
+ * pula quando rtk não está no PATH (RT-C1, item 4). Falta de registro no
+ * settings é warn (hook roda menos, não quebra), não error.
+ * @param {object} deps
+ * @param {string} deps.wizzDir
+ * @param {string} deps.settingsFile - .claude/settings.json do projeto
+ * @param {string} [deps.globalSettingsFile] - ~/.claude/settings.json (só para a mensagem)
+ * @param {(p: string) => boolean} deps.fileExists
+ * @param {() => object|null} deps.readProjectSettings
+ * @param {() => object|null} deps.readGlobalSettings - ~/.claude/settings.json
+ * @param {boolean} [deps.rtkOnPath] - igual ao installer: sem rtk no PATH,
+ *   o registro do rtk-rewrite.sh não é exigido (ele é opcional, RT-C1 item 4)
+ * @returns {{check: 'hooks', status: 'ok'|'warn'|'error', detail: string}}
+ */
+function checkHooks({ wizzDir, settingsFile, globalSettingsFile, fileExists, readProjectSettings, readGlobalSettings, rtkOnPath = false }) {
+  // `wizzDir` já É o diretório _wizz/ do projeto; HOOKS_DIR ('_wizz/hooks')
+  // é relativo à raiz, então o subdiretório aqui é só 'hooks'.
+  const hooksDir = path.join(wizzDir, 'hooks');
+  const missingFiles = [];
+  const missingSettings = [];
+  const skippedGlobal = [];
+
+  const globalSettings = readGlobalSettings ? readGlobalSettings() : null;
+  const projectSettings = readProjectSettings ? readProjectSettings() : null;
+
+  for (const def of HOOK_DEFS) {
+    const fileOnDisk = fileExists(path.join(hooksDir, def.id));
+    if (!fileOnDisk) {
+      if (def.requires === 'rtk') {
+        // Opcional por design: o installer só registra rtk-rewrite.sh
+        // quando rtk está no PATH; ausência aqui é estado normal.
+        continue;
+      }
+      missingFiles.push(def.id);
+      continue;
+    }
+
+    // Registrado no global? Mesma semântica de filterHooksRegisteredGlobally
+    // (hooks-settings.js): basename dentro do command, qualquer matcher do
+    // evento conta. O path global (~/.claude/hooks/...) nunca contém
+    // _wizz/hooks/, então isOurHookCommand não serve aqui — compara por id.
+    const registeredGlobally = (() => {
+      const blocks =
+        globalSettings && globalSettings.hooks && Array.isArray(globalSettings.hooks[def.event]) ? globalSettings.hooks[def.event] : [];
+      return blocks.some(
+        (block) => Array.isArray(block.hooks) && block.hooks.some((h) => h && typeof h.command === 'string' && h.command.includes(def.id)),
+      );
+    })();
+    if (registeredGlobally) {
+      skippedGlobal.push(def.id);
+      continue;
+    }
+
+    const blocks =
+      projectSettings && projectSettings.hooks && Array.isArray(projectSettings.hooks[def.event]) ? projectSettings.hooks[def.event] : [];
+    const registered = blocks.some(
+      (block) => Array.isArray(block.hooks) && block.hooks.some((h) => isOurHookCommand(h && h.command, def.id)),
+    );
+    if (!registered) {
+      // rtk-rewrite.sh presente em disco mas rtk ausente: o installer não
+      // o registra (RT-C1 item 4), então não cobrar registro aqui.
+      if (def.requires === 'rtk' && !rtkOnPath) continue;
+      missingSettings.push(def.id);
+    }
+  }
+
+  if (missingFiles.length > 0) {
+    return {
+      check: 'hooks',
+      status: 'error',
+      detail: `Faltam arquivos de hook em _wizz/hooks/: ${missingFiles.join(', ')}. Execute wizz update para repor.`,
+    };
+  }
+
+  if (missingSettings.length > 0) {
+    return {
+      check: 'hooks',
+      status: 'warn',
+      detail:
+        `Arquivos ok, mas sem registro no settings do PROJETO (${settingsFile}): ${missingSettings.join(', ')}. ` +
+        `Também não estão no settings GLOBAL (${globalSettingsFile || '~/.claude/settings.json'}). ` +
+        `Rode wizz install para registrar no projeto, ou registre no global.`,
+    };
+  }
+
+  const skippedNote =
+    skippedGlobal.length > 0
+      ? ` (${skippedGlobal.length} já registrado(s) no settings global ${globalSettingsFile || '~/.claude/settings.json'}, ok)`
+      : '';
+  return { check: 'hooks', status: 'ok', detail: `${HOOK_DEFS.length} hooks verificados${skippedNote}.` };
+}
+
+/**
+ * Checagem genérica de binário no PATH, com versão opcional contra um piso.
+ * `runVersion(cmd)` devolve stdout+stderr de `<cmd> --version` (ou null).
+ * @param {object} args
+ * @param {string} args.check - 'rtk' | 'jq'
+ * @param {string|null} args.version - saída de --version (null se ausente)
+ * @param {string} [args.floor] - versão mínima (só rtk)
+ * @returns {{check: 'rtk'|'jq', status: 'ok'|'warn'|'error', detail: string}}
+ */
+function checkCli({ check, version, floor }) {
+  if (check === 'rtk') {
+    if (!version) {
+      return {
+        check,
+        status: 'warn',
+        detail: `rtk não encontrado no PATH. Opcional, mas sem ele o hook rtk-rewrite.sh não é registrado e a economia de tokens não roda. Instale: cargo install rtk`,
+      };
+    }
+    const installed = extractVersion(version);
+    if (installed && compareSemver(installed, RTK_HOOK_FLOOR) < 0) {
+      return {
+        check,
+        status: 'warn',
+        detail: `rtk ${installed} é mais antigo que o piso do hook (${RTK_HOOK_FLOOR}); o rewrite falha em warn. Atualize: cargo install rtk`,
+      };
+    }
+    return { check, status: 'ok', detail: `rtk ${installed || '(versão não informada)'} no PATH.` };
+  }
+
+  // jq — sem verificação de versão, o hook só precisa dele presente.
+  if (!version) {
+    return {
+      check: 'jq',
+      status: 'warn',
+      detail:
+        'jq não encontrado no PATH. O hook rtk-rewrite.sh precisa dele; sem jq o rewrite de Bash avisa e segue sem reescrever. Instale: brew install jq',
+    };
+  }
+  return { check: 'jq', status: 'ok', detail: 'jq no PATH.' };
+}
+
+/**
+ * Checagem de python: INFORMATIVA desde o item 29 (2026-09-12). O núcleo do
+ * Wizz roda só com Node — memlog é `memlog.js` e as configs TOML viram
+ * `_wizz/_resolved/*.json` na instalação. Python só compra as skills BMAD que
+ * trazem script próprio, então a ausência dele nunca é `warn`: é `ok` com o
+ * detalhe dizendo o que fica de fora. Reusa classifyPython de python-check.js
+ * sobre o resultado do detector injetado (mesmo contrato de detectPython).
+ * @param {object} args
+ * @param {{command: string, version: {major: number, minor: number, patch: number, raw: string}, isRuntimeCommand: boolean}|null} args.detected
+ * @returns {{check: 'python', status: 'ok'|'warn'|'error', detail: string}}
+ */
+function checkPython({ detected }) {
+  const status = classifyPython(detected ? detected.version : null);
+  // Nunca warn: Python é opcional. O detalhe diz o que está disponível.
+  const detail = pythonDetail(status, detected);
+  return { check: 'python', status: 'ok', detail };
+}
+
+/**
+ * Frase do check de python por caso detectado. Toda variante fecha dizendo
+ * que o núcleo não depende disso, para ninguém ler "opcional" como "quebrado".
+ * @param {'full'|'partial'|'unsupported'|'none'} status
+ * @param {object|null} detected
+ * @returns {string}
+ */
+function pythonDetail(status, detected) {
+  const optional = `Opcional: o núcleo roda só com Node; Python só habilita as skills com script próprio (${PYTHON_ONLY_SKILLS}).`;
+  if (status === 'full' && detected.isRuntimeCommand) {
+    return `Python ${detected.version.raw} via ${detected.command} (tomllib ok): as skills Python também rodam.`;
+  }
+  if (status === 'full') {
+    return `Python ${detected.version.raw} existe via ${detected.command}, mas os scripts chamam python3, que não está no PATH. ${optional}`;
+  }
+  if (status === 'partial') {
+    return `Python ${detected.version.raw} no PATH, sem tomllib (as skills com script próprio pedem 3.11+). ${optional}`;
+  }
+  if (status === 'unsupported') {
+    return `Python ${detected.version.raw} é antigo demais (as skills com script próprio pedem 3.11+). ${optional}`;
+  }
+  return `python3 não encontrado no PATH. ${optional} Para tê-las: brew install python3 (macOS).`;
+}
+
+/**
+ * Checagem de drift (RT-M3): compara o hash de cada linha do
+ * `_wizz/_config/files-manifest.csv` com o hash atual do arquivo em
+ * `_wizz/<path>`. Hash divergente ou arquivo sumido = drift. Não tenta
+ * adivinhar fonte no pacote: o files-manifest é escrito pelo installer
+ * contra o INSTALADO, então basta o estado em disco — funciona igual para
+ * módulos builtin, externos e custom.
+ * @param {object} args
+ * @param {string} args.wizzDir
+ * @param {string|null} args.manifestContent - conteúdo de files-manifest.csv (null = ausente)
+ * @param {(p: string) => Promise<string|null>} args.hashFile - sha256 (fs-native.calculateFileHash)
+ * @param {(p: string) => Promise<boolean>} args.fileExists
+ * @returns {Promise<{check: 'drift', status: 'ok'|'warn'|'error', detail: string}>}
+ */
+async function checkDrift({ wizzDir, manifestContent, hashFile, fileExists }) {
+  if (manifestContent == null) {
+    return {
+      check: 'drift',
+      status: 'warn',
+      detail: 'files-manifest.csv não encontrado em _wizz/_config/. Sem ele não dá para detectar drift; rode wizz update para gerar.',
+    };
+  }
+
+  const lines = manifestContent.split('\n').filter((l) => l.trim());
+  // header: type,name,module,path,hash
+  const rows = lines
+    .slice(1)
+    .map(parseCsvLine)
+    .filter((f) => f.length >= 5 && f[3] && f[4]);
+  if (rows.length === 0) {
+    return { check: 'drift', status: 'ok', detail: 'files-manifest.csv vazio, nada a comparar.' };
+  }
+
+  const drifted = [];
+  const missing = [];
+  for (const fields of rows) {
+    const relPath = fields[3];
+    const recorded = fields[4];
+    const absPath = path.join(wizzDir, relPath);
+    if (!(await fileExists(absPath))) {
+      missing.push(relPath);
+      continue;
+    }
+    const current = await hashFile(absPath);
+    if (current && current !== recorded) {
+      drifted.push(relPath);
+    }
+  }
+
+  if (drifted.length === 0 && missing.length === 0) {
+    return { check: 'drift', status: 'ok', detail: `${rows.length} arquivos batem com o files-manifest.csv.` };
+  }
+
+  const parts = [];
+  if (drifted.length > 0) parts.push(`${drifted.length} alterado(s)`);
+  if (missing.length > 0) parts.push(`${missing.length} ausente(s)`);
+  return {
+    check: 'drift',
+    status: 'warn',
+    detail: `Drift em _wizz/: ${parts.join(' e ')} contra o files-manifest.csv (ex.: ${[...drifted, ...missing].slice(0, 3).join(', ')}). Edita manuais em _wizz/ são perdidos no próximo update — mova para _wizz/custom/ e rode wizz update.`,
+  };
+}
+
+/**
+ * Checagem dos snapshots de customização (`_wizz/_resolved/`, item 19).
+ *
+ * A ativação de agente lê `_resolved/<skill>.json` com um único Read e não
+ * checa nada — sem mtime, sem stat, sem spawn. O preço disso é que um
+ * snapshot desatualizado é invisível em runtime, então a detecção mora
+ * aqui: `_resolved/.index.json` guarda o sha256 de cada arquivo que
+ * alimentou cada snapshot (customize.toml base, seus includes, as camadas
+ * team/user e os includes delas) e este check recalcula.
+ *
+ * Duas sutilezas do layout instalado:
+ *  - o pipeline verbatim MOVE o diretório da skill de `_wizz/` para a pasta
+ *    de skills do IDE, então o path do customize.toml gravado no índice
+ *    costuma não existir mais; a cópia implantada
+ *    (`.claude/skills/<skill>/customize.toml`) é a que o usuário edita e é
+ *    contra ela que o hash é comparado nesse caso;
+ *  - entrada que sumiu e não tem cópia implantada é "não verificável", não
+ *    é obsolescência: avisar ali seria gritar em toda instalação limpa.
+ *
+ * Nunca é error: um snapshot ausente ou velho degrada para o fallback
+ * Python ou para uma customização antiga, nunca quebra a instalação.
+ *
+ * @param {object} args
+ * @param {string} args.projectDir - raiz do projeto (os paths do índice são relativos a ela)
+ * @param {Map<string, string[]>} args.skillSources - skill → customize.toml encontrados
+ * @param {object|null} args.index - `.index.json` já lido (null = ausente/ilegível)
+ * @param {(p: string) => boolean|Promise<boolean>} args.fileExists
+ * @param {(p: string) => Promise<string|null>} args.hashFile - sha256
+ * @param {string} args.resolvedDir
+ * @returns {Promise<{check: 'resolved', status: 'ok'|'warn', detail: string}>}
+ */
+async function checkResolved({ projectDir, skillSources, index, fileExists, hashFile, resolvedDir }) {
+  const sources = skillSources instanceof Map ? skillSources : new Map(Object.entries(skillSources || {}));
+  const skills = [...sources.keys()].sort();
+  if (skills.length === 0) {
+    return { check: 'resolved', status: 'ok', detail: 'Nenhuma skill com customize.toml instalada; nada a resolver.' };
+  }
+
+  if (!index || typeof index !== 'object' || !index.skills || typeof index.skills !== 'object') {
+    return {
+      check: 'resolved',
+      status: 'warn',
+      detail: `Índice ${path.join(resolvedDir, '.index.json')} ausente ou ilegível: não dá para saber se os ${skills.length} snapshots estão atualizados. Rode wizz resolve.`,
+    };
+  }
+
+  const missing = [];
+  const stale = [];
+  for (const skill of skills) {
+    // Prototype-safe: um skill chamado "constructor" (ou qualquer outra
+    // chave herdada de Object.prototype) não deve resolver para
+    // Object.prototype.constructor quando não há entrada própria no índice.
+    const entry = Object.hasOwn(index.skills, skill) ? index.skills[skill] : undefined;
+    const snapshotPath = path.join(resolvedDir, `${skill}.json`);
+    if (!entry || !(await fileExists(snapshotPath))) {
+      missing.push(skill);
+      continue;
+    }
+    // O snapshot em si também é conferido: truncado, corrompido ou editado
+    // à mão diverge do hash gravado na geração (entry.output).
+    if (typeof entry.output === 'string') {
+      const currentOutput = await hashFile(snapshotPath);
+      if (currentOutput !== null && currentOutput !== entry.output) {
+        stale.push(`${skill} (snapshot)`);
+        continue;
+      }
+    }
+    const inputs = entry.inputs && typeof entry.inputs === 'object' ? entry.inputs : {};
+    for (const [relPath, recorded] of Object.entries(inputs)) {
+      const current = await currentInputHash({ projectDir, relPath, skill, sources, fileExists, hashFile, recorded });
+      if (current !== null && current !== recorded) {
+        stale.push(`${skill} (${relPath})`);
+        break;
+      }
+    }
+  }
+
+  if (missing.length === 0 && stale.length === 0) {
+    return {
+      check: 'resolved',
+      status: 'ok',
+      detail: `${skills.length} snapshots em _wizz/_resolved/ batem com as entradas que os geraram.`,
+    };
+  }
+
+  const parts = [];
+  if (missing.length > 0) parts.push(`${missing.length} sem snapshot (${missing.slice(0, 3).join(', ')})`);
+  if (stale.length > 0) parts.push(`${stale.length} com snapshot obsoleto (${stale.slice(0, 3).join(', ')})`);
+  const prefix = stale.length > 0 ? 'snapshot obsoleto: rode wizz resolve' : 'rode wizz resolve';
+  return { check: 'resolved', status: 'warn', detail: `${prefix} — ${parts.join('; ')}.` };
+}
+
+/**
+ * Hash atual de uma entrada do índice, ou null quando não dá para verificar.
+ * O path gravado vale primeiro; se o arquivo sumiu e a entrada é o
+ * `customize.toml` da skill, compara com as cópias implantadas nas pastas
+ * de skills dos IDEs (é lá que o arquivo vive depois do install, e é lá que
+ * o usuário edita). Nenhuma cópia encontrada = não verificável (null).
+ * @returns {Promise<string|null>}
+ */
+async function currentInputHash({ projectDir, relPath, skill, sources, fileExists, hashFile, recorded }) {
+  const absPath = path.resolve(projectDir, relPath);
+  if (await fileExists(absPath)) return hashFile(absPath);
+  if (path.basename(relPath) !== 'customize.toml') return null;
+
+  const candidates = (sources.get(skill) || []).filter((p) => p !== absPath);
+  let first = null;
+  for (const candidate of candidates) {
+    const hash = await hashFile(candidate);
+    if (hash === null) continue;
+    if (hash === recorded) return hash;
+    if (first === null) first = hash;
+  }
+  return first;
+}
+
+/**
+ * Orquestra os 6 checks. Todos os efeitos de ambiente chegam por `deps`,
+ * então esta função é pura o bastante para testes com fixtures em tmp dir.
+ * @param {object} [options]
+ * @param {object} [options.deps] - checkers injetáveis (ver chamadas abaixo)
+ * @returns {Promise<{results: Array<{check, status, detail}>, exitCode: number, hasError: boolean}>}
+ */
+async function runDoctor(options = {}) {
+  const deps = options.deps || {};
+  const {
+    wizzDir,
+    projectDir = process.cwd(),
+    fileExists = (p) => require('../fs-native').pathExistsSync(p),
+    hashFile = (p) => require('../fs-native').calculateFileHash(p),
+    readFile = (p) => require('../fs-native').readFileSync(p, 'utf8'),
+    hasCommand = defaultHasCommand,
+    runVersion = defaultRunVersion,
+    detectPython: detectPy = () => require('./python-check').detectPython(),
+    readProjectSettings,
+    readGlobalSettings,
+    globalSettingsFile,
+    discoverSkillSources = (root, dir) =>
+      require('./resolved-customizations').discoverSkillCustomizeTomls({ projectRoot: root, wizzDir: dir }),
+    readResolvedIndex = (dir) => require('./resolved-customizations').readIndex(dir),
+    rtkOnPath = () => hasCommand('rtk'),
+    skip = [],
+  } = deps;
+
+  const settingsFile = path.join(projectDir, '.claude', 'settings.json');
+  const readSettingsSafe = readProjectSettings || (() => safeReadJson(settingsFile));
+  const readGlobalSafe = readGlobalSettings || (() => null);
+
+  const results = [];
+
+  // 1) hooks — só faz sentido com _wizz/ presente.
+  if (skip.includes('hooks')) {
+    results.push({ check: 'hooks', status: 'ok', detail: 'pulado.' });
+  } else if (wizzDir) {
+    results.push(
+      checkHooks({
+        wizzDir,
+        settingsFile,
+        globalSettingsFile,
+        fileExists,
+        readProjectSettings: readSettingsSafe,
+        readGlobalSettings: readGlobalSafe,
+        rtkOnPath: rtkOnPath(),
+      }),
+    );
+  } else {
+    results.push({
+      check: 'hooks',
+      status: 'warn',
+      detail: 'Sem instalação Wizz neste diretório (_wizz/ ausente); hooks do projeto não verificados. Rode wizz install.',
+    });
+  }
+
+  // 2) rtk (com piso de versão do hook) e 3) jq (presença).
+  for (const cli of ['rtk', 'jq']) {
+    if (skip.includes(cli)) {
+      results.push({ check: cli, status: 'ok', detail: 'pulado.' });
+      continue;
+    }
+    const onPath = hasCommand(cli);
+    let version = null;
+    if (onPath) {
+      version = runVersion(cli);
+      if (version == null && cli === 'rtk') {
+        // No PATH mas --version falhou: reporta presente sem versão em vez
+        // de "não encontrado" — o binário quebra por outro motivo.
+        version = '';
+      }
+    }
+    results.push(checkCli({ check: cli, version }));
+  }
+
+  // 4) python — detector stubável (mesmo padrão de checkPythonEnvironment).
+  if (skip.includes('python')) {
+    results.push({ check: 'python', status: 'ok', detail: 'pulado.' });
+  } else {
+    results.push(checkPython({ detected: detectPy() }));
+  }
+
+  // 5) drift — só com _wizz/ presente; sem instalação, skip informado.
+  if (skip.includes('drift')) {
+    results.push({ check: 'drift', status: 'ok', detail: 'pulado.' });
+  } else if (wizzDir) {
+    const manifestPath = path.join(wizzDir, '_config', 'files-manifest.csv');
+    const manifestContent = (await fileExists(manifestPath)) ? await readFile(manifestPath) : null;
+    results.push(await checkDrift({ wizzDir, manifestContent, hashFile, fileExists }));
+  } else {
+    results.push({
+      check: 'drift',
+      status: 'warn',
+      detail: 'Sem instalação Wizz neste diretório; drift não verificado. Rode wizz install.',
+    });
+  }
+
+  // 6) resolved — snapshots de customização contra o hash das entradas.
+  if (skip.includes('resolved')) {
+    results.push({ check: 'resolved', status: 'ok', detail: 'pulado.' });
+  } else if (wizzDir) {
+    const resolvedDir = path.join(wizzDir, '_resolved');
+    results.push(
+      await checkResolved({
+        projectDir,
+        skillSources: discoverSkillSources(projectDir, wizzDir),
+        index: readResolvedIndex(resolvedDir),
+        fileExists,
+        hashFile,
+        resolvedDir,
+      }),
+    );
+  } else {
+    results.push({
+      check: 'resolved',
+      status: 'warn',
+      detail: 'Sem instalação Wizz neste diretório; snapshots de _wizz/_resolved/ não verificados. Rode wizz install.',
+    });
+  }
+
+  const hasError = results.some((r) => r.status === 'error');
+  return { results, exitCode: hasError ? 1 : 0, hasError };
+}
+
+/**
+ * `command -v <cmd>` via sh — mesmo padrão dos testes do repo; spawnSync
+ * com args estáticos, sem risco de injection (cmd é literal da lista).
+ * @param {string} cmd
+ * @returns {boolean}
+ */
+function defaultHasCommand(cmd) {
+  try {
+    const { spawnSync } = require('node:child_process');
+    const res = spawnSync('sh', ['-c', `command -v ${cmd}`], { encoding: 'utf8', timeout: 5000 });
+    return res.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Roda `<cmd> --version` e devolve stdout+stderr juntos (o rtk imprime em
+ * stdout, python em stderr; ambos os casos caem no mesmo regex).
+ * @param {string} cmd
+ * @returns {string|null} saída combinada, null quando o comando falha
+ */
+function defaultRunVersion(cmd) {
+  try {
+    const { spawnSync } = require('node:child_process');
+    const res = spawnSync(cmd, ['--version'], { encoding: 'utf8', timeout: 5000 });
+    if (res.error || (res.status !== 0 && !res.stdout)) return null;
+    return `${res.stdout || ''}\n${res.stderr || ''}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Lê JSON de settings.json com fallback seguro para null (nunca lança).
+ * @param {string} file
+ * @returns {object|null}
+ */
+function safeReadJson(file) {
+  try {
+    const raw = require('../fs-native').readFileSync(file, 'utf8');
+    if (!raw.trim()) return null;
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  CHECKS,
+  RTK_HOOK_FLOOR,
+  extractVersion,
+  compareSemver,
+  parseCsvLine,
+  checkHooks,
+  checkCli,
+  checkPython,
+  pythonDetail,
+  checkDrift,
+  checkResolved,
+  runDoctor,
+  defaultHasCommand,
+  defaultRunVersion,
+};