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

package/src/lib/manifest.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * AC 4 and AC 5: `.ignity/manifest.json`. Holds only versions, client, dates,
+ * relative paths and hashes — never environment values, tokens or URLs (Q-04).
+ */
+
+const fs = require('node:fs');
+const { MANIFEST_PATH, CLIENTS, isSafeRelative, resolveInside } = require('./paths');
+const { atomicWriteFile, sha256, sha256File } = require('./files');
+
+const HEX64 = /^[0-9a-f]{64}$/;
+
+/** @returns {string[]} validation problems (empty when valid) */
+function validateManifest(data) {
+  const problems = [];
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return ['o manifesto não é um objeto JSON'];
+  if (typeof data.ignityVersion !== 'string' || !data.ignityVersion) problems.push('ignityVersion ausente');
+  if (!CLIENTS.includes(data.client)) problems.push(`client inválido (use ${CLIENTS.join(', ')})`);
+  for (const key of ['installedAt', 'updatedAt']) {
+    if (typeof data[key] !== 'string' || Number.isNaN(Date.parse(data[key]))) problems.push(`${key} inválido`);
+  }
+  if (!Array.isArray(data.files)) return [...problems, 'files[] ausente'];
+  const seen = new Set();
+  data.files.forEach((f, i) => {
+    const label = `files[${i}]`;
+    if (!f || typeof f !== 'object') return problems.push(`${label} não é objeto`);
+    if (!isSafeRelative(f.path)) problems.push(`${label}: caminho inseguro`);
+    else if (seen.has(f.path)) problems.push(`${label}: caminho duplicado ${f.path}`);
+    else seen.add(f.path);
+    if (f.owner !== 'ignity') problems.push(`${label}: owner deve ser "ignity"`);
+    if (typeof f.created !== 'boolean') problems.push(`${label}: created deve ser booleano`);
+    if (f.kind === 'merged-block') {
+      if (!HEX64.test(f.blockSha256 || '')) problems.push(`${label}: blockSha256 inválido`);
+    } else if (f.kind !== undefined) problems.push(`${label}: kind desconhecido`);
+    else if (!HEX64.test(f.sha256 || '')) problems.push(`${label}: sha256 inválido`);
+  });
+  return problems;
+}
+
+/**
+ * @returns {object|null} parsed manifest, or null when it does not exist
+ * @throws when the manifest exists but is unreadable or invalid
+ */
+function readManifest(root) {
+  const file = resolveInside(root, MANIFEST_PATH);
+  if (!fs.existsSync(file)) return null;
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    // The parser error is not echoed: it may quote file content.
+    throw new Error(`${MANIFEST_PATH} não é um JSON válido.`);
+  }
+  const problems = validateManifest(data);
+  if (problems.length) throw new Error(`${MANIFEST_PATH} inválido: ${problems.join('; ')}.`);
+  return data;
+}
+
+function serializeManifest(data) {
+  const files = [...data.files].sort((a, b) => Buffer.compare(Buffer.from(a.path), Buffer.from(b.path)));
+  return `${JSON.stringify({ ...data, files }, null, 2)}\n`;
+}
+
+function writeManifest(root, data) {
+  const problems = validateManifest(data);
+  if (problems.length) throw new Error(`Manifesto gerado inválido: ${problems.join('; ')}.`);
+  atomicWriteFile(resolveInside(root, MANIFEST_PATH), serializeManifest(data));
+}
+
+module.exports = { validateManifest, readManifest, writeManifest, serializeManifest, sha256, sha256File };

package/src/lib/mcp-config.js

