wizz-method 2.0.0 → 2.1.0

package/tools/installer/commands/doctor.js

@@ -0,0 +1,124 @@
+// doctor.js — comando `wizz doctor` (item 17 da auditoria 2026-09-11).
+// Wrapper fino sobre core/doctor.js (a lógica pura mora lá): imprime um
+// bloco por check com status ok/warn/error, resumo final e próximo passo,
+// e sai com a convenção do repo (0 = ok/warn, 1 = error).
+//
+// Registro no wizz-cli.js é automático: o CLI faz readdir de commands/ e
+// registra todo módulo que exporta {command, description, options, action}.
+
+const path = require('node:path');
+const os = require('node:os');
+const prompts = require('../prompts');
+const { runDoctor } = require('../core/doctor');
+const { findWizzDir } = require('../core/installer');
+
+/**
+ * Path do `settings.json` GLOBAL do usuário. Mesmo override que o installer
+ * usa em `Installer._globalSettingsFile` (core/installer.js): a env var
+ * existe para os testes injetarem um arquivo temporário em vez de tocar o
+ * `~/.claude/settings.json` real da máquina.
+ * @returns {string}
+ */
+function globalSettingsFile() {
+  return process.env.WIZZ_GLOBAL_SETTINGS_FILE || path.join(os.homedir(), '.claude', 'settings.json');
+}
+
+/**
+ * Lê o settings global com fallback seguro para null: arquivo ausente,
+ * vazio ou JSON inválido nunca lançam — o check de hooks só perde a
+ * informação "já registrado globalmente" e volta a cobrar o registro no
+ * projeto.
+ *
+ * Sem isso (bug 9 da review da fase 3) o caminho `registeredGlobally` de
+ * core/doctor.js era código morto e o doctor mandava registrar exatamente
+ * os hooks que o installer pulou de propósito
+ * (`filterHooksRegisteredGlobally`).
+ * @returns {object|null}
+ */
+function readGlobalSettingsFile() {
+  try {
+    const raw = require('../fs-native').readFileSync(globalSettingsFile(), 'utf8');
+    if (!raw.trim()) return null;
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+const STATUS_LABEL = {
+  ok: 'ok',
+  warn: 'warn',
+  error: 'ERROR',
+};
+
+module.exports = {
+  command: 'doctor',
+  description: 'Diagnóstico do projeto Wizz: hooks, rtk, jq, python e drift de _wizz/',
+  options: [],
+  // Exportado para teste (item 17 fase3, bug 9): prova, a partir do comando
+  // real da CLI, que o leitor de settings.json GLOBAL usado por checkHooks
+  // não é código morto — os testes de core/doctor.js só injetam um stub.
+  readGlobalSettingsFile,
+  action: async () => {
+    try {
+      const projectDir = process.cwd();
+      const { wizzDir } = findWizzDir(projectDir);
+      const hasInstall = path.basename(wizzDir) && require('../fs-native').existsSync(wizzDir);
+
+      const { results, exitCode } = await runDoctor({
+        deps: {
+          wizzDir: hasInstall ? wizzDir : null,
+          projectDir,
+          readGlobalSettings: readGlobalSettingsFile,
+          globalSettingsFile: globalSettingsFile(),
+        },
+      });
+
+      await prompts.log.message('wizz doctor — diagnóstico do projeto\n');
+
+      for (const r of results) {
+        const line = `[${STATUS_LABEL[r.status]}] ${r.check}: ${r.detail}`;
+        if (r.status === 'error') {
+          await prompts.log.error(line);
+        } else if (r.status === 'warn') {
+          await prompts.log.warn(line);
+        } else {
+          await prompts.log.success(line);
+        }
+      }
+
+      const errors = results.filter((r) => r.status === 'error').length;
+      const warns = results.filter((r) => r.status === 'warn').length;
+      const oks = results.filter((r) => r.status === 'ok').length;
+
+      await prompts.log.message('');
+      await prompts.log.message(`Resumo: ${oks} ok, ${warns} warn, ${errors} error.`);
+
+      const staleResolved = results.find((r) => r.check === 'resolved' && r.status === 'warn');
+
+      if (errors > 0) {
+        await prompts.log.message(
+          'Próximo passo: corrija os itens com ERROR acima (wizz update repor os arquivos de hook) e rode wizz doctor de novo.',
+        );
+      } else if (warns > 0) {
+        await prompts.log.message(
+          'Próximo passo: os warns são opcionais ou degradam features pontuais; siga a dica de cada bloco quando fizer sentido.',
+        );
+        if (staleResolved) {
+          await prompts.log.message('Para os snapshots de customização, o comando é: wizz resolve');
+        }
+      } else {
+        await prompts.log.message('Tudo certo: instalação íntegra, tools no lugar e sem drift em _wizz/.');
+      }
+
+      process.exit(exitCode);
+    } catch (error) {
+      await prompts.log.error(`wizz doctor falhou: ${error.message}`);
+      if (process.env.WIZZ_DEBUG) {
+        await prompts.log.message(error.stack);
+      }
+      process.exit(1);
+    }
+  },
+};

package/tools/installer/commands/install.js

@@ -56,7 +56,7 @@ module.exports = {
     ['--next <code>', 'Install module <code> from main HEAD (next channel). Repeatable.', (value, prev) => [...(prev || []), value], []],
     [
       '--pin <spec>',
-      'Pin module to a specific tag: --pin CODE=TAG (e.g. --pin bmb=v1.7.0). Repeatable.',
+      'Pin module to a specific tag, optionally verified against a commit SHA after clone: --pin CODE=TAG or CODE=TAG@SHA (e.g. --pin bmb=v1.7.0@abc1234). Repeatable.',
       (value, prev) => [...(prev || []), value],
       [],
     ],

package/tools/installer/commands/resolve.js

@@ -0,0 +1,95 @@
+// resolve.js — comando `wizz resolve` (item 19 da auditoria 2026-09-11).
+//
+// Regenera `_wizz/_resolved/`: o snapshot por skill (base customize.toml +
+// camadas team/user mescladas), o `_config.json` com a config central (merge
+// das 4 camadas, item 29), o `.index.json` com o sha256 de cada entrada e o
+// `.gitignore`. A ativação de agente lê o snapshot e mais
+// nada — nem stat, nem mtime, nem spawn de Python —, então a obsolescência
+// é resolvida na ESCRITA: `wizz install`, `wizz update`, este comando e a
+// skill wizz-customize depois de editar uma camada. Quem só quer saber se
+// algo ficou para trás roda `wizz doctor` (check `resolved`).
+//
+// Registro no wizz-cli.js é automático: o CLI faz readdir de commands/ e
+// registra todo módulo que exporta {command, description, options, action}.
+//
+// De onde ele re-resolve: o pipeline verbatim move cada diretório de skill de
+// `_wizz/` para a pasta do IDE, então o customize.toml que o usuário edita
+// mora em `.claude/skills/<skill>/customize.toml`. É essa cópia que vale
+// (`includeDeployed`), com a cópia staged em `_wizz/` como segunda opção. Os
+// `include = ["../../_shared/..."]` dessas cópias caem no fallback `_shared/`
+// do resolver (tools/installer/core/resolved-includes.js), que acha o arquivo
+// em `_wizz/<módulo>/_shared/`. Sai 1 só quando não há `_wizz/` nenhum, ou
+// quando `--skill` nomeia uma skill sem customize.toml em lugar algum.
+//
+// Nada do que este comando escreve entra no files-manifest.csv: `_resolved/`
+// é artefato gerado e gitignorado, fora do manifesto e fora da detecção de
+// drift. Mesmo sem nenhum customize.toml no projeto o comando ainda passa:
+// poda snapshots órfãos e regrava `.gitignore` + um índice vazio, para que
+// `wizz doctor` não fique comparando com um índice de outra instalação.
+
+const prompts = require('../prompts');
+const fs = require('../fs-native');
+const { findWizzDir } = require('../core/installer');
+const { resolveAll, resolveOne } = require('../core/resolved-customizations');
+
+module.exports = {
+  command: 'resolve',
+  description: 'Regenera os snapshots de customização em _wizz/_resolved/ (todas as skills ou uma)',
+  options: [['--skill <name>', 'Regenera só a skill indicada (nome do diretório, ex.: wizz-maestro)']],
+  action: async (options = {}) => {
+    try {
+      const projectDir = process.cwd();
+      const { wizzDir } = findWizzDir(projectDir);
+
+      if (!fs.existsSync(wizzDir)) {
+        await prompts.log.error('Nenhuma instalação Wizz neste diretório (_wizz/ ausente). Rode wizz install primeiro.');
+        process.exit(1);
+        return;
+      }
+
+      const warn = async (msg) => await prompts.log.warn(msg);
+      const skillName = typeof options.skill === 'string' ? options.skill.trim() : '';
+
+      if (skillName) {
+        const result = await resolveOne(projectDir, wizzDir, skillName, { warn, includeDeployed: true });
+        if (!result.found) {
+          await prompts.log.error(`Skill "${skillName}" não tem customize.toml em lugar nenhum deste projeto.`);
+          await prompts.log.message(`Procurei em:\n  ${(result.searched || []).join('\n  ')}`);
+          process.exit(1);
+          return;
+        }
+        await prompts.log.message(`wizz resolve — ${result.written} snapshot gravado, ${result.skipped} pulado (skill ${skillName}).`);
+        process.exit(0);
+        return;
+      }
+
+      const result = await resolveAll({ projectRoot: projectDir, wizzDir, warn, includeDeployed: true });
+      const configNote = result.config ? '_config.json regravado' : '_config.json NÃO gerado (config.toml ausente ou inválido)';
+      if (result.written === 0 && result.skipped === 0) {
+        await prompts.log.warn('Nenhum customize.toml neste projeto (nem em _wizz/, nem nas pastas de skill dos IDEs).');
+        if (result.pruned.length > 0) {
+          await prompts.log.message(`${result.pruned.length} snapshot(s) órfão(s) removido(s) de _wizz/_resolved/.`);
+        }
+        await prompts.log.message(`${configNote}. Se a instalação parece incompleta, rode: wizz update`);
+        process.exit(0);
+        return;
+      }
+      const parts = [`${result.written} snapshot(s) gravado(s)`, `${result.skipped} pulado(s)`];
+      if (result.pruned.length > 0) parts.push(`${result.pruned.length} órfão(s) removido(s)`);
+      parts.push(configNote);
+      await prompts.log.message(`wizz resolve — ${parts.join(', ')} em _wizz/_resolved/.`);
+      if (result.skipped > 0) {
+        await prompts.log.message(
+          'Skills puladas têm customize.toml inválido: o snapshot delas foi removido e a ativação cai no customize.toml bruto até o arquivo ser corrigido.',
+        );
+      }
+      process.exit(0);
+    } catch (error) {
+      await prompts.log.error(`wizz resolve falhou: ${error.message}`);
+      if (process.env.WIZZ_DEBUG) {
+        await prompts.log.message(error.stack);
+      }
+      process.exit(1);
+    }
+  },
+};