engine-kit 0.0.0-stage → 0.2.0

package/kit/ensure.mjs

@@ -0,0 +1,82 @@
+// engine-kit/ensure.mjs — `npx engine-kit ensure <motor>`: instala um motor com um comando, sem clonar o repo.
+//
+// O mesmo caminho do doctor --fix (resolve → provision: sha256 + Ed25519 fail-closed, lock, swap), com uma
+// diferença na raiz de confiança: a chave pública do PRIMEIRO contato vem do manifest.json que viaja DENTRO deste
+// pacote (publicado no npm com proveniência), não do registry baixado na hora. Ela entra como `trustedKeys`: se o
+// registry servir outra chave, é ABORT já na primeira instalação — quem toma o repositório não troca a chave sem
+// também publicar um engine-kit novo, e essa publicação deixa rastro público (proveniência do npm).
+//
+// Motor que não está no manifest deste pacote é recusado: sem a chave embarcada não há primeiro contato
+// verificável, e cair no TOFU calado seria justamente o buraco que o pacote fecha. Saída: atualizar o kit.
+// NUNCA lança: devolve { ok, reason } para o cli decidir o exit code.
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { resolve } from "./resolve.mjs";
+import { provision, installedVersion, satisfiesPin } from "./provision.mjs";
+import { shutdown } from "./lifecycle.mjs";
+
+const BUNDLED_MANIFEST = new URL("../manifest.json", import.meta.url);
+
+/** Manifest que viaja dentro do pacote (lança se ilegível; `ensureCommand` transforma em reason). */
+export function bundledManifest() {
+  return JSON.parse(readFileSync(BUNDLED_MANIFEST, "utf8"));
+}
+
+/**
+ * @param {string} name motor no registry.
+ * @param {object} opts
+ * @param {string=} opts.version pin de versão (default: a do registry).
+ * @param {string=} opts.registryUrl manifest remoto (default: registry público).
+ * @param {object=} opts.bundled manifest embarcado (default: o deste pacote; testes injetam).
+ * @param {object=} opts.manifest manifest do registry já carregado (testes; pula rede e cache).
+ * @param {Function=} opts.fetcher download injetável (testes).
+ * @param {boolean=} opts.autoUpdate false = motor já instalado fica na versão dele e o retorno avisa a nova
+ *        (`available`). Default true. Um `version` explícito sempre vale: foi pedido.
+ * @returns {Promise<{ok:true, entryPath:string, version:string, kind:string, reused?:boolean, signed?:boolean,
+ *          previous?:string, available?:string} | {ok:false, reason:string}>} `previous` = versão substituída.
+ */
+export async function ensureCommand(name, { version, registryUrl, bundled, manifest, fetcher, autoUpdate = true, log = () => {} } = {}) {
+  let local;
+  try { local = bundled ?? bundledManifest(); }
+  catch (e) { return { ok: false, reason: `manifest embarcado ilegível: ${e.message}` }; }
+
+  const pinned = (local.engines ?? []).find((e) => e.name === name);
+  if (!pinned) {
+    return { ok: false, reason: `motor "${name}" não está no manifest deste engine-kit → atualize o kit (npx engine-kit@latest ensure ${name})` };
+  }
+  const publicKey = pinned.install?.publicKey;
+  if (!publicKey) {
+    return { ok: false, reason: `${name}: o manifest embarcado não traz publicKey → sem chave do primeiro contato não instalo (ABORT)` };
+  }
+
+  // refresh: instalar quer a verdade do registry, não um descritor de cache.
+  const r = await resolve(name, { version, registryUrl, refresh: true, ...(manifest ? { manifest } : {}) });
+  if (!r.ok) { return { ok: false, reason: r.reason }; }
+
+  const engine = r.engine;
+  const entryPath = join(engine.homeDir, engine.install.entry);
+  const previous = existsSync(entryPath) ? installedVersion(join(engine.homeDir, engine.install.extractTo ?? "bin")) : null;
+  if (!autoUpdate && !version && previous && !satisfiesPin(previous, engine.version)) {
+    return { ok: true, entryPath, version: previous, kind: engine.kind, reused: true, available: engine.version };
+  }
+
+  const p = await provision(r.engine, {
+    log,
+    trustedKeys: { [name]: publicKey },
+    ...(fetcher ? { fetcher } : {}),
+    // Windows: arquivo em uso não se sobrescreve. Derruba o daemon pelo shutdownPath que o registry declara.
+    onBeforeReplace: async () => {
+      const s = await shutdown(r.engine, { log });
+      if (!s.ok) { log(`aviso: ${s.reason} — o swap pode falhar com o motor vivo`); }
+    },
+  });
+  if (!p.ok) {
+    // Rotação legítima de chave chega ao registry antes de chegar a este pacote: a saída é o kit novo.
+    const hint = /FIXADA|não declara publicKey/.test(p.reason) ? ` — se a chave foi rotacionada de propósito, rode npx engine-kit@latest ensure ${name}` : "";
+    return { ok: false, reason: p.reason + hint };
+  }
+  return {
+    ok: true, entryPath: p.entryPath, version: p.version, kind: engine.kind, reused: p.reused === true, signed: p.signed,
+    ...(p.installed && previous && previous !== p.version ? { previous } : {}),
+  };
+}