@@ -0,0 +1,69 @@
+'use strict';
+
+/**
+ * AC 17: reads ONLY server names from MCP client configs. Values of env, headers,
+ * args and URLs are never returned, so they can never reach the output (Q-04).
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+function namesFromJson(text, projectRoot) {
+  const data = JSON.parse(text);
+  const names = [];
+  const take = (servers) => {
+    if (servers && typeof servers === 'object' && !Array.isArray(servers)) names.push(...Object.keys(servers));
+  };
+  take(data && data.mcpServers);
+  // ~/.claude.json keeps per-project servers under projects[<abs path>].mcpServers.
+  if (projectRoot && data && data.projects && typeof data.projects === 'object') {
+    const entry = data.projects[projectRoot];
+    take(entry && entry.mcpServers);
+  }
+  return names;
+}
+
+const TOML_TABLE = /^\s*\[\s*mcp_servers\.(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_-]+))/;
+
+function namesFromToml(text) {
+  const names = [];
+  for (const line of text.split(/\r?\n/)) {
+    const m = TOML_TABLE.exec(line);
+    if (m) names.push(m[1] || m[2] || m[3]);
+  }
+  return names;
+}
+
+/** Config files that may declare MCP servers, per client. Labels use `~` instead of the home path. */
+function mcpSources(root, client, home = os.homedir()) {
+  const sources = [];
+  if (client === 'claude' || client === 'both') {
+    sources.push({ label: '.mcp.json', file: path.join(root, '.mcp.json'), format: 'json' });
+    sources.push({ label: '~/.claude.json', file: path.join(home, '.claude.json'), format: 'json', projectRoot: root });
+  }
+  if (client === 'codex' || client === 'both') {
+    sources.push({ label: '.codex/config.toml', file: path.join(root, '.codex', 'config.toml'), format: 'toml' });
+    sources.push({ label: '~/.codex/config.toml', file: path.join(home, '.codex', 'config.toml'), format: 'toml' });
+  }
+  return sources;
+}
+
+/**
+ * @returns {{label: string, exists: boolean, readable: boolean, names: string[]}[]}
+ */
+function readMcpServerNames(root, client, home) {
+  return mcpSources(root, client, home).map((src) => {
+    if (!fs.existsSync(src.file)) return { label: src.label, exists: false, readable: false, names: [] };
+    try {
+      const text = fs.readFileSync(src.file, 'utf8');
+      const names = src.format === 'json' ? namesFromJson(text, src.projectRoot) : namesFromToml(text);
+      return { label: src.label, exists: true, readable: true, names: [...new Set(names)] };
+    } catch {
+      // Parser errors may quote file content (and secrets): never propagate them.
+      return { label: src.label, exists: true, readable: false, names: [] };
+    }
+  });
+}
+
+module.exports = { readMcpServerNames, mcpSources, namesFromJson, namesFromToml };

