@daniellins/power-claude 0.16.3

package/scripts/pod-export-compile.cjs

@@ -0,0 +1,487 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * pod-export-compile.cjs — compilador de motor: transforma um pod maduro (contrato
+ * v0.3) num BUNDLE server-side versionado + um `export.lock.json` auditável.
+ *
+ * Comando (padrão da casa, ADR-007):
+ *   node scripts/pod-export-compile.cjs compile <pod-dir> [opções]
+ *
+ * Opções:
+ *   --out <dir>        override do diretório do bundle (default: .power-claude/pod-export/<pod>/bundle)
+ *   --pins <file>      override do arquivo de pins (default: exports/<pod>/pins.json)
+ *   --lock-out <file>  override do path do lock (default: exports/<pod>/export.lock.json)
+ *   --no-endpoint-check  pula a checagem de endpoint do modelo de imagem (uso: debug local; NUNCA em release)
+ *
+ * Fronteiras (ADR-018 F1; Story SF10.1):
+ *   - REUSA `validate-pod-workflow.cjs` para o preflight de contrato (não reimplementa schema/DAG).
+ *   - O "grafo" é o `wf-*.yaml` ORIGINAL empacotado VERBATIM (D3 — sem IR, sem tradução).
+ *   - Knowledge citado vem do campo estruturado `knowledge:` POR STEP no wf (D2), com 3 checks
+ *     fail-loud (existência, superconjunto, órfãos) — derivação PROGRAMÁTICA, nunca mapa hardcoded.
+ *   - Não roda o bundle (executor/runtime é F2), não faz release/selo (F4), não faz push.
+ *
+ * Node >= 18, zero dependências externas. Determinístico: mesmo pod@sha (digest de conteúdo)
+ * + mesmo COMPILER_VERSION → bundle byte-idêntico (nenhum timestamp/aleatório no conteúdo).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const {
+  parseYaml,
+  validateWorkflow,
+  topoOrder,
+  Fail,
+} = require('./validate-pod-workflow.cjs');
+
+// Versão da SAÍDA do compilador (semver). Bumpar quando a forma do bundle/lock mudar
+// (D4: chave de determinismo é `pod@sha + COMPILER_VERSION`; NÃO usar framework_version aqui).
+const COMPILER_VERSION = '1.0.0';
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const VETO_CHECKS_DIR = path.join(REPO_ROOT, 'scripts', 'veto-checks');
+
+class CompileError extends Error {}
+function fail(msg) { throw new CompileError(msg); }
+
+function sha256(buf) { return crypto.createHash('sha256').update(buf).digest('hex'); }
+function read(p) { return fs.readFileSync(p, 'utf8'); }
+function readBuf(p) { return fs.readFileSync(p); }
+
+/** Ordena as chaves de um objeto plano → serialização determinística. */
+function sortedObject(obj) {
+  const out = {};
+  for (const k of Object.keys(obj).sort()) out[k] = obj[k];
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Parsing de agente (frontmatter, corpo, golden rules, citações de comando).
+// ---------------------------------------------------------------------------
+
+function splitFrontmatter(md) {
+  const m = md.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!m) return { frontmatter: {}, body: md.trim() };
+  const fmText = m[1];
+  const body = md.slice(m[0].length).trim();
+  const fm = {};
+  for (const line of fmText.split(/\r?\n/)) {
+    const mm = line.match(/^([A-Za-z0-9_]+):\s*(.*)$/);
+    if (mm) fm[mm[1]] = mm[2].trim();
+  }
+  return { frontmatter: fm, body };
+}
+
+/** Extrai a seção `## Regras de ouro` (golden rules) do corpo do agente; '' se ausente. */
+function extractGoldenRules(body) {
+  const lines = body.split(/\r?\n/);
+  const start = lines.findIndex((l) => /^##\s+Regras de ouro\b/i.test(l.trim()));
+  if (start === -1) return '';
+  const out = [lines[start]];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^##\s+\S/.test(lines[i].trim())) break;
+    out.push(lines[i]);
+  }
+  return out.join('\n').trim();
+}
+
+/**
+ * D2 check 2 (superconjunto): citações `knowledge/<x>.md` parseáveis nas LINHAS DE COMANDO
+ * do agente (bullets iniciando por `- \`*comando`). Retorna Set de basenames (ex.: "slides-html.md").
+ */
+function parseCommandKnowledge(body) {
+  const cited = new Set();
+  for (const line of body.split(/\r?\n/)) {
+    if (!/^\s*-\s*`\*/.test(line)) continue; // só linhas de comando
+    const re = /knowledge\/([A-Za-z0-9._-]+\.md)/g;
+    let m;
+    while ((m = re.exec(line)) !== null) cited.add(m[1]);
+  }
+  return cited;
+}
+
+// ---------------------------------------------------------------------------
+// Pins de modelo (D4): INPUT explícito committado; FALHA se algum alias sem pin.
+// ---------------------------------------------------------------------------
+
+function loadPins(pinsPath) {
+  if (!fs.existsSync(pinsPath)) {
+    fail(`pins.json ausente: ${path.relative(REPO_ROOT, pinsPath)} — o lock exige id CONCRETO de modelo por alias (D4). Crie o arquivo.`);
+  }
+  let pins;
+  try { pins = JSON.parse(read(pinsPath)); } catch (e) { fail(`pins.json inválido (${path.relative(REPO_ROOT, pinsPath)}): ${e.message}`); }
+  if (!pins.models || typeof pins.models !== 'object') fail('pins.json: campo "models" (alias→id Anthropic) ausente');
+  if (!pins.image_model || typeof pins.image_model !== 'object' || !pins.image_model.id) {
+    fail('pins.json: campo "image_model" {id, endpoints_url} ausente');
+  }
+  return pins;
+}
+
+// ---------------------------------------------------------------------------
+// Checagem de endpoint do modelo de imagem (AC5 / Achado 1 do spike).
+// Rede injetável (fetchImpl) para CI hermética; default usa fetch global (Node 18+).
+// ---------------------------------------------------------------------------
+
+async function validateImageEndpoint(imageModel, { fetchImpl, apiKey } = {}) {
+  const doFetch = fetchImpl || globalThis.fetch;
+  const url = imageModel.endpoints_url;
+  if (!url) fail('pins.json image_model.endpoints_url ausente — não há como validar disponibilidade (AC5)');
+  let res;
+  try {
+    res = await doFetch(url, { headers: apiKey ? { Authorization: `Bearer ${apiKey}` } : {} });
+  } catch (e) {
+    fail(`modelo de imagem "${imageModel.id}": falha ao consultar endpoint (${url}): ${e.message}`);
+  }
+  if (!res.ok) {
+    fail(`modelo de imagem "${imageModel.id}": endpoint indisponível — HTTP ${res.status} em ${url} (Achado 1 do spike: modelo descontinuado FALHA o compile)`);
+  }
+  let body;
+  try { body = await res.json(); } catch (e) { fail(`modelo de imagem "${imageModel.id}": resposta do endpoint não é JSON: ${e.message}`); }
+  const endpoints = body && body.data && body.data.endpoints;
+  if (!Array.isArray(endpoints) || endpoints.length === 0) {
+    fail(`modelo de imagem "${imageModel.id}": SEM endpoints ativos ("No endpoints" — Achado 1 do spike). Pino de imagem morto: compile ABORTADO.`);
+  }
+  return { id: imageModel.id, endpoints_count: endpoints.length };
+}
+
+// ---------------------------------------------------------------------------
+// Compilação.
+// ---------------------------------------------------------------------------
+
+/**
+ * Compila o pod em bundle + lock (não escreve o lock; devolve o objeto). Async por causa
+ * da checagem de endpoint (AC5). `opts.fetchImpl`/`opts.apiKey` injetáveis (CI mocka a rede).
+ */
+async function compile(podDir, opts = {}) {
+  const podRoot = path.resolve(podDir);
+  if (!fs.existsSync(podRoot) || !fs.statSync(podRoot).isDirectory()) {
+    fail(`pod-dir inexistente ou não é diretório: ${podDir}`);
+  }
+
+  // pod-spec.json → nome do pod + workflowId (D6: nome vem do spec, não do path).
+  const specPath = path.join(podRoot, 'pod-spec.json');
+  if (!fs.existsSync(specPath)) fail(`pod-spec.json ausente em ${podDir} — não é um pod v0.3`);
+  const spec = JSON.parse(read(specPath));
+  const podName = spec.pod;
+  const wfId = spec.workflowId || podName;
+  if (!podName) fail('pod-spec.json sem campo "pod"');
+
+  const wfPath = path.join(podRoot, 'workflows', `wf-${wfId}.yaml`);
+  if (!fs.existsSync(wfPath)) fail(`workflow ausente: workflows/wf-${wfId}.yaml`);
+
+  // Preflight de contrato — REUSO do validador (não reimplementa; D3). Fail-loud.
+  try {
+    validateWorkflow(wfPath, podRoot);
+  } catch (e) {
+    if (e instanceof Fail) fail(`pod-fonte reprovado por validate-pod-workflow: ${e.message}`);
+    throw e;
+  }
+
+  const doc = parseYaml(read(wfPath));
+  const order = topoOrder(doc);
+  const stepById = (id) => doc.steps.find((s) => s.id === id);
+
+  // Pins.
+  const pinsPath = opts.pinsPath || path.join(REPO_ROOT, 'exports', podName, 'pins.json');
+  const pins = loadPins(pinsPath);
+
+  // Inventário de knowledge .md do pod (para o check de órfãos, D2 check 3).
+  const knowledgeDir = path.join(podRoot, 'knowledge');
+  const podKnowledgeMd = fs.existsSync(knowledgeDir)
+    ? fs.readdirSync(knowledgeDir).filter((f) => f.endsWith('.md')).sort()
+    : [];
+  const knowledgeExclude = Array.isArray(doc.knowledge_exclude) ? doc.knowledge_exclude : [];
+
+  const perFileSha = {}; // relpath (posix, pod-relativo ou framework-relativo p/ veto) → sha
+  const bundleFiles = []; // { rel, content(Buffer|string) }
+  const claimedKnowledge = new Set();
+  const phasesMeta = {};
+  const modelosAgentes = {};
+  const vetoScriptsToBundle = new Set();
+
+  function trackSource(absPath, relKey) {
+    const buf = readBuf(absPath);
+    perFileSha[relKey] = sha256(buf);
+    return buf;
+  }
+
+  // ---- Tabela de compilação (ADR-018 Decisão 2), por fase, na ordem topológica ----
+  for (const stepId of order) {
+    const step = stepById(stepId);
+    const agentName = step.agent;
+    const agentAbs = path.join(podRoot, 'agents', `${agentName}.md`);
+    if (!fs.existsSync(agentAbs)) fail(`etapa "${stepId}": agente inexistente agents/${agentName}.md`);
+    const agentBuf = trackSource(agentAbs, `agents/${agentName}.md`);
+    const { frontmatter, body } = splitFrontmatter(agentBuf.toString('utf8'));
+
+    // Modelo PINADO (D4): frontmatter traz ALIAS; lock exige id concreto.
+    const alias = frontmatter.model;
+    if (!alias) fail(`etapa "${stepId}": agente sem "model" no frontmatter`);
+    const modelId = pins.models[alias];
+    if (!modelId) fail(`etapa "${stepId}": alias de modelo "${alias}" sem pin em ${path.relative(REPO_ROOT, pinsPath)} (D4: FALHA se algum alias sem pin)`);
+    modelosAgentes[stepId] = modelId;
+    const budgetTokens = frontmatter.budget_tokens != null ? Number(frontmatter.budget_tokens) : null;
+
+    // Knowledge declarado (D2): OBRIGATÓRIO para o compile.
+    const declared = Array.isArray(step.knowledge) ? step.knowledge : null;
+    if (!declared || declared.length === 0) {
+      fail(`etapa "${stepId}": campo "knowledge:" ausente ou vazio no wf — OBRIGATÓRIO para exportar (D2). ` +
+        `Declare a lista ordenada de knowledge/*.md que a fase realmente cita.`);
+    }
+    // Check 1 — existência.
+    for (const k of declared) {
+      const kAbs = path.join(knowledgeDir, k);
+      if (!fs.existsSync(kAbs)) {
+        fail(`etapa "${stepId}": knowledge declarado inexistente no pod — knowledge/${k} (D2 check 1: mata o fantasma tipo "hn-fetch.md" declarado num pod que não o tem)`);
+      }
+      claimedKnowledge.add(k);
+    }
+    // Check 2 — superconjunto (citações parseáveis ⊆ declarado).
+    const parsed = parseCommandKnowledge(body);
+    for (const c of parsed) {
+      if (!declared.includes(c)) {
+        fail(`etapa "${stepId}": knowledge/${c} é CITADO na linha de comando do agente mas NÃO está declarado em knowledge: [${declared.join(', ')}] ` +
+          `(D2 check 2: declaração deve ser superconjunto das citações, nunca subconjunto)`);
+      }
+    }
+
+    // Corpo do agente + golden rules + knowledge (ORDEM DECLARADA) + memória (SÓ-LEITURA).
+    const golden = extractGoldenRules(body);
+    const sysParts = [];
+    sysParts.push(`# AGENTE DA FASE (${agentName})\n\n${body}`);
+    if (golden) sysParts.push(`\n\n# REGRAS DE OURO (golden rules — ${agentName})\n\n${golden}`);
+    for (const k of declared) { // ordem declarada = ordem de anexação (D2)
+      const kBuf = trackSource(path.join(knowledgeDir, k), `knowledge/${k}`);
+      sysParts.push(`\n\n# KNOWLEDGE: ${k}\n\n${kBuf.toString('utf8').trim()}`);
+      bundleFiles.push({ rel: `knowledge/${k}`, content: kBuf });
+    }
+    // Memória consolidada (SÓ-LEITURA — recordLearning DESLIGADO no export).
+    const consolidatedAbs = path.join(podRoot, 'memory', 'learnings.consolidated.md');
+    let consolidatedBlock = '';
+    if (fs.existsSync(consolidatedAbs)) {
+      const cBuf = trackSource(consolidatedAbs, 'memory/learnings.consolidated.md');
+      // Ramificação POR TRANSPORTE (DF-SF11.2-2, agora também DF-SF11.4-6): o prompt
+      // compilado nunca cita arquivo que não viaja no bundle. `learnings.jsonl` (log cru)
+      // sai de vez — o agente nunca o lê. A trilha auditável das endurecidas
+      // (`memory/learnings.hardened.md`) existe no repositório do pod, não no bundle:
+      // a linha é REESCRITA (não some) para não deixar referência pendurada no export,
+      // preservando a referência agregada que a precede.
+      const cBody = cBuf.toString('utf8')
+        .split(/\r?\n/)
+        .filter((l) => !/learnings\.jsonl/.test(l))
+        .map((l) => (/learnings\.hardened\.md/.test(l)
+          ? '_Detalhe auditável das endurecidas (asserção, aprovador, momento) vive no repositório do pod — NÃO viaja no bundle do export; aqui valem os arquivos de knowledge compilados acima._'
+          : l))
+        .join('\n').trim();
+      consolidatedBlock = `\n\n# MEMÓRIA CONSOLIDADA DO POD (SÓ-LEITURA — não evolui no export; recordLearning DESLIGADO)\n\n${cBody}`;
+      sysParts.push(consolidatedBlock);
+    }
+    sysParts.push('\n\n# EXECUÇÃO SERVER-SIDE (export)\n' +
+      'Você roda como executor autônomo via API, SEM operador humano na etapa. A memória acima é SÓ-LEITURA ' +
+      '(não registre aprendizados). Use SOMENTE as tools fornecidas ao executor. Ao terminar, escreva o artefato ' +
+      'final da etapa no path exato indicado e pare. Não invente fato fora da fonte.');
+    const systemPrompt = sysParts.join('');
+
+    // Template → contrato de saída no user prompt.
+    const tmplRel = step.template;
+    const tmplAbs = path.join(podRoot, tmplRel);
+    const tmplBuf = trackSource(tmplAbs, tmplRel);
+    const userPrompt = [
+      `# CONTRATO DE SAÍDA — fase ${stepId}`,
+      `Escreva o artefato "${(step.outputs || []).join(', ')}" EXATAMENTE no formato do template abaixo, com todos os headings "##" e campos de máquina.`,
+      '',
+      '```',
+      tmplBuf.toString('utf8').trim(),
+      '```',
+    ].join('\n');
+    bundleFiles.push({ rel: `templates/${path.basename(tmplRel)}`, content: tmplBuf });
+
+    // Vetos: command_check blessed → empacotar o script blessed no bundle (D2 tabela linha 6).
+    const assertions = (step.veto && Array.isArray(step.veto.assertions)) ? step.veto.assertions : [];
+    for (const a of assertions) {
+      if (a && a.type === 'command_check' && typeof a.command === 'string') {
+        vetoScriptsToBundle.add(a.command);
+      }
+    }
+
+    // Escreve os prompts compilados da fase no bundle.
+    bundleFiles.push({ rel: `phases/${stepId}/system.md`, content: systemPrompt });
+    bundleFiles.push({ rel: `phases/${stepId}/user.md`, content: userPrompt });
+    phasesMeta[stepId] = {
+      agent: agentName,
+      model_id: modelId,
+      budget_tokens: budgetTokens,
+      knowledge: declared, // ordem preservada
+      template: `templates/${path.basename(tmplRel)}`,
+      outputs: step.outputs || [],
+      veto_scripts: assertions.filter((a) => a && a.type === 'command_check').map((a) => a.command),
+    };
+    bundleFiles.push({ rel: `phases/${stepId}/meta.json`, content: JSON.stringify(phasesMeta[stepId], null, 2) + '\n' });
+  }
+
+  // Check 3 — órfãos (D2): todo knowledge/*.md do pod é reivindicado OU excluído.
+  const orphans = podKnowledgeMd.filter((k) => !claimedKnowledge.has(k) && !knowledgeExclude.includes(k));
+  if (orphans.length > 0) {
+    fail(`knowledge órfão(s) — presente(s) no pod mas não reivindicado(s) por nenhuma fase nem em knowledge_exclude: ${orphans.join(', ')} ` +
+      `(D2 check 3: teria pego "identidade-visual-mascote.md" esquecido). Declare-o(s) na fase que usa ou em knowledge_exclude: no topo do wf.`);
+  }
+
+  // Empacota os scripts de veto blessed citados (verbatim).
+  for (const cmd of [...vetoScriptsToBundle].sort()) {
+    const vAbs = path.join(VETO_CHECKS_DIR, cmd);
+    if (!fs.existsSync(vAbs)) fail(`veto blessed citado inexistente: scripts/veto-checks/${cmd}`);
+    const vBuf = trackSource(vAbs, `veto-checks/${cmd}`);
+    bundleFiles.push({ rel: `veto-checks/${cmd}`, content: vBuf });
+  }
+
+  // Grafo VERBATIM (D3) + pod-spec.
+  const wfBuf = trackSource(wfPath, `workflows/wf-${wfId}.yaml`);
+  bundleFiles.push({ rel: 'workflow.yaml', content: wfBuf });
+  const specBuf = trackSource(specPath, 'pod-spec.json');
+  bundleFiles.push({ rel: 'pod-spec.json', content: specBuf });
+  const consolidatedAbs = path.join(podRoot, 'memory', 'learnings.consolidated.md');
+  if (fs.existsSync(consolidatedAbs)) {
+    bundleFiles.push({ rel: 'memory/learnings.consolidated.md', content: readBuf(consolidatedAbs) });
+  }
+
+  // Validação de endpoint do modelo de imagem (AC5) — sempre, salvo debug local.
+  let imageEndpoint = null;
+  if (opts.checkEndpoint !== false) {
+    imageEndpoint = await validateImageEndpoint(pins.image_model, {
+      fetchImpl: opts.fetchImpl,
+      apiKey: opts.apiKey || process.env.OPENROUTER_API_KEY,
+    });
+  }
+
+  // Índice do bundle (determinístico).
+  const bundleIndex = {
+    pod: podName,
+    compiler_version: COMPILER_VERSION,
+    graph: 'workflow.yaml',
+    order,
+    phases: phasesMeta,
+    modelo_pinado: { agents: sortedObject(modelosAgentes), image: pins.image_model.id },
+  };
+  bundleFiles.push({ rel: 'bundle.json', content: JSON.stringify(bundleIndex, null, 2) + '\n' });
+
+  // pod_sha = digest de conteúdo determinístico das FONTES que alimentam o bundle
+  // (git-independente; "same pod@sha → byte-identical bundle"). D4/AC4.
+  const podShaInput = Object.keys(perFileSha).sort().map((k) => `${k}:${perFileSha[k]}`).join('\n');
+  const podSha = sha256(Buffer.from(podShaInput, 'utf8'));
+
+  // bundle_hashes = sha de cada arquivo escrito no bundle.
+  const bundleHashes = {};
+  for (const f of bundleFiles) {
+    const buf = Buffer.isBuffer(f.content) ? f.content : Buffer.from(f.content, 'utf8');
+    bundleHashes[f.rel] = sha256(buf);
+  }
+
+  const framework_version = JSON.parse(read(path.join(REPO_ROOT, 'package.json'))).version;
+
+  // Schema do lock (AC6) — chaves na ordem do schema; hashes com chaves ordenadas.
+  const lock = {
+    pod: podName,
+    pod_sha: podSha,
+    per_file_sha: sortedObject(perFileSha),
+    modelo_pinado: {
+      agents: sortedObject(modelosAgentes),
+      image: sortedObject({ id: pins.image_model.id, endpoints_url: pins.image_model.endpoints_url || null }),
+    },
+    framework_version,
+    compiler_version: COMPILER_VERSION,
+    bundle_hashes: sortedObject(bundleHashes),
+  };
+
+  return { podName, bundleFiles, lock, imageEndpoint };
+}
+
+/** Escreve o bundle em disco (limpa o dir antes → determinismo/sem stale). */
+function writeBundle(bundleDir, bundleFiles) {
+  fs.rmSync(bundleDir, { recursive: true, force: true });
+  for (const f of bundleFiles) {
+    const abs = path.join(bundleDir, f.rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, Buffer.isBuffer(f.content) ? f.content : Buffer.from(f.content, 'utf8'));
+  }
+}
+
+function serializeLock(lock) {
+  return JSON.stringify(lock, null, 2) + '\n';
+}
+
+// ---------------------------------------------------------------------------
+// CLI.
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const sub = argv[0];
+  if (sub !== 'compile') {
+    console.error('Uso: node scripts/pod-export-compile.cjs compile <pod-dir> [--out <dir>] [--pins <file>] [--lock-out <file>] [--no-endpoint-check]');
+    process.exit(2);
+  }
+  const rest = argv.slice(1);
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === '--out') flags.out = rest[++i];
+    else if (rest[i] === '--pins') flags.pins = rest[++i];
+    else if (rest[i] === '--lock-out') flags.lockOut = rest[++i];
+    else if (rest[i] === '--no-endpoint-check') flags.noEndpoint = true;
+    else positionals.push(rest[i]);
+  }
+  const podDir = positionals[0];
+  if (!podDir) {
+    console.error('Erro: informe o <pod-dir>.');
+    process.exit(2);
+  }
+
+  try {
+    const { podName, bundleFiles, lock, imageEndpoint } = await compile(podDir, {
+      pinsPath: flags.pins ? path.resolve(flags.pins) : undefined,
+      checkEndpoint: !flags.noEndpoint,
+    });
+    const bundleDir = flags.out
+      ? path.resolve(flags.out)
+      : path.join(REPO_ROOT, '.power-claude', 'pod-export', podName, 'bundle');
+    const lockPath = flags.lockOut
+      ? path.resolve(flags.lockOut)
+      : path.join(REPO_ROOT, 'exports', podName, 'export.lock.json');
+
+    writeBundle(bundleDir, bundleFiles);
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    fs.writeFileSync(lockPath, serializeLock(lock));
+
+    console.log(`[OK] pod "${podName}" compilado.`);
+    console.log(`  bundle : ${path.relative(process.cwd(), bundleDir)} (${bundleFiles.length} arquivos, NÃO commitado)`);
+    console.log(`  lock   : ${path.relative(process.cwd(), lockPath)} (commitado)`);
+    console.log(`  pod_sha: ${lock.pod_sha}`);
+    if (imageEndpoint) console.log(`  imagem : ${imageEndpoint.id} — ${imageEndpoint.endpoints_count} endpoint(s) ativo(s)`);
+    else console.log('  imagem : checagem de endpoint PULADA (--no-endpoint-check)');
+    process.exit(0);
+  } catch (e) {
+    if (e instanceof CompileError || e instanceof Fail) {
+      console.error(`[FALHA] ${e.message}`);
+      process.exit(1);
+    }
+    throw e;
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  COMPILER_VERSION,
+  compile,
+  writeBundle,
+  serializeLock,
+  validateImageEndpoint,
+  splitFrontmatter,
+  extractGoldenRules,
+  parseCommandKnowledge,
+  loadPins,
+  CompileError,
+};