engine-kit 0.0.0-stage → 0.2.0

package/consumers/mcp-gateway.mjs

@@ -0,0 +1,192 @@
+// consumers/mcp-gateway.mjs — adaptador pronto do motor `mcp-gateway`.
+//
+// Qualquer extensão que queira falar com o agregador MCP importa isto e chama `ensureGateway()`.
+// O adaptador sabe o que é específico DESTE motor (handshake do /health, onde mora o bearer
+// token, como pedir shutdown antes de uma atualização) — o engine-kit cuida do resto
+// (resolver no registry, baixar com SHA256, instalar, subir, esperar o anúncio).
+//
+//   import { ensureGateway } from "engine-registry/consumers/mcp-gateway.mjs";
+//
+//   const gw = await ensureGateway({ log });
+//   if (!gw.available) { log(`gateway indisponível: ${gw.reason}`); return; }   // degrade SINALIZADO
+//   // gw.url   -> http://127.0.0.1:<porta>/mcp
+//   // gw.token -> bearer para o header Authorization (cofre DPAPI no HOME padrão; ver readToken)
+//
+// Contrato: nunca lança.
+import { readFileSync, existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join, dirname, resolve as resolvePath, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { ensureEngine } from "../kit/index.mjs";
+
+const DEFAULT_HOME = join(homedir(), ".mcp-gateway");
+const DEFAULT_PORT = 7337;
+const ENGINE_NAME = "mcp-gateway";
+// manifest.json do próprio engine-registry — mesmo arquivo que declara `install.agentInstructions`
+// e `install.extractTo` para este motor (fonte única de verdade; ver schema.json).
+const MANIFEST_PATH = join(dirname(dirname(fileURLToPath(import.meta.url))), "manifest.json");
+
+/** HOME do motor, resolvido a cada chamada (respeita override de teste/dev via env). */
+function resolveHome() {
+  return process.env.MCP_GATEWAY_DATA_DIR || DEFAULT_HOME;
+}
+
+const HOME = resolveHome();
+
+/**
+ * Descritor do motor `mcp-gateway` lido do manifest.json do registry. Nunca lança: manifest
+ * ilegível ou motor ausente do registro → null (quem chama sinaliza, não inventa um default).
+ */
+function loadEngineDescriptor() {
+  try {
+    const manifest = JSON.parse(readFileSync(MANIFEST_PATH, "utf8"));
+    return (manifest.engines ?? []).find((e) => e?.name === ENGINE_NAME) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Lê a porta configurada pelo usuário (config.json), caindo no default do motor. */
+function configuredPort() {
+  try {
+    return JSON.parse(readFileSync(join(HOME, "config.json"), "utf8")).port ?? DEFAULT_PORT;
+  } catch {
+    return DEFAULT_PORT;
+  }
+}
+
+/**
+ * Lê o bearer token pela MESMA regra do daemon (mcp-gateway src/daemon/auth.ts): no HOME de
+ * produção (~/.mcp-gateway) no Windows o token mora no cofre DPAPI (segredo MCP_GATEWAY_TOKEN em
+ * %LOCALAPPDATA%\Vault, entropia `vault.ps1/v1`) — ordem cofre → env MCP_GATEWAY_TOKEN → arquivo
+ * `auth-token` legado. Em qualquer outro HOME (teste/dev, não-Windows) só vale o arquivo
+ * `auth-token`. Nunca lança nem loga o valor: ausência → null; falha ao abrir um cofre que
+ * existe → null com o motivo em `log` (não finge que o token não existe).
+ * @param {{home?:string, defaultHome?:string, env?:object, platform?:string, log?:(m:string)=>void}} [o]
+ */
+export function readToken({ home = resolveHome(), defaultHome = DEFAULT_HOME, env = process.env, platform = process.platform, log = () => {} } = {}) {
+  const legacy = () => {
+    try { return readFileSync(join(home, "auth-token"), "utf8").trim() || null; } catch { return null; }
+  };
+  const isProd = platform === "win32" && resolvePath(home).toLowerCase() === resolvePath(defaultHome).toLowerCase();
+  if (!isProd) { return legacy(); }
+
+  const vaultDir = env.VAULT_DIR?.trim() || join(env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "Vault");
+  const blob = join(vaultDir, "MCP_GATEWAY_TOKEN.dpapi");
+  if (existsSync(blob)) {
+    const script = "$ErrorActionPreference='Stop'; Add-Type -AssemblyName System.Security; " +
+      "$b=[IO.File]::ReadAllBytes($env:MCPGW_BLOB); [Console]::Out.Write([Text.Encoding]::UTF8.GetString([Security.Cryptography.ProtectedData]::Unprotect($b,[Text.Encoding]::UTF8.GetBytes('vault.ps1/v1'),'CurrentUser')))";
+    try {
+      const out = execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], {
+        windowsHide: true, encoding: "utf8", timeout: 20000, stdio: ["ignore", "pipe", "pipe"], env: { ...env, MCPGW_BLOB: blob },
+      }).trim();
+      if (out) { return out; }
+    } catch (e) {
+      log(`mcp-gateway: cofre do token ilegível: ${String(e.message).split("\n")[0]}`);
+      return null;
+    }
+  }
+  return env.MCP_GATEWAY_TOKEN?.trim() || legacy();
+}
+
+/**
+ * Handshake do gateway: confirma que quem atende na porta é MESMO este motor e já está
+ * servindo. `degraded` é ACEITO — significa que o gateway está de pé e atendendo, com um
+ * ou mais backends em reconexão; `starting` não serve (ainda conectando pela primeira vez).
+ */
+async function healthCheck() {
+  const port = configuredPort();
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/health`, { signal: AbortSignal.timeout(2000) });
+    if (!res.ok) { return null; }
+    const h = await res.json();
+    const serving = h?.status === "ok" || h?.status === "degraded";
+    return h?.name === "mcp-gateway" && serving ? { ...h, port } : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Derruba o daemon antes de sobrescrever os arquivos (Windows trava arquivo em uso). */
+async function onBeforeReplace() {
+  try {
+    const rt = JSON.parse(readFileSync(join(HOME, "runtime.json"), "utf8"));
+    if (rt?.pid) { process.kill(rt.pid, "SIGTERM"); }
+    await new Promise((r) => setTimeout(r, 1500));
+  } catch { /* já parado / sem runtime */ }
+}
+
+/**
+ * Caminho do pacote de instruções para agente, dentro do HOME do motor. Composto a partir do
+ * MESMO `install.agentInstructions` declarado no manifest.json (fonte única de verdade — mudar
+ * o manifest muda o consumer, nunca o contrário) e de `install.extractTo` (a pasta onde o
+ * `provision` REALMENTE desempacota o artefato — ver kit/provision.mjs: `binDir = join(home,
+ * install.extractTo ?? "bin")`). Sem isso o caminho apontaria para <home>/docs/... enquanto o
+ * artefato desempacotado mora em <home>/<extractTo>/docs/... — dois lugares diferentes.
+ * Função pura: só resolve o caminho, não toca rede (o manifest.json lido é o arquivo estático
+ * empacotado junto com este módulo, não uma chamada ao registry remoto).
+ * @returns {string|null} null quando o manifest não declara `agentInstructions` para o motor.
+ */
+export function instructionsPath() {
+  const engine = loadEngineDescriptor();
+  const rel = engine?.install?.agentInstructions;
+  if (!rel) { return null; }
+  const extractTo = engine.install.extractTo ?? "bin";
+  if (rel.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(rel) || rel.split(/[\\/]+/).includes("..")) {
+    return null;
+  }
+  const home = resolvePath(resolveHome());
+  const candidate = resolvePath(home, extractTo, rel);
+  if (candidate !== home && !candidate.startsWith(`${home}${sep}`)) {
+    return null;
+  }
+  return candidate;
+}
+
+/**
+ * Carrega o pacote de instruções do disco (sem rede, sem healthcheck). Host-agnóstico:
+ * devolve o conteúdo cru para qualquer cliente MCP decidir o que fazer com ele.
+ * @returns {{available:true, path:string, content:string} | {available:false, reason:string}}
+ */
+export function readInstructions() {
+  const path = instructionsPath();
+  if (!path) {
+    return { available: false, reason: "manifest.json não declara um caminho seguro para as instruções do mcp-gateway" };
+  }
+  try {
+    return { available: true, path, content: readFileSync(path, "utf8") };
+  } catch (e) {
+    return { available: false, reason: e.message };
+  }
+}
+
+/**
+ * Garante o agregador MCP instalado e vivo.
+ * @returns {Promise<{available:true, url:string, token:string|null, port:number, backends:string[], health:object}
+ *                  | {available:false, reason:string}>}
+ */
+export async function ensureGateway({ log = () => {}, version, allowNetwork = true, bootTimeoutMs = 45000, registryUrl, fetcher } = {}) {
+  const r = await ensureEngine("mcp-gateway", {
+    healthCheck,
+    onBeforeReplace,
+    log,
+    version,
+    allowNetwork,
+    bootTimeoutMs,
+    registryUrl,
+    fetcher,
+    env: { MCP_GATEWAY_DATA_DIR: HOME },
+  });
+  if (!r.available) { return r; }
+
+  const port = r.health.port ?? configuredPort();
+  return {
+    available: true,
+    url: `http://127.0.0.1:${port}/mcp`,
+    token: readToken({ log }),
+    port,
+    backends: r.health.backends ?? [],
+    health: r.health,
+  };
+}