package/src/lib/merger.js

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * AC 8 and AC 10: merges the Ignity block into CLAUDE.md / AGENTS.md.
+ * Only the text between the markers is ever owned by Ignity; everything else is
+ * preserved byte for byte. The original line ending (LF or CRLF) is kept.
+ */
+
+const START = '<!-- IGNITY:START -->';
+const END = '<!-- IGNITY:END -->';
+
+function detectEol(text) {
+  return typeof text === 'string' && text.includes('\r\n') ? '\r\n' : '\n';
+}
+
+function normalizeBody(body, eol) {
+  return body.replace(/\r\n/g, '\n').replace(/\n+$/, '').split('\n').join(eol);
+}
+
+/** Locates the marker pair. Returns null without markers; throws when they are malformed. */
+function findBlock(text) {
+  const starts = text.split(START).length - 1;
+  const ends = text.split(END).length - 1;
+  if (starts === 0 && ends === 0) return null;
+  const start = text.indexOf(START);
+  const end = text.indexOf(END);
+  if (starts !== 1 || ends !== 1 || end < start) {
+    throw new Error(
+      `Marcadores ${START} / ${END} malformados (esperado um par, nesta ordem). ` +
+        'Corrija o arquivo à mão, deixando um único par ou nenhum, e rode o comando de novo.',
+    );
+  }
+  return { start, end: end + END.length };
+}
+
+function hasBlock(text) {
+  return typeof text === 'string' && findBlock(text) !== null;
+}
+
+function renderBlock(body, eol) {
+  return `${START}${eol}${normalizeBody(body, eol)}${eol}${END}`;
+}
+
+/**
+ * @param {string|null} existing current file content (null when the file does not exist)
+ * @param {string} body adapter content
+ * @returns {string} new file content
+ */
+function upsertBlock(existing, body) {
+  if (existing === null || existing === undefined || existing === '') return `${renderBlock(body, '\n')}\n`;
+  const eol = detectEol(existing);
+  const block = findBlock(existing);
+  if (block) return existing.slice(0, block.start) + renderBlock(body, eol) + existing.slice(block.end);
+  const sep = existing.endsWith('\n') ? eol : eol + eol;
+  return `${existing}${sep}${renderBlock(body, eol)}${eol}`;
+}
+
+/** Replaces the first occurrence of `oldText` (LF or CRLF variant) with the block. Returns null if absent. */
+function replaceTextWithBlock(existing, oldText, body) {
+  const eol = detectEol(existing);
+  for (const candidate of [oldText, oldText.replace(/\r?\n/g, '\r\n')]) {
+    const idx = existing.indexOf(candidate);
+    if (idx < 0) continue;
+    const trailing = candidate.endsWith('\n') ? eol : '';
+    return existing.slice(0, idx) + renderBlock(body, eol) + trailing + existing.slice(idx + candidate.length);
+  }
+  return null;
+}
+
+/** Removes the block (and the blank separator line the merger added). Returns the text unchanged without markers. */
+function removeBlock(existing) {
+  const block = findBlock(existing);
+  if (!block) return existing;
+  const eol = detectEol(existing);
+  let before = existing.slice(0, block.start);
+  let after = existing.slice(block.end);
+  if (after.startsWith(eol)) after = after.slice(eol.length);
+  else if (after.startsWith('\n')) after = after.slice(1);
+  if (after === '' && before.endsWith(eol + eol)) before = before.slice(0, -eol.length);
+  return before + after;
+}
+
+/** Body between the markers (LF-normalized) or null. */
+function extractBody(existing) {
+  if (typeof existing !== 'string') return null;
+  const block = findBlock(existing);
+  if (!block) return null;
+  return existing
+    .slice(block.start + START.length, block.end - END.length)
+    .replace(/\r\n/g, '\n')
+    .replace(/^\n/, '')
+    .replace(/\n$/, '');
+}
+
+module.exports = { START, END, upsertBlock, removeBlock, replaceTextWithBlock, extractBody, hasBlock, normalizeBody };

package/src/lib/node-check.js

@@ -0,0 +1,28 @@
+'use strict';
+
+/**
+ * AC 1a: runtime Node.js version check.
+ *
+ * This file is required by bin/ignity.js before anything else, so it must parse
+ * on old Node versions: ES5 syntax only (var, function, string concatenation).
+ */
+
+var REQUIRED_MAJOR = 22;
+
+/**
+ * @param {string} versionString e.g. "22.1.0" or "v20.11.0"
+ * @returns {{ok: boolean, found: string, major: number, required: number, message: string}}
+ */
+function checkNodeVersion(versionString) {
+  var found = String(versionString || '').replace(/^v/, '');
+  var major = parseInt(found.split('.')[0], 10);
+  var ok = !isNaN(major) && major >= REQUIRED_MAJOR;
+  var message = ok
+    ? 'Node.js ' + found + ' (mínimo exigido: ' + REQUIRED_MAJOR + ').'
+    : 'O Ignity precisa do Node.js ' + REQUIRED_MAJOR + ' ou mais novo. Versão encontrada: ' +
+      (found || 'desconhecida') + '. Mínima exigida: ' + REQUIRED_MAJOR + '.\n' +
+      'Próximo passo: instale o Node 22 LTS ou mais novo em https://nodejs.org/ e rode o comando de novo.';
+  return { ok: ok, found: found, major: major, required: REQUIRED_MAJOR, message: message };
+}
+
+module.exports = { checkNodeVersion: checkNodeVersion, REQUIRED_MAJOR: REQUIRED_MAJOR };

