@daniellins/power-claude 0.16.3

package/installer/__tests__/merge-settings.test.cjs

@@ -0,0 +1,330 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * merge-settings.test.cjs — regressão do merge aditivo de `hooks` e
+ * `permissions` no instalador (story SF13.13).
+ *
+ * O DEFEITO QUE ESTE TESTE EXISTE PARA IMPEDIR: `shallowMergeSettings` era
+ * `{ ...template, ...usuário }`. `hooks` é chave de TOPO, então toda
+ * instalação que já tinha `hooks` descartava o bloco INTEIRO do template —
+ * hook novo do framework não alcançava instalação nenhuma, nunca.
+ *
+ * POR QUE ELE INSTALA SOBRE UM `settings.json` PRÉ-EXISTENTE: o ramo de merge
+ * (`copy.js`, `rel === SETTINGS_REL`) só dispara com destino EXISTENTE. O
+ * único E2E do repo (`scripts/validate-install.js`) instala em `mkdtempSync`
+ * vazio e por isso nunca exerceu esta função — cobertura zero foi a razão de o
+ * bug sobreviver desde o início. Teste que instalasse em diretório vazio
+ * repetiria o mesmo ponto cego.
+ *
+ * CONTROLES NA MESMA EXECUÇÃO (o conjunto não pode ser vácuo): cada bateria
+ * roda também contra 2 mutantes de referência — `noop` (devolve o objeto do
+ * usuário: o comportamento efetivo de ANTES do conserto) e `tw` (template
+ * vence). Uma bateria que não reprovasse os dois não estaria medindo nada.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const copy = require(path.resolve(__dirname, '..', 'copy.js'));
+const { shallowMergeSettings, copyTemplate } = copy;
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const TEMPLATE_SETTINGS = path.join(ROOT, 'template', '.claude', 'settings.json');
+const T = JSON.parse(fs.readFileSync(TEMPLATE_SETTINGS, 'utf8'));
+
+const C = (x) => JSON.parse(JSON.stringify(x));
+const S = (x) => JSON.stringify(x);
+
+let failures = 0;
+const tmpDirs = [];
+
+function assert(ok, msg) {
+  if (ok) {
+    console.log(`[OK   ] ${msg}`);
+  } else {
+    console.error(`[FALHA] ${msg}`);
+    failures++;
+  }
+}
+
+/**
+ * O `settings.json` de usuário do caso real (SF13.12): igual ao template
+ * MENOS a entrada `enforce-ready-oracles.cjs`, MAIS coisas só dele — 1 entrada
+ * própria no mesmo bloco (com `timeout` próprio), 1 bloco próprio (`Task`),
+ * `permissions` próprias, `language` próprio, e NENHUM `PostToolUse`.
+ */
+function usuario() {
+  const u = C(T);
+  u.language = 'english';
+  const ew = u.hooks.PreToolUse.find((b) => b.matcher === 'Edit|Write');
+  ew.hooks = ew.hooks.filter((h) => String(h.command).indexOf('enforce-ready-oracles') < 0);
+  ew.hooks.push({ type: 'command', command: 'node meu-hook.cjs', timeout: 5 });
+  u.hooks.PreToolUse.push({
+    matcher: 'Task',
+    hooks: [{ type: 'command', command: 'node meu-task.cjs', timeout: 5 }],
+  });
+  delete u.hooks.PostToolUse;
+  u.permissions.deny = ['Read(.legado-core/**)'];
+  u.permissions.allow = ['Bash(ls:*)'];
+  return u;
+}
+
+// --- mutantes de referência -------------------------------------------------
+const real = shallowMergeSettings;
+const noop = (t, u) => C(u); // comportamento efetivo de antes do conserto
+const tw = (t, u) => Object.assign({}, C(u), C(t)); // template vence
+
+/** Roda a bateria contra real/noop/tw e assere real verde + os 2 mutantes vermelhos. */
+function bateria(nome, fn) {
+  const v = { real: fn(real), noop: fn(noop), tw: fn(tw) };
+  assert(v.real === null, `${nome}: implementação real passa (motivo: ${v.real})`);
+  assert(v.noop !== null, `${nome}: controle "noop" (merge raso de antes) REPROVA — bateria não é vácua`);
+  assert(v.tw !== null, `${nome}: controle "template vence" REPROVA — bateria não é vácua`);
+}
+
+// --- AC-1: hooks ------------------------------------------------------------
+function batHooks(m) {
+  let r;
+  try {
+    r = m(C(T), usuario());
+  } catch (e) {
+    return 'lancou:' + e.message;
+  }
+  const pre = ((r.hooks || {}).PreToolUse) || [];
+  const ew = pre.filter((b) => b.matcher === 'Edit|Write');
+  if (ew.length !== 1) return 'bloco-Edit|Write-nao-unico:' + ew.length;
+  const cmds = (ew[0].hooks || []).map((h) => String(h.command || ''));
+  const n = (s) => cmds.filter((c) => c.indexOf(s) >= 0).length;
+  if (n('enforce-ready-oracles') !== 1) return 'entrada-do-template-ausente-ou-duplicada:' + n('enforce-ready-oracles');
+  if (n('enforce-cycle-authority') !== 1) return 'entrada-preexistente-perdida-ou-duplicada:' + n('enforce-cycle-authority');
+  if (n('meu-hook') !== 1) return 'entrada-so-do-usuario-perdida:' + n('meu-hook');
+  const meu = (ew[0].hooks || []).find((h) => String(h.command).indexOf('meu-hook') >= 0);
+  if (!meu || meu.timeout !== 5) return 'timeout-do-usuario-sobrescrito:' + (meu && meu.timeout);
+  if (pre.filter((b) => b.matcher === 'Task').length !== 1) return 'bloco-so-do-usuario-perdido';
+  if (!r.hooks.PostToolUse) return 'evento-so-do-template-ausente';
+  let r2;
+  try {
+    r2 = m(C(T), C(r));
+  } catch (e) {
+    return '2a-passada-lancou:' + e.message;
+  }
+  if (S(r2) !== S(r)) return 'nao-idempotente';
+  return null;
+}
+
+// --- AC-2: permissions ------------------------------------------------------
+function batPermissions(m) {
+  let r;
+  try {
+    r = m(C(T), usuario());
+  } catch (e) {
+    return 'lancou:' + e.message;
+  }
+  const d = ((r.permissions || {}).deny) || [];
+  for (const x of ['Read(.env)', 'Read(.env.*)', 'Read(.legado-core/**)']) {
+    if (d.indexOf(x) < 0) return 'deny-sem:' + x;
+  }
+  if (d.length !== 3) return 'deny-com-duplicata-ou-lixo:' + d.length;
+  if (d[0] !== 'Read(.legado-core/**)') return 'ordem-do-usuario-nao-preservada';
+  const a = ((r.permissions || {}).allow) || [];
+  if (a.length !== 1 || a[0] !== 'Bash(ls:*)') return 'allow-so-do-usuario-alterado';
+  let r2;
+  try {
+    r2 = m(C(T), C(r));
+  } catch (e) {
+    return '2a-passada-lancou:' + e.message;
+  }
+  if (S(r2) !== S(r)) return 'nao-idempotente';
+  return null;
+}
+
+// --- AC-3: não-dano universal (comparação estrutural, insensível a ordem) ----
+function cmp(a, d, cam, prob, acr) {
+  const tp = (x) => (Array.isArray(x) ? 'arr' : x && typeof x === 'object' ? 'obj' : 'prim');
+  if (tp(a) !== tp(d)) {
+    prob.push(cam + ':tipo');
+    return;
+  }
+  if (tp(a) === 'prim') {
+    if (a !== d) prob.push(cam + ':alterado');
+    return;
+  }
+  if (tp(a) === 'obj') {
+    for (const k of Object.keys(a)) {
+      if (!(k in d)) {
+        prob.push(cam + '.' + k + ':removido');
+        continue;
+      }
+      cmp(a[k], d[k], cam + '.' + k, prob, acr);
+    }
+    for (const k of Object.keys(d)) if (!(k in a)) acr.push(cam + '.' + k);
+    return;
+  }
+  const usado = d.map(() => false);
+  const pend = [];
+  for (const el of a) {
+    const i = d.findIndex((x, j) => !usado[j] && S(x) === S(el));
+    if (i >= 0) usado[i] = true;
+    else pend.push(el);
+  }
+  for (const el of pend) {
+    let ok = false;
+    for (let j = 0; j < d.length && !ok; j++) {
+      if (usado[j]) continue;
+      const p2 = [];
+      const a2 = [];
+      cmp(el, d[j], cam + '[]', p2, a2);
+      if (p2.length === 0) {
+        usado[j] = true;
+        a2.forEach((x) => acr.push(x));
+        ok = true;
+      }
+    }
+    if (!ok) prob.push(cam + '[]:removido-ou-alterado');
+  }
+  for (let j = 0; j < d.length; j++) if (!usado[j]) acr.push(cam + '[]');
+}
+
+/** (a) nada removido/alterado; (b) todo acréscimo sob hooks/permissions; (c) ao menos 1 acréscimo. */
+function dano(antes, depois) {
+  const prob = [];
+  const acr = [];
+  cmp(antes, depois, '', prob, acr);
+  const fora = acr.filter((c) => !(c.indexOf('.hooks') === 0 || c.indexOf('.permissions') === 0));
+  if (prob.length) return 'danos:' + S(prob);
+  if (fora.length) return 'acrescimo-fora:' + S(fora);
+  if (acr.length < 1) return 'nenhum-acrescimo';
+  return null;
+}
+
+function batNaoDano(m) {
+  const u = usuario();
+  let r;
+  try {
+    r = m(C(T), C(u));
+  } catch (e) {
+    return 'lancou:' + e.message;
+  }
+  return dano(u, r);
+}
+
+// --- AC-4: guarda — chave não-aditiva mantém o override raso ----------------
+function batOverrideRaso(m) {
+  let r;
+  try {
+    const u = usuario();
+    r = m(C(T), C(u));
+    const T2 = C(T);
+    T2.statusLine = { type: 'command', command: 'x' };
+    const r2 = m(T2, C(u));
+    const u3 = C(u);
+    u3.model = 'opus';
+    const r3 = m(C(T), u3);
+    if (r.language !== 'english') return 'language-do-usuario-perdido:' + r.language;
+    if (!r2.statusLine) return 'chave-nova-do-template-nao-entrou';
+    if (r3.model !== 'opus') return 'chave-so-do-usuario-perdida:' + r3.model;
+    return null;
+  } catch (e) {
+    return 'lancou:' + e.message;
+  }
+}
+
+// --- AC-5: ponta a ponta, em disco, nos DOIS pontos de chamada --------------
+async function e2eEmDisco() {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'sf1313-test-'));
+  tmpDirs.push(tmp);
+  const tdir = path.join(tmp, 'tpl');
+  const ddir = path.join(tmp, 'dst');
+  fs.mkdirSync(path.join(tdir, '.claude'), { recursive: true });
+  fs.mkdirSync(path.join(ddir, '.claude'), { recursive: true });
+  fs.copyFileSync(TEMPLATE_SETTINGS, path.join(tdir, '.claude', 'settings.json'));
+  const src = path.join(tdir, '.claude', 'settings.json');
+  const alvo = path.join(ddir, '.claude', 'settings.json');
+  // Pré-existente: o ramo de merge só dispara com destino EXISTENTE.
+  const escreve = () => fs.writeFileSync(alvo, S(usuario()) + '\n', 'utf8');
+  const antes = C(usuario());
+
+  const inst = () => copyTemplate({ templateDir: tdir, destDir: ddir, yes: true, selectedPods: [], prompter: null });
+
+  escreve();
+  await inst();
+  assert(dano(antes, JSON.parse(fs.readFileSync(alvo, 'utf8'))) === null, 'AC-5(a) install: arquivo em disco satisfaz o não-dano (acrescenta, não remove)');
+  const b1 = fs.readFileSync(alvo, 'utf8');
+  await inst();
+  assert(fs.readFileSync(alvo, 'utf8') === b1, 'AC-5(a) install: 2ª passada devolve o arquivo BYTE-IDÊNTICO (idempotente)');
+
+  let rm = null;
+  try {
+    rm = require(path.resolve(__dirname, '..', 'update.js')).remergeSettings;
+  } catch (e) {
+    rm = null;
+  }
+  assert(typeof rm === 'function', 'AC-5(b) `remergeSettings` é exportado por installer/update.js (o caminho de update é observável)');
+  if (typeof rm !== 'function') return;
+
+  escreve();
+  const antesTexto = fs.readFileSync(alvo, 'utf8');
+  rm(src, alvo);
+  assert(dano(antes, JSON.parse(fs.readFileSync(alvo, 'utf8'))) === null, 'AC-5(b) update: arquivo em disco satisfaz o não-dano');
+  const b2 = fs.readFileSync(alvo, 'utf8');
+  assert(b2 !== antesTexto, 'AC-5(d) update MUDA o arquivo — controle contra a versão degenerada que "não faz dano" por não fazer nada');
+  rm(src, alvo);
+  assert(fs.readFileSync(alvo, 'utf8') === b2, 'AC-5(b) update: 2ª passada devolve o arquivo BYTE-IDÊNTICO (idempotente)');
+  assert(b2.indexOf('enforce-ready-oracles') >= 0, 'AC-5(c) a entrada nova está NO ARQUIVO EM DISCO, não só no objeto em memória');
+}
+
+async function main() {
+  bateria('AC-1 hooks (entrada que falta entra, o que existe fica, 2× não duplica)', batHooks);
+  bateria('AC-2 permissions (união aditiva, ordem do usuário, sem duplicata)', batPermissions);
+  bateria('AC-3 não-dano universal (nada removido/alterado; acréscimo só sob hooks/permissions)', batNaoDano);
+
+  // AC-3, controles extras: reordenação NÃO é dano; chave de topo nova É.
+  const u = usuario();
+  const r = real(C(T), C(u));
+  const reord = (() => {
+    const x = C(r);
+    x.hooks.PreToolUse.reverse();
+    return { hooks: x.hooks, permissions: x.permissions, language: x.language };
+  })();
+  const lixo = (() => {
+    const x = C(r);
+    x.tudoNovo = 1;
+    return x;
+  })();
+  assert(dano(u, reord) === null, 'AC-3 controle: resultado REORDENADO passa — reserialização não é dano');
+  assert(dano(u, lixo) !== null, 'AC-3 controle: chave de topo nova REPROVA — acréscimo fora de hooks/permissions é dano');
+
+  // AC-4 é guarda (preserva comportamento já correto): só `tw` precisa reprovar.
+  assert(batOverrideRaso(real) === null, 'AC-4 guarda: chave não-aditiva mantém o override raso (language do usuário vence; statusLine do template entra; model só do usuário fica)');
+  assert(batOverrideRaso(tw) !== null, 'AC-4 guarda: controle "template vence" REPROVA (o language do usuário sumiria)');
+
+  // R4: tipo divergente no settings.json do usuário não pode lançar.
+  let lancou = false;
+  let divergente = null;
+  try {
+    const ud = usuario();
+    ud.hooks = 'nao-sou-objeto';
+    divergente = real(C(T), ud);
+  } catch (e) {
+    lancou = true;
+  }
+  assert(!lancou, 'R4: `hooks` com tipo divergente (string) não lança — o update não quebra');
+  assert(divergente && divergente.hooks === 'nao-sou-objeto', 'R4: em tipo divergente o valor do USUÁRIO vence, sem alteração');
+
+  await e2eEmDisco();
+
+  for (const d of tmpDirs) fs.rmSync(d, { recursive: true, force: true });
+
+  if (failures > 0) {
+    console.error(`\nSuíte FALHOU: ${failures} violação(ões).`);
+    process.exit(1);
+  }
+  console.log('\nSuíte verde.');
+  process.exit(0);
+}
+
+main().catch((e) => {
+  console.error('[FALHA] suíte não completou: ' + (e && e.stack));
+  process.exit(1);
+});