package/consumers/neural-link.mjs

@@ -0,0 +1,66 @@
+// consumers/neural-link.mjs — adaptador pronto do motor `neural-link` (dispatcher de hooks).
+//
+// Qualquer extensão que traga hook (`.js` + companion `<hook>.neural-link.json`) importa isto e
+// chama `ensureNeuralLink()` na ativação, DEPOIS de copiar seus arquivos para a pasta de hooks.
+// O adaptador garante o dispatcher instalado/atualizado (achar-ou-baixar-ou-atualizar — o kit
+// cuida disso) e roda o `install()` do próprio motor para que os companions recém-entregues
+// virem registro REAL no `neural-link.config.json` — sem isso, o hook fica instalado mas
+// nunca é chamado por nenhum evento.
+//
+//   import { ensureNeuralLink } from "engine-kit/consumers/neural-link.mjs";
+//
+//   const n = await ensureNeuralLink({ log });
+//   if (!n.available) { log(`hooks desativados: ${n.reason}`); /* degrade SINALIZADO */ }
+//   // n.entryPath -> caminho do dispatcher instalado (kind=cli, sem processo persistente)
+//
+// Contrato: nunca lança.
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { ensureEngine } from "../kit/index.mjs";
+
+/** Pin default: última versão do neural-link confirmada publicada no manifest deste kit. */
+const DEFAULT_PIN = "0.7.15";
+
+/**
+ * Garante o dispatcher de hooks `neural-link` instalado/atualizado, e roda o `install()` dele
+ * para que os companions (`<hook>.neural-link.json`) recém-entregues pela extensão virem
+ * registro real no config global — o `install()` é quem lê os companions; `provision()` só
+ * garante o binário no disco, ele não sabe nada sobre config de hooks.
+ *
+ * Sem `healthCheck`: `kind=cli` não sobe processo persistente — o kit devolve o caminho do
+ * binário e sai (ver `kit/lifecycle.mjs`).
+ *
+ * @param {object} opts
+ * @param {string=} opts.version pin de versão mínima (default: {@link DEFAULT_PIN}).
+ * @param {(msg:string)=>void=} opts.log
+ * @param {boolean=} opts.allowNetwork permite baixar/atualizar (default true). Com `false` e um
+ *        neural-link já instalado que satisfaça o pin, reusa sem tocar rede (comportamento do
+ *        próprio `provision()` — não há necessidade de um caminho manual separado: o kit já
+ *        reusa QUALQUER instalação existente que satisfaça o pin antes de olhar para a rede).
+ * @returns {Promise<{available:true, entryPath:string, version:string, registered:object|null}
+ *                  | {available:false, reason:string}>}
+ */
+export async function ensureNeuralLink({ version = DEFAULT_PIN, log = () => {}, allowNetwork = true } = {}) {
+  const r = await ensureEngine("neural-link", { version, allowNetwork, log });
+  if (!r.available) { return r; }
+
+  const entryPath = r.bin;
+  let registered = null;
+  try {
+    const installMod = await import(pathToFileURL(join(dirname(entryPath), "install.js")).href);
+    registered = installMod.install({});
+    log(`[engine-kit] neural-link: install() rodou — ${registered.written?.length ?? 0} declarado(s), ${registered.companions?.selados?.length ?? 0} companion(s) selado(s)`);
+  } catch (e) {
+    // O dispatcher está presente e é invocável por evento mesmo se o `install()` falhar aqui
+    // (ex.: permissão de escrita no config, layout inesperado do binário) — não travamos a
+    // extensão por isso; só sinalizamos que o registro pode não ter acontecido.
+    log(`[engine-kit] neural-link: install() falhou (${e?.message || e}) — companions podem não estar registrados`);
+  }
+
+  return {
+    available: true,
+    entryPath,
+    version: r.engine?.installedVersion ?? version,
+    registered,
+  };
+}

