@marvinribeiro_/ignity 0.0.0-stage → 2.0.0-alpha.0

package/src/commands/doctor.js

@@ -0,0 +1,214 @@
+'use strict';
+
+/**
+ * AC 16, 17, 17a: diagnostics. Each check is `{id, run(ctx) -> {level, message, fix}}`
+ * so later epics (G4) can plug more checks in. Only local files are read; the CLI
+ * never contacts the site. Exit 1 only when some check is FAIL.
+ */
+
+const fs = require('node:fs');
+const { checkNodeVersion } = require('../lib/node-check');
+const { FRAMEWORK_PATH, V1_FRAMEWORK_PATH, CLIENT_FOLDERS, SKILLS_DIR, MANIFEST_PATH, resolveInside } = require('../lib/paths');
+const { listFiles, sha256File, sha256, readIfExists } = require('../lib/files');
+const { readManifest } = require('../lib/manifest');
+const { extractBody } = require('../lib/merger');
+const { detectV1 } = require('../lib/v1-detect');
+const { detectClient } = require('../lib/client-detect');
+const { readMcpServerNames } = require('../lib/mcp-config');
+const { missingTemplates, templateCopyHint } = require('../lib/sync');
+
+const LEVELS = ['OK', 'INFO', 'WARN', 'FAIL'];
+
+const ELEMENTOR_PLAN_REQUIREMENT =
+  'Requer Elementor Pro Advanced ou superior (Advanced Solo em diante). O plano Essential não tem Custom Code, usado pelo runtime da Ignity Motion.';
+
+const nodeCheck = {
+  id: 'node',
+  run(ctx) {
+    const r = checkNodeVersion(ctx.nodeVersion || process.versions.node);
+    return r.ok
+      ? { level: 'OK', message: `Node.js ${r.found} (mínimo ${r.required}).` }
+      : {
+          level: 'FAIL',
+          message: `Node.js ${r.found || 'desconhecido'} abaixo do mínimo ${r.required}.`,
+          fix: 'Instale o Node 22 LTS ou mais novo em https://nodejs.org/ e rode o comando de novo.',
+        };
+  },
+};
+
+const manifestCheck = {
+  id: 'manifest',
+  run(ctx) {
+    if (ctx.manifestError) {
+      return {
+        level: 'FAIL',
+        message: ctx.manifestError,
+        fix: 'Restaure o arquivo a partir de um backup ou apague-o e rode `npx @marvinribeiro_/ignity update` (instalações v1 são migradas).',
+      };
+    }
+    if (ctx.manifest) return { level: 'OK', message: `${MANIFEST_PATH} válido (Ignity ${ctx.manifest.ignityVersion}, cliente ${ctx.manifest.client}).` };
+    if (ctx.v1.detected) {
+      return { level: 'WARN', message: 'Instalação v1 sem manifesto.', fix: 'Rode `npx @marvinribeiro_/ignity update` para migrar para o layout v2 (project/ não é tocado).' };
+    }
+    return { level: 'FAIL', message: `${MANIFEST_PATH} não encontrado.`, fix: 'Rode `npx @marvinribeiro_/ignity init` nesta pasta.' };
+  },
+};
+
+const integrityCheck = {
+  id: 'integrity',
+  run(ctx) {
+    if (!ctx.manifest) return { level: 'INFO', message: 'Sem manifesto: integridade não verificada.' };
+    const changed = [];
+    const missing = [];
+    for (const f of ctx.manifest.files) {
+      const abs = resolveInside(ctx.root, f.path);
+      if (f.kind === 'merged-block') {
+        const body = extractBody(readIfExists(abs, 'utf8'));
+        if (body === null) missing.push(`${f.path} (bloco)`);
+        else if (sha256(body) !== f.blockSha256) changed.push(`${f.path} (bloco)`);
+      } else if (!fs.existsSync(abs)) missing.push(f.path);
+      else if (sha256File(abs) !== f.sha256) changed.push(f.path);
+    }
+    if (!changed.length && !missing.length) return { level: 'OK', message: `${ctx.manifest.files.length} arquivo(s) do manifesto íntegros.` };
+    const parts = [];
+    if (changed.length) parts.push(`alterados: ${changed.join(', ')}`);
+    if (missing.length) parts.push(`ausentes: ${missing.join(', ')}`);
+    return { level: 'WARN', message: `Arquivos do Ignity divergem do manifesto (${parts.join('; ')}).`, fix: 'Rode `npx @marvinribeiro_/ignity update` (arquivos alterados vão para .ignity/backups/ antes da troca).' };
+  },
+};
+
+const skillsCheck = {
+  id: 'skills',
+  run(ctx) {
+    const expected = [...new Set(listFiles(SKILLS_DIR).map((rel) => rel.split('/')[0]))];
+    const lines = [];
+    let missingAny = false;
+    for (const folder of CLIENT_FOLDERS[ctx.client]) {
+      const found = expected.filter((s) => fs.existsSync(resolveInside(ctx.root, `${folder}/skills/${s}/SKILL.md`)));
+      if (found.length < expected.length) missingAny = true;
+      lines.push(`${folder}/skills: ${found.length}/${expected.length}`);
+    }
+    return missingAny
+      ? { level: 'WARN', message: `Skills incompletas (${lines.join('; ')}).`, fix: 'Rode `npx @marvinribeiro_/ignity update` para reinstalar as skills.' }
+      : { level: 'OK', message: `Skills encontradas (${lines.join('; ')}).` };
+  },
+};
+
+const templatesCheck = {
+  id: 'templates',
+  run(ctx) {
+    const missing = missingTemplates(ctx.root);
+    if (!missing.length) return { level: 'OK', message: 'Templates de project/ presentes.' };
+    return {
+      level: 'WARN',
+      message: `Templates ausentes em project/: ${missing.join(', ')}.`,
+      fix: `O update não toca project/. Para copiar: ${missing.map((tpl) => templateCopyHint(tpl, ctx.root)).join(' ; ')} (ou rode \`npx @marvinribeiro_/ignity init\`, que só cria templates ausentes).`,
+    };
+  },
+};
+
+const obsoleteFrameworkCheck = {
+  id: 'v1-framework',
+  run(ctx) {
+    if (!fs.existsSync(resolveInside(ctx.root, V1_FRAMEWORK_PATH))) return { level: 'OK', message: `Sem ${V1_FRAMEWORK_PATH} obsoleto.` };
+    return {
+      level: 'INFO',
+      message: `${V1_FRAMEWORK_PATH} é da instalação v1 e está obsoleto; o guia atual fica em ${FRAMEWORK_PATH}.`,
+      fix: 'Pode manter ou apagar o arquivo; o Ignity não remove nada de project/.',
+    };
+  },
+};
+
+function mcpCheck(id, label, pattern) {
+  return {
+    id,
+    run(ctx) {
+      const sources = readMcpServerNames(ctx.root, ctx.client, ctx.home);
+      const hit = sources.find((s) => s.names.some((n) => pattern.test(n)));
+      if (hit) return { level: 'OK', message: `Servidor MCP do ${label} declarado em ${hit.label}.` };
+      const read = sources.filter((s) => s.readable).map((s) => `${s.label}: ${s.names.length} servidor(es)`);
+      const unreadable = sources.filter((s) => s.exists && !s.readable).map((s) => s.label);
+      const seen = read.length ? ` Lidos: ${read.join('; ')}.` : ' Nenhuma configuração MCP encontrada.';
+      const bad = unreadable.length ? ` Não foi possível ler: ${unreadable.join(', ')}.` : '';
+      return {
+        level: 'WARN',
+        message: `Servidor MCP do ${label} não declarado.${seen}${bad}`,
+        fix: `Declare o servidor MCP do ${label} na configuração do cliente (${sources.map((s) => s.label).join(', ')}), com um nome que contenha "${label.toLowerCase()}". O Ignity não configura MCP nem acessa o site.`,
+      };
+    },
+  };
+}
+
+/**
+ * A9: Elementor Pro plan. Without verified evidence it is always INFO (never OK).
+ * `ctx.elementorEvidence` = `{customCodeAvailable: boolean}` is the contract for a future source (G4).
+ */
+const elementorProPlanCheck = {
+  id: 'elementor-pro-plan',
+  run(ctx = {}) {
+    const evidence = ctx.elementorEvidence;
+    if (evidence && typeof evidence.customCodeAvailable === 'boolean') {
+      return evidence.customCodeAvailable
+        ? { level: 'OK', message: `${ELEMENTOR_PLAN_REQUIREMENT} Custom Code disponível.` }
+        : { level: 'FAIL', message: `${ELEMENTOR_PLAN_REQUIREMENT} Custom Code indisponível.`, fix: 'Faça upgrade para Elementor Pro Advanced ou superior.' };
+    }
+    return {
+      level: 'INFO',
+      message: ELEMENTOR_PLAN_REQUIREMENT,
+      fix: 'Confira o plano da sua licença na conta Elementor; se for Essential, faça upgrade para Advanced ou superior.',
+    };
+  },
+};
+
+const DEFAULT_CHECKS = [
+  nodeCheck,
+  manifestCheck,
+  integrityCheck,
+  skillsCheck,
+  templatesCheck,
+  obsoleteFrameworkCheck,
+  mcpCheck('mcp-elementor', 'Elementor', /elementor/i),
+  mcpCheck('mcp-figma', 'Figma', /figma/i),
+  elementorProPlanCheck,
+];
+
+/** Runs checks; a throwing check becomes FAIL without echoing internal details. */
+function runChecks(checks, ctx) {
+  return checks.map((check) => {
+    try {
+      const r = check.run(ctx);
+      if (!r || !LEVELS.includes(r.level)) throw new Error('resultado inválido');
+      return { id: check.id, ...r };
+    } catch (error) {
+      return { id: check.id, level: 'FAIL', message: `Check falhou: ${error.message}`, fix: 'Rode com IGNITY_DEBUG=1 para detalhes.' };
+    }
+  });
+}
+
+function buildContext(ctx) {
+  let manifest = null;
+  let manifestError = null;
+  try {
+    manifest = readManifest(ctx.root);
+  } catch (error) {
+    manifestError = error.message;
+  }
+  const client = ctx.client || (manifest && manifest.client) || detectClient(ctx.root);
+  return { ...ctx, manifest, manifestError, client, v1: detectV1(ctx.root) };
+}
+
+function doctor(ctx, checks = DEFAULT_CHECKS) {
+  const full = buildContext(ctx);
+  const results = runChecks(checks, full);
+  full.out.line(`Ignity doctor — ${full.root} (cliente: ${full.client})`);
+  for (const r of results) {
+    full.out.line(`[${r.level}] ${r.id}: ${r.message}`);
+    if (r.fix && r.level !== 'OK') full.out.line(`       → ${r.fix}`);
+  }
+  const count = (lvl) => results.filter((r) => r.level === lvl).length;
+  full.out.line('');
+  full.out.line(`Resumo: ${count('OK')} OK, ${count('INFO')} INFO, ${count('WARN')} WARN, ${count('FAIL')} FAIL.`);
+  return count('FAIL') > 0 ? 1 : 0;
+}
+
+module.exports = { doctor, runChecks, DEFAULT_CHECKS, elementorProPlanCheck, nodeCheck, mcpCheck, ELEMENTOR_PLAN_REQUIREMENT };