package/installer/adopt.js

@@ -0,0 +1,161 @@
+'use strict';
+/**
+ * adopt.js — adota uma instalação POWER CLAUDE montada à mão (sem manifest),
+ * gerando `.power-claude/manifest.json` a partir do estado atual do disco para
+ * que `power-claude update` passe a alcançá-la.
+ *
+ * Contrato (compõe com install/update — não altera nenhum dos dois):
+ * - Fonte de verdade = os MESMOS arquivos que o update itera:
+ *   template/ inteiro + scripts/validate-budgets.js do pacote.
+ * - Cada arquivo do template é classificado contra o disco:
+ *     idêntico  → rastreado {path, sha256} (igual ao install).
+ *     modificado→ rastreado {path, sha256: <baseline do template>, origin:
+ *                 'modified'}. O baseline divergente faz o update PRESERVAR o
+ *                 arquivo (mesmo mecanismo de hash-mismatch de hoje) e o doctor
+ *                 reportá-lo como modificado — sem tocar no contrato do update.
+ *     ausente   → perguntado item a item (interativo: instalar agora?) ou, em
+ *                 --yes, registrado como não-instalado SEM escrita.
+ * - NUNCA sobrescreve nada: adopt só LÊ o projeto e escreve APENAS o manifest
+ *   (+ instalação opcional dos ausentes confirmados item a item no interativo).
+ * - Arquivos do usuário fora do template são ignorados (nunca tocados).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { readManifest, writeManifest, sha256OfFile } = require('./manifest');
+const { walkFiles, createPrompter, ensureParentDir } = require('./util');
+const { motorEntries, motorRels } = require('./motor-scripts');
+
+const MOTOR_RELS = new Set(motorRels());
+
+/**
+ * Classifica cada arquivo-fonte (template + budget script) contra o disco.
+ * Puro/sem efeitos colaterais — reutilizável em teste.
+ * @returns {{identical: string[], modified: string[], absent: string[],
+ *            entries: Array<{path: string, sha256: string, origin?: string}>}}
+ */
+function classify({ templateDir, pkgRoot, destDir }) {
+  const sources = walkFiles(templateDir).map((rel) => ({
+    rel,
+    src: path.join(templateDir, ...rel.split('/')),
+  }));
+  for (const { path: rel } of motorEntries()) {
+    const src = path.join(pkgRoot, ...rel.split('/'));
+    if (fs.existsSync(src)) sources.push({ rel, src });
+  }
+
+  const identical = [];
+  const modified = [];
+  const absent = [];
+  const entries = [];
+
+  for (const { rel, src } of sources) {
+    const destPath = path.join(destDir, ...rel.split('/'));
+    const srcHash = sha256OfFile(src);
+    if (!fs.existsSync(destPath)) {
+      absent.push(rel);
+      continue;
+    }
+    const destHash = sha256OfFile(destPath);
+    if (destHash === srcHash) {
+      identical.push(rel);
+      entries.push({ path: rel, sha256: destHash });
+    } else {
+      modified.push(rel);
+      // Baseline = hash do template: faz o update tratar como "modificado pelo
+      // usuário" (destHash !== entry.sha256) e preservar, sem alterar o update.
+      entries.push({ path: rel, sha256: srcHash, origin: 'modified' });
+    }
+  }
+
+  return { identical, modified, absent, entries };
+}
+
+async function adopt({ yes = false } = {}) {
+  const destDir = process.cwd();
+  const pkgRoot = path.resolve(__dirname, '..');
+  const templateDir = path.join(pkgRoot, 'template');
+  const pkg = require(path.join(pkgRoot, 'package.json'));
+
+  if (path.resolve(destDir) === path.resolve(pkgRoot)) {
+    throw new Error('Não rode adopt dentro do próprio repositório do framework. Rode no diretório do seu projeto.');
+  }
+  if (!fs.existsSync(templateDir)) {
+    throw new Error(`Template não encontrado em ${templateDir}. Pacote corrompido?`);
+  }
+
+  const existing = readManifest(destDir);
+  if (existing) {
+    console.log(`Esta instalação já é rastreada (POWER CLAUDE ${existing.version}, manifest presente).`);
+    console.log('Nada a adotar. Use "power-claude update" para atualizar.');
+    return 0;
+  }
+
+  console.log(`POWER CLAUDE adopt — ${destDir}\n`);
+
+  const { identical, modified, absent, entries } = classify({ templateDir, pkgRoot, destDir });
+
+  if (identical.length + modified.length === 0) {
+    console.log('Nenhum arquivo do POWER CLAUDE encontrado no disco — não há instalação para adotar.');
+    console.log('Rode "power-claude install" para instalar do zero.');
+    return 0;
+  }
+
+  // Ausentes: interativo pergunta item a item; --yes registra como não-instalados.
+  const installedAbsent = [];
+  const declinedAbsent = [];
+  if (absent.length > 0) {
+    if (yes) {
+      declinedAbsent.push(...absent);
+    } else {
+      const prompter = createPrompter();
+      try {
+        console.log(`\n${absent.length} arquivo(s) do template ausente(s) no disco:`);
+        for (const rel of absent) {
+          const install = await prompter.confirm(`  Instalar agora "${rel}"?`, false);
+          if (install) {
+            const src = MOTOR_RELS.has(rel)
+              ? path.join(pkgRoot, ...rel.split('/'))
+              : path.join(templateDir, ...rel.split('/'));
+            const destPath = path.join(destDir, ...rel.split('/'));
+            ensureParentDir(destPath);
+            fs.copyFileSync(src, destPath);
+            entries.push({ path: rel, sha256: sha256OfFile(destPath) });
+            installedAbsent.push(rel);
+          } else {
+            declinedAbsent.push(rel);
+          }
+        }
+      } finally {
+        prompter.close();
+      }
+    }
+  }
+
+  writeManifest(destDir, { version: pkg.version, files: entries });
+
+  printReport({ identical, modified, installedAbsent, declinedAbsent, total: entries.length });
+
+  console.log('\nInstalação adotada. Manifesto em .power-claude/manifest.json');
+  console.log('Próximo passo: rode "power-claude update" para propagar as correções do template.');
+  return 0;
+}
+
+function printReport({ identical, modified, installedAbsent, declinedAbsent, total }) {
+  console.log('\n--- Relatório de adoção ---');
+  console.log(`Idênticos ao template (rastreados): ${identical.length}`);
+  console.log(`Modificados por você (rastreados, preservados pelo update): ${modified.length}`);
+  for (const f of modified) console.log(`  ~ ${f}`);
+  if (installedAbsent.length > 0) {
+    console.log(`Ausentes instalados agora (sua confirmação): ${installedAbsent.length}`);
+    for (const f of installedAbsent) console.log(`  + ${f}`);
+  }
+  if (declinedAbsent.length > 0) {
+    console.log(`Ausentes NÃO instalados (registrados como não-instalados): ${declinedAbsent.length}`);
+    for (const f of declinedAbsent) console.log(`  - ${f}`);
+  }
+  console.log(`Total de arquivos gerenciados no manifest: ${total}`);
+}
+
+module.exports = { adopt, classify };