package/kit/app-release.mjs

@@ -0,0 +1,94 @@
+// engine-kit/app-release.mjs — a release de um APLICATIVO (manifest.apps), não de um motor.
+//
+// Um app não é provisionado pelo kit: não há home, entry nem lifecycle. O que o registry garante
+// é o download — cada asset publicado, com .sha256 e (se o app tiver chave) .sig conferindo.
+// Este módulo monta as URLs a partir da entrada e faz essa prova; o CLI é
+// `node kit/verify-release.mjs --app <nome>`.
+//
+// NUNCA lança: devolve { ok:false, reason } com o asset que falhou.
+import { createHash } from "node:crypto";
+import { fill } from "./resolve.mjs";
+import { verifyBlob, DEFAULT_ALGORITHM } from "./signature.mjs";
+
+/** Acha a entrada `name` em manifest.apps. */
+export function findApp(manifest, name) {
+  const app = (manifest?.apps ?? []).find((a) => a?.name === name);
+  if (!app) {
+    const known = (manifest?.apps ?? []).map((a) => a?.name).join(", ") || "(nenhum)";
+    return { ok: false, reason: `app "${name}" não existe em manifest.apps (registrados: ${known})` };
+  }
+  return { ok: true, app };
+}
+
+/**
+ * Expande os templates da entrada: nome com {version}; checksum e signature com {asset} e
+ * {version}. Nome literal (sem placeholder) passa intacto.
+ */
+export function appAssetUrls(app) {
+  const vars = { version: app.version };
+  const tag = fill(app.release.tag, vars);
+  const base = `https://github.com/${app.release.repo}/releases/download/${tag}`;
+  return {
+    tag,
+    assets: app.release.assets.map((a) => {
+      const name = fill(a.name, vars);
+      const checksum = fill(a.checksum, { ...vars, asset: name });
+      const signature = fill(a.signature ?? "{asset}.sig", { ...vars, asset: name });
+      return {
+        name,
+        platform: a.platform,
+        url: `${base}/${encodeURIComponent(name)}`,
+        checksumUrl: `${base}/${encodeURIComponent(checksum)}`,
+        signatureUrl: `${base}/${encodeURIComponent(signature)}`,
+      };
+    }),
+  };
+}
+
+async function anonymousGet(url) {
+  // Sem Authorization de propósito: a promessa do registry é download SEM login.
+  const res = await fetch(url, { signal: AbortSignal.timeout(300000) });
+  if (!res.ok) { throw new Error(`HTTP ${res.status} em ${url}`); }
+  return Buffer.from(await res.arrayBuffer());
+}
+
+/**
+ * Baixa TODOS os assets da entrada e confere sha256 e, havendo publicKey, a assinatura — mais a
+ * metade negativa (adulterado é recusado).
+ * @param opts.get  fetcher injetável (testes); padrão = GET anônimo.
+ * @returns {Promise<{ok:true, assets:object[]} | {ok:false, reason:string}>}
+ */
+export async function verifyAppRelease(app, { get = anonymousGet, log = () => {} } = {}) {
+  const { publicKey, signatureRequired } = app.release;
+  if (signatureRequired && !publicKey) {
+    return { ok: false, reason: "signatureRequired sem publicKey na entrada do app — corrija antes de anunciar" };
+  }
+  const algorithm = app.release.signatureAlgorithm ?? DEFAULT_ALGORITHM;
+  const { assets } = appAssetUrls(app);
+  const results = [];
+
+  for (const a of assets) {
+    let blob, sha;
+    try { blob = await get(a.url); } catch (e) { return { ok: false, reason: `${a.name}: asset não baixou — ${e.message}` }; }
+    try { sha = String(await get(a.checksumUrl)).trim().split(/\s+/)[0].toLowerCase(); }
+    catch (e) { return { ok: false, reason: `${a.name}: sidecar .sha256 não baixou — ${e.message}` }; }
+
+    const actual = createHash("sha256").update(blob).digest("hex");
+    if (actual !== sha) { return { ok: false, reason: `${a.name}: SHA256 divergente (release=${sha.slice(0, 12)}… baixado=${actual.slice(0, 12)}…)` }; }
+
+    let signed = false;
+    if (publicKey) {
+      let sig;
+      try { sig = await get(a.signatureUrl); } catch (e) { return { ok: false, reason: `${a.name}: sidecar .sig não baixou — ${e.message}` }; }
+      const v = verifyBlob(blob, sig, publicKey, { algorithm });
+      if (!v.ok) { return { ok: false, reason: `${a.name}: ${v.reason}` }; }
+      if (verifyBlob(Buffer.concat([blob, Buffer.from([0])]), sig, publicKey, { algorithm }).ok) {
+        return { ok: false, reason: `${a.name}: a verificação ACEITOU um artefato adulterado — contrato quebrado` };
+      }
+      signed = true;
+    }
+    log(`${a.name}: sha256 ${actual} OK${signed ? `, assinatura ${algorithm} OK` : ""}`);
+    results.push({ name: a.name, platform: a.platform, sha256: actual, signed });
+  }
+  return { ok: true, assets: results };
+}