package/src/lib/paths.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const PKG_ROOT = path.resolve(__dirname, '..', '..');
+const CONTENT_DIR = path.join(PKG_ROOT, 'content');
+const SKILLS_DIR = path.join(CONTENT_DIR, 'skills');
+const TEMPLATES_DIR = path.join(CONTENT_DIR, 'templates');
+const ADAPTERS_DIR = path.join(CONTENT_DIR, 'adapters');
+const FRAMEWORK_SOURCE = path.join(CONTENT_DIR, 'framework', 'FRAMEWORK.md');
+
+const IGNITY_DIR = '.ignity';
+const MANIFEST_PATH = '.ignity/manifest.json';
+const FRAMEWORK_PATH = '.ignity/framework/FRAMEWORK.md';
+const BACKUPS_DIR = '.ignity/backups';
+const PROJECT_DIR = 'project';
+const V1_FRAMEWORK_PATH = 'project/framework/FRAMEWORK.md';
+
+const CLIENTS = ['claude', 'codex', 'both'];
+const CLIENT_FOLDERS = { claude: ['.claude'], codex: ['.agents'], both: ['.claude', '.agents'] };
+const CLIENT_ADAPTERS = { claude: ['CLAUDE.md'], codex: ['AGENTS.md'], both: ['CLAUDE.md', 'AGENTS.md'] };
+
+/** A manifest/relative path is safe when it is POSIX, relative and has no `..`, `.` or empty segments. */
+function isSafeRelative(rel) {
+  if (typeof rel !== 'string' || rel === '' || rel.includes('\\') || rel.includes('\0')) return false;
+  if (rel.startsWith('/') || /^[A-Za-z]:/.test(rel)) return false;
+  return rel.split('/').every((part) => part !== '' && part !== '.' && part !== '..');
+}
+
+function isInside(root, abs) {
+  return abs === root || abs.startsWith(root + path.sep);
+}
+
+/**
+ * Resolves `rel` inside `root` (which must already be a real path). Throws on path
+ * traversal and when an existing ancestor is a symlink that escapes `root`.
+ */
+function resolveInside(root, rel) {
+  if (!isSafeRelative(rel)) throw new Error(`Caminho inseguro recusado: ${JSON.stringify(rel)}`);
+  const abs = path.resolve(root, ...rel.split('/'));
+  if (!isInside(root, abs)) throw new Error(`Caminho fora da pasta do projeto recusado: ${rel}`);
+  let probe = abs;
+  while (probe !== root && !fs.existsSync(probe)) probe = path.dirname(probe);
+  if (!isInside(root, fs.realpathSync(probe))) {
+    throw new Error(`Caminho que aponta para fora da pasta do projeto (link simbólico) recusado: ${rel}`);
+  }
+  return abs;
+}
+
+function isProjectPath(rel) {
+  return rel === PROJECT_DIR || rel.startsWith(`${PROJECT_DIR}/`);
+}
+
+// Resolve existing ancestors so aliases into project/ cannot bypass its guard,
+// including when the final file does not exist yet.
+function canonicalPath(abs) {
+  let probe = abs;
+  while (!fs.existsSync(probe)) {
+    const parent = path.dirname(probe);
+    if (parent === probe) break;
+    probe = parent;
+  }
+  return path.resolve(fs.realpathSync(probe), path.relative(probe, abs));
+}
+
+function resolvesToProject(root, abs) {
+  return isInside(canonicalPath(path.join(root, PROJECT_DIR)), canonicalPath(abs));
+}
+
+module.exports = {
+  PKG_ROOT,
+  CONTENT_DIR,
+  SKILLS_DIR,
+  TEMPLATES_DIR,
+  ADAPTERS_DIR,
+  FRAMEWORK_SOURCE,
+  IGNITY_DIR,
+  MANIFEST_PATH,
+  FRAMEWORK_PATH,
+  BACKUPS_DIR,
+  PROJECT_DIR,
+  V1_FRAMEWORK_PATH,
+  CLIENTS,
+  CLIENT_FOLDERS,
+  CLIENT_ADAPTERS,
+  isSafeRelative,
+  resolveInside,
+  isProjectPath,
+  resolvesToProject,
+};

