@tavaressan/vetor 0.1.0

package/README.md

@@ -0,0 +1,42 @@
+# Vetor
+
+<div align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Tavaressan/Vetor/master/assets/logo-dark.png">
+    <img src="https://raw.githubusercontent.com/Tavaressan/Vetor/master/assets/logo.png" alt="Vetor Logo" width="320" />
+  </picture>
+</div>
+
+[![npm version](https://img.shields.io/npm/v/@tavaressan/vetor.svg)](https://www.npmjs.com/package/@tavaressan/vetor)
+[![license](https://img.shields.io/npm/l/@tavaressan/vetor.svg)](https://github.com/Tavaressan/Vetor/blob/master/LICENSE)
+
+Instalador do **Vetor**: plugin de skills para automação de workflow de desenvolvimento no Claude Code, Codex e outras engines de agente.
+
+Este pacote é o instalador de linha de comando. As skills em si (ideação, coordenação de issues, fix loop, ship, guardian) vivem no [repositório principal](https://github.com/Tavaressan/Vetor) — leia o README de lá para o que o Vetor faz.
+
+## Instalação
+
+```
+npm install -g @tavaressan/vetor
+vetor install
+```
+
+**Pré-requisitos:** [Deno](https://deno.com) e `gh` CLI autenticado no PATH, Git com suporte a `git worktree`.
+
+## Uso
+
+```
+vetor install     # instala o Vetor no projeto atual
+vetor update       # sincroniza a instalação existente com a fonte
+vetor status       # mostra o status da instalação por engine
+vetor uninstall    # remove os arquivos instalados pelo Vetor (pede confirmação)
+vetor --help       # lista os comandos disponíveis
+```
+
+## Documentação
+
+Skills, arquitetura, configuração e compatibilidade multi-engine: [wiki do repositório principal](https://github.com/Tavaressan/Vetor/tree/master/wiki).
+
+## Licença
+
+[MIT](https://github.com/Tavaressan/Vetor/blob/master/LICENSE) © 2026 Vitor Tavares Chaves.

package/bin/vetor.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+'use strict';
+
+const { run } = require('../lib/router.js');
+
+run(process.argv.slice(2));

package/lib/banner.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const LOGO_LINES = [
+  '██╗   ██╗███████╗████████╗ ██████╗ ██████╗',
+  '██║   ██║██╔════╝╚══██╔══╝██╔═══██╗██╔══██╗',
+  '██║   ██║█████╗     ██║   ██║   ██║██████╔╝',
+  '╚██╗ ██╔╝██╔══╝     ██║   ██║   ██║██╔══██╗',
+  ' ╚████╔╝ ███████╗   ██║   ╚██████╔╝██║  ██║',
+  '  ╚═══╝  ╚══════╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝',
+];
+
+const LOGO_COLOR = '\x1b[36m';
+const RESET = '\x1b[0m';
+
+// Só aplica cor quando stdout é um terminal e a convenção NO_COLOR
+// (https://no-color.org/) não está definida. Isso evita poluir saídas
+// redirecionadas para arquivo/pipe (CI, `vetor --help > log`).
+function shouldUseColor() {
+  return Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+}
+
+function printBanner() {
+  const useColor = shouldUseColor();
+
+  for (const line of LOGO_LINES) {
+    console.info(useColor ? `${LOGO_COLOR}${line}${RESET}` : line);
+  }
+
+  console.info('');
+}
+
+module.exports = {
+  printBanner,
+  LOGO_LINES,
+};

package/lib/commands/install.js

@@ -0,0 +1,71 @@
+'use strict';
+
+const { detectEngines: defaultDetectEngines } = require('../installer/detector.js');
+const { runInstallPrompts: defaultRunInstallPrompts } = require('../installer/prompts.js');
+const { installFiles: defaultInstallFiles } = require('../installer/writer.js');
+
+/**
+ * Comando `install`: detecta engines suportadas no projeto-alvo (ver `ENGINES` em
+ * `installer/detector.js`) e oferece seleção interativa
+ * com as engines detectadas pré-marcadas. A detecção é só sugestão inicial: nenhuma
+ * engine é instalada sem confirmação explícita do usuário via `runInstallPrompts`.
+ *
+ * Após a confirmação, copia `skills/`/`agents/`/`hooks/` (ou a árvore nativa da engine,
+ * quando existir) para o destino de cada engine selecionada via `installFiles` (writer,
+ * issue #255, tradução de formato por engine revisada na #283), gravando manifesto de hash
+ * por arquivo para updates seguros mais tarde. Engine sem destino de arquivo confirmado
+ * (`enginesSkipped`) é reportada ao usuário em vez de silenciosamente ignorada.
+ *
+ * `detectEngines`/`runInstallPrompts`/`installFiles`/`input`/`output` são injetáveis para
+ * testes.
+ */
+async function install(cwd = process.cwd(), options = {}) {
+  const detectEngines = options.detectEngines ?? defaultDetectEngines;
+  const runInstallPrompts = options.runInstallPrompts ?? defaultRunInstallPrompts;
+  const installFiles = options.installFiles ?? defaultInstallFiles;
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+
+  const engines = detectEngines(cwd);
+  const detectedNames = engines.filter((engine) => engine.detected).map((engine) => engine.name);
+
+  if (detectedNames.length > 0) {
+    console.info(`Engines detectadas: ${detectedNames.join(', ')}.`);
+  } else {
+    console.info('Nenhuma engine detectada no diretório atual.');
+  }
+
+  const selected = await runInstallPrompts(engines, { input, output });
+
+  if (selected.length === 0) {
+    console.info('Nenhuma engine selecionada. Instalação cancelada.');
+    return;
+  }
+
+  console.info(`Engines selecionadas: ${selected.map((engine) => engine.name).join(', ')}.`);
+
+  const {
+    copied,
+    skipped,
+    warnings = [],
+    enginesSkipped = [],
+  } = installFiles({ projectRoot: cwd, engines: selected });
+  console.info(`${copied.length} arquivo(s) copiado(s).`);
+  if (skipped.length > 0) {
+    console.info(
+      `${skipped.length} arquivo(s) não sobrescrito(s) (editado(s) pelo usuário ou não gerado(s) pelo instalador).`,
+    );
+  }
+  for (const warning of warnings) {
+    console.info(`Aviso: ${warning}`);
+  }
+  // Issue #283: engine selecionada sem destino de arquivo confirmado (ex.: Antigravity) não
+  // falha nem copia nada — mas precisa ser visível para o usuário, não silenciosa.
+  for (const engine of enginesSkipped) {
+    console.info(
+      `${engine.name}: nenhum arquivo instalado (sem convenção de projeto confirmada para esta engine ainda).`,
+    );
+  }
+}
+
+module.exports = { install };

package/lib/commands/status.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { ENGINES } = require('../installer/detector.js');
+const { readManifest: defaultReadManifest, hashFile: defaultHashFile } = require('../installer/manifest.js');
+
+const ENGINE_NAME_BY_ID = new Map(ENGINES.map((engine) => [engine.id, engine.name]));
+
+const STATE_LABEL = {
+  ok: '[ok]',
+  missing: '[ausente]',
+  modified: '[modificado]',
+};
+
+function classify(cwd, key, entry, hashFile) {
+  const filePath = path.join(cwd, ...key.split('/'));
+  if (!fs.existsSync(filePath)) return 'missing';
+  return hashFile(filePath) === entry.sha256 ? 'ok' : 'modified';
+}
+
+/**
+ * Comando `status` (issue #302): classifica cada arquivo do manifesto de instalação
+ * (`.vetor/install-manifest.json`) comparando o hash atual em disco com o hash gravado —
+ * `ok` (íntegro), `modificado` (hash diverge do manifesto) ou `ausente` (arquivo sumiu do
+ * disco). Somente leitura: nenhum arquivo é criado, alterado ou apagado.
+ *
+ * `readManifest`/`hashFile` são injetáveis para testes.
+ */
+function status(cwd = process.cwd(), options = {}) {
+  const readManifest = options.readManifest ?? defaultReadManifest;
+  const hashFile = options.hashFile ?? defaultHashFile;
+
+  const manifest = readManifest(cwd);
+  const entries = Object.entries(manifest.files);
+
+  if (entries.length === 0) {
+    console.info('Vetor não está instalado neste projeto.');
+    return;
+  }
+
+  const byEngine = new Map();
+  for (const [key, entry] of entries) {
+    const engineName = ENGINE_NAME_BY_ID.get(entry.engine) ?? entry.engine;
+    const state = classify(cwd, key, entry, hashFile);
+    if (!byEngine.has(engineName)) byEngine.set(engineName, []);
+    byEngine.get(engineName).push({ key, state });
+  }
+
+  for (const [engineName, files] of byEngine) {
+    console.info(`${engineName}:`);
+    for (const { key, state } of files) {
+      console.info(`  ${STATE_LABEL[state]} ${key}`);
+    }
+  }
+}
+
+module.exports = { status };

package/lib/commands/uninstall.js

@@ -0,0 +1,119 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const readline = require('node:readline');
+
+const {
+  manifestPathFor,
+  readManifest: defaultReadManifest,
+  writeManifest: defaultWriteManifest,
+  hashFile: defaultHashFile,
+} = require('../installer/manifest.js');
+
+/**
+ * Confirmação simples (s/N) antes da remoção. Sessão não-interativa (sem TTY) não tem como
+ * obter confirmação explícita — cancela por padrão, mesma postura de `runInstallPrompts`
+ * (installer/prompts.js) para seleção vazia em ambiente não-interativo.
+ */
+function confirmUninstall(message, { input = process.stdin, output = process.stdout, isTTY } = {}) {
+  const interactive = isTTY ?? input.isTTY ?? false;
+
+  if (!interactive) {
+    output.write(`${message} Sessão não-interativa: cancelado (confirmação explícita é obrigatória).\n`);
+    return Promise.resolve(false);
+  }
+
+  const rl = readline.createInterface({ input, output });
+  return new Promise((resolve) => {
+    rl.question(`${message} [s/N]: `, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === 's');
+    });
+  });
+}
+
+/**
+ * Comando `uninstall` (issue #303): remove do projeto-alvo os arquivos gerenciados pelo
+ * manifesto de instalação (`.vetor/install-manifest.json`) — única operação destrutiva dos
+ * três comandos pendentes de `router.js`, por isso pede confirmação antes de apagar algo.
+ *
+ * Só remove entrada cujo hash atual em disco ainda bate com o manifestado (não editada pelo
+ * usuário desde a instalação). Entrada com hash divergente, ou cujo path resolvido cai fora
+ * de `projectRoot` (manifesto corrompido/adulterado), é preservada — nunca apagada
+ * silenciosamente — e continua registrada no manifesto. Entrada já ausente do disco é só
+ * descartada do manifesto (nada físico para preservar).
+ *
+ * Se nenhuma entrada sobrar após a rodada, o próprio arquivo de manifesto é removido — não
+ * um manifesto com `files: {}` — para que `status`/`update` voltem a reportar "não
+ * instalado" em vez de uma instalação vazia.
+ *
+ * `readManifest`/`writeManifest`/`hashFile`/`confirm`/`input`/`output` são injetáveis para
+ * testes.
+ */
+async function uninstall(cwd = process.cwd(), options = {}) {
+  const readManifest = options.readManifest ?? defaultReadManifest;
+  const writeManifest = options.writeManifest ?? defaultWriteManifest;
+  const hashFile = options.hashFile ?? defaultHashFile;
+  const confirm = options.confirm ?? confirmUninstall;
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+
+  const manifest = readManifest(cwd);
+  const entries = Object.entries(manifest.files);
+
+  if (entries.length === 0) {
+    console.info('Nada para desinstalar: Vetor não está instalado neste projeto.');
+    return;
+  }
+
+  console.info(`${entries.length} arquivo(s) gerenciado(s) encontrado(s).`);
+  const confirmed = await confirm('Remover todos os arquivos instalados pelo Vetor?', { input, output });
+  if (!confirmed) {
+    console.info('Desinstalação cancelada.');
+    return;
+  }
+
+  const removed = [];
+  const preserved = [];
+  const remainingFiles = {};
+
+  for (const [key, entry] of entries) {
+    const destFile = path.resolve(cwd, ...key.split('/'));
+    const relative = path.relative(cwd, destFile);
+    const isInsideProject = relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+
+    if (!isInsideProject) {
+      preserved.push({ path: key, reason: 'outside-project-root' });
+      remainingFiles[key] = entry;
+      continue;
+    }
+
+    if (!fs.existsSync(destFile)) {
+      preserved.push({ path: key, reason: 'already-missing' });
+      continue;
+    }
+
+    if (hashFile(destFile) !== entry.sha256) {
+      preserved.push({ path: key, reason: 'user-modified' });
+      remainingFiles[key] = entry;
+      continue;
+    }
+
+    fs.unlinkSync(destFile);
+    removed.push(key);
+  }
+
+  console.info(`${removed.length} arquivo(s) removido(s).`);
+  if (preserved.length > 0) {
+    console.info(`${preserved.length} arquivo(s) preservado(s) (editado(s) pelo usuário ou já ausente(s)).`);
+  }
+
+  if (Object.keys(remainingFiles).length > 0) {
+    writeManifest(cwd, { ...manifest, files: remainingFiles });
+  } else {
+    fs.rmSync(manifestPathFor(cwd), { force: true });
+  }
+}
+
+module.exports = { uninstall, confirmUninstall };

package/lib/commands/update.js

@@ -0,0 +1,63 @@
+'use strict';
+
+const { ENGINES } = require('../installer/detector.js');
+const { installFiles: defaultInstallFiles } = require('../installer/writer.js');
+const { readManifest: defaultReadManifest } = require('../installer/manifest.js');
+
+const ENGINE_NAME_BY_ID = new Map(ENGINES.map((engine) => [engine.id, engine.name]));
+
+/**
+ * Comando `update`: sincroniza a instalação existente sem repetir a detecção/seleção de
+ * engines do `install` (issue #301) — as engines a atualizar são derivadas do próprio
+ * manifesto (`.vetor/install-manifest.json`, campo `engine` de cada entrada), nunca de
+ * `detectEngines()`, para não arriscar instalar numa engine que o usuário nunca selecionou
+ * (ou deixar de atualizar uma que ele selecionou).
+ *
+ * A política de "update seguro" por arquivo (ausente copia, hash bate sincroniza,
+ * unmanaged/user-modified nunca sobrescreve) já vive em `installFiles`/`copyManagedFile` —
+ * este comando só monta os argumentos e reporta o resultado.
+ *
+ * Arquivo que constava no manifesto antes desta rodada e não aparece em `copied` nem
+ * `skipped` depois é órfão (fonte removeu o arquivo, ex.: skill descontinuada): reportado,
+ * nunca apagado — deleção fica reservada ao comando `uninstall`.
+ *
+ * `readManifest`/`installFiles` são injetáveis para testes.
+ */
+function update(cwd = process.cwd(), options = {}) {
+  const readManifest = options.readManifest ?? defaultReadManifest;
+  const installFiles = options.installFiles ?? defaultInstallFiles;
+
+  const manifestBefore = readManifest(cwd);
+  const keysBefore = Object.keys(manifestBefore.files);
+
+  if (keysBefore.length === 0) {
+    console.info('Nenhuma instalação encontrada neste projeto. Rode "vetor install" primeiro.');
+    return;
+  }
+
+  const engineIds = [...new Set(Object.values(manifestBefore.files).map((entry) => entry.engine))];
+  const engines = engineIds.map((id) => ({ id, name: ENGINE_NAME_BY_ID.get(id) ?? id }));
+
+  console.info(`Atualizando engines: ${engines.map((engine) => engine.name).join(', ')}.`);
+
+  const { copied, skipped, warnings = [] } = installFiles({ projectRoot: cwd, engines });
+
+  console.info(`${copied.length} arquivo(s) sincronizado(s).`);
+  if (skipped.length > 0) {
+    console.info(
+      `${skipped.length} arquivo(s) não sobrescrito(s) (editado(s) pelo usuário ou não gerado(s) pelo instalador).`,
+    );
+  }
+  for (const warning of warnings) {
+    console.info(`Aviso: ${warning}`);
+  }
+
+  const touched = new Set([...copied, ...skipped.map((entry) => entry.path)]);
+  for (const key of keysBefore) {
+    if (!touched.has(key)) {
+      console.info(`${key}: não existe mais na fonte (não removido — use "vetor uninstall" se quiser limpar).`);
+    }
+  }
+}
+
+module.exports = { update };

package/lib/installer/command-exists.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Verifica se um comando existe em algum diretório do PATH, sem executá-lo — apenas
+ * resolve candidatos no filesystem (evita spawn/child_process e efeitos colaterais).
+ * No Windows, cruza cada diretório do PATH com as extensões de PATHEXT (`.cmd`, `.exe`, ...),
+ * já que CLIs instaladas via npm (`claude`, `codex`, `opencode`) viram shims `.cmd`.
+ *
+ * `env` é injetável para testes determinísticos (ex.: PATH vazio → nenhum comando encontrado).
+ */
+function commandExists(command, env = process.env) {
+  const pathEnv = env.PATH ?? env.Path ?? '';
+  const dirs = pathEnv.split(path.delimiter).filter(Boolean);
+  const extensions = process.platform === 'win32'
+    ? (env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM').split(';')
+    : [''];
+
+  for (const dir of dirs) {
+    for (const ext of extensions) {
+      const candidate = path.join(dir, command + ext);
+      if (fs.existsSync(candidate)) return true;
+    }
+  }
+  return false;
+}
+
+module.exports = { commandExists };

package/lib/installer/cursor-hooks.js

@@ -0,0 +1,181 @@
+'use strict';
+
+// Tradução de hooks/hooks.json (formato Claude Code, fonte agnóstica deste repositório) para
+// o schema nativo do Cursor (`.cursor/hooks.json`), confirmado contra a documentação oficial:
+// - cursor.com/docs/hooks (schema, `version`, `hooks.<evento>[]` com `command`/`matcher`/
+//   `timeout`, lista de eventos suportados)
+// - cursor.com/docs/reference/third-party-hooks (mapeamento de nomes de evento e de tool entre
+//   Claude Code e Cursor)
+// Ver wiki/Compatibilidade-Cursor.md, seção Hooks, para o achado completo (issue #284).
+//
+// Cobre só os eventos usados por hooks/hooks.json deste repositório hoje (YAGNI) — não é um
+// tradutor genérico para qualquer hooks.json arbitrário de terceiros.
+
+// cursor.com/docs/reference/third-party-hooks#hook-step-mapping — só os eventos que essa
+// tabela documenta como suportados; eventos sem linha na tabela (ex.: WorktreeCreate, que nem
+// existe no Claude Code como conceito de hook nativo do produto, só neste plugin) não têm
+// equivalente e são reportados em `dropped`.
+const EVENT_NAME_MAP = {
+  PreToolUse: 'preToolUse',
+  PostToolUse: 'postToolUse',
+  UserPromptSubmit: 'beforeSubmitPrompt',
+  Stop: 'stop',
+  SubagentStop: 'subagentStop',
+  SessionStart: 'sessionStart',
+  SessionEnd: 'sessionEnd',
+  PreCompact: 'preCompact',
+};
+
+// cursor.com/docs/reference/third-party-hooks#tool-name-mapping. Edit e Write mapeiam para o
+// mesmo tool Cursor ("Write") — o Cursor não distingui edição em lugar de escrita nova.
+const TOOL_NAME_MAP = {
+  Bash: 'Shell',
+  Read: 'Read',
+  Write: 'Write',
+  Edit: 'Write',
+  Grep: 'Grep',
+  Task: 'Task',
+};
+
+// Eventos cujo `matcher` do Claude Code filtra por NOME de tool — únicos onde o vocabulário de
+// TOOL_NAME_MAP se aplica. Outros eventos com matcher (ex.: SubagentStop, que no Claude Code
+// filtra por nome customizado de subagente) têm semântica diferente da do Cursor (que filtra
+// por `subagent_type` fixo: generalPurpose/explore/shell) e não são traduzíveis — ver
+// `translateHooksForCursor`.
+const TOOL_MATCHER_EVENTS = new Set(['PreToolUse', 'PostToolUse']);
+
+// Lista completa de eventos documentados em cursor.com/docs/hooks (Agent hooks + Tab hooks +
+// App lifecycle hook) — usada por `validateCursorHooksSchema` para rejeitar nomes de evento
+// inventados/não suportados, não só os que este tradutor emite.
+const CURSOR_EVENT_NAMES = new Set([
+  'sessionStart',
+  'sessionEnd',
+  'preToolUse',
+  'postToolUse',
+  'postToolUseFailure',
+  'subagentStart',
+  'subagentStop',
+  'beforeShellExecution',
+  'afterShellExecution',
+  'beforeMCPExecution',
+  'afterMCPExecution',
+  'beforeReadFile',
+  'afterFileEdit',
+  'beforeSubmitPrompt',
+  'preCompact',
+  'stop',
+  'afterAgentResponse',
+  'afterAgentThought',
+  'beforeTabFileRead',
+  'afterTabFileEdit',
+  'workspaceOpen',
+]);
+
+/**
+ * Traduz o `matcher` de PreToolUse/PostToolUse (nomes de tool do Claude Code, string "|"-
+ * separated) para o vocabulário de tool do Cursor, removendo duplicatas geradas por tools que
+ * colapsam no mesmo tool Cursor (Edit/Write -> Write). Tokens fora de TOOL_NAME_MAP passam
+ * inalterados (ex.: um nome de tool MCP customizado).
+ */
+function translateToolMatcher(matcher) {
+  const tokens = matcher.split('|').map((token) => TOOL_NAME_MAP[token] ?? token);
+  return [...new Set(tokens)].join('|');
+}
+
+/** Achata uma entrada `{matcher?, hooks:[{type,command,timeout}]}` do Claude Code em uma ou mais entradas planas `{command,timeout?,matcher?}` do Cursor. */
+function translateHookEntry(event, entry, canTranslateMatcher) {
+  const matcher = entry.matcher;
+  return (entry.hooks ?? []).map((inner) => {
+    const translated = { command: inner.command };
+    if (typeof inner.timeout === 'number') translated.timeout = inner.timeout;
+    if (matcher && canTranslateMatcher) {
+      translated.matcher = translateToolMatcher(matcher);
+    }
+    return translated;
+  });
+}
+
+/**
+ * Traduz `hooks/hooks.json` (formato Claude Code) para o schema nativo do Cursor
+ * (`.cursor/hooks.json`). Retorna `{ hooks, dropped }`:
+ * - `hooks`: objeto pronto para `JSON.stringify` em `.cursor/hooks.json` (com `version: 1`).
+ * - `dropped`: eventos/matchers da fonte sem equivalente fiel no Cursor — nunca lançado como
+ *   erro (perda de cobertura parcial não deve travar a instalação), mas sempre reportado para
+ *   quem for decidir o que fazer com o gap (ver wiki/Compatibilidade-Cursor.md).
+ */
+function translateHooksForCursor(sourceHooksJson) {
+  const sourceEvents = sourceHooksJson?.hooks ?? {};
+  const translatedHooks = {};
+  const dropped = [];
+
+  for (const [event, entries] of Object.entries(sourceEvents)) {
+    const cursorEvent = EVENT_NAME_MAP[event];
+    if (!cursorEvent) {
+      dropped.push({ event, reason: 'no-cursor-equivalent' });
+      continue;
+    }
+
+    const canTranslateMatcher = TOOL_MATCHER_EVENTS.has(event);
+    const hasUntranslatableMatcher = entries.some(
+      (entry) => entry.matcher && !canTranslateMatcher,
+    );
+    if (hasUntranslatableMatcher) {
+      dropped.push({ event, reason: 'matcher-not-translatable' });
+    }
+
+    translatedHooks[cursorEvent] = entries.flatMap((entry) =>
+      translateHookEntry(event, entry, canTranslateMatcher),
+    );
+  }
+
+  return { hooks: { version: 1, hooks: translatedHooks }, dropped };
+}
+
+/**
+ * Validação mínima do `.cursor/hooks.json` gerado contra o schema documentado em
+ * cursor.com/docs/hooks (nomes de evento válidos, `version` numérica, `command` obrigatório
+ * por entrada). Não é um validador de JSON Schema genérico — cobre só os campos que este
+ * tradutor emite e os erros mais prováveis de regressão (evento inventado, entrada sem
+ * `command`), suficiente para o critério de aceite da issue #284 sem depender de uma lib
+ * externa (este pacote não tem dependências — ver cli/package.json).
+ */
+function validateCursorHooksSchema(hooksJson) {
+  const errors = [];
+
+  if (typeof hooksJson?.version !== 'number') {
+    errors.push('"version" ausente ou não-numérico — cursor.com/docs/hooks exige um inteiro positivo (ex.: 1)');
+  }
+
+  const hooks = hooksJson?.hooks;
+  if (hooks && typeof hooks === 'object') {
+    for (const [event, entries] of Object.entries(hooks)) {
+      if (!CURSOR_EVENT_NAMES.has(event)) {
+        errors.push(`evento "${event}" não está na lista documentada em cursor.com/docs/hooks`);
+        continue;
+      }
+      for (const [index, entry] of (entries ?? []).entries()) {
+        if (typeof entry?.command !== 'string' || entry.command.length === 0) {
+          errors.push(`hooks.${event}[${index}] sem "command" (campo obrigatório)`);
+        }
+        if ('timeout' in entry && typeof entry.timeout !== 'number') {
+          errors.push(`hooks.${event}[${index}].timeout precisa ser numérico`);
+        }
+        if ('matcher' in entry && typeof entry.matcher !== 'string') {
+          errors.push(`hooks.${event}[${index}].matcher precisa ser string`);
+        }
+      }
+    }
+  } else {
+    errors.push('"hooks" ausente ou não é um objeto');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+module.exports = {
+  translateHooksForCursor,
+  validateCursorHooksSchema,
+  EVENT_NAME_MAP,
+  TOOL_NAME_MAP,
+  CURSOR_EVENT_NAMES,
+};