package/kit/gen-key.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// engine-kit/gen-key.mjs — gera o par Ed25519 de UM motor.
+//
+//   node kit/gen-key.mjs <motor>
+//
+// Uma chave POR MOTOR (não uma chave do publisher): comprometer uma chave obriga a republicar
+// aquele motor, não a casa inteira. A privada fica só nesta máquina, em ~/.engine-signing/, e
+// NUNCA entra em CI — é o que garante que um CI comprometido não consegue forjar um release.
+//
+// A pública sai no stdout para você colar em `install.publicKey` do manifest.json.
+import { mkdirSync, writeFileSync, existsSync, chmodSync } from "node:fs";
+import { generateKeyPairHex, publicKeyFromHex, signBlob, verifyBlob } from "./signature.mjs";
+import { SIGNING_DIR, keyPathFor } from "./keystore.mjs";
+
+const die = (msg) => { console.error(`FALHOU: ${msg}`); process.exit(1); };
+
+const engine = process.argv[2];
+if (!engine || !/^[a-z0-9][a-z0-9-]*$/.test(engine)) {
+  die("uso: node kit/gen-key.mjs <motor>   (nome em minúsculas, ex.: mcp-gateway)");
+}
+
+const keyPath = keyPathFor(engine);
+if (existsSync(keyPath)) {
+  // Sobrescrever invalidaria TODAS as releases já assinadas deste motor: os consumidores têm a
+  // pública antiga pinada e passariam a recusar tudo. Recusa alto em vez de destruir em silêncio.
+  die(`já existe uma chave para "${engine}" em ${keyPath}.\n` +
+      "       Sobrescrever invalidaria todas as releases assinadas com ela (os consumidores têm a pública pinada).\n" +
+      "       Se a rotação for intencional, mova o arquivo antigo à mão e rode de novo.");
+}
+const { publicKeyHex, privateKeyHex } = generateKeyPairHex();
+
+// Auto-prova antes de gravar: o par gerado assina e verifica de verdade, e recusa adulterado.
+// Sem isto, um par quebrado só apareceria na primeira instalação de um consumidor.
+const probe = Buffer.from(`engine-kit gen-key probe :: ${engine}`);
+const sig = signBlob(probe, privateKeyHex);
+if (!verifyBlob(probe, sig, publicKeyHex).ok) { die("o par gerado não se auto-verificou — abortando"); }
+if (verifyBlob(Buffer.concat([probe, Buffer.from("x")]), sig, publicKeyHex).ok) {
+  die("o par gerado ACEITOU conteúdo adulterado — abortando");
+}
+publicKeyFromHex(publicKeyHex); // prova que o envelope DER importa no Node desta máquina
+
+mkdirSync(SIGNING_DIR, { recursive: true });
+writeFileSync(keyPath, privateKeyHex, { encoding: "utf8", mode: 0o600 });
+try { chmodSync(keyPath, 0o600); } catch { /* NTFS ignora o modo; o ACL do perfil já restringe */ }
+
+console.log(`chave privada  : ${keyPath}  (NÃO versionar, NÃO subir para CI)`);
+console.log(`chave pública  : ${publicKeyHex}`);
+console.log("");
+console.log(`Cole no manifest.json, no motor "${engine}":`);
+console.log(JSON.stringify({
+  install: { publicKey: publicKeyHex, signatureAlgorithm: "ed25519-sha256-raw", signatureRequired: true },
+}, null, 2));

package/kit/index.mjs