package/src/lib/prompt.js

@@ -0,0 +1,30 @@
+'use strict';
+const readline = require('node:readline/promises');
+const { sanitizeUrl } = require('./sanitize-url');
+const { CliError } = require('./log');
+function environment(value) {
+  value = value || 'staging';
+  if (!['staging', 'produção', 'producao', 'production'].includes(value)) throw new CliError('Ambiente deve ser produção ou staging.');
+  return value === 'staging' ? value : 'produção';
+}
+function clean(value) { return (value || 'desconhecido').replace(/[\r\n\x00-\x1f\x7f]/g, ' '); }
+function answers(flags = {}) {
+  return { site: sanitizeUrl(flags['site-url']), env: environment(flags.env), figma: sanitizeUrl(flags.figma, true), assets: clean(flags.assets || './assets'), scope: clean(flags.scope) };
+}
+async function ask(flags, out) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  async function question(label, initial, validate) {
+    if (initial !== undefined) return validate(initial);
+    for (;;) {
+      try { return validate(await rl.question(label)); } catch (e) { out.warn(e.message); }
+    }
+  }
+  try {
+    const site = await question('URL do site WordPress (ambiente entre parênteses, padrão staging): ', flags['site-url'], value => {
+      const match = value.match(/^(.*?)\s*\(([^)]+)\)\s*$/);
+      return { site: sanitizeUrl(match ? match[1].trim() : value), env: environment(flags.env || (match && match[2])) };
+    });
+    return { ...site, figma: await question('Link do Figma: ', flags.figma, v => sanitizeUrl(v, true)), assets: await question('Pasta dos assets [./assets]: ', flags.assets, v => clean(v || './assets')), scope: await question('O que construir agora: ', flags.scope, clean) };
+  } finally { rl.close(); }
+}
+module.exports = { answers, ask };

package/src/lib/sanitize-url.js

@@ -0,0 +1,14 @@
+'use strict';
+const { CliError } = require('./log');
+function sanitizeUrl(value, figma = false) {
+  if (!value || value === 'desconhecido') return 'desconhecido';
+  let url;
+  try { url = new URL(value); } catch { throw new CliError('Informe uma URL http ou https válida, sem credenciais.'); }
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw new CliError('Informe uma URL http ou https sem credenciais embutidas.');
+  if (figma && !['figma.com', 'www.figma.com'].includes(url.hostname)) throw new CliError('O link do Figma deve usar figma.com ou www.figma.com.');
+  const node = figma && url.searchParams.get('node-id');
+  url.search = ''; url.hash = '';
+  if (node) url.searchParams.set('node-id', node);
+  return url.toString();
+}
+module.exports = { sanitizeUrl };

package/src/lib/sync.js