package/src/commands/init.js

@@ -0,0 +1,36 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { sync } = require('../lib/sync');
+const { detectClient } = require('../lib/client-detect');
+const { answers, ask } = require('../lib/prompt');
+const { doctor } = require('./doctor');
+const ELEMENTOR_REQUIREMENT = 'Requisito: Elementor Pro Advanced ou superior (Advanced Solo em diante); o plano Essential não tem Custom Code, usado pelo runtime da Ignity Motion.';
+const NO_SITE_ACTION = 'A conexão MCP é configurada separadamente no cliente. O CLI não agiu no site.';
+function finish(ctx, values) {
+  if (values) {
+    const template = fs.readFileSync(path.resolve(__dirname, '../../content/templates/BRIEF.md'), 'utf8');
+    ctx.brief = template.replace(/\{\{(\w+)\}\}/g, (_, key) => values[key]);
+    if (!fs.existsSync(path.resolve(ctx.root, values.assets))) ctx.out.warn('pasta não encontrada, crie e exporte os assets do Figma nela');
+  }
+  const code = sync(ctx, { mode: 'init' });
+  if (!ctx.dryRun) {
+    doctor({ ...ctx, out: { line: text => { if (/^\[(WARN|FAIL)\]/.test(text)) ctx.out.line(text); } } });
+    ctx.out.line(ELEMENTOR_REQUIREMENT);
+    ctx.out.line(NO_SITE_ACTION);
+    ctx.out.line(`Próximo passo: abra ${ctx.client === 'codex' ? 'o Codex e carregue a skill web-orchestrator' : ctx.client === 'both' ? 'o Claude Code e digite /web-orchestrator, ou carregue a skill web-orchestrator no Codex' : 'o Claude Code e digite /web-orchestrator'}`);
+  }
+  return code;
+}
+function init(ctx) {
+  ctx.client = ctx.client || detectClient(ctx.root);
+  ctx.out.line(`Detectado: ${ctx.client === 'claude' ? 'Claude Code (.claude/)' : ctx.client === 'codex' ? 'Codex (.agents/)' : 'Claude Code e Codex'} · ${['CLAUDE.md', 'AGENTS.md'].filter(f => fs.existsSync(path.join(ctx.root, f))).map(f => `${f} existente → mesclado`).join(' · ')}`);
+  if (fs.existsSync(path.join(ctx.root, 'project/BRIEF.md'))) {
+    ctx.out.line('BRIEF existente preservado');
+    return finish(ctx);
+  }
+  const flags = ctx.flags || {};
+  if (!ctx.dryRun && !flags.yes && process.stdin.isTTY && process.stdout.isTTY) return ask(flags, ctx.out).then(values => finish(ctx, values));
+  return finish(ctx, answers(flags));
+}
+module.exports = { init, ELEMENTOR_REQUIREMENT, NO_SITE_ACTION };

