engine-kit 0.0.0-stage → 0.2.0

package/kit/provision.mjs

@@ -0,0 +1,379 @@
+// engine-kit/provision.mjs — PROVISION: garante o motor instalado em <home>/<extractTo>.
+// Generalização do provision.mjs do embed-house (medido em produção), agora parametrizado pelo
+// descritor do registry. Mantém as garantias que já funcionavam:
+//   • SHA256 sidecar OBRIGATÓRIO, fail-closed (ausente/malformado/mismatch = ABORT, não instala);
+//   • lock atômico ('wx') para serializar consumidores concorrentes na mesma máquina;
+//   • reúso por semver same-major >= (dois consumidores com pins diferentes convergem no maior);
+//   • download -> .part -> rename atômico; extração em staging -> swap;
+//   • shutdown-first (Windows: DLL/EXE em uso impede sobrescrever o diretório).
+// NUNCA lança: devolve { ok:false, reason }.
+import { mkdirSync, existsSync, renameSync, rmSync, openSync, closeSync, readFileSync, writeFileSync, unlinkSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { verifyBlob, DEFAULT_ALGORITHM } from "./signature.mjs";
+import { checkTrust, trustPath } from "./trust.mjs";
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Lock mais velho que isto é considerado ÓRFÃO (processo morreu antes do finally). */
+const LOCK_STALE_MS = 120000;
+
+/**
+ * Extrai o .tgz. Usa o `tar` do sistema (presente por padrão no Windows 10 1803+, macOS e Linux).
+ * Se faltar, falha com razão EXPLÍCITA e acionável em vez de um erro cru de spawn — nunca
+ * instala pela metade.
+ */
+// No Windows, o tar NATIVO (bsdtar, System32) quando existir: um processo aberto a partir de um terminal
+// Git Bash herda o GNU tar do Git na frente do PATH, e o GNU tar lê "C:\..." como host remoto ("Cannot
+// connect to C: resolve failed") — a instalação de QUALQUER motor quebrava só por onde o host foi aberto.
+export function tarBinary({ platform = process.platform, systemRoot = process.env.SystemRoot || process.env.windir, exists = existsSync } = {}) {
+  if (platform === "win32" && systemRoot) {
+    const native = join(systemRoot, "System32", "tar.exe");
+    if (exists(native)) return native;
+  }
+  return "tar";
+}
+
+function extractTgz(tgz, dest) {
+  const tar = tarBinary();
+  try {
+    execFileSync(tar, ["--version"], { stdio: "ignore" });
+  } catch {
+    return { ok: false, reason: "`tar` não encontrado no PATH — necessário para extrair o artefato (Windows 10 1803+, macOS e Linux já trazem). Instale-o e tente de novo." };
+  }
+  try {
+    execFileSync(tar, ["-xzf", tgz, "-C", dest], { stdio: "ignore" });
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, reason: `extração (tar) falhou: ${e?.message || e}` };
+  }
+}
+
+/**
+ * Tenta claim do lock de provisionamento. Grava o PID para diagnóstico e reclama locks
+ * órfãos (mais velhos que {@link LOCK_STALE_MS}) — sem isso, um processo morto entre o
+ * `openSync` e o `finally` travaria todos os consumidores para sempre.
+ */
+function claimLock(lock) {
+  try {
+    const fd = openSync(lock, "wx");
+    try { writeFileSync(lock, String(process.pid)); } catch { /* diagnóstico é best-effort */ }
+    return fd;
+  } catch {
+    try {
+      if (Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS) {
+        unlinkSync(lock);
+        const fd = openSync(lock, "wx");
+        try { writeFileSync(lock, String(process.pid)); } catch { /* ignore */ }
+        return fd;
+      }
+    } catch { /* outro consumidor ganhou a corrida */ }
+    return null;
+  }
+}
+
+const parseVer = (v) => String(v || "").split(".").map((n) => parseInt(n, 10) || 0);
+
+/** true se a versão instalada serve o pin: MESMO major e >= (protocolo é atado ao major). */
+export function satisfiesPin(installed, pinned) {
+  const a = parseVer(installed), b = parseVer(pinned);
+  if (a[0] !== b[0]) { return false; }
+  for (let i = 0; i < 3; i++) {
+    const x = a[i] || 0, y = b[i] || 0;
+    if (x > y) { return true; }
+    if (x < y) { return false; }
+  }
+  return true;
+}
+
+function sha256File(p) {
+  return createHash("sha256").update(readFileSync(p)).digest("hex").toLowerCase();
+}
+
+async function fetchBuf(url, timeoutMs) {
+  const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+  if (!res.ok) { const e = new Error(`HTTP ${res.status}`); e.status = res.status; throw e; }
+  return Buffer.from(await res.arrayBuffer());
+}
+
+/** Lê a versão instalada a partir do package.json do artefato (se houver). */
+export function installedVersion(binDir) {
+  try { return JSON.parse(readFileSync(join(binDir, "package.json"), "utf8")).version; } catch { return null; }
+}
+
+/**
+ * AUTENTICIDADE do artefato (Ed25519 hash-then-sign) — o passo que o SHA256 não cobre.
+ *
+ * O sidecar `.sha256` só prova que o download não corrompeu: quem publica o artefato publica o
+ * hash junto, então um artefato TROCADO vem com o hash certo do artefato trocado. A assinatura é
+ * o que amarra o artefato a quem detém a chave privada (que nunca sai da máquina do dono).
+ *
+ * Política, deliberadamente fail-closed e sem meio-termo silencioso:
+ *   • `publicKey` declarada no registry  → assinatura é OBRIGATÓRIA (declarar = exigir);
+ *   • `signatureRequired:true` sem `publicKey` → manifesto INCONSISTENTE, aborta (não "passa");
+ *   • nenhum dos dois → motor ainda não migrado: instala, mas o log SINALIZA (nunca calado).
+ *
+ * @returns {Promise<{ok:true, signed:boolean} | {ok:false, reason:string}>} nunca lança.
+ */
+async function verifyAuthenticity(engine, blob, { log, fetcher, trustedKeys }) {
+  const publicKey = engine.install?.publicKey;
+  const required = engine.install?.signatureRequired === true;
+  const algorithm = engine.install?.signatureAlgorithm ?? DEFAULT_ALGORITHM;
+
+  if (!publicKey) {
+    // Chave fixada pelo consumidor e registry sem chave: tirar a publicKey do manifest não pode
+    // ser o atalho para instalar sem assinatura.
+    if (trustedKeys?.[engine.name]) {
+      return { ok: false, reason: `${engine.name}: o consumidor fixou uma chave mas o registry não declara publicKey → ABORT (registry pode estar comprometido)` };
+    }
+    if (required) {
+      return { ok: false, reason: `${engine.name}: registry pede assinatura (signatureRequired) mas não declara publicKey → ABORT (manifesto inconsistente)` };
+    }
+    log(`[engine-kit] ${engine.name}: SEM assinatura no registry — integridade (sha256) verificada, AUTENTICIDADE não`);
+    return { ok: true, signed: false };
+  }
+
+  // A chave veio do MESMO manifest que o kit baixou — sozinha, ela não prova nada contra um
+  // registry comprometido. Confronta com a raiz de confiança LOCAL antes de usá-la.
+  const t = checkTrust(engine.name, publicKey, { trustedKeys });
+  if (!t.ok) { return { ok: false, reason: t.reason }; }
+  if (t.tofu) {
+    const how = trustedKeys?.[engine.name] ? "chave FIXADA pelo consumidor conferiu e foi gravada" : "chave pública gravada na 1ª vez (TOFU)";
+    log(`[engine-kit] ${engine.name}: ${how} em ${trustPath()} — trocas futuras serão ABORT`);
+  }
+
+  let sig;
+  try {
+    sig = await fetcher(engine.signatureUrl, 15000);
+  } catch (e) {
+    return { ok: false, reason: `${engine.name}: sidecar .sig inacessível (${e.status || e.message}) mas o registry declara publicKey → ABORT (fail-closed)` };
+  }
+
+  const v = verifyBlob(blob, sig, publicKey, { algorithm });
+  if (!v.ok) { return { ok: false, reason: `${engine.name}: ${v.reason}` }; }
+
+  log(`[engine-kit] ${engine.name}: assinatura Ed25519 CONFERE (${algorithm})`);
+  return { ok: true, signed: true };
+}
+
+/**
+ * Baixa e VERIFICA um artefato sem instalar — o caminho dos motores `self-managed`.
+ *
+ * Existe para fechar o ovo-e-galinha do primeiro install: um motor que traz o próprio
+ * instalador (o `vox-engine` é um app Python com `install.ps1`) não pode se instalar sozinho
+ * numa máquina onde ainda não está. Alguém tem de buscar o instalador — e esse alguém estava
+ * sendo CADA consumidor, cada um com sua cópia de resolução de release, SHA256 e Ed25519.
+ *
+ * Aqui o kit faz o que já sabe fazer (integridade + autenticidade fail-closed) e devolve o
+ * caminho do arquivo verificado. Quem sabe o que fazer com ele — rodar um instalador, extrair,
+ * conferir uma assinatura extra — é o consumidor. O kit não executa nada.
+ *
+ * @returns {Promise<{ok:true, path:string, version:string, signed:boolean} | {ok:false, reason:string}>} nunca lança.
+ */
+export async function fetchArtifact(engine, { log = () => {}, destDir, downloadTimeoutMs = 300000, fetcher = fetchBuf, trustedKeys } = {}) {
+  const dir = destDir ?? engine.homeDir;
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch (e) {
+    return { ok: false, reason: `${engine.name}: não consegui criar ${dir}: ${e?.message || e}` };
+  }
+
+  let expected;
+  try {
+    const buf = await fetcher(engine.checksumUrl, 15000);
+    expected = String(buf).trim().split(/\s+/)[0].toLowerCase();
+  } catch (e) {
+    return { ok: false, reason: `${engine.name}: sha256 sidecar inacessível (${e.status || e.message}) → ABORT (fail-closed)` };
+  }
+  if (!/^[0-9a-f]{64}$/.test(expected)) {
+    return { ok: false, reason: `${engine.name}: sha256 sidecar malformado → ABORT` };
+  }
+
+  log(`[engine-kit] baixando ${engine.assetUrl} …`);
+  let buf;
+  try { buf = await fetcher(engine.assetUrl, downloadTimeoutMs); }
+  catch (e) { return { ok: false, reason: `${engine.name}: download falhou (${e.status || e.message})` }; }
+
+  const actual = createHash("sha256").update(buf).digest("hex").toLowerCase();
+  if (actual !== expected) {
+    return { ok: false, reason: `${engine.name}: SHA256 mismatch (esperado ${expected.slice(0, 12)}…, obtido ${actual.slice(0, 12)}…) → ABORT` };
+  }
+
+  const auth = await verifyAuthenticity(engine, buf, { log, fetcher, trustedKeys });
+  if (!auth.ok) { return { ok: false, reason: auth.reason }; }
+
+  // .part → rename: nunca entregar um caminho que aponta para download pela metade.
+  const part = join(dir, `${engine.assetName}.part`);
+  const out = join(dir, engine.assetName);
+  try {
+    writeFileSync(part, buf);
+    renameSync(part, out);
+  } catch (e) {
+    return { ok: false, reason: `${engine.name}: não consegui gravar ${out}: ${e?.message || e}` };
+  }
+  log(`[engine-kit] ${engine.name} v${engine.version} verificado em ${out}`);
+  return { ok: true, path: out, version: engine.version, signed: auth.signed };
+}
+
+/**
+ * Garante o motor instalado. `onBeforeReplace` é o gancho de shutdown do MOTOR (o kit nunca
+ * adivinha como derrubar um daemon: quem sabe é o descritor/consumidor).
+ * @returns {Promise<{ok:true, entryPath:string, version:string, reused?:boolean, installed?:boolean} | {ok:false, reason:string}>}
+ */
+export async function provision(engine, { log = () => {}, allowNetwork = true, onBeforeReplace, downloadTimeoutMs = 120000, fetcher = fetchBuf, trustedKeys } = {}) {
+  const home = engine.homeDir;
+  const binDir = join(home, engine.install.extractTo ?? "bin");
+  const entryPath = join(home, engine.install.entry);
+  const lock = join(home, "provision.lock");
+
+  // Já instalado? Só reusa se a versão instalada for LEGÍVEL e satisfizer o pin.
+  // Versão ilegível (package.json ausente/corrompido = extração interrompida, disco cheio,
+  // arquivo truncado) NÃO é motivo para reusar: é estado desconhecido → reprovisiona.
+  // Reusar aqui seria fail-open silencioso — o oposto do resto do kit — e congelaria a máquina
+  // numa instalação quebrada para sempre, ignorando o pin do registry.
+  if (existsSync(entryPath)) {
+    const inst = installedVersion(binDir);
+    if (inst && satisfiesPin(inst, engine.version)) {
+      return { ok: true, entryPath, version: inst, reused: true };
+    }
+    if (!inst && engine.status !== "self-managed") {
+      log(`[engine-kit] ${engine.name}: instalação em estado desconhecido (versão ilegível) → reprovisionando`);
+      if (!allowNetwork) {
+        return { ok: false, reason: `${engine.name}: instalação em estado desconhecido (package.json ausente/corrompido em ${binDir}) e rede desabilitada — não dá para validar nem reparar` };
+      }
+    } else if (inst) {
+      log(`[engine-kit] ${engine.name}: instalada v${inst} não satisfaz o pin v${engine.version} → atualizando`);
+    }
+  }
+
+  // Antes de qualquer teste de rede/estado local: o que o kit NÃO faz com este motor vale
+  // independente de como ele está instalado.
+  // Motor que traz o PRÓPRIO instalador (ex.: um app com updater embutido). A entrada no registry
+  // existe como descritor de registro — release, chave, versão — mas quem instala é ele mesmo.
+  // Tentar provisionar aqui daria erro obscuro (o artefato é um instalador, não um tarball de
+  // `extractTo`); melhor recusar dizendo QUEM instala.
+  if (engine.status === "self-managed") {
+    return { ok: false, reason: `${engine.name} é self-managed: instala e atualiza pelo próprio updater, não pelo engine-kit (o registry guarda o descritor da release)` };
+  }
+
+  if (!allowNetwork) { return { ok: false, reason: `${engine.name} ausente/desatualizado e rede desabilitada` }; }
+  if (engine.status === "pending-release") {
+    return { ok: false, reason: `${engine.name} ainda não publicou release (status: pending-release)` };
+  }
+
+  mkdirSync(home, { recursive: true });
+
+  // LOCK atômico: só um consumidor provisiona; os demais aguardam o resultado dele.
+  // Um lock órfão (processo morto) é reclamado por idade — não trava a máquina para sempre.
+  const lockFd = claimLock(lock);
+  if (lockFd === null) {
+    for (let i = 0; i < 40; i++) {
+      if (existsSync(entryPath)) {
+        const inst = installedVersion(binDir);
+        // Se o vencedor terminou mas a versão continua ilegível, não invente: sinalize.
+        if (inst) { return { ok: true, entryPath, version: inst, reused: true }; }
+      }
+      await sleep(1000);
+    }
+    return { ok: false, reason: `${engine.name}: provision-locked-timeout (outro consumidor está instalando há >40s)` };
+  }
+
+  try {
+    // 1) SHA256 sidecar OBRIGATÓRIO (fail-closed).
+    let expected;
+    try {
+      const buf = await fetcher(engine.checksumUrl, 15000);
+      expected = String(buf).trim().split(/\s+/)[0].toLowerCase();
+    } catch (e) {
+      return { ok: false, reason: `${engine.name}: sha256 sidecar inacessível (${e.status || e.message}) → ABORT (fail-closed)` };
+    }
+    if (!/^[0-9a-f]{64}$/.test(expected)) {
+      return { ok: false, reason: `${engine.name}: sha256 sidecar malformado → ABORT` };
+    }
+
+    // 2) Download → .part → rename atômico.
+    log(`[engine-kit] baixando ${engine.assetUrl} …`);
+    let buf;
+    try { buf = await fetcher(engine.assetUrl, downloadTimeoutMs); }
+    catch (e) { return { ok: false, reason: `${engine.name}: download falhou (${e.status || e.message})` }; }
+    const part = join(home, `${engine.assetName}.part`);
+    const tgz = join(home, engine.assetName);
+    writeFileSync(part, buf);
+    renameSync(part, tgz);
+
+    // 3) Integridade (mismatch = apaga + ABORT).
+    const actual = sha256File(tgz);
+    if (actual !== expected) {
+      try { unlinkSync(tgz); } catch { /* ignore */ }
+      return { ok: false, reason: `${engine.name}: SHA256 mismatch (esperado ${expected.slice(0, 12)}…, obtido ${actual.slice(0, 12)}…) → ABORT` };
+    }
+
+    // 3.5) AUTENTICIDADE — antes de extrair. Um artefato não confiável não chega a tocar o disco
+    //      final: se a assinatura não confere, o .tgz é apagado e nada é instalado.
+    const auth = await verifyAuthenticity(engine, buf, { log, fetcher, trustedKeys });
+    if (!auth.ok) {
+      try { unlinkSync(tgz); } catch { /* ignore */ }
+      return { ok: false, reason: auth.reason };
+    }
+
+    // 4) Extrai em staging e faz o swap (com shutdown-first se já existe).
+    const staging = join(home, `stage-${engine.version}`);
+    rmSync(staging, { recursive: true, force: true });
+    mkdirSync(staging, { recursive: true });
+    const ex = extractTgz(tgz, staging);
+    if (!ex.ok) { return { ok: false, reason: `${engine.name}: ${ex.reason}` }; }
+
+    // 4.5) VERSÃO — a assinatura prova QUEM publicou o artefato, não QUAL versão ele é. Uma release
+    //      antiga, legitimamente assinada, servida no lugar da nova (replay/downgrade) passaria pelo
+    //      sha256 e pela Ed25519. O package.json do artefato tem de dizer a versão que o registry pede.
+    const got = installedVersion(staging);
+    if (got !== engine.version) {
+      rmSync(staging, { recursive: true, force: true });
+      try { unlinkSync(tgz); } catch { /* ignore */ }
+      return { ok: false, reason: `${engine.name}: o artefato diz v${got ?? "? (package.json ausente/ilegível)"} e o registry pede v${engine.version} → ABORT` };
+    }
+
+    // A instalação atual sai do caminho por RENAME, não por rmSync: no Windows, com o motor em uso
+    // (sem shutdownPath, ou um host segurando o processo), o rmSync apagava metade da pasta antes do
+    // EPERM e deixava a máquina sem motor nenhum. O rename falha inteiro ou passa inteiro.
+    let aside = null;
+    if (existsSync(binDir)) {
+      if (onBeforeReplace) { try { await onBeforeReplace(); } catch { /* best-effort */ } }
+      aside = `${binDir}.old-${process.pid}`;
+      rmSync(aside, { recursive: true, force: true });
+      try {
+        renameSync(binDir, aside);
+      } catch (e) {
+        rmSync(staging, { recursive: true, force: true });
+        try { unlinkSync(tgz); } catch { /* ignore */ }
+        return { ok: false, reason: `${engine.name}: não consegui trocar ${binDir} (${e.code || e.message}): arquivos em uso — feche quem usa o motor e rode de novo; a instalação atual ficou intacta` };
+      }
+    }
+    // `extractTo` pode ser ANINHADO (ex.: "runtimes/<motor>", quando o home guarda estado que
+    // precisa sobreviver ao swap — pesos, logs). O rename exige o diretório-pai existente: sem
+    // isto, funciona na máquina que já tem a pasta e falha justamente na máquina limpa.
+    mkdirSync(dirname(binDir), { recursive: true });
+    try {
+      renameSync(staging, binDir);
+    } catch (e) {
+      if (aside) { try { renameSync(aside, binDir); } catch { /* o reason abaixo diz onde ficou */ } }
+      return { ok: false, reason: `${engine.name}: swap falhou (${e.code || e.message})${aside && existsSync(aside) ? `; a instalação anterior está em ${aside}` : ""}` };
+    }
+    if (aside) {
+      try { rmSync(aside, { recursive: true, force: true }); }
+      catch (e) { log(`[engine-kit] ${engine.name}: instalado, mas a versão anterior ficou em ${aside} (${e.code || e.message})`); }
+    }
+    try { unlinkSync(tgz); } catch { /* ignore */ }
+
+    if (!existsSync(entryPath)) {
+      return { ok: false, reason: `${engine.name}: artefato extraído incompleto (sem ${engine.install.entry})` };
+    }
+    log(`[engine-kit] ${engine.name} instalado em ${binDir} (v${engine.version})`);
+    return { ok: true, entryPath, version: engine.version, installed: true, signed: auth.signed };
+  } catch (e) {
+    return { ok: false, reason: `${engine.name}: provision falhou: ${e?.message || e}` };
+  } finally {
+    try { closeSync(lockFd); unlinkSync(lock); } catch { /* ignore */ }
+  }
+}