package/kit/budget.mjs

@@ -0,0 +1,112 @@
+// engine-kit/budget.mjs — o KILL-SWITCH de tamanho, auto-aplicado.
+//
+//   node kit/budget.mjs          # mede e falha (exit 1) se estourar
+//
+// Por que existe: o budget vivia como um NÚMERO NUM PLANO, e número em plano apodrece —
+// o plano dizia "393 linhas" quando o real já era 1087. Um kill-switch que ninguém mede
+// não é kill-switch, é decoração. Aqui ele se mede sozinho e falha loud.
+//
+// O que ele mede (a distinção que faltava): o budget existe para impedir que **as extensões**
+// carreguem um monstro. Então o que conta é o CAMINHO DO CONSUMIDOR — o fecho transitivo dos
+// imports a partir de `index.mjs`, que é o que um `import "engine-kit"` realmente traz. O
+// ferramental de AUTOR (assinar, gerar chave, publicar, diagnosticar) nunca é importado por
+// consumidor: roda como comando na mão de quem publica. Misturar os dois numa soma só compara
+// alhos com bugalhos e faz o kill-switch disparar pelo motivo errado.
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const KIT = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolvePath(KIT, "..");
+
+// Budgets. A métrica ENFORÇADA é **bytes de código** (linhas em branco e comentários fora), não
+// linhas: uma review corroborada apontou, com razão, que LOC é proxy ruim — o que custa ao
+// consumidor é o que ele carrega e parseia, e este kit é comentado em pt-BR (comentário engorda
+// LOC sem custar comportamento). LOC fica como informação, não como portão.
+//
+// Contra o "mover a trave": cada faixa registra `baseline` — o valor MEDIDO quando a métrica foi
+// adotada (2026-07-29, já com a raiz de confiança). O relatório imprime o crescimento desde essa
+// marca, então subir o teto depois deixa de ser invisível: vira um número na tela e um diff.
+// Calibrar uma vez, na adoção da métrica, é linha de base; recalibrar toda vez que dispara é
+// contornar o guarda-corpo — e é isso que o baseline expõe.
+//
+// Recalibrações com delta justificado (o baseline NÃO muda; só o teto):
+//   2026-10-11 tooling 18000 → 24000: catálogo de APLICATIVOS (manifest.apps) — app-release.mjs e
+//   os modos --app de update-manifest/verify-release, +6.4 KB. É escopo novo (segundo tipo de
+//   entrada no registry), não inchaço; e é ferramental de autor: o caminho do consumidor não mudou.
+//   2026-10-23 adapter 4000 → 5000: o token do mcp-gateway passou ao cofre DPAPI (0.13.8) e o
+//   adaptador precisa lê-lo (cofre → env → arquivo, a regra do daemon), +1.4 KB. Não é gordura:
+//   é o contrato de autenticação do motor, que só o adaptador do motor pode conhecer.
+//   2026-10-27 tooling 24000 → 31000 (loc 800 → 950): canal npm aprovado pelo dono — cli.mjs, ensure.mjs
+//   e update.mjs (`npx engine-kit ensure <motor>` com autoatualização exigida pelo gate de release), +6.3 KB.
+//   Escopo novo (comando de instalação), rodado pela mão de quem instala, nunca importado por consumidor:
+//   o caminho do `import "engine-kit"` não mudou.
+const BUDGETS = {
+  runtime: { codeBytes: 27000, baseline: 24519, loc: 900 },
+  tooling: { codeBytes: 31000, baseline: 16420, loc: 950 },
+  adapter: { codeBytes: 5000, baseline: 1859, loc: 150 },
+};
+
+// `split("\n")` num arquivo terminado em newline devolve um elemento vazio no fim — linha
+// fantasma. Sem o `replace`, cada arquivo inflava a conta em 1 e o kill-switch disparava
+// por medição errada (foi o que aconteceu na primeira execução deste arquivo).
+const linesOf = (f) => readFileSync(f, "utf8").replace(/\n$/, "").split("\n");
+const lines = (f) => linesOf(f).length;
+
+/** Bytes que não são linha em branco nem comentário de linha inteira. */
+const codeBytes = (f) =>
+  linesOf(f)
+    .filter((l) => {
+      const t = l.trim();
+      return t && !t.startsWith("//") && !t.startsWith("*") && !t.startsWith("/*");
+    })
+    .reduce((n, l) => n + Buffer.byteLength(l, "utf8") + 1, 0);
+
+/** Fecho transitivo dos imports relativos a partir de um entrypoint. */
+function closure(entry) {
+  const seen = new Set();
+  const walk = (file) => {
+    if (seen.has(file)) { return; }
+    seen.add(file);
+    const src = readFileSync(file, "utf8");
+    for (const m of src.matchAll(/from\s+"(\.[^"]+)"/g)) {
+      walk(resolvePath(dirname(file), m[1]));
+    }
+  };
+  walk(entry);
+  return seen;
+}
+
+const runtime = closure(join(KIT, "index.mjs"));
+const all = readdirSync(KIT).filter((f) => f.endsWith(".mjs")).map((f) => join(KIT, f));
+const tooling = all.filter((f) => !runtime.has(f));
+
+const rel = (f) => f.replace(ROOT + "\\", "").replace(ROOT + "/", "").replaceAll("\\", "/");
+
+let failed = false;
+const report = (label, files, budget) => {
+  const bytes = files.reduce((n, f) => n + codeBytes(f), 0);
+  const loc = files.reduce((n, f) => n + lines(f), 0);
+  const over = bytes > budget.codeBytes;
+  failed ||= over;
+  console.log(`\n${over ? "!!" : "OK"}  ${label}`);
+  const growth = bytes - budget.baseline;
+  const pct = ((growth / budget.baseline) * 100).toFixed(1);
+  console.log(`      ${bytes}/${budget.codeBytes} bytes de código   (${loc} linhas, informativo)`);
+  console.log(`      baseline ${budget.baseline} B → ${growth >= 0 ? "+" : ""}${growth} B (${pct}%) desde a adoção da métrica`);
+  for (const f of [...files].sort((a, b) => codeBytes(b) - codeBytes(a))) {
+    console.log(`      ${String(codeBytes(f)).padStart(6)} B  ${String(lines(f)).padStart(4)} L  ${rel(f)}`);
+  }
+  if (over) { console.log(`      ESTOUROU em ${bytes - budget.codeBytes} bytes → decidir: cortar ou re-baselinar com delta justificado.`); }
+};
+
+console.log("== engine-kit budget ==  (kill-switch auto-aplicado; métrica = bytes de código)");
+report("runtime do consumidor (fecho de index.mjs)", [...runtime], BUDGETS.runtime);
+report("ferramental de autor (nunca importado por consumidor)", tooling, BUDGETS.tooling);
+
+for (const f of readdirSync(join(ROOT, "consumers")).filter((x) => x.endsWith(".mjs"))) {
+  report(`adaptador ${f}`, [join(ROOT, "consumers", f)], BUDGETS.adapter);
+}
+
+console.log(failed ? "\nBUDGET ESTOURADO — kill-switch disparou." : "\nDentro do budget.");
+process.exit(failed ? 1 : 0);