package/installer/copy.js

@@ -0,0 +1,203 @@
+'use strict';
+/**
+ * copy.js — cópia do template/ para o projeto destino.
+ *
+ * Regras:
+ * - NUNCA sobrescreve arquivo existente modificado sem decisão:
+ *   - modo --yes: mantém o arquivo do usuário e registra no relatório;
+ *   - modo interativo: pergunta (readline).
+ * - Exceção: `.claude/settings.json` recebe MERGE de chaves — chaves do
+ *   usuário são preservadas; chaves do template que faltam são adicionadas.
+ *   `hooks` e `permissions` são ADITIVAS (ver `shallowMergeSettings`):
+ *   NÃO MAIS "entram só se a chave de topo estiver ausente" — essa leitura
+ *   está superada e não deve ser repetida; ela descrevia o defeito da
+ *   `SF13.13` (instalação com `hooks` descartava o bloco INTEIRO do
+ *   template, e hook novo do framework nunca chegava) como se fosse a
+ *   garantia. Hoje o acréscimo desce ao nível da ENTRADA.
+ *   Consequência aceita e declarada (`SF13.13` R2): entrada do template que
+ *   o usuário removeu de propósito VOLTA no próximo install/update — é o
+ *   preço de o framework entregar o que distribui, sem deriva.
+ * - Filtro de pods: arquivos sob `pods/<pod>/` só são copiados se o pod
+ *   estiver na seleção (pods/README.md e demais arquivos sempre entram).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { sha256OfFile, sha256OfBuffer } = require('./manifest');
+const { walkFiles, ensureParentDir } = require('./util');
+
+const SETTINGS_REL = '.claude/settings.json';
+
+/** Lista os nomes dos pods disponíveis no template. */
+function listPods(templateDir) {
+  const podsDir = path.join(templateDir, 'pods');
+  if (!fs.existsSync(podsDir)) return [];
+  return fs
+    .readdirSync(podsDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+}
+
+/** Retorna o nome do pod dono de um path relativo, ou null. */
+function podOf(relPath) {
+  const match = relPath.match(/^pods\/([^/]+)\//);
+  return match ? match[1] : null;
+}
+
+/** Chaves que a plataforma trata como aditivas — as únicas com merge profundo. */
+const ADDITIVE_KEYS = ['hooks', 'permissions'];
+/** Identidade de elemento de array: bloco de hook por `matcher`, entrada por `command`. */
+const IDENTITY_KEYS = ['matcher', 'command'];
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+function sameIdentity(a, b) {
+  if (isPlainObject(a) && isPlainObject(b)) {
+    for (const k of IDENTITY_KEYS) {
+      if (typeof a[k] === 'string' && typeof b[k] === 'string') return a[k] === b[k];
+    }
+  }
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/**
+ * Acrescenta ao valor do USUÁRIO o que só existe no template. Nunca remove,
+ * nunca altera, idempotente (2ª passada devolve estrutura idêntica).
+ */
+function additiveMerge(t, u) {
+  if (Array.isArray(t) && Array.isArray(u)) {
+    const out = u.slice();
+    for (const el of t) {
+      const i = out.findIndex((x) => sameIdentity(el, x));
+      if (i === -1) {
+        out.push(el);
+        continue;
+      }
+      if (isPlainObject(el) && isPlainObject(out[i])) out[i] = additiveMerge(el, out[i]);
+    }
+    return out;
+  }
+  if (isPlainObject(t) && isPlainObject(u)) {
+    const out = { ...u };
+    for (const k of Object.keys(t)) {
+      if (!(k in out)) {
+        out[k] = t[k];
+        continue;
+      }
+      out[k] = additiveMerge(t[k], out[k]);
+    }
+    return out;
+  }
+  return u; // primitivo ou tipos divergentes: o do usuário vence, e nada é alterado
+}
+
+/**
+ * Merge do settings.json.
+ *
+ * - Chaves NÃO-aditivas: override raso — a do usuário vence; a que só o
+ *   template tem entra.
+ * - `hooks` e `permissions` (ADDITIVE_KEYS): merge ADITIVO em profundidade —
+ *   acrescenta a entrada que falta sem remover nem alterar o que o usuário
+ *   tem (inclusive `timeout` ajustado por ele). NÃO é mais o merge raso que
+ *   descartava o bloco inteiro do template quando o usuário tinha a chave.
+ */
+function shallowMergeSettings(templateObj, userObj) {
+  const merged = { ...templateObj, ...userObj };
+  if (!isPlainObject(templateObj) || !isPlainObject(userObj)) return merged;
+  for (const key of ADDITIVE_KEYS) {
+    if (!(key in templateObj) || !(key in userObj)) continue;
+    merged[key] = additiveMerge(templateObj[key], userObj[key]);
+  }
+  return merged;
+}
+
+/**
+ * Copia o template para destDir.
+ *
+ * @param {object} opts
+ * @param {string} opts.templateDir  raiz do template no pacote
+ * @param {string} opts.destDir     raiz do projeto destino (cwd)
+ * @param {boolean} opts.yes        modo não-interativo
+ * @param {string[]|null} opts.selectedPods  pods a instalar (null = todos)
+ * @param {object|null} opts.prompter        prompter interativo (null em --yes)
+ * @returns {Promise<{entries: Array, report: object}>}
+ */
+async function copyTemplate({ templateDir, destDir, yes, selectedPods, prompter }) {
+  const allFiles = walkFiles(templateDir);
+  const entries = [];
+  const report = { installed: [], merged: [], kept: [], overwritten: [], skippedPods: new Set() };
+
+  for (const rel of allFiles) {
+    const pod = podOf(rel);
+    if (pod && selectedPods && !selectedPods.includes(pod)) {
+      report.skippedPods.add(pod);
+      continue;
+    }
+
+    const srcPath = path.join(templateDir, ...rel.split('/'));
+    const destPath = path.join(destDir, ...rel.split('/'));
+
+    if (!fs.existsSync(destPath)) {
+      ensureParentDir(destPath);
+      fs.copyFileSync(srcPath, destPath);
+      entries.push({ path: rel, sha256: sha256OfFile(destPath) });
+      report.installed.push(rel);
+      continue;
+    }
+
+    // Destino já existe.
+    if (rel === SETTINGS_REL) {
+      const result = mergeSettingsFile(srcPath, destPath);
+      if (result.merged) {
+        entries.push({ path: rel, sha256: result.sha256, origin: 'merged' });
+        report.merged.push(rel);
+      } else {
+        // settings.json do usuário não parseia — preserva intacto.
+        report.kept.push(`${rel} (JSON inválido no destino; mantido sem merge)`);
+      }
+      continue;
+    }
+
+    const srcHash = sha256OfFile(srcPath);
+    const destHash = sha256OfFile(destPath);
+    if (srcHash === destHash) {
+      // Conteúdo idêntico — apenas registra como gerenciado.
+      entries.push({ path: rel, sha256: destHash });
+      continue;
+    }
+
+    // Conflito: destino existe e difere do template.
+    let overwrite = false;
+    if (!yes && prompter) {
+      overwrite = await prompter.confirm(`  Arquivo já existe e difere do template: ${rel}. Sobrescrever?`, false);
+    }
+    if (overwrite) {
+      fs.copyFileSync(srcPath, destPath);
+      entries.push({ path: rel, sha256: srcHash });
+      report.overwritten.push(rel);
+    } else {
+      report.kept.push(rel);
+    }
+  }
+
+  report.skippedPods = [...report.skippedPods];
+  return { entries, report };
+}
+
+/** Faz o merge (aditivo em hooks/permissions, override raso nas demais chaves) do settings.json e grava no destino. */
+function mergeSettingsFile(srcPath, destPath) {
+  const templateObj = JSON.parse(fs.readFileSync(srcPath, 'utf8'));
+  let userObj;
+  try {
+    userObj = JSON.parse(fs.readFileSync(destPath, 'utf8'));
+  } catch {
+    return { merged: false };
+  }
+  const mergedObj = shallowMergeSettings(templateObj, userObj);
+  const content = JSON.stringify(mergedObj, null, 2) + '\n';
+  fs.writeFileSync(destPath, content, 'utf8');
+  return { merged: true, sha256: sha256OfBuffer(Buffer.from(content, 'utf8')) };
+}
+
+module.exports = { copyTemplate, listPods, podOf, shallowMergeSettings, SETTINGS_REL };