package/kit/publish-base.ps1

@@ -0,0 +1,163 @@
+<#
+publish-base.ps1 - Publica UM motor no engine-registry, assinado, com prova do caminho real.
+
+  Por que existe: o publish.ps1 do vox-engine ja resolvia, na marra, quatro armadilhas que
+  nenhum README impede alguem de esquecer. Este script generaliza esses passos para QUALQUER
+  motor, para que um motor novo nao repita a licao a partir do zero:
+
+    1. o app Copilot injeta o token de uma conta de TRABALHO em todo processo filho, e o gh
+       publica pela conta ERRADA (a release aparece no lugar errado, ou some);
+    2. assinar so tem valor se a assinatura for CONFERIDA antes de sair do computador;
+    3. "publiquei" nao e prova: asset faltando, .sig esquecido ou tag errada so aparecem
+       quando um consumidor tenta instalar -- em producao;
+    4. editar o manifest.json com regex corrompe o arquivo em silencio.
+
+  Este script NAO builda o motor. Cada motor tem seu build (wheel Python, bundle esbuild, tgz
+  multi-plataforma) -- parametrizar isso seria reescrever cada build dentro daqui. O motor
+  builda e chama este script com o(s) artefato(s) prontos.
+
+  PUBLICACAO DUPLA: o engine-registry (publico) e o CANONICO de consumo -- e o unico que o
+  manifest aponta e o unico cuja falha aborta. O espelho no repo privado do motor (-SourceRepo)
+  e historico/rollback: se falhar, AVISA alto mas nao invalida a publicacao. Dois canonicos
+  seriam duas verdades, e a divergencia apareceria como "atualizei e voltou a versao velha".
+
+  PONTE DE MIGRACAO (-MarketplaceMirror): enquanto existir consumidor com a URL ANTIGA gravada
+  no codigo (SDK vendorizado, provision copiado), a release precisa continuar aparecendo la
+  tambem -- senao a migracao quebra quem ainda nao foi repontado. Tambem e o rollback: para
+  voltar atras, o consumidor so reaponta a URL, sem rebuild. Como o -SourceRepo, a falha aqui
+  AVISA e segue: o canonico ja esta de pe. Desligue quando um grep nos consumidores pela URL
+  antiga daquele motor voltar VAZIO.
+
+Uso:
+  ./publish-base.ps1 -Engine mcp-gateway -Version 0.2.0 -Asset dist/mcp-gateway.tgz
+  ./publish-base.ps1 -Engine vox-engine -Version 0.23.0 -Asset a.tgz,b.tgz -SourceRepo AllanSantos-DV/vox-engine
+  ./publish-base.ps1 -Engine embed-house -Version 1.0.5 -Asset x.tgz -MarketplaceMirror AllanSantos-DV/copilot-marketplace
+  ./publish-base.ps1 -Engine mcp-gateway -Version 0.2.0 -Asset dist/x.tgz -DryRun
+#>
+param(
+    [Parameter(Mandatory = $true)][string]$Engine,
+    [Parameter(Mandatory = $true)][string]$Version,
+    [Parameter(Mandatory = $true)][string[]]$Asset,
+    [string]$Registry = "AllanSantos-DV/engine-registry",
+    [string]$SourceRepo = "",
+    [string]$MarketplaceMirror = "",
+    [string]$RegistryPath = "",
+    [string]$Notes = "",
+    [switch]$SkipManifest,
+    [switch]$DryRun
+)
+
+$ErrorActionPreference = "Stop"
+$kit = $PSScriptRoot
+if (-not $RegistryPath) { $RegistryPath = Split-Path -Parent $kit }
+$manifest = Join-Path $RegistryPath "manifest.json"
+
+function Step($m) { Write-Host "==> $m" -ForegroundColor Cyan }
+function Warn($m) { Write-Host "AVISO: $m" -ForegroundColor Yellow }
+function Fail($m) { Write-Host "FALHOU: $m" -ForegroundColor Red; exit 1 }
+
+if ($Version -notmatch '^\d+\.\d+\.\d+$') { Fail "versao '$Version' invalida (esperado x.y.z)" }
+if ($Engine -notmatch '^[a-z0-9][a-z0-9-]*$') { Fail "motor '$Engine' invalido (minusculas, hifens)" }
+
+# --- 1. A armadilha da conta de TRABALHO --------------------------------------------------
+# O token injetado pelo app vence o keyring pessoal. Sem zerar, o gh autentica como a conta
+# errada e a release vai parar em outro lugar (ou falha com 404 num repo que existe).
+$env:GH_TOKEN = ''
+$env:GITHUB_TOKEN = ''
+$env:GIT_CONFIG_PARAMETERS = ''
+
+Step "Conferindo identidade do gh"
+$who = (gh api user --jq '.login' 2>$null)
+if ($LASTEXITCODE -ne 0 -or -not $who) { Fail "gh nao autenticado - rode 'gh auth login' com a conta dona dos repos" }
+$owner = $Registry.Split('/')[0]
+if ($who.Trim() -ne $owner) { Fail "gh autenticado como '$($who.Trim())' mas o registry e de '$owner' (token da conta errada)" }
+Write-Host "    gh=$($who.Trim())  registry=$Registry"
+
+Step "Conferindo os artefatos"
+$assets = @()
+foreach ($a in $Asset) {
+    if (-not (Test-Path $a)) { Fail "artefato nao encontrado: $a" }
+    $full = (Resolve-Path $a).Path
+    if ((Get-Item $full).Length -eq 0) { Fail "artefato vazio: $full" }
+    $assets += $full
+    Write-Host "    $([IO.Path]::GetFileName($full))  ($((Get-Item $full).Length) bytes)"
+}
+
+$keyPath = Join-Path $env:USERPROFILE ".engine-signing\${Engine}_ed25519_private.key"
+$envVar = "ENGINE_SIGNING_KEY_" + ($Engine -replace '-', '_').ToUpper()
+if (Test-Path "env:$envVar") { $keyPath = (Get-Item "env:$envVar").Value }
+if (-not (Test-Path $keyPath)) {
+    Fail "chave privada ausente: $keyPath`n       gere com: node `"$kit\gen-key.mjs`" $Engine`n       ou aponte a existente com: `$env:$envVar = '<caminho>'"
+}
+
+# --- 2. Assinar e PROVAR a assinatura antes de publicar -----------------------------------
+Step "Assinando (Ed25519 hash-then-sign; a chave privada nunca entra no CI)"
+$upload = @()
+foreach ($a in $assets) {
+    node (Join-Path $kit "sign.mjs") $a --engine $Engine
+    if ($LASTEXITCODE -ne 0) { Fail "assinatura de $a" }
+    if (-not (Test-Path "$a.sig")) { Fail ".sig nao foi gerado para $a" }
+    if (-not (Test-Path "$a.sha256")) { Fail ".sha256 nao foi gerado para $a" }
+    $upload += @($a, "$a.sig", "$a.sha256")
+}
+
+$pubKey = node -e "import('file:///' + process.argv[1].replace(/\\/g,'/')).then(async s => { const fs = await import('node:fs'); console.log(s.publicKeyHexFromPrivateHex(fs.readFileSync(process.argv[2],'utf8').trim())); })" (Join-Path $kit "signature.mjs") $keyPath
+if ($LASTEXITCODE -ne 0 -or -not $pubKey) { Fail "nao foi possivel derivar a chave publica de $keyPath" }
+$pubKey = $pubKey.Trim()
+Write-Host "    chave publica: $pubKey"
+
+$tag = "$Engine-v$Version"
+if ($DryRun) {
+    Step "DRY-RUN: publicaria a tag '$tag' em $Registry com:"
+    $upload | ForEach-Object { Write-Host "      $([IO.Path]::GetFileName($_))" }
+    if ($SourceRepo) { Write-Host "      + espelho no repo privado $SourceRepo (nao-fatal)" }
+    if ($MarketplaceMirror) { Write-Host "      + ponte no canal antigo $MarketplaceMirror (nao-fatal)" }
+    Write-Host "    e atualizaria $manifest (publicKey=$pubKey, signatureRequired=true, repo=$Registry)"
+    exit 0
+}
+
+# --- 3. Publicar no CANONICO (falha aqui aborta) ------------------------------------------
+Step "Publicando a release no registry ($Registry, tag $tag)"
+if (-not $Notes) {
+    $Notes = "$Engine $Version. Artefato assinado com Ed25519 (ed25519-sha256-raw): o engine-kit e fail-closed e recusa artefato sem assinatura valida."
+}
+gh release view $tag --repo $Registry 2>$null | Out-Null
+if ($LASTEXITCODE -eq 0) { Fail "a release '$tag' ja existe em $Registry - suba a versao ou apague a release antes (nao sobrescreva um artefato ja assinado)" }
+
+gh release create $tag --repo $Registry --title "$Engine $Version" --notes $Notes @upload
+if ($LASTEXITCODE -ne 0) { Fail "gh release create em $Registry" }
+
+# --- 4. Espelho no repo privado: historico/rollback, NAO canonico --------------------------
+if ($SourceRepo) {
+    Step "Espelhando no repo do codigo ($SourceRepo) - historico, nao canonico"
+    gh release create $tag --repo $SourceRepo --title "$Engine $Version" --notes "Espelho do release canonico: https://github.com/$Registry/releases/tag/$tag" @upload
+    if ($LASTEXITCODE -ne 0) {
+        Warn "o espelho em $SourceRepo falhou. A publicacao CANONICA esta de pe (consumidores nao sao afetados); refaca o espelho a mao se quiser o historico la."
+    }
+}
+
+# --- 4b. Ponte no canal ANTIGO: para quem ainda tem a URL velha gravada no codigo ----------
+if ($MarketplaceMirror) {
+    Step "Publicando a ponte no canal antigo ($MarketplaceMirror) - consumidores nao repontados"
+    $bridgeNotes = "PONTE DE MIGRACAO. O canonico deste motor agora e https://github.com/$Registry/releases/tag/$tag - esta copia existe so para os consumidores que ainda apontam para ca e sera removida quando nao restar nenhum."
+    gh release create $tag --repo $MarketplaceMirror --title "$Engine $Version (ponte)" --notes $bridgeNotes @upload
+    if ($LASTEXITCODE -ne 0) {
+        Warn "a ponte em $MarketplaceMirror falhou. O canonico esta de pe, mas quem AINDA aponta para o canal antigo nao vera esta versao - publique a ponte a mao ou reponte esses consumidores."
+    }
+}
+
+# --- 5. Manifest: parseado, nao editado com regex -----------------------------------------
+if (-not $SkipManifest) {
+    Step "Atualizando o manifest do registry"
+    node (Join-Path $kit "update-manifest.mjs") $Engine --version $Version --public-key $pubKey --repo $Registry --manifest $manifest
+    if ($LASTEXITCODE -ne 0) { Fail "update-manifest (a release esta publicada; corrija o manifest e commite)" }
+}
+
+# --- 6. A prova: baixar do release como um consumidor faria -------------------------------
+Step "Provando o caminho REAL (baixa do release publicado e confere sha256 + assinatura)"
+node (Join-Path $kit "verify-release.mjs") $Engine --manifest $manifest
+if ($LASTEXITCODE -ne 0) { Fail "a release publicada NAO passa pelo caminho do consumidor - conserte antes de anunciar" }
+
+Write-Host ""
+Write-Host "OK: $Engine v$Version publicado e VERIFICADO em $Registry." -ForegroundColor Green
+Write-Host "Falta: commitar e enviar o manifest.json ($manifest) para o registry publico."

package/kit/resolve.mjs

@@ -0,0 +1,119 @@
+// engine-kit/resolve.mjs — RESOLVE: descobre o descritor de um motor no registry.
+// Ordem: cache local fresco -> registry remoto -> cache obsoleto (degradação sinalizada).
+// NUNCA lança: devolve { ok:false, reason } para o consumidor decidir (fail-loud no caller).
+import { mkdirSync, existsSync, readFileSync, writeFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export const DEFAULT_REGISTRY_URL =
+  "https://raw.githubusercontent.com/AllanSantos-DV/engine-registry/main/manifest.json";
+
+const CACHE_DIR = join(homedir(), ".engine-kit");
+const CACHE = join(CACHE_DIR, "manifest.json");
+const CACHE_TTL_MS = 6 * 60 * 60 * 1000; // 6h
+
+/** Expande `~` e placeholders de plataforma. */
+export function expandHome(p) {
+  return p.startsWith("~") ? join(homedir(), p.slice(1).replace(/^[/\\]/, "")) : p;
+}
+
+export function target() {
+  return `${process.platform}-${process.arch}`;
+}
+
+/** Substitui {version}, {platform}, {arch}, {asset} num template. */
+export function fill(tpl, vars) {
+  return String(tpl).replace(/\{(\w+)\}/g, (m, k) => (k in vars ? vars[k] : m));
+}
+
+function readCache() {
+  try {
+    const age = Date.now() - statSync(CACHE).mtimeMs;
+    return { manifest: JSON.parse(readFileSync(CACHE, "utf8")), stale: age > CACHE_TTL_MS };
+  } catch {
+    return null;
+  }
+}
+
+async function fetchManifest(url, timeoutMs) {
+  const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+  if (!res.ok) { throw new Error(`HTTP ${res.status}`); }
+  return res.json();
+}
+
+/**
+ * Devolve o descritor do motor `name`, já com caminhos expandidos e URLs montadas.
+ * @param opts.manifest manifest JÁ carregado (pula rede e cache) — usado pelo publish para
+ *        conferir a release contra o manifest LOCAL que ele acabou de escrever, e por testes.
+ * @returns {Promise<{ok:true, engine:object} | {ok:false, reason:string}>}
+ */
+export async function resolve(name, { registryUrl = DEFAULT_REGISTRY_URL, allowNetwork = true, timeoutMs = 10000, version, manifest: given, refresh = false } = {}) {
+  let manifest = null;
+  const cached = given ? null : readCache();
+  // Sinalizações marcadas ONDE acontecem (não deduzidas depois):
+  //  • degraded  → tentou a rede, falhou, e caiu num cache VENCIDO (descritor pode estar velho);
+  //  • offline   → não se falou com o registry nesta resolução (rede desabilitada ou falha).
+  let degraded = false;
+  let offline = false;
+
+  // `refresh` ignora o cache fresco de propósito. Sem isso, quem já resolveu uma vez fica com o
+  // descritor congelado pelo TTL inteiro: publiquei três versões seguidas do mcp-gateway e o
+  // consumidor continuou instalando a primeira, porque o cache tinha 6 minutos de vida. Cache
+  // acelera o caminho quente (reusar o que já está instalado); INSTALAR ou DIAGNOSTICAR quer a
+  // verdade do registry, e essas operações são raras — pagar uma requisição não pesa.
+  const useCache = cached && !cached.stale && !refresh;
+
+  if (given) {
+    manifest = given;
+    offline = true; // manifest entregue na mão: não se falou com o registry
+  } else if (useCache) {
+    manifest = cached.manifest;
+    offline = true; // cache fresco: não precisou da rede
+  } else if (allowNetwork) {
+    try {
+      manifest = await fetchManifest(registryUrl, timeoutMs);
+      try { mkdirSync(CACHE_DIR, { recursive: true }); writeFileSync(CACHE, JSON.stringify(manifest, null, 2)); } catch { /* cache é best-effort */ }
+    } catch (e) {
+      if (!cached) { return { ok: false, reason: `registry inacessível (${e.message}) e sem cache` }; }
+      manifest = cached.manifest;
+      offline = true;
+      degraded = cached.stale; // AQUI é a degradação real: rede falhou e o cache está vencido
+    }
+  } else if (cached) {
+    manifest = cached.manifest;
+    offline = true;
+    degraded = cached.stale;
+  } else {
+    return { ok: false, reason: "sem cache do registry e rede desabilitada" };
+  }
+
+  const found = (manifest.engines ?? []).find((e) => e.name === name);
+  if (!found) { return { ok: false, reason: `motor "${name}" não existe no registry` }; }
+
+  const v = version ?? found.version;
+  const vars = { version: v, platform: process.platform, arch: process.arch };
+  const asset = fill(found.install.asset, vars);
+  const tag = fill(found.install.tag, vars);
+  const base = `https://github.com/${found.install.repo}/releases/download/${tag}`;
+  // Sidecar de assinatura: template opcional, default `<asset>.sig`. A URL é sempre montada —
+  // quem decide se ela é OBRIGATÓRIA é o provision, olhando publicKey/signatureRequired.
+  const sigName = fill(found.install.signature ?? "{asset}.sig", { ...vars, asset });
+
+  return {
+    ok: true,
+    engine: {
+      ...found,
+      version: v,
+      homeDir: expandHome(found.home),
+      assetName: asset,
+      assetUrl: `${base}/${asset}`,
+      checksumUrl: `${base}/${fill(found.install.checksum, { ...vars, asset })}`,
+      signatureName: sigName,
+      signatureUrl: `${base}/${sigName}`,
+      /** true = o descritor veio de um cache VENCIDO porque o registry não respondeu. */
+      staleCache: degraded,
+      /** true = esta resolução não falou com o registry (cache fresco, sem rede, ou falha). */
+      offline,
+    },
+  };
+}