package/src/commands/status.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const fs = require('node:fs');
+const { resolveInside } = require('../lib/paths');
+const { readManifest } = require('../lib/manifest');
+const { detectV1 } = require('../lib/v1-detect');
+const { PKG_VERSION } = require('../lib/sync');
+
+/** Text under a `## {title}` heading, until the next `## `. */
+function section(text, title) {
+  const lines = text.replace(/\r\n/g, '\n').split('\n');
+  const start = lines.findIndex((l) => l.trim().toLowerCase() === `## ${title}`.toLowerCase());
+  if (start < 0) return null;
+  const body = [];
+  for (const l of lines.slice(start + 1)) {
+    if (/^##\s/.test(l)) break;
+    body.push(l);
+  }
+  return body;
+}
+
+/** Tolerant reader of the v1 STATE.md (Markdown): active goal and the Etapas table. */
+function parseState(text) {
+  const goalLines = section(text, 'Objetivo ativo');
+  const goal = goalLines ? goalLines.map((l) => l.trim()).filter(Boolean).join(' ') : null;
+  const stages = [];
+  for (const l of section(text, 'Etapas') || []) {
+    if (!l.trim().startsWith('|')) continue;
+    const cells = l.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
+    if (cells.length < 2 || /^:?-+:?$/.test(cells[0]) || cells[0].toLowerCase() === 'etapa') continue;
+    stages.push({ stage: cells[0], state: cells[1] || '' });
+  }
+  return { goal, stages };
+}
+
+/** AC 18: read-only summary. */
+function status(ctx) {
+  const { root, out } = ctx;
+  const manifest = readManifest(root);
+  out.line(`Pacote: ignity ${PKG_VERSION}`);
+  if (manifest) {
+    out.line(`Instalado: ${manifest.ignityVersion}${manifest.ignityVersion === PKG_VERSION ? '' : ' (rode `npx @marvinribeiro_/ignity update`)'}`);
+    out.line(`Cliente: ${manifest.client}`);
+    out.line(`Última atualização: ${manifest.updatedAt}`);
+  } else if (detectV1(root).detected) {
+    out.line('Instalado: v1 (sem manifesto). Rode `npx @marvinribeiro_/ignity update` para migrar.');
+  } else {
+    out.line('Instalado: não (rode `npx @marvinribeiro_/ignity init`).');
+  }
+
+  const stateFile = resolveInside(root, 'project/STATE.md');
+  if (!fs.existsSync(stateFile)) {
+    out.line('project/STATE.md não encontrado. Para começar, carregue /web-orchestrator no seu cliente.');
+    return 0;
+  }
+  const { goal, stages } = parseState(fs.readFileSync(stateFile, 'utf8'));
+  out.line('');
+  out.line(`Objetivo ativo: ${goal || '(não preenchido)'}`);
+  if (stages.length) {
+    out.line('Etapas:');
+    const width = Math.max(...stages.map((s) => s.stage.length));
+    for (const s of stages) out.line(`  ${s.stage.padEnd(width)}  ${s.state}`);
+  }
+  return 0;
+}
+
+module.exports = { status, parseState };

package/src/commands/uninstall.js

@@ -0,0 +1,74 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { MANIFEST_PATH, IGNITY_DIR, BACKUPS_DIR, resolveInside, isProjectPath } = require('../lib/paths');
+const { sha256File } = require('../lib/files');
+const { readManifest } = require('../lib/manifest');
+const { createBackup } = require('../lib/backup');
+const { createWriter } = require('../lib/writer');
+const { removeAdapterBlock } = require('../lib/sync');
+const { detectV1 } = require('../lib/v1-detect');
+const { CliError } = require('../lib/log');
+
+/** AC 15: removes only what the manifest lists and is still unchanged. Never touches project/. */
+function uninstall(ctx) {
+  const { root, dryRun, force, out } = ctx;
+  const manifest = readManifest(root);
+  if (!manifest) {
+    const hint = detectV1(root).detected
+      ? ' Há sinais de uma instalação v1: rode `npx @marvinribeiro_/ignity update` para migrar e depois `npx @marvinribeiro_/ignity uninstall`.'
+      : '';
+    throw new CliError(`Nada a remover: ${MANIFEST_PATH} não encontrado nesta pasta.${hint}`);
+  }
+
+  out.line(`Ignity — uninstall${dryRun ? ' (simulação: nada será removido)' : ''}`);
+  const writer = createWriter({ root, dryRun, out });
+  const backup = createBackup({ root, dryRun, out });
+  const kept = [];
+
+  for (const f of manifest.files) {
+    if (isProjectPath(f.path)) continue;
+    if (f.kind === 'merged-block') {
+      removeAdapterBlock({ root, rel: f.path, created: f.created, writer, backup, blockSha256: f.blockSha256 });
+      continue;
+    }
+    const abs = resolveInside(root, f.path);
+    if (!fs.existsSync(abs)) continue;
+    if (sha256File(abs) === f.sha256) writer.remove(f.path);
+    else if (force) {
+      backup.save(f.path);
+      writer.remove(f.path, 'alterado; removido por --force');
+    } else {
+      kept.push(f.path);
+      out.warn(`${f.path} foi alterado depois da instalação e foi mantido. Use --force para removê-lo (com backup).`);
+    }
+  }
+
+  // .ignity/ last; backups are preserved.
+  const ignityAbs = resolveInside(root, IGNITY_DIR);
+  if (fs.existsSync(ignityAbs)) {
+    if (dryRun) out.line(`PREVER REMOVER ${MANIFEST_PATH}`);
+    else {
+      fs.rmSync(resolveInside(root, MANIFEST_PATH), { force: true });
+      out.line(`REMOVIDO ${MANIFEST_PATH}`);
+    }
+    const backupsAbs = resolveInside(root, BACKUPS_DIR);
+    const hasBackups = fs.existsSync(backupsAbs) && fs.readdirSync(backupsAbs).length > 0;
+    if (hasBackups || (dryRun && backup.count > 0)) {
+      out.line(`Backups mantidos em ${path.posix.join(BACKUPS_DIR)}/`);
+    }
+    if (!dryRun && fs.readdirSync(ignityAbs).length === 0) {
+      fs.rmdirSync(ignityAbs);
+    } else if (!dryRun && !hasBackups) {
+      out.line('Arquivos restantes em .ignity/ foram mantidos.');
+    }
+  }
+
+  out.line('');
+  out.line('project/ não foi tocado.');
+  if (kept.length) out.line(`${kept.length} arquivo(s) alterado(s) mantido(s).`);
+  return 0;
+}
+
+module.exports = { uninstall };

package/src/commands/update.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const { sync } = require('../lib/sync');
+
+/**
+ * AC 11-14: updates skills, `.ignity/framework/` and adapter blocks; migrates v1.
+ * Never creates, changes or removes anything in project/ (enforced by the writer guard).
+ */
+function update(ctx) {
+  return sync(ctx, { mode: 'update' });
+}
+
+module.exports = { update };

package/src/data/v1-hashes.json

@@ -0,0 +1,44 @@
+{
+  "description": "Hashes SHA-256 dos 29 arquivos instalados pelo instalar.py v1 (modo both) e texto original dos adapters v1. Copiado de test/fixtures/v1-manifest.json (Story 1.2).",
+  "files": {
+    ".agents/skills/elementor/SKILL.md": "d02ff39a656da6298d1070c7f5ea116e5d9ccaadf17a54417137f60021997786",
+    ".agents/skills/elementor/references/operacao.md": "4eb60cd80b4a65282b377449867a5fd168f7e198d173aa6f88f2c2285e98a6b7",
+    ".agents/skills/web-assets/SKILL.md": "322744840caf94539c3b5a1080753255037bbacb46b1fff91e6b249254e53049",
+    ".agents/skills/web-figma-spec/SKILL.md": "5a0029f9d66c922cd52df61f3a33779549289aa0aa37c489fc59b608feb94564",
+    ".agents/skills/web-motion/SKILL.md": "9ed2022909b01806b43a9c41eddec88193f09fbc0c1ce5945fefe4d8794fa9f1",
+    ".agents/skills/web-orchestrator/SKILL.md": "057fd27edc2726b418995ad519459700a6e9265d36955522fadceb0a519b8e56",
+    ".agents/skills/web-qa/SKILL.md": "6a6b5f30c45645490a33c6c257b572c1bef54ec2ac37f4e42986a06584f0e931",
+    ".agents/skills/web-release/SKILL.md": "e72e8dbbb793cb450f4e79800c855966f914fa520da6fb981621509c7660f315",
+    ".agents/skills/web-seo/SKILL.md": "b9906bcba3064de7d8b87749e9305b3bdbd092b2d9dc5c4e92f182bc9bc5eb34",
+    ".claude/skills/elementor/SKILL.md": "d02ff39a656da6298d1070c7f5ea116e5d9ccaadf17a54417137f60021997786",
+    ".claude/skills/elementor/references/operacao.md": "4eb60cd80b4a65282b377449867a5fd168f7e198d173aa6f88f2c2285e98a6b7",
+    ".claude/skills/web-assets/SKILL.md": "322744840caf94539c3b5a1080753255037bbacb46b1fff91e6b249254e53049",
+    ".claude/skills/web-figma-spec/SKILL.md": "5a0029f9d66c922cd52df61f3a33779549289aa0aa37c489fc59b608feb94564",
+    ".claude/skills/web-motion/SKILL.md": "9ed2022909b01806b43a9c41eddec88193f09fbc0c1ce5945fefe4d8794fa9f1",
+    ".claude/skills/web-orchestrator/SKILL.md": "057fd27edc2726b418995ad519459700a6e9265d36955522fadceb0a519b8e56",
+    ".claude/skills/web-qa/SKILL.md": "6a6b5f30c45645490a33c6c257b572c1bef54ec2ac37f4e42986a06584f0e931",
+    ".claude/skills/web-release/SKILL.md": "e72e8dbbb793cb450f4e79800c855966f914fa520da6fb981621509c7660f315",
+    ".claude/skills/web-seo/SKILL.md": "b9906bcba3064de7d8b87749e9305b3bdbd092b2d9dc5c4e92f182bc9bc5eb34",
+    "AGENTS.md": "431cecd1ef9f68c2d0ffa39c0ddbac6f71bbe9635a75d92951041dd0c0676072",
+    "CLAUDE.md": "1456b0bc41cc0bf8baf9cf38c18c170e999316e2a8d222c48886b5ca0049eee6",
+    "project/ASSETS.csv": "e832759924d6c484237f411754cad43f2c413b0b0f794850f9c80a7db8ae0429",
+    "project/BRIEF.md": "7d4a165dc55875cb3c1c8b5ab0cc3d7973b6e9191db0cb8c0d1230af3339c62b",
+    "project/DECISIONS.md": "e63a4eb92651c3a0c319fca0d7e2f14bbd8d5db48cdb074f8b7ba1d7ffd00a19",
+    "project/INICIAR.md": "892f5911925982a052348763dd1b4dd79f981e6f2234d3ba994734fb9c6424a0",
+    "project/QA.md": "a392fd4087c2f774fe20e157c327a3b969f1e9928efc3086a92f1026dc073513",
+    "project/RETOMAR.md": "3d39da759ab4124c462acbdbef7f5deaa7d5229636f072dce7683b3a14137dce",
+    "project/SECTIONS.md": "99f8e4d905b464139bb3e5b3ae54306d1b5381a6b6744c5a6e6383c0471aa88f",
+    "project/STATE.md": "d8a1001afd77551745720733788d6cee9c38a5e0ea471f3710dca571786237d5",
+    "project/framework/FRAMEWORK.md": "e7db2f4e18069b96b42178e4dc008792cdae564e0ddb5dd1666f84d5a43a99fa"
+  },
+  "adapters": {
+    "CLAUDE.md": {
+      "sha256": "1456b0bc41cc0bf8baf9cf38c18c170e999316e2a8d222c48886b5ca0049eee6",
+      "text": "# Orientações do projeto web\n\nEste projeto usa o Framework Agêntico Web. Para iniciar ou retomar o fluxo completo, carregar `web-orchestrator` em `.claude/skills/web-orchestrator/SKILL.md`, disponível também como `/web-orchestrator` no Claude Code. Para uma alteração pontual, ler o estado e carregar apenas os módulos pertinentes.\n\nContexto: `project/BRIEF.md`. Continuidade: `project/STATE.md`. Decisões: `project/DECISIONS.md`. Referências e QA: demais arquivos em `project/`. Guia: `project/framework/FRAMEWORK.md`.\n\nPreservar conteúdo nativo e editável no Elementor, reutilizar componentes e conferir desktop/mobile. Descobrir o MCP e o schema reais, ler a revisão atual antes de editar e verificar persistência. Não transportar IDs, acessos ou decisões de outra marca. Priorizar o pedido atual e as autorizações existentes; o framework não concede permissões adicionais.\n\nNão abrir agentes paralelos automaticamente. Registrar evidência e próximo passo ao encerrar. Não salvar segredos ou URLs assinadas nos registros. Se estas orientações forem adicionadas a um projeto existente, mesclar com suas instruções sem apagar regras anteriores.\n"
+    },
+    "AGENTS.md": {
+      "sha256": "431cecd1ef9f68c2d0ffa39c0ddbac6f71bbe9635a75d92951041dd0c0676072",
+      "text": "# Orientações do projeto web\n\nEste projeto usa o Framework Agêntico Web. Para iniciar ou retomar o fluxo completo, carregar `web-orchestrator` em `.agents/skills/web-orchestrator/SKILL.md`. Para uma alteração pontual, ler o estado e carregar apenas os módulos pertinentes.\n\nContexto: `project/BRIEF.md`. Continuidade: `project/STATE.md`. Decisões: `project/DECISIONS.md`. Referências e QA: demais arquivos em `project/`. Guia: `project/framework/FRAMEWORK.md`.\n\nPreservar conteúdo nativo e editável no Elementor, reutilizar componentes e conferir desktop/mobile. Descobrir o MCP e o schema reais, ler a revisão atual antes de editar e verificar persistência. Não transportar IDs, acessos ou decisões de outra marca. Priorizar o pedido atual e as autorizações existentes; o framework não concede permissões adicionais.\n\nNão abrir agentes paralelos automaticamente. Registrar evidência e próximo passo ao encerrar. Não salvar segredos ou URLs assinadas nos registros. Se estas orientações forem adicionadas a um projeto existente, mesclar com suas instruções sem apagar regras anteriores.\n"
+    }
+  }
+}

package/src/lib/backup.js

@@ -0,0 +1,52 @@
+'use strict';
+
+/** AC 9: copies a file to .ignity/backups/{timestamp}/{path} before it is changed or removed. */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { BACKUPS_DIR, resolveInside } = require('./paths');
+
+function timestamp(date = new Date()) {
+  return date.toISOString().replace(/[:.]/g, '-');
+}
+
+/**
+ * One backup folder per run, created lazily on the first saved file.
+ * @param {{root: string, dryRun: boolean, out: object, now?: Date}} options
+ */
+function createBackup({ root, dryRun, out, now = new Date() }) {
+  const dir = `${BACKUPS_DIR}/${timestamp(now)}`;
+  let count = 0;
+  return {
+    dir,
+    get count() {
+      return count;
+    },
+    /** @returns {string} relative path of the backup copy */
+    save(rel) {
+      const target = `${dir}/${rel}`;
+      if (dryRun) {
+        out.line(`PREVER CRIAR ${target} (backup)`);
+      } else {
+        const dest = resolveInside(root, target);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        const source = resolveInside(root, rel);
+        const mode = fs.statSync(source).mode & 0o7777;
+        // Create or tighten the destination before copying private contents.
+        const fd = fs.openSync(dest, 'w', 0o600);
+        try {
+          fs.fchmodSync(fd, 0o600);
+        } finally {
+          fs.closeSync(fd);
+        }
+        fs.copyFileSync(source, dest);
+        fs.chmodSync(dest, mode);
+        out.line(`BACKUP ${rel} -> ${target}`);
+      }
+      count++;
+      return target;
+    },
+  };
+}
+
+module.exports = { createBackup, timestamp };

package/src/lib/client-detect.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * AC 3: `.claude/` -> claude; `.agents/` or `AGENTS.md` -> codex; both -> both; none -> both (v1 default).
+ * @param {string} root
+ * @returns {'claude'|'codex'|'both'}
+ */
+function detectClient(root) {
+  const claude = fs.existsSync(path.join(root, '.claude'));
+  const codex = fs.existsSync(path.join(root, '.agents')) || fs.existsSync(path.join(root, 'AGENTS.md'));
+  if (claude && !codex) return 'claude';
+  if (codex && !claude) return 'codex';
+  return 'both';
+}
+
+module.exports = { detectClient };

package/src/lib/files.js

@@ -0,0 +1,86 @@
+'use strict';
+
+/**
+ * File helpers used at runtime by the CLI. Mirrors scripts/lib/fs-utils.js
+ * (listFiles/sha256), which is not shipped in the npm package (`files` in
+ * package.json), plus atomic writes.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+/** Every regular file under `root` as sorted POSIX relative paths. Symlinks are skipped. */
+function listFiles(root) {
+  const out = [];
+  (function walk(dir) {
+    for (const dirent of fs.readdirSync(dir, { withFileTypes: true })) {
+      const abs = path.join(dir, dirent.name);
+      if (dirent.isDirectory()) walk(abs);
+      else if (dirent.isFile()) out.push(path.relative(root, abs).split(path.sep).join('/'));
+    }
+  })(root);
+  return out.sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)));
+}
+
+function sha256(data) {
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+function sha256File(file) {
+  return sha256(fs.readFileSync(file));
+}
+
+/** Returns the file content (Buffer, or string if `encoding`) or null if it does not exist. */
+function readIfExists(file, encoding) {
+  try {
+    return fs.readFileSync(file, encoding);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+/** Writes via a temp file in the same directory + rename, so readers never see a partial file. */
+function atomicWriteFile(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  // Rename over a symlink would replace the link itself. The caller validates
+  // its destination inside the project; write atomically to that destination.
+  let target = file;
+  try {
+    if (fs.lstatSync(file).isSymbolicLink()) target = fs.realpathSync(file);
+  } catch (error) {
+    if (error.code !== 'ENOENT' || fs.existsSync(file)) throw error;
+    // A dangling link is not a new file and must never be silently replaced.
+    try {
+      if (fs.lstatSync(file).isSymbolicLink()) throw new Error('Link simbólico sem destino recusado.');
+    } catch (inner) {
+      if (inner.code !== 'ENOENT') throw inner;
+    }
+  }
+  const tmp = path.join(path.dirname(target), `.${path.basename(target)}.ignity-tmp-${process.pid}`);
+  try {
+    let mode;
+    try {
+      mode = fs.statSync(target).mode & 0o7777;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      mode = 0o666 & ~process.umask();
+    }
+    // Keep the temporary file private until its final permissions are set.
+    const fd = fs.openSync(tmp, 'w', 0o600);
+    try {
+      fs.fchmodSync(fd, 0o600);
+      fs.writeFileSync(fd, data);
+      fs.fchmodSync(fd, mode);
+    } finally {
+      fs.closeSync(fd);
+    }
+    fs.renameSync(tmp, target);
+  } catch (error) {
+    fs.rmSync(tmp, { force: true });
+    throw error;
+  }
+}
+
+module.exports = { listFiles, sha256, sha256File, readIfExists, atomicWriteFile };

package/src/lib/log.js

@@ -0,0 +1,44 @@
+'use strict';
+
+/**
+ * Output helper. Every line the CLI prints goes through here; callers only pass
+ * paths, counts and fixed pt-BR messages — never environment values or config contents (Q-04).
+ */
+
+class CliError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = 'CliError';
+    this.exitCode = exitCode;
+  }
+}
+
+function createOutput({ stdout = process.stdout, stderr = process.stderr } = {}) {
+  const warnings = [];
+  return {
+    warnings,
+    line(text = '') {
+      stdout.write(`${text}\n`);
+    },
+    warn(text) {
+      warnings.push(text);
+      stdout.write(`AVISO: ${text}\n`);
+    },
+    error(text) {
+      stderr.write(`${text}\n`);
+    },
+  };
+}
+
+/** Collects output in memory (unit tests). */
+function createMemoryOutput() {
+  const chunks = { stdout: '', stderr: '' };
+  const out = createOutput({
+    stdout: { write: (s) => (chunks.stdout += s) },
+    stderr: { write: (s) => (chunks.stderr += s) },
+  });
+  out.text = chunks;
+  return out;
+}
+
+module.exports = { CliError, createOutput, createMemoryOutput };