@tavaressan/vetor 0.1.0

package/lib/installer/detector.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { commandExists } = require('./command-exists.js');
+
+function isDirectory(targetPath) {
+  try {
+    return fs.statSync(targetPath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isFile(targetPath) {
+  try {
+    return fs.statSync(targetPath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+// Escopo da issue #254: só as 4 engines já suportadas pelo Vetor hoje (ver wiki/Compatibilidade-*.md
+// para os arquivos-âncora de cada uma). Cursor foi investigado e adicionado na issue #256.
+//
+// Premissa declarada: não há convenção de arquivo-âncora de projeto documentada para Antigravity
+// neste repositório (sem equivalente a `.claude/`, `AGENTS.md` ou `.opencode/` encontrado em
+// wiki/Compatibilidade-Antigravity.md nem na estrutura do repo) — a detecção de Antigravity usa
+// somente o comando `agy` no PATH (nome confirmado em scripts/lib/delegation-runtime.ts).
+const ENGINES = [
+  {
+    id: 'claude-code',
+    name: 'Claude Code',
+    detect: (root, env) => isDirectory(path.join(root, '.claude')) || commandExists('claude', env),
+  },
+  {
+    id: 'codex',
+    name: 'Codex',
+    detect: (root, env) => isFile(path.join(root, 'AGENTS.md')) || commandExists('codex', env),
+  },
+  {
+    id: 'opencode',
+    name: 'OpenCode',
+    detect: (root, env) =>
+      isDirectory(path.join(root, '.opencode')) || commandExists('opencode', env),
+  },
+  {
+    id: 'antigravity',
+    name: 'Antigravity',
+    detect: (_root, env) => commandExists('agy', env),
+  },
+  // Issue #256 (ver wiki/Compatibilidade-Cursor.md): `.cursor/` é a âncora de projeto
+  // confirmada contra a doc oficial (rules/skills/agents/hooks vivem todos ali). O comando
+  // de PATH usado é `cursor-agent`, não `agent` — `agent` é o nome "primary" hoje na doc do
+  // CLI, mas é genérico demais e colide com facilidade com binários não relacionados ao
+  // Cursor; `cursor-agent` é mantido como symlink "legacy" pelo próprio script oficial de
+  // instalação (`cursor.com/install`, verificado nesta investigação) e carrega o mesmo sinal
+  // com risco de falso positivo muito menor.
+  {
+    id: 'cursor',
+    name: 'Cursor',
+    detect: (root, env) =>
+      isDirectory(path.join(root, '.cursor')) || commandExists('cursor-agent', env),
+  },
+];
+
+/**
+ * Detecta engines suportadas no projeto-alvo: arquivo/diretório-âncora já existente,
+ * ou comando disponível no PATH. Nunca lança erro — ausência total de sinal apenas
+ * resulta em `detected: false` para todas as entradas.
+ *
+ * `env` é injetável para testes determinísticos (ex.: PATH vazio).
+ */
+function detectEngines(root = process.cwd(), env = process.env) {
+  return ENGINES.map(({ id, name, detect }) => ({ id, name, detected: detect(root, env) }));
+}
+
+module.exports = { detectEngines, ENGINES };

package/lib/installer/manifest.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+// Correção pós-code-review da PR #282 (issue #256): o manifesto vivia em
+// `.claude/vetor/install-manifest.json`, mas `writeManifest`/`readManifest` fazem
+// `mkdirSync(dirname(manifestPath), { recursive: true })` — criar `.claude/` como efeito
+// colateral de QUALQUER instalação (mesmo uma "Cursor-exclusiva", sem Claude Code
+// envolvido) polui `detectEngines()`: uma segunda execução de `vetor install` passaria a
+// reportar `claude-code: detected: true` falsamente, só por causa do diretório-âncora que
+// o próprio manifesto criou. `.vetor/` na raiz do projeto-alvo (fora de `.claude/`) não é
+// âncora de detecção de nenhuma engine hoje (ver `detector.js`) nem previsivelmente no
+// futuro, então não contamina a detecção de nenhuma delas.
+//
+// Decisão de migração (issue #285): este já é o segundo path usado por
+// MANIFEST_RELATIVE_PATH nesta mesma feature (o primeiro, `.claude/vetor/...` acima, durou
+// só até a PR #282) — sem nenhuma lógica de migração implementada para quem tivesse
+// instalado com o path antigo. Avaliado e decidido não implementar migração automática
+// (opção b, não a): até a data desta issue, `vetor install`/`installFiles` nunca foi
+// publicado em nenhum release/pacote npm — não existe usuário real com manifesto gravado
+// no path antigo para migrar. A primeira versão publicada já nasce com este path como
+// definitivo. Se `MANIFEST_RELATIVE_PATH` precisar mudar de novo DEPOIS de uma versão
+// publicada, essa migração (ler o path antigo se o novo não existir, ou equivalente) passa
+// a ser obrigatória — o que não se aplicou nas duas mudanças anteriores continua não se
+// aplicando por acidente.
+const MANIFEST_RELATIVE_PATH = path.join('.vetor', 'install-manifest.json');
+
+function manifestPathFor(projectRoot) {
+  return path.join(projectRoot, MANIFEST_RELATIVE_PATH);
+}
+
+function hashFile(filePath) {
+  return hashContent(fs.readFileSync(filePath));
+}
+
+/** Hash de conteúdo já em memória (ex.: bytes traduzidos, nunca lidos de volta do disco antes
+ * de gravar) — usado quando o arquivo gravado no destino não é uma cópia byte-a-byte da fonte
+ * (ex.: `.cursor/hooks.json` traduzido, ver `writer.js`/`cursor-hooks.js`, issue #284). */
+function hashContent(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Lê o manifesto de instalação do projeto-alvo. Ausência do arquivo (primeira instalação)
+ * não é erro — retorna manifesto vazio.
+ */
+function readManifest(projectRoot) {
+  const manifestPath = manifestPathFor(projectRoot);
+  try {
+    const raw = fs.readFileSync(manifestPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return { version: 1, files: {}, ...parsed };
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return { version: 1, files: {} };
+    }
+    throw error;
+  }
+}
+
+function writeManifest(projectRoot, manifest) {
+  const manifestPath = manifestPathFor(projectRoot);
+  fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+}
+
+module.exports = {
+  MANIFEST_RELATIVE_PATH,
+  manifestPathFor,
+  hashFile,
+  hashContent,
+  readManifest,
+  writeManifest,
+};

package/lib/installer/prompts.js

@@ -0,0 +1,97 @@
+'use strict';
+
+const readline = require('node:readline');
+
+/**
+ * Deriva o estado inicial do checkbox a partir da detecção: engine detectada nasce
+ * pré-marcada, não detectada nasce desmarcada. Função pura — o usuário ainda pode alterar
+ * cada item na interação; a detecção é só sugestão inicial, nunca decide a instalação sozinha.
+ */
+function buildEngineChoices(engines) {
+  return engines.map((engine) => ({ ...engine, checked: engine.detected }));
+}
+
+function renderChoices(choices) {
+  return choices
+    .map((choice, index) => {
+      const box = choice.checked ? '[x]' : '[ ]';
+      const suffix = choice.detected ? ' (detectada)' : '';
+      return `  ${index + 1}. ${box} ${choice.name}${suffix}`;
+    })
+    .join('\n');
+}
+
+/**
+ * Prompt interativo de seleção de engines: checkbox por número (sem dependência externa),
+ * engines detectadas pré-marcadas. Usuário digita números para alternar marcação e confirma
+ * com Enter (linha vazia) — exige ao menos uma engine marcada para aceitar a confirmação.
+ *
+ * Em sessão não-interativa (sem TTY) não há como obter confirmação explícita do usuário:
+ * imprime a detecção e resolve com seleção vazia, sem marcar nenhuma engine por padrão.
+ */
+function runInstallPrompts(
+  engines,
+  { input = process.stdin, output = process.stdout, isTTY } = {},
+) {
+  const choices = buildEngineChoices(engines);
+  const interactive = isTTY ?? input.isTTY ?? false;
+
+  output.write('Selecione as engines para instalar:\n');
+  output.write(renderChoices(choices) + '\n');
+
+  if (!interactive) {
+    output.write(
+      '\nSessão não-interativa: nenhuma engine selecionada automaticamente ' +
+        '(confirmação explícita é obrigatória).\n',
+    );
+    return Promise.resolve([]);
+  }
+
+  const rl = readline.createInterface({ input, output });
+
+  return new Promise((resolve) => {
+    function prompt() {
+      rl.question(
+        '\nDigite números para marcar/desmarcar (ex.: 1,3), Enter para confirmar, ' +
+          '"q" para cancelar: ',
+        (answer) => {
+          const trimmed = answer.trim();
+
+          if (trimmed.toLowerCase() === 'q') {
+            rl.close();
+            resolve([]);
+            return;
+          }
+
+          if (trimmed === '') {
+            const selected = choices.filter((choice) => choice.checked);
+            if (selected.length === 0) {
+              output.write('Selecione pelo menos uma engine antes de confirmar.\n');
+              prompt();
+              return;
+            }
+            rl.close();
+            resolve(selected);
+            return;
+          }
+
+          const indexes = trimmed
+            .split(',')
+            .map((part) => Number.parseInt(part.trim(), 10) - 1)
+            .filter((index) => Number.isInteger(index) && index >= 0 && index < choices.length);
+
+          for (const index of indexes) {
+            choices[index].checked = !choices[index].checked;
+          }
+
+          output.write('\n' + renderChoices(choices) + '\n');
+          prompt();
+        },
+      );
+    }
+
+    prompt();
+  });
+}
+
+module.exports = { buildEngineChoices, runInstallPrompts };

package/lib/installer/writer.js

@@ -0,0 +1,382 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { hashFile, hashContent, readManifest, writeManifest } = require('./manifest.js');
+const { translateHooksForCursor } = require('./cursor-hooks.js');
+
+// Decisão de escopo (issue #255, revisada na #283): destino nativo por engine é o
+// diretório-âncora já usado pela própria detecção (detector.js usa `.claude`/`.opencode`/
+// `.cursor` como âncora; `.codex` segue a mesma convenção por consistência, mesmo sem
+// detecção por diretório própria hoje).
+//
+// Cursor (#256, ver wiki/Compatibilidade-Cursor.md): `.cursor/skills/` e `.cursor/agents/`
+// são descobertos nativamente pelo Cursor sem tradução de formato (SKILL.md e agents/*.md já
+// são agnósticos de engine desde #251) — cópia direta funciona de verdade para essas duas
+// pastas. `hooks/` é tratado à parte (ver `installCursorHooks` abaixo, issue #284): o Cursor
+// só carrega hooks de projeto em `.cursor/hooks.json` (arquivo único na raiz, schema próprio
+// em camelCase), nunca `.cursor/hooks/hooks.json` (diretório, o formato que este writer copia
+// para as demais engines) — por isso `hooks/hooks.json` é traduzido em memória
+// (`cursor-hooks.js`) e gravado como arquivo único em vez de entrar no loop genérico de
+// `SOURCE_DIRS` abaixo.
+//
+// Redundância conhecida e aceita (YAGNI, achado #4 do code-review da PR #282): quando
+// Claude Code E Cursor estão ambos selecionados, `skills/`/`agents/` são copiados tanto
+// para `.claude/` quanto para `.cursor/`, mesmo a wiki confirmando que o Cursor já lê
+// `.claude/skills/`/`.claude/agents/` nativamente para compatibilidade (ver
+// wiki/Compatibilidade-Cursor.md). Deduplicar exigiria decidir qual engine é a "fonte da
+// verdade" em disco e como reagir a edição de só uma das cópias — complexidade/risco maior
+// que o custo de ter uma cópia extra em disco. Não implementado de propósito.
+//
+// Antigravity (#283): removida de ENGINE_DEST_DIR. `.antigravity` era uma convenção
+// assumida sem confirmação (ver detector.js, que já não usa esse diretório como âncora de
+// detecção — só o comando `agy` no PATH). Investigação nesta issue com o CLI `agy` real
+// instalado (`agy plugin validate .`, `agy plugin list`) confirma que a distribuição de
+// plugin do Antigravity não é "copiar skills/agents/hooks para um diretório de projeto":
+// é `agy plugin install/import` lendo um `plugin.json` na RAIZ do plugin (mesmo schema
+// `antigravity.google/schemas/v1/plugin.json` já usado por este repo) e registrando o
+// import num manifesto global do usuário (`~/.gemini/antigravity-cli/settings.json`), não
+// num diretório de projeto-alvo. Não existe hoje um segundo mecanismo de "instalação
+// project-local" documentado ou observado para o Antigravity equivalente a `.claude/` do
+// Claude Code — copiar arquivos para um `.antigravity/` inventado produziria uma pasta que
+// o Antigravity nunca lê. Engine sem destino conhecido cai em `enginesSkipped` (ver
+// `installFiles`), reportado ao usuário em vez de silenciosamente não fazer nada.
+const ENGINE_DEST_DIR = {
+  'claude-code': '.claude',
+  codex: '.codex',
+  opencode: '.opencode',
+  cursor: '.cursor',
+};
+
+const SOURCE_DIRS = ['skills', 'agents', 'hooks'];
+
+// Diretórios de SOURCE_DIRS que não devem ser copiados (cópia genérica byte-a-byte) para o
+// destino de uma engine específica, mesmo existindo na fonte, porque o resultado é
+// comprovadamente inerte.
+//
+// - Cursor: `hooks/` NÃO entra aqui — virou tradução dedicada (`installCursorHooks`, issue
+//   #284) em vez de exclusão pura. O loop genérico de SOURCE_DIRS trata `cursor`+`hooks`
+//   como caso especial (ver o `continue` dedicado abaixo) antes mesmo de chegar a esta
+//   lista, produzindo `.cursor/hooks.json` de verdade — colocar `cursor` aqui excluiria
+//   `hooks` antes desse caso especial rodar.
+// - OpenCode (#283): `skills/`, `agents/`, `hooks/` inteiros, porque o OpenCode tem
+//   árvore-fonte própria já traduzida para o seu formato (ver `ENGINE_NATIVE_SOURCE_DIR`
+//   abaixo) — copiar os genéricos produziria skills inertes (referenciam
+//   `$CLAUDE_PLUGIN_ROOT`, variável que o OpenCode não define), um diretório `agents/`
+//   (plural) que o OpenCode não escaneia (ele usa `agent/`, singular) e hooks em JSON
+//   declarativo onde o OpenCode espera plugin TS (`tool.execute.before/after`). Ver
+//   wiki/Compatibilidade-OpenCode.md.
+const ENGINE_EXCLUDED_SOURCE_DIRS = {
+  opencode: ['skills', 'agents', 'hooks'],
+};
+
+// OpenCode (#283): em vez dos SOURCE_DIRS agnósticos, copia a árvore `opencode/` (já
+// adaptada ao formato nativo — `opencode/agent/*.md`, `opencode/skills/*/SKILL.md`,
+// `opencode/plugin/*.ts`, `opencode/scripts/*`) para a raiz do destino, achatada (não
+// aninhada em `.opencode/opencode/...`). Mesmo mecanismo de instalação manual documentado
+// em wiki/Compatibilidade-OpenCode.md (`cp -r opencode/. <projeto>/.opencode/`), só que
+// via `vetor install` com o mesmo controle de manifesto/update seguro das demais engines.
+// `opencode/mcp.jsonc` é copiado como referência; o merge do bloco `mcp` em
+// `opencode.json` do projeto-alvo continua manual (documentado na wiki) — automatizar
+// merge de JSON de config alheio está fora de escopo (YAGNI).
+const ENGINE_NATIVE_SOURCE_DIR = {
+  opencode: 'opencode',
+};
+
+// Formatos de subagente coexistem em `agents/`: `agents/<nome>.md` (Claude Code e Cursor —
+// agnóstico de engine desde #251), `agents/<nome>/agent.json` (Antigravity) e
+// `agents/<nome>/codex.toml` (Codex — ver wiki/Compatibilidade-Codex.md, ".codex/agents/
+// (projeto)"). Cada engine só reconhece o seu formato; copiar os outros junto (comportamento
+// anterior à #283) produz arquivo inerte no destino. Este mapa filtra e, quando necessário,
+// traduz o path (achata `<nome>/codex.toml` para `<nome>.toml`, que é o path plano que o
+// Codex espera em `.codex/agents/`). Engine sem entrada aqui mantém o path original (só
+// `SOURCE_DIRS` decide se `agents/` entra em jogo para ela).
+const ENGINE_AGENT_FILE_MAP = {
+  'claude-code': (relPath) => (relPath.endsWith('.md') ? relPath : null),
+  cursor: (relPath) => (relPath.endsWith('.md') ? relPath : null),
+  codex: (relPath) => {
+    const match = relPath.match(/^([^/\\]+)[/\\]codex\.toml$/);
+    return match ? `${match[1]}.toml` : null;
+  },
+};
+
+// cli/lib/installer/writer.js -> cli/lib -> cli (raiz do pacote, tanto em dev quanto no
+// pacote npm publicado, onde "cli/" é achatado para a raiz do pacote).
+//
+// Decide entre a raiz do monorepo e `templates/` (populado por
+// `cli/scripts/sync-templates.js` via hook `prepack` do npm, ver #255 redespacho) por um
+// marcador, não por "templates/ tem conteúdo": `plugin.json` só existe na raiz do monorepo
+// Vetor, nunca no pacote publicado nem em node_modules de um projeto-alvo qualquer. Isso
+// evita dois problemas:
+// - Falso-positivo: checar só "skills/ existe um nível acima" arriscaria ler o `skills/`
+//   do próprio projeto-alvo do usuário como se fosse a fonte do Vetor.
+// - Deriva em dev: se a decisão fosse "usa templates/ quando tiver conteúdo", um
+//   dev editando `skills/` na raiz e rodando `vetor install` logo depois de qualquer
+//   `npm test` (que já roda o sync via prepack) leria o snapshot congelado de
+//   templates/, não a edição viva — o mesmo tipo de deriva que a automação do sync
+//   existe para evitar, só que realocada para o runtime do installer.
+// Em dev, a raiz do monorepo (sempre viva) vence. Só no pacote publicado, sem o marcador,
+// cai para `templates/`.
+//
+// `packageRoot` é injetável só para teste (evita depender do `cli/templates/` real, que
+// outros testes também sincronizam via prepack — ver sync-templates.test.js).
+function defaultSourceRoot({ packageRoot = path.join(__dirname, '..', '..') } = {}) {
+  const monorepoRoot = path.join(packageRoot, '..');
+  const isMonorepoCheckout = fs.existsSync(path.join(monorepoRoot, 'plugin.json'));
+  if (isMonorepoCheckout) return monorepoRoot;
+
+  return path.join(packageRoot, 'templates');
+}
+
+function listFilesRecursive(dir) {
+  const result = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      result.push(...listFilesRecursive(fullPath));
+    } else if (entry.isFile()) {
+      result.push(fullPath);
+    }
+  }
+  return result;
+}
+
+// Copia um único arquivo para o destino aplicando a mesma política de update seguro para
+// todas as engines/origens (SOURCE_DIRS agnósticos ou árvore nativa de uma engine):
+// arquivo ausente copia e manifesta; presente e íntegro (hash bate com o manifesto)
+// sincroniza; presente sem entrada no manifesto ou com hash divergente nunca é
+// sobrescrito, só reportado em `skipped`.
+function copyManagedFile({ sourceFile, destFile, manifestKey, manifest, engineId, copied, skipped }) {
+  const existingEntry = manifest.files[manifestKey];
+
+  if (fs.existsSync(destFile)) {
+    if (!existingEntry) {
+      // Arquivo existe no destino mas não consta no manifesto: não foi este
+      // instalador que o gerou. Nunca sobrescreve nem deleta.
+      skipped.push({ path: manifestKey, reason: 'unmanaged' });
+      return;
+    }
+
+    const destHash = hashFile(destFile);
+    if (destHash !== existingEntry.sha256) {
+      // Editado pelo usuário desde a última instalação: nunca sobrescreve sem sinalizar.
+      skipped.push({ path: manifestKey, reason: 'user-modified' });
+      return;
+    }
+  }
+
+  fs.mkdirSync(path.dirname(destFile), { recursive: true });
+  fs.copyFileSync(sourceFile, destFile);
+  manifest.files[manifestKey] = { sha256: hashFile(sourceFile), engine: engineId };
+  copied.push(manifestKey);
+}
+
+/**
+ * Núcleo de idempotência compartilhado por cópia genérica de arquivo e por
+ * `installCursorHooks` (que grava conteúdo *traduzido*, não uma cópia byte-a-byte da fonte):
+ * - Arquivo ausente no destino: escreve e manifesta.
+ * - Arquivo presente e já manifestado com o mesmo hash do destino atual: seguro
+ *   sobrescrever (não foi editado pelo usuário desde a última instalação) — sincroniza
+ *   com a fonte/tradução, mesmo que o conteúdo produzido tenha mudado (isso é o "update
+ *   seguro").
+ * - Arquivo presente mas SEM entrada no manifesto, ou com hash divergente da entrada
+ *   manifestada: não foi gerado por este instalador ou foi editado pelo usuário — NUNCA
+ *   sobrescreve, só reporta como `skipped`.
+ *
+ * `contentHash` é o hash do conteúdo que `write()` vai efetivamente gravar (não
+ * necessariamente o hash dos bytes da fonte — ver `installCursorHooks`), para que uma segunda
+ * execução compare o destino contra o que este instalador realmente produziu.
+ */
+function writeManaged({ destFile, manifestKey, contentHash, write, engineId, manifest, copied, skipped }) {
+  const existingEntry = manifest.files[manifestKey];
+
+  if (fs.existsSync(destFile)) {
+    if (!existingEntry) {
+      // Arquivo existe no destino mas não consta no manifesto: não foi este
+      // instalador que o gerou. Nunca sobrescreve nem deleta.
+      skipped.push({ path: manifestKey, reason: 'unmanaged' });
+      return;
+    }
+
+    const destHash = hashFile(destFile);
+    if (destHash !== existingEntry.sha256) {
+      // Editado pelo usuário desde a última instalação: nunca sobrescreve sem sinalizar.
+      skipped.push({ path: manifestKey, reason: 'user-modified' });
+      return;
+    }
+  }
+
+  fs.mkdirSync(path.dirname(destFile), { recursive: true });
+  write();
+  manifest.files[manifestKey] = { sha256: contentHash, engine: engineId };
+  copied.push(manifestKey);
+}
+
+/**
+ * Traduz `<sourceRoot>/hooks/hooks.json` (formato Claude Code) para o schema nativo do Cursor
+ * e grava como arquivo único em `<destRootName>/hooks.json` (não `<destRootName>/hooks/...`,
+ * que o Cursor não descobre — ver `cursor-hooks.js` e wiki/Compatibilidade-Cursor.md, issue
+ * #284). Silenciosamente no-op se a fonte não existir (mesmo comportamento do loop genérico
+ * para uma `sourceDir` ausente). Outros arquivos de `hooks/` (ex.: `hooks-codex.json`) não são
+ * tocados — só `hooks.json` tem tradução para o Cursor.
+ */
+function installCursorHooks({ sourceRoot, projectRoot, destRootName, manifest, copied, skipped, warnings }) {
+  const sourceFile = path.join(sourceRoot, 'hooks', 'hooks.json');
+  if (!fs.existsSync(sourceFile)) return;
+
+  const destFile = path.join(projectRoot, destRootName, 'hooks.json');
+  const manifestKey = path.relative(projectRoot, destFile).split(path.sep).join('/');
+
+  let sourceJson;
+  try {
+    sourceJson = JSON.parse(fs.readFileSync(sourceFile, 'utf8'));
+  } catch (error) {
+    // JSON inválido na fonte não pode derrubar toda a instalação (outras engines/dirs já
+    // processados no mesmo loop perderiam a entrada no manifesto, ver writeManifest só no
+    // final de installFiles) — reporta e segue.
+    skipped.push({ path: manifestKey, reason: 'invalid-source' });
+    warnings.push(`${manifestKey}: hooks/hooks.json não é JSON válido (${error.message})`);
+    return;
+  }
+
+  const { hooks: translated, dropped } = translateHooksForCursor(sourceJson);
+  const content = `${JSON.stringify(translated, null, 2)}\n`;
+
+  for (const { event, reason } of dropped) {
+    const description = reason === 'no-cursor-equivalent'
+      ? `evento "${event}" sem equivalente no Cursor — não incluído em ${manifestKey}`
+      : `matcher de "${event}" não é traduzível com fidelidade — hook mantido em ${manifestKey}, mas sem matcher (roda para todos os casos do evento)`;
+    warnings.push(`${description} — ver wiki/Compatibilidade-Cursor.md`);
+  }
+
+  writeManaged({
+    destFile,
+    manifestKey,
+    contentHash: hashContent(content),
+    write: () => fs.writeFileSync(destFile, content, 'utf8'),
+    engineId: 'cursor',
+    manifest,
+    copied,
+    skipped,
+  });
+}
+
+/**
+ * Copia `skills/`, `agents/`, `hooks/` (fonte agnóstica de engine, #251) para o destino
+ * nativo de cada engine selecionada — com tradução de formato/path por engine quando
+ * necessário (ver `ENGINE_AGENT_FILE_MAP`, `ENGINE_NATIVE_SOURCE_DIR`,
+ * `ENGINE_EXCLUDED_SOURCE_DIRS`) — gravando manifesto de hash SHA-256 por arquivo copiado
+ * em `.vetor/install-manifest.json` no projeto-alvo. `hooks/` para o Cursor é tratado à
+ * parte por `installCursorHooks` (issue #284): não é uma cópia byte-a-byte, é uma tradução
+ * de schema + caminho de destino.
+ *
+ * Idempotente e seguro para update (ver `copyManagedFile`/`writeManaged`).
+ *
+ * Engine sem destino conhecido (ex.: Antigravity, #283 — sem âncora de projeto confirmada)
+ * não é silenciosamente ignorada: entra em `enginesSkipped` para o chamador reportar ao
+ * usuário.
+ *
+ * Retorna `{ copied, skipped, warnings, enginesSkipped }` com os paths relativos ao
+ * projeto-alvo. `warnings` cobre perdas parciais que não impedem a instalação (ex.: evento
+ * de hook sem tradução fiel para uma engine, ver `installCursorHooks`) — vazio quando não há
+ * nada a avisar.
+ */
+function installFiles({ projectRoot, engines, sourceRoot = defaultSourceRoot() } = {}) {
+  if (!projectRoot) {
+    throw new Error('installFiles: "projectRoot" é obrigatório.');
+  }
+
+  const manifest = readManifest(projectRoot);
+  const copied = [];
+  const skipped = [];
+  const warnings = [];
+  const enginesSkipped = [];
+
+  for (const engine of engines ?? []) {
+    const destRootName = ENGINE_DEST_DIR[engine.id];
+    if (!destRootName) {
+      enginesSkipped.push({
+        id: engine.id,
+        name: engine.name,
+        reason: 'no-verified-project-anchor',
+      });
+      continue;
+    }
+
+    const nativeSourceDirName = ENGINE_NATIVE_SOURCE_DIR[engine.id];
+    if (nativeSourceDirName) {
+      // Engine com árvore-fonte própria (ex.: OpenCode): copia tudo, achatado, sem passar
+      // pelos SOURCE_DIRS agnósticos abaixo.
+      const nativeSourceDir = path.join(sourceRoot, nativeSourceDirName);
+      if (fs.existsSync(nativeSourceDir)) {
+        for (const sourceFile of listFilesRecursive(nativeSourceDir)) {
+          const relativeToSourceDir = path.relative(nativeSourceDir, sourceFile);
+          const destFile = path.join(projectRoot, destRootName, relativeToSourceDir);
+          const manifestKey = path.relative(projectRoot, destFile).split(path.sep).join('/');
+          copyManagedFile({
+            sourceFile,
+            destFile,
+            manifestKey,
+            manifest,
+            engineId: engine.id,
+            copied,
+            skipped,
+          });
+        }
+      }
+      continue;
+    }
+
+    const excludedSourceDirs = ENGINE_EXCLUDED_SOURCE_DIRS[engine.id] ?? [];
+    const mapAgentFile = ENGINE_AGENT_FILE_MAP[engine.id];
+
+    for (const sourceDirName of SOURCE_DIRS) {
+      if (excludedSourceDirs.includes(sourceDirName)) continue;
+
+      if (engine.id === 'cursor' && sourceDirName === 'hooks') {
+        installCursorHooks({ sourceRoot, projectRoot, destRootName, manifest, copied, skipped, warnings });
+        continue;
+      }
+
+      const sourceDir = path.join(sourceRoot, sourceDirName);
+      if (!fs.existsSync(sourceDir)) continue;
+
+      for (const sourceFile of listFilesRecursive(sourceDir)) {
+        const relativeToSourceDir = path.relative(sourceDir, sourceFile);
+
+        let destRelativePath = relativeToSourceDir;
+        if (sourceDirName === 'agents' && mapAgentFile) {
+          const mapped = mapAgentFile(relativeToSourceDir);
+          if (!mapped) continue; // formato de subagente que esta engine não reconhece
+          destRelativePath = mapped;
+        }
+
+        const destFile = path.join(projectRoot, destRootName, sourceDirName, destRelativePath);
+        const manifestKey = path.relative(projectRoot, destFile).split(path.sep).join('/');
+        copyManagedFile({
+          sourceFile,
+          destFile,
+          manifestKey,
+          manifest,
+          engineId: engine.id,
+          copied,
+          skipped,
+        });
+      }
+    }
+  }
+
+  writeManifest(projectRoot, manifest);
+  return { copied, skipped, warnings, enginesSkipped };
+}
+
+module.exports = {
+  installFiles,
+  ENGINE_DEST_DIR,
+  SOURCE_DIRS,
+  ENGINE_EXCLUDED_SOURCE_DIRS,
+  ENGINE_NATIVE_SOURCE_DIR,
+  ENGINE_AGENT_FILE_MAP,
+  defaultSourceRoot,
+};