package/kit/cli.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// engine-kit — comando de instalação dos motores (campo `bin` do package.json).
+//
+//   npx engine-kit ensure <motor>                    # instala/atualiza verificando sha256 + Ed25519
+//   npx engine-kit ensure <motor> --version <x.y.z>  # pin de versão
+//   npx engine-kit ensure <motor> --registry-url <url>
+//
+// Por padrão o kit se atualiza (roda de novo como a última versão do npm) e atualiza o motor instalado.
+// ENGINE_KIT_NO_AUTO_UPDATE=1 desliga os dois e deixa só o aviso de versão nova (ver update.mjs).
+// Exit code: 0 = motor instalado (ou reusado). 1 = recusou/falhou, com o motivo na saída de erro.
+import { ensureCommand } from "./ensure.mjs";
+import { selfUpdate, autoUpdateEnabled } from "./update.mjs";
+
+const USAGE = "uso: engine-kit ensure <motor> [--version <x.y.z>] [--registry-url <url>]\n" +
+  "ENGINE_KIT_NO_AUTO_UPDATE=1 desliga a atualização automática do kit e dos motores (fica só o aviso).";
+
+const args = process.argv.slice(2);
+const flag = (n) => { const i = args.indexOf(n); return i === -1 ? undefined : args[i + 1]; };
+const [cmd, name] = args;
+
+if (cmd === "--help" || cmd === "-h") {
+  console.log(USAGE);
+} else if (cmd !== "ensure" || !name || name.startsWith("-")) {
+  console.error(cmd && cmd !== "ensure" ? `comando desconhecido: ${cmd}\n${USAGE}` : USAGE);
+  process.exitCode = 1;
+} else if (args.includes("--version") && !/^\d+\.\d+\.\d+$/.test(flag("--version") ?? "")) {
+  console.error(`--version precisa de x.y.z (recebi: ${flag("--version") ?? "nada"})`);
+  process.exitCode = 1;
+} else {
+  // Sem process.exit() depois de rede: no Windows o Node aborta com sockets ainda fechando (ver doctor.mjs).
+  const u = await selfUpdate(args);
+  if (u.action === "relaunched") {
+    process.exitCode = u.status;
+  } else {
+    const autoUpdate = autoUpdateEnabled();
+    const r = await ensureCommand(name, { version: flag("--version"), registryUrl: flag("--registry-url"), autoUpdate, log: (m) => console.log(m) });
+    if (r.ok) {
+      const how = r.reused ? "já instalado, reusado" : r.signed ? "assinatura Ed25519 conferida" : "SEM assinatura no registry";
+      if (r.previous) { console.log(`motor atualizado: ${name} v${r.previous} → v${r.version}`); }
+      console.log(`OK ${name} v${r.version} (${how}) em ${r.entryPath}`);
+      if (r.available) { console.log(`aviso: ${name} v${r.available} disponível; ENGINE_KIT_NO_AUTO_UPDATE ligado — rode sem ele para atualizar`); }
+      if (r.kind === "daemon") { console.log("daemon: quem sobe o motor é o consumidor (ensureEngine com healthCheck)."); }
+    } else {
+      console.error(`FALHOU ${name}: ${r.reason}`);
+      process.exitCode = 1;
+    }
+  }
+}