@@ -0,0 +1,54 @@
+// engine-kit — a dependência que as extensões importam para consumir um MOTOR.
+//
+// Um motor (embed-house, vox-engine, mcp-gateway…) é infraestrutura compartilhada: instala UMA vez
+// por máquina, em `~/.<motor>`, e serve N consumidores. O consumidor não empacota o motor nem
+// duplica a lógica de "achar ou baixar" — declara a dependência e chama `ensureEngine`.
+//
+//   import { ensureEngine } from "engine-kit";
+//   const r = await ensureEngine("embed-house", { healthCheck: async (rt) => { ... } });
+//   if (!r.available) { /* degrade sinalizado — NUNCA silencioso */ }
+//
+// Contrato: nenhuma função lança. Falha vira `{ ok:false | available:false, reason }` para o
+// consumidor decidir (fail-loud no caller, não no kit).
+export { resolve, DEFAULT_REGISTRY_URL, expandHome, target, fill } from "./resolve.mjs";
+export { provision, satisfiesPin, fetchArtifact } from "./provision.mjs";
+export { lifecycle, readRuntime, readFreshRuntime, shutdown } from "./lifecycle.mjs";
+export {
+  verifyBlob, signBlob, generateKeyPairHex, publicKeyFromHex, privateKeyFromHex, publicKeyHexFromPrivateHex,
+  SUPPORTED_ALGORITHMS, DEFAULT_ALGORITHM, SIGNATURE_BYTES,
+} from "./signature.mjs";
+export { SIGNING_DIR, keyPathFor } from "./keystore.mjs";
+
+import { resolve } from "./resolve.mjs";
+import { provision } from "./provision.mjs";
+import { lifecycle } from "./lifecycle.mjs";
+
+/**
+ * RESOLVE → PROVISION → LIFECYCLE numa chamada: o caminho que 99% dos consumidores querem.
+ * @param {string} name nome do motor no registry.
+ * @param {object} opts
+ * @param {(runtime:object)=>Promise<object|null>} opts.healthCheck validação de saúde/protocolo (obrigatória).
+ * @param {string=} opts.version pin de versão (default: a do registry).
+ * @param {boolean=} opts.allowNetwork permite baixar/atualizar (default true).
+ * @param {Record<string,string>=} opts.trustedKeys chaves públicas FIXADAS pelo consumidor
+ *        (`{ "<motor>": "<hex>" }`). Divergência com o registry = ABORT. Sem isso vale TOFU:
+ *        a chave da 1ª instalação é gravada e qualquer troca posterior aborta.
+ * @param {string=} opts.registryUrl URL do manifest (default: registry público; testes apontam para um local).
+ * @param {(url:string,timeoutMs:number)=>Promise<Buffer>=} opts.fetcher download injetável (testes).
+ * @param {()=>Promise<void>=} opts.onBeforeReplace shutdown do motor antes de sobrescrever (Windows).
+ * @returns {Promise<{available:true, runtime:object, health:object, engine:object} | {available:false, reason:string}>}
+ */
+export async function ensureEngine(name, opts = {}) {
+  const { healthCheck, version, allowNetwork = true, registryUrl, log = () => {}, bootTimeoutMs, onBeforeReplace, env, trustedKeys, refresh = false, fetcher } = opts;
+
+  const r = await resolve(name, { version, allowNetwork, registryUrl, refresh });
+  if (!r.ok) { return { available: false, reason: r.reason }; }
+
+  const p = await provision(r.engine, { log, allowNetwork, onBeforeReplace, trustedKeys, ...(fetcher ? { fetcher } : {}) });
+  if (!p.ok) { return { available: false, reason: p.reason }; }
+
+  const l = await lifecycle(r.engine, p.entryPath, { healthCheck, log, bootTimeoutMs, env });
+  if (!l.available) { return l; }
+
+  return { ...l, engine: { ...r.engine, installedVersion: p.version } };
+}

package/kit/keystore.mjs

@@ -0,0 +1,29 @@
+// engine-kit/keystore.mjs — ONDE moram as chaves privadas de assinatura nesta máquina.
+//
+// Módulo separado de propósito: `gen-key.mjs` e `sign.mjs` são CLIs (executam ao serem
+// carregados). Se um importasse o outro só para reaproveitar o caminho da chave, o CLI do outro
+// dispararia junto. O caminho é dado — vive num módulo sem efeito colateral.
+//
+// Uma chave POR MOTOR: o raio de explosão de um vazamento é um motor, não a casa toda.
+//
+// OVERRIDE por ambiente: `ENGINE_SIGNING_KEY_<MOTOR>` (hífens viram `_`, tudo em maiúsculas).
+// Existe por um motivo concreto: a chave do `vox-engine` já vive em
+// `~/.action/signing/vox_engine_ed25519_private.key` e a PÚBLICA dela está pinada em mais de dez
+// cópias vendorizadas do SDK, espalhadas por outros repositórios. Mover o arquivo por estética
+// arriscaria invalidar todas elas. O padrão da casa continua sendo `~/.engine-signing/`; o
+// override é a porta de entrada para as chaves que já existiam antes dele.
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export const SIGNING_DIR = join(homedir(), ".engine-signing");
+
+/** Nome da variável de ambiente que sobrescreve o caminho da chave de um motor. */
+export const envVarFor = (engine) => `ENGINE_SIGNING_KEY_${String(engine).replace(/-/g, "_").toUpperCase()}`;
+
+/** Caminho canônico da chave privada de um motor (respeita o override por ambiente). */
+export function keyPathFor(engine) {
+  const override = process.env[envVarFor(engine)];
+  if (override && override.trim()) { return override.trim(); }
+  return join(SIGNING_DIR, `${engine}_ed25519_private.key`);
+}
+