@@ -0,0 +1,251 @@
+'use strict';
+
+/**
+ * Shared engine of `init` and `update`: computes the package layout for a client,
+ * reconciles it with what is on disk (v2 manifest or v1 hashes as baseline),
+ * merges the adapter blocks and rewrites the manifest.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+  SKILLS_DIR,
+  TEMPLATES_DIR,
+  ADAPTERS_DIR,
+  FRAMEWORK_SOURCE,
+  FRAMEWORK_PATH,
+  MANIFEST_PATH,
+  V1_FRAMEWORK_PATH,
+  CLIENT_FOLDERS,
+  CLIENT_ADAPTERS,
+  resolveInside,
+} = require('./paths');
+const { listFiles, sha256, sha256File, readIfExists } = require('./files');
+const { readManifest, writeManifest, serializeManifest } = require('./manifest');
+const merger = require('./merger');
+const { createBackup } = require('./backup');
+const { createWriter } = require('./writer');
+const { detectClient } = require('./client-detect');
+const { detectV1, v1Hashes, v1AdapterText } = require('./v1-detect');
+const { CliError } = require('./log');
+const { version: PKG_VERSION } = require('../../package.json');
+
+/** Files the package installs for `client` (skills + framework guide), excluding adapters and templates. */
+function desiredFiles(client) {
+  const skills = listFiles(SKILLS_DIR);
+  const out = [];
+  for (const folder of CLIENT_FOLDERS[client]) {
+    for (const rel of skills) out.push({ path: `${folder}/skills/${rel}`, source: path.join(SKILLS_DIR, rel) });
+  }
+  out.push({ path: FRAMEWORK_PATH, source: FRAMEWORK_SOURCE });
+  return out;
+}
+
+function desiredAdapters(client) {
+  return CLIENT_ADAPTERS[client].map((name) => ({ path: name, source: path.join(ADAPTERS_DIR, name) }));
+}
+
+/** Templates from the package that are missing in project/. */
+function missingTemplates(root) {
+  return listFiles(TEMPLATES_DIR).filter((tpl) => !fs.existsSync(resolveInside(root, `project/${tpl}`)));
+}
+
+function templateCopyHint(tpl, root) {
+  const quote = (value) => `'${value.replace(/'/g, "'\\''")}'`;
+  return `cp ${quote(path.join(TEMPLATES_DIR, tpl))} ${quote(path.join(root, 'project', tpl))}`;
+}
+
+/**
+ * @param {{root: string, dryRun: boolean, client?: string, out: object}} ctx
+ * @param {{mode: 'init'|'update'}} options
+ * @returns {number} exit code
+ */
+function sync(ctx, { mode }) {
+  const { root, dryRun, out } = ctx;
+  const existing = readManifest(root);
+  const v1 = existing ? null : detectV1(root);
+  const migrating = Boolean(v1 && v1.detected);
+
+  if (mode === 'update' && !existing && !migrating) {
+    throw new CliError(
+      'Nenhuma instalação do Ignity encontrada nesta pasta (sem .ignity/manifest.json e sem sinais do v1). ' +
+        'Para instalar, rode: npx @marvinribeiro_/ignity init',
+    );
+  }
+
+  const client = ctx.client || (existing && existing.client) || detectClient(root);
+  const previous = new Map(((existing && existing.files) || []).map((f) => [f.path, f]));
+  // Different client adapters cannot safely share one physical file: each has
+  // a different block, and updating or removing either would affect the other.
+  // Check before creating skills, backups, or any other files.
+  const adapters = new Set(desiredAdapters(client).map((a) => a.path));
+  for (const entry of previous.values()) if (entry.kind === 'merged-block') adapters.add(entry.path);
+  const seenAdapters = new Map();
+  for (const rel of adapters) {
+    const abs = resolveInside(root, rel);
+    if (!fs.existsSync(abs)) continue;
+    const stat = fs.statSync(abs);
+    const identity = `${stat.dev}:${stat.ino}`;
+    if (seenAdapters.has(identity)) {
+      throw new CliError(`${seenAdapters.get(identity)} e ${rel} apontam para o mesmo arquivo. Separe os arquivos antes de executar o Ignity novamente.`);
+    }
+    seenAdapters.set(identity, rel);
+  }
+  const baseline = migrating ? v1Hashes() : new Map([...previous.values()].filter((f) => !f.kind).map((f) => [f.path, f.sha256]));
+
+  out.line(`Ignity ${PKG_VERSION} — ${mode}${dryRun ? ' (simulação: nada será gravado)' : ''}`);
+  out.line(`Pasta: ${root}`);
+  out.line(`Cliente: ${client}${ctx.client ? '' : existing ? ' (do manifesto)' : ' (detectado)'}`);
+
+  if (migrating) {
+    out.line('Instalação v1 detectada (sem .ignity/manifest.json). Migrando para o layout v2.');
+    for (const l of v1.describe()) out.line(`  ${l}`);
+    if (!v1.skillSignals.length) {
+      out.warn(`skills v1 não encontradas; as skills serão instaladas do zero em ${CLIENT_FOLDERS[client].join(' e ')}.`);
+    }
+  }
+
+  const writer = createWriter({ root, dryRun, out, allowProjectCreate: mode === 'init' });
+  const backup = createBackup({ root, dryRun, out });
+  const entries = [];
+  const desired = desiredFiles(client);
+  const desiredPaths = new Set(desired.map((d) => d.path));
+
+  // Skills and framework guide.
+  for (const d of desired) {
+    const data = fs.readFileSync(d.source);
+    const hash = sha256(data);
+    const abs = resolveInside(root, d.path);
+    const prev = previous.get(d.path);
+    let created;
+    if (!fs.existsSync(abs)) {
+      writer.create(d.path, data);
+      created = prev ? prev.created : true;
+    } else {
+      const current = sha256File(abs);
+      const known = baseline.get(d.path);
+      created = prev ? prev.created : Boolean(known);
+      if (current !== hash) {
+        if (known && current === known) {
+          backup.save(d.path);
+          writer.update(d.path, data);
+        } else {
+          const copy = backup.save(d.path);
+          out.warn(`${d.path} foi alterado fora do Ignity; cópia salva em ${copy} e arquivo substituído pela versão do pacote.`);
+          writer.update(d.path, data);
+        }
+      }
+    }
+    entries.push({ path: d.path, sha256: hash, owner: 'ignity', created });
+  }
+
+  // Files from a previous manifest that the package no longer installs (e.g. client narrowed).
+  for (const prev of previous.values()) {
+    if (prev.kind || desiredPaths.has(prev.path)) continue;
+    const abs = resolveInside(root, prev.path);
+    if (!fs.existsSync(abs)) continue;
+    if (sha256File(abs) === prev.sha256) writer.remove(prev.path, 'não faz mais parte da instalação');
+    else out.warn(`${prev.path} não faz mais parte da instalação, mas foi alterado; mantido no lugar.`);
+  }
+
+  // Adapter blocks.
+  const desiredAdapterPaths = new Set();
+  for (const a of desiredAdapters(client)) {
+    desiredAdapterPaths.add(a.path);
+    const body = fs.readFileSync(a.source, 'utf8');
+    const prev = previous.get(a.path);
+    const text = readIfExists(resolveInside(root, a.path), 'utf8');
+    let created = prev ? prev.created : false;
+    let next;
+    let note;
+    if (text === null) {
+      next = merger.upsertBlock(null, body);
+      created = true;
+    } else if (merger.hasBlock(text)) {
+      next = merger.upsertBlock(text, body);
+    } else if (migrating && sha256(text) === (v1Hashes().get(a.path) || '')) {
+      next = merger.upsertBlock(null, body);
+      created = true;
+      note = 'adapter v1 trocado pelo bloco com marcadores';
+    } else if (migrating && v1AdapterText(a.path) && merger.replaceTextWithBlock(text, v1AdapterText(a.path), body) !== null) {
+      next = merger.replaceTextWithBlock(text, v1AdapterText(a.path), body);
+      note = 'trecho v1 trocado pelo bloco com marcadores';
+    } else {
+      next = merger.upsertBlock(text, body);
+      note = 'bloco anexado ao final; conteúdo existente preservado';
+      if (migrating) out.warn(`${a.path} não contém o texto do adapter v1; o bloco do Ignity foi anexado ao final. Revise se há instruções duplicadas.`);
+    }
+    if (text === null) writer.create(a.path, next);
+    else if (next !== text) {
+      backup.save(a.path);
+      writer.update(a.path, next, note);
+    }
+    entries.push({ path: a.path, kind: 'merged-block', owner: 'ignity', created, blockSha256: sha256(merger.normalizeBody(body, '\n')) });
+  }
+
+  // Adapter blocks of a client that is no longer installed.
+  for (const prev of previous.values()) {
+    if (prev.kind !== 'merged-block' || desiredAdapterPaths.has(prev.path)) continue;
+    removeAdapterBlock({ root, rel: prev.path, created: prev.created, writer, backup });
+  }
+
+  // Templates in project/.
+  if (mode === 'init') {
+    for (const tpl of listFiles(TEMPLATES_DIR)) {
+      const rel = `project/${tpl}`;
+      if (!fs.existsSync(resolveInside(root, rel))) writer.create(rel, tpl === 'BRIEF.md' && ctx.brief ? ctx.brief : fs.readFileSync(path.join(TEMPLATES_DIR, tpl)));
+    }
+  } else {
+    for (const tpl of missingTemplates(root)) {
+      out.warn(`template project/${tpl} ausente. O update não toca project/; para copiá-lo: ${templateCopyHint(tpl, root)}`);
+    }
+  }
+
+  if (fs.existsSync(resolveInside(root, V1_FRAMEWORK_PATH))) {
+    out.line(`INFO: ${V1_FRAMEWORK_PATH} é da instalação v1 e ficou onde está (obsoleto). O guia atual está em ${FRAMEWORK_PATH}.`);
+  }
+
+  // Manifest (rewritten only when something changed, so a no-op run leaves no diff).
+  const now = new Date().toISOString();
+  const manifest = {
+    ignityVersion: PKG_VERSION,
+    client,
+    installedAt: (existing && existing.installedAt) || now,
+    updatedAt: now,
+    files: entries,
+  };
+  const unchanged =
+    existing &&
+    writer.changes === 0 &&
+    serializeManifest({ ...manifest, updatedAt: existing.updatedAt }) === serializeManifest(existing);
+  if (!unchanged) {
+    if (dryRun) out.line(`${existing ? 'PREVER ATUALIZAR' : 'PREVER CRIAR'} ${MANIFEST_PATH}`);
+    else {
+      writeManifest(root, manifest);
+      out.line(`${existing ? 'ATUALIZADO' : 'CRIADO'} ${MANIFEST_PATH}`);
+    }
+  }
+
+  out.line('');
+  if (writer.changes === 0 && unchanged) out.line('Nada a fazer: a instalação já está na versão do pacote.');
+  if (backup.count > 0 && !dryRun) out.line(`Backups em ${backup.dir}/`);
+  if (out.warnings.length) out.line(`${out.warnings.length} aviso(s) acima.`);
+  return 0;
+}
+
+/** Removes the Ignity block from an adapter; deletes the file if Ignity created it and it became empty. */
+function removeAdapterBlock({ root, rel, created, writer, backup, blockSha256 }) {
+  const text = readIfExists(resolveInside(root, rel), 'utf8');
+  if (text === null || !merger.hasBlock(text)) return false;
+  const next = merger.removeBlock(text);
+  if (created && next.trim() === '') {
+    if (blockSha256 && sha256(merger.extractBody(text)) !== blockSha256) backup.save(rel);
+    writer.remove(rel, 'criado pelo Ignity e vazio sem o bloco');
+  } else {
+    backup.save(rel);
+    writer.update(rel, next, 'bloco do Ignity removido');
+  }
+  return true;
+}
+
+module.exports = { sync, desiredFiles, desiredAdapters, missingTemplates, templateCopyHint, removeAdapterBlock, PKG_VERSION };