package/kit/doctor.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// engine-kit/doctor.mjs — concilia os MOTORES INSTALADOS nesta máquina com o registry.
+//
+//   node kit/doctor.mjs                 # só diagnostica (não toca em nada)
+//   node kit/doctor.mjs --fix           # instala o que falta, atualiza o que está velho
+//   node kit/doctor.mjs --local         # usa o manifest.json LOCAL em vez do publicado
+//   node kit/doctor.mjs --engine <nome> # um motor só
+//
+// A regra é a mesma do kit e não muda aqui: **desatualizado → atualiza; ausente → baixa;
+// atualizado → REUSA**. Reusar é o caminho comum e precisa ser barato — por isso o diagnóstico
+// não baixa nada, e o `--fix` delega ao `provision` (SHA256 + assinatura fail-closed, lock e swap
+// atômicos). O doctor não reimplementa instalação: ele só decide QUEM precisa.
+//
+// Exit code: 0 = tudo conciliado. 1 = há divergência (e `--fix` não foi passado) ou algo falhou.
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { resolve } from "./resolve.mjs";
+import { provision, satisfiesPin } from "./provision.mjs";
+import { shutdown } from "./lifecycle.mjs";
+
+const args = process.argv.slice(2);
+const useLocal = args.includes("--local");
+const doFix = args.includes("--fix");
+const onlyIdx = args.indexOf("--engine");
+const only = onlyIdx === -1 ? null : args[onlyIdx + 1];
+const regIdx = args.indexOf("--registry-url");
+const registryUrl = regIdx === -1 ? undefined : args[regIdx + 1];
+
+const manifestPath = new URL("../manifest.json", import.meta.url);
+let manifest;
+try { manifest = JSON.parse(readFileSync(manifestPath, "utf8")); }
+catch (e) { console.error(`FALHOU: manifest local ilegível: ${e.message}`); process.exit(1); }
+
+/** Versão instalada no disco, lida do artefato — a mesma fonte que o provision usa para o pin. */
+function installedVersion(engine) {
+  const binDir = join(engine.homeDir, engine.install.extractTo ?? "bin");
+  try { return JSON.parse(readFileSync(join(binDir, "package.json"), "utf8")).version ?? null; }
+  catch { return null; }
+}
+
+const names = (manifest.engines ?? []).map((e) => e.name).filter((n) => !only || n === only);
+if (only && names.length === 0) {
+  console.error(`FALHOU: motor "${only}" não existe no manifest`);
+  process.exit(1);
+}
+
+console.log(`== engine-kit doctor ==  (registry: ${useLocal ? "manifest LOCAL" : "publicado"}${doFix ? ", modo --fix" : ", só diagnóstico"})\n`);
+
+// Sem process.exit() depois de rede: o fetch (undici) ainda tem sockets fechando e o Node do
+// Windows aborta com "Assertion failed: !(handle->flags & UV_HANDLE_CLOSING)" (exit 127).
+// Deixar o event loop esvaziar e só marcar process.exitCode.
+const rows = [];
+for (const name of names) {
+  // `refresh`: diagnóstico com cache velho mente — dizer "atualizado" olhando um descritor
+  // vencido é pior do que não diagnosticar. Aqui a requisição de rede vale a pena.
+  const r = await resolve(name, { allowNetwork: !useLocal, manifest: useLocal ? manifest : undefined, refresh: !useLocal, registryUrl });
+  if (!r.ok) { rows.push({ name, state: "ERRO", detail: r.reason }); continue; }
+
+  const engine = r.engine;
+  const entry = join(engine.homeDir, engine.install.entry);
+  const present = existsSync(entry);
+  const inst = present ? installedVersion(engine) : null;
+
+  let state, detail;
+  if (engine.status === "self-managed") {
+    // Traz o próprio instalador/updater. O doctor NÃO opina sobre a versão dele: olhar o disco
+    // pelo caminho do manifest daria "ausente" para um motor que está instalado e funcionando,
+    // só que em outro lugar. Reportar e não agir é a resposta honesta.
+    state = "SELF-MANAGED"; detail = `v${engine.version} no registry — atualiza pelo próprio updater`;
+  } else if (!present) {
+    state = "AUSENTE"; detail = `baixar v${engine.version}`;
+  } else if (!inst) {
+    // Estado desconhecido: o artefato está lá mas a versão não é legível. Não invente que está ok.
+    state = "ILEGÍVEL"; detail = "instalado, mas package.json ausente/corrompido → reprovisionar";
+  } else if (satisfiesPin(inst, engine.version)) {
+    state = "OK"; detail = `v${inst} satisfaz o pin v${engine.version} → reusar`;
+  } else {
+    state = "DESATUALIZADO"; detail = `v${inst} → v${engine.version}`;
+  }
+  rows.push({ name, state, detail, engine, needsWork: state !== "OK" && state !== "SELF-MANAGED" });
+}
+
+const pad = (s, n) => String(s).padEnd(n);
+const w = Math.max(12, ...rows.map((r) => r.name.length));
+for (const r of rows) {
+  const mark = (r.state === "OK" || r.state === "SELF-MANAGED") ? "  OK  " : r.state === "ERRO" ? " ERRO " : "  !!  ";
+  console.log(`${mark} ${pad(r.name, w)}  ${pad(r.state, 14)} ${r.detail}`);
+}
+
+const pending = rows.filter((r) => r.needsWork);
+if (pending.length === 0) {
+  console.log(`\n== todos os motores conciliados (${rows.length}) ==`);
+  process.exitCode = rows.some((r) => r.state === "ERRO") ? 1 : 0;
+} else if (!doFix) {
+  console.log(`\n${pending.length} motor(es) precisam de ação. Rode com --fix para instalar/atualizar.`);
+  process.exitCode = 1;
+} else {
+console.log("\n-- aplicando (--fix) --");
+let failures = 0;
+for (const r of pending) {
+  console.log(`\n${r.name}: ${r.detail}`);
+  const p = await provision(r.engine, {
+    log: (m) => console.log(`    ${m}`),
+    // No Windows um arquivo EM USO não pode ser sobrescrito: sem derrubar o daemon antes, o
+    // update de um motor vivo falha com EPERM no meio do swap. O kit não adivinha como parar
+    // um motor — usa o `shutdownPath` que o próprio registry declara.
+    onBeforeReplace: async () => {
+      const s = await shutdown(r.engine, { log: (m) => console.log(`    ${m}`) });
+      if (!s.ok) { console.log(`    aviso: ${s.reason} — o swap pode falhar com o motor vivo`); }
+    },
+  });
+  if (p.ok) {
+    console.log(`  OK   ${r.name} v${p.version}${p.signed === false ? " (SEM assinatura — motor ainda não migrado)" : ""}`);
+  } else {
+    failures++;
+    console.log(` FALHA ${r.name} — ${p.reason}`);
+  }
+}
+
+console.log(`\n== ${failures === 0 ? "conciliado" : `${failures} falha(s)`} ==`);
+process.exitCode = failures === 0 ? 0 : 1;
+}