package/kit/lifecycle.mjs

@@ -0,0 +1,160 @@
+// engine-kit/lifecycle.mjs — LIFECYCLE: garante o motor VIVO e devolve como falar com ele.
+// Generalização do ensureDaemon.mjs do embed-house. Regra do kit: ele NUNCA adivinha a saúde do
+// motor — `healthCheck` é sempre um callback de quem conhece o protocolo (handshake de versão,
+// modelo, dimensão…). O kit cuida do que é genérico: ler o runtime.json fresco, subir o processo
+// destacado e esperar o auto-anúncio. NUNCA lança.
+//
+// Dois tipos de motor (`kind`):
+//   • daemon — processo longo que anuncia `runtime.json` e responde health. É o fluxo abaixo.
+//   • cli    — executável invocado POR EVENTO (ex.: o dispatcher de hooks): não há processo para
+//              manter vivo, nem runtime, nem health. Provisionar já é entregar. Forçar um daemon
+//              aqui seria inventar um ciclo de vida que o motor não tem.
+import { spawn } from "node:child_process";
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Janela padrão de frescor quando o motor não declara `heartbeatMs`.
+ * NUNCA usar Infinity aqui: um `runtime.json` de dias atrás passaria como "vivo" e o
+ * lifecycle devolveria um motor morto. Sem heartbeat declarado, 2 minutos é o teto.
+ */
+const DEFAULT_STALE_MS = 120000;
+
+/** Lê o runtime.json do motor, sem julgar idade. `null` se ausente/ilegível. */
+export function readRuntime(engine) {
+  try {
+    const rt = join(engine.homeDir, engine.runtime?.runtimeFile ?? "runtime.json");
+    return JSON.parse(readFileSync(rt, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Lê o runtime.json do motor SE estiver fresco (heartbeat vivo). null se ausente/obsoleto. */
+export function readFreshRuntime(engine, { staleMs } = {}) {
+  const rt = join(engine.homeDir, engine.runtime?.runtimeFile ?? "runtime.json");
+  const hb = engine.runtime?.heartbeatMs;
+  const limit = staleMs ?? (hb ? hb * 3 : DEFAULT_STALE_MS);
+  try {
+    if (Date.now() - statSync(rt).mtimeMs > limit) { return null; }
+    return JSON.parse(readFileSync(rt, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Localiza um motor VIVO: lê o runtime (dica de onde procurar) e pergunta ao próprio motor
+ * (prova de que está vivo).
+ *
+ * A ordem importa e custou um bug de produção: antes, o frescor do `runtime.json` **vetava** o
+ * handshake — um motor que escreve o arquivo só no boot (o caso do mcp-gateway) era declarado
+ * morto depois de 2 minutos de uptime, e o kit tentava subir outro por cima do que estava
+ * servindo. Arquivo é DICA (diz a porta); handshake é AUTORIDADE (prova que atende, e que é o
+ * motor certo — o healthCheck confere o nome). Runtime velho apontando para porta alheia
+ * continua seguro: o handshake não reconhece e o fluxo segue para o spawn.
+ */
+async function findAlive(engine, healthCheck) {
+  const rt = readRuntime(engine);
+  if (!rt) { return null; }
+  const health = await healthCheck(rt);
+  return health ? { runtime: rt, health } : null;
+}
+
+/**
+ * Pede ao motor que se encerre, usando SÓ o que o registry declara.
+ *
+ * Existe porque no Windows um arquivo em uso não pode ser sobrescrito: atualizar um daemon vivo
+ * falha com EPERM no meio do swap. O kit continua não adivinhando nada — se o descritor não
+ * declara `shutdownPath`, ele não tenta; se declara um token, o token vem do campo declarado do
+ * runtime.json, no cabeçalho declarado. Sem declaração, sem token (e não se inventa um: seria um
+ * endpoint de desligar aberto no loopback).
+ *
+ * @returns {Promise<{ok:true, stopped:boolean} | {ok:false, reason:string}>} nunca lança.
+ */
+export async function shutdown(engine, { log = () => {}, timeoutMs = 5000 } = {}) {
+  const path = engine.runtime?.shutdownPath;
+  if (!path) { return { ok: true, stopped: false }; }
+
+  // Runtime SEM gate de frescor: um motor que só escreve o arquivo no boot (caso do mcp-gateway)
+  // seria considerado "morto" aqui e o shutdown viraria no-op — e aí o swap de arquivos falharia
+  // no Windows com EPERM, exatamente o problema que esta função existe para evitar.
+  const rt = readRuntime(engine);
+  if (!rt?.port) { return { ok: true, stopped: false }; } // nada vivo para derrubar
+
+  const headers = {};
+  const field = engine.runtime?.shutdownTokenField;
+  const header = engine.runtime?.shutdownTokenHeader;
+  if (field && header && rt[field]) { headers[header] = rt[field]; }
+
+  try {
+    const res = await fetch(`http://127.0.0.1:${rt.port}${path}`, {
+      method: "POST", headers, signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) { return { ok: false, reason: `${engine.name}: shutdown respondeu HTTP ${res.status}` }; }
+    log(`[engine-kit] ${engine.name}: shutdown pedido (pid ${rt.pid ?? "?"})`);
+    // O motor responde ANTES de sair. Sem esta espera, o swap ainda encontra o arquivo em uso.
+    await sleep(1500);
+    return { ok: true, stopped: true };
+  } catch (e) {
+    return { ok: false, reason: `${engine.name}: shutdown falhou (${e?.message || e})` };
+  }
+}
+
+/** Sobe o motor destacado, com ambiente limpo (fora do fork do host). */
+function spawnEngine(nodePath, entryPath, log, extraEnv) {
+  try {
+    const child = spawn(nodePath, [entryPath], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+      env: { ...process.env, NODE_OPTIONS: "", COPILOT_SDK_PATH: "", ...extraEnv },
+    });
+    child.unref();
+    log(`[engine-kit] motor disparado: ${nodePath} ${entryPath}`);
+    return true;
+  } catch (e) {
+    log(`[engine-kit] falha ao subir motor (sinalizado): ${e?.message || e}`);
+    return false;
+  }
+}
+
+/**
+ * Garante o motor vivo.
+ * @param engine   descritor resolvido (resolve.mjs)
+ * @param entryPath caminho do entrypoint instalado (provision.mjs)
+ * @param healthCheck (runtimeInfo) => Promise<object|null> — validação de saúde/protocolo DO MOTOR.
+ * @returns {Promise<{available:true, runtime:object, health:object} | {available:false, reason:string}>}
+ */
+export async function lifecycle(engine, entryPath, { healthCheck, log = () => {}, bootTimeoutMs = 60000, nodePath = process.execPath, env } = {}) {
+  // 0) MOTOR CLI: não existe daemon a subir nem runtime a esperar — o binário provisionado É a
+  //    entrega. Sai ANTES da exigência de healthCheck: cobrar handshake de quem não tem protocolo
+  //    de rede seria uma barreira artificial.
+  if (engine.kind === "cli") {
+    log(`[engine-kit] ${engine.name}: motor kind=cli (invocado por evento) — sem processo para manter vivo`);
+    return { available: true, kind: "cli", bin: entryPath, runtime: null, health: null };
+  }
+
+  if (typeof healthCheck !== "function") {
+    return { available: false, reason: "healthCheck é obrigatório (o kit não adivinha o protocolo do motor)" };
+  }
+
+  // 1) FAST PATH: já vivo? (runtime diz onde; o handshake do motor prova que sim)
+  const alive = await findAlive(engine, healthCheck);
+  if (alive) { log(`[engine-kit] ${engine.name}: fast-path (já vivo)`); return { available: true, ...alive }; }
+
+  // 2) SOBE. A corrida por singleton é resolvida DENTRO do motor (port-lock/bind); quem perde sai.
+  if (!spawnEngine(nodePath, entryPath, log, env)) {
+    return { available: false, reason: `${engine.name}: spawn falhou` };
+  }
+
+  const deadline = Date.now() + bootTimeoutMs;
+  while (Date.now() < deadline) {
+    const up = await findAlive(engine, healthCheck);
+    if (up) { return { available: true, ...up }; }
+    await sleep(1000);
+  }
+  return { available: false, reason: `${engine.name}: não anunciou em ${bootTimeoutMs}ms` };
+}