engine-kit 0.2.4 → 0.2.5

package/kit/budget.mjs

@@ -41,9 +41,12 @@ const ROOT = resolvePath(KIT, "..");
 //   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.
+//   2026-11-09 tooling 31000 → 34000: diagnóstico de vida (pid, porta, idade do runtime) e do ponteiro
+//   `cli.json` no doctor (diagnose.mjs), +2.7 KB. Só leitura, rodado na mão de quem diagnostica; 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 },
+  tooling: { codeBytes: 34000, baseline: 16420, loc: 950 },
   adapter: { codeBytes: 5000, baseline: 1859, loc: 150 },
 };
 

package/kit/diagnose.mjs

@@ -0,0 +1,58 @@
+// engine-kit/diagnose.mjs — diagnóstico SOMENTE LEITURA de vida e de ponteiro, usado pelo doctor.
+// Não sobe, não derruba e não fala com o motor: lê o runtime que o motor anuncia e o `cli.json`
+// que ele publica (CONTRATO-MOTOR §4). Nunca lança.
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+import { readRuntime } from "./lifecycle.mjs";
+
+const alive = (pid) => {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
+};
+
+/**
+ * Vida do motor segundo o arquivo de runtime que ele declara: pid vivo, porta e idade do heartbeat.
+ * Estados: SEM-DECLARAÇÃO (o registry não declara arquivo de runtime), PARADO (sem runtime),
+ * VIVO (pid existe), ÓRFÃO (runtime aponta para pid que não existe mais).
+ * @returns {{state:string, detail:string}}
+ */
+export function lifeOf(engine, now = Date.now()) {
+  const rt = engine.runtime;
+  if (!rt?.runtimeFile) { return { state: "SEM-DECLARAÇÃO", detail: rt?.transport ? `transporte ${rt.transport}, sem arquivo de runtime` : "motor sem bloco runtime" }; }
+  const data = readRuntime(engine);
+  if (!data) { return { state: "PARADO", detail: `sem ${rt.runtimeFile}` }; }
+  let age = "";
+  try {
+    const ms = now - statSync(join(engine.homeDir, rt.runtimeFile)).mtimeMs;
+    const limit = rt.heartbeatMs ? ` (limite ${Math.round((rt.heartbeatMs * 3) / 1000)}s)` : "";
+    age = `, runtime atualizado há ${Math.round(ms / 1000)}s${limit}`;
+  } catch { /* o arquivo sumiu entre a leitura e o stat */ }
+  const where = `pid ${data.pid ?? "?"}${data.port ? `, porta ${data.port}` : ""}${age}`;
+  return data.pid && alive(data.pid)
+    ? { state: "VIVO", detail: where }
+    : { state: "ÓRFÃO", detail: `${where}; o pid não existe mais` };
+}
+
+/**
+ * Ponteiro `<home>/cli.json`: todo caminho absoluto que o motor publica precisa existir, e o kit
+ * avisa quando o ponteiro vive fora da instalação que ele provisionou.
+ * Estados: AUSENTE, ILEGÍVEL, QUEBRADO (algum caminho não existe), FORA-DA-INSTALAÇÃO, OK.
+ * @returns {{state:string, detail:string}}
+ */
+export function pointerOf(engine) {
+  const file = join(engine.homeDir, "cli.json");
+  if (!existsSync(file)) { return { state: "AUSENTE", detail: "o motor ainda não publicou o ponteiro" }; }
+  let data;
+  try { data = JSON.parse(readFileSync(file, "utf8")); }
+  catch { return { state: "ILEGÍVEL", detail: `${file} não é JSON válido` }; }
+  const paths = Object.entries(data).filter(([, v]) => typeof v === "string" && isAbsolute(v));
+  const missing = paths.filter(([, v]) => !existsSync(v)).map(([k]) => k);
+  if (missing.length) { return { state: "QUEBRADO", detail: `aponta para caminho inexistente: ${missing.join(", ")}` }; }
+  const binDir = join(engine.homeDir, engine.install.extractTo ?? "bin");
+  const outside = paths.filter(([k, v]) => {
+    const rel = relative(binDir, v);
+    return k !== "node" && (rel.startsWith("..") || isAbsolute(rel));
+  });
+  return outside.length
+    ? { state: "FORA-DA-INSTALAÇÃO", detail: `${outside.map(([k]) => k).join(", ")} fora de ${binDir}` }
+    : { state: "OK", detail: `${paths.length} caminho(s) existem` };
+}

package/kit/doctor.mjs

@@ -17,6 +17,7 @@ import { join } from "node:path";
 import { resolve } from "./resolve.mjs";
 import { provision, satisfiesPin } from "./provision.mjs";
 import { shutdown } from "./lifecycle.mjs";
+import { lifeOf, pointerOf } from "./diagnose.mjs";
 
 const args = process.argv.slice(2);
 const useLocal = args.includes("--local");
@@ -85,6 +86,11 @@ 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}`);
+  if (r.engine && r.engine.status !== "self-managed") {
+    const life = lifeOf(r.engine), ptr = pointerOf(r.engine);
+    console.log(`       ${pad("", w)}  vida: ${life.state} (${life.detail})`);
+    console.log(`       ${pad("", w)}  ponteiro cli.json: ${ptr.state} (${ptr.detail})`);
+  }
 }
 
 const pending = rows.filter((r) => r.needsWork);

package/kit/ensure.mjs

@@ -63,6 +63,7 @@ export async function ensureCommand(name, { version, registryUrl, bundled, manif
   const p = await provision(r.engine, {
     log,
     trustedKeys: { [name]: publicKey },
+    allowDowngrade: Boolean(version),
     ...(fetcher ? { fetcher } : {}),
     // Windows: arquivo em uso não se sobrescreve. Derruba o daemon pelo shutdownPath que o registry declara.
     onBeforeReplace: async () => {

package/kit/provision.mjs

@@ -12,7 +12,7 @@ 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";
+import { checkTrust, trustPath, cmpVer, rollbackReason, noteVersion } from "./trust.mjs";
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
@@ -77,22 +77,29 @@ function claimLock(lock) {
   }
 }
 
-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; }
+export const satisfiesPin = (installed, pinned) => String(installed).split(".")[0] === String(pinned).split(".")[0] && cmpVer(installed, pinned) >= 0;
+
+/**
+ * Baixa o artefato e confere o sidecar SHA256 (obrigatório, fail-closed) em memória.
+ * @returns {Promise<{buf:Buffer} | {reason:string}>}
+ */
+async function downloadChecked(engine, { log, fetcher, timeoutMs }) {
+  let expected;
+  try {
+    expected = String(await fetcher(engine.checksumUrl, 15000)).trim().split(/\s+/)[0].toLowerCase();
+  } catch (e) {
+    return { reason: `${engine.name}: sha256 sidecar inacessível (${e.status || e.message}) → ABORT (fail-closed)` };
   }
-  return true;
-}
+  if (!/^[0-9a-f]{64}$/.test(expected)) { return { reason: `${engine.name}: sha256 sidecar malformado → ABORT` }; }
 
-function sha256File(p) {
-  return createHash("sha256").update(readFileSync(p)).digest("hex").toLowerCase();
+  log(`[engine-kit] baixando ${engine.assetUrl} …`);
+  let buf;
+  try { buf = await fetcher(engine.assetUrl, timeoutMs); }
+  catch (e) { return { reason: `${engine.name}: download falhou (${e.status || e.message})` }; }
+
+  const actual = createHash("sha256").update(buf).digest("hex").toLowerCase();
+  return actual === expected ? { buf } : { reason: `${engine.name}: SHA256 mismatch (esperado ${expected.slice(0, 12)}…, obtido ${actual.slice(0, 12)}…) → ABORT` };
 }
 
 async function fetchBuf(url, timeoutMs) {
@@ -183,26 +190,9 @@ export async function fetchArtifact(engine, { log = () => {}, destDir, downloadT
     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 dl = await downloadChecked(engine, { log, fetcher, timeoutMs: downloadTimeoutMs });
+  if (!dl.buf) { return { ok: false, reason: dl.reason }; }
+  const buf = dl.buf;
 
   const auth = await verifyAuthenticity(engine, buf, { log, fetcher, trustedKeys });
   if (!auth.ok) { return { ok: false, reason: auth.reason }; }
@@ -225,7 +215,7 @@ export async function fetchArtifact(engine, { log = () => {}, destDir, downloadT
  * 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 } = {}) {
+export async function provision(engine, { log = () => {}, allowNetwork = true, onBeforeReplace, downloadTimeoutMs = 120000, fetcher = fetchBuf, trustedKeys, allowDowngrade } = {}) {
   const home = engine.homeDir;
   const binDir = join(home, engine.install.extractTo ?? "bin");
   const entryPath = join(home, engine.install.entry);
@@ -239,6 +229,7 @@ export async function provision(engine, { log = () => {}, allowNetwork = true, o
   if (existsSync(entryPath)) {
     const inst = installedVersion(binDir);
     if (inst && satisfiesPin(inst, engine.version)) {
+      noteVersion(engine.name, inst);
       return { ok: true, entryPath, version: inst, reused: true };
     }
     if (!inst && engine.status !== "self-managed") {
@@ -266,6 +257,9 @@ export async function provision(engine, { log = () => {}, allowNetwork = true, o
     return { ok: false, reason: `${engine.name} ainda não publicou release (status: pending-release)` };
   }
 
+  const rb = !allowDowngrade && rollbackReason(engine.name, engine.version);
+  if (rb) { return { ok: false, reason: rb }; }
+
   mkdirSync(home, { recursive: true });
 
   // LOCK atômico: só um consumidor provisiona; os demais aguardam o resultado dele.
@@ -284,35 +278,15 @@ export async function provision(engine, { log = () => {}, allowNetwork = true, o
   }
 
   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})` }; }
+    // 1-3) Sidecar SHA256 obrigatório, download e integridade: nada toca o disco antes de conferir.
+    const dl = await downloadChecked(engine, { log, fetcher, timeoutMs: downloadTimeoutMs });
+    if (!dl.buf) { return { ok: false, reason: dl.reason }; }
+    const buf = dl.buf;
     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) {
-      dropFile(tgz);
-      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 });
@@ -373,6 +347,7 @@ export async function provision(engine, { log = () => {}, allowNetwork = true, o
     if (!existsSync(entryPath)) {
       return { ok: false, reason: `${engine.name}: artefato extraído incompleto (sem ${engine.install.entry})` };
     }
+    noteVersion(engine.name, engine.version);
     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) {

package/kit/trust.mjs

@@ -70,3 +70,22 @@ export function checkTrust(engineName, publicKey, { trustedKeys } = {}) {
 }
 
 export const trustPath = () => trustFile();
+
+/** Compara versões `x.y.z` numericamente: negativo, zero ou positivo. */
+export const cmpVer = (a, b) => String(a).localeCompare(String(b), "en", { numeric: true });
+
+/** Motivo do ABORT se `version` é menor que a maior já instalada do motor (anti-rollback); falsy se pode seguir. */
+export function rollbackReason(name, version) {
+  const max = readTrust()[name]?.maxVersion;
+  return max && cmpVer(version, max) < 0 && `${name}: v${version} < v${max} já instalada → ABORT (rollback; downgrade só com --version)`;
+}
+
+/** Grava `version` como a maior vista do motor, se superar a registrada. */
+export function noteVersion(name, version) {
+  const store = readTrust(), max = store[name]?.maxVersion;
+  if (max && cmpVer(version, max) <= 0) return;
+  try {
+    mkdirSync(trustDir(), { recursive: true });
+    writeFileSync(trustFile(), JSON.stringify({ ...store, [name]: { ...store[name], maxVersion: version } }, null, 2));
+  } catch { /* sem gravar, a proteção vale a partir da próxima instalação */ }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engine-kit",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Cliente das dependências compartilhadas (motores) do engine-registry: resolve, provisiona com SHA256 e assinatura Ed25519 fail-closed, e mantém o motor vivo — uma instalação por máquina, N consumidores.",
   "type": "module",
   "bin": {
@@ -24,7 +24,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node kit/budget.mjs && node tests/test-silencio.mjs && node tests/smoke.mjs && node tests/test-edge.mjs && node tests/test-signature.mjs && node tests/test-ensure.mjs && node tests/test-ensure-daemon.mjs && node tests/test-update.mjs && node tests/test-trust.mjs && node tests/test-tar.mjs && node tests/test-apps.mjs && node tests/test-resolve-cache.mjs && node tests/test-doctor-exit.mjs && node tests/test-mcp-gateway-token.mjs && node tests/test-gateway-provision.mjs && node tests/test-neural-link-alignment.mjs && node tests/test-site.mjs && node tests/test-pages-branch.mjs && node tests/test-readme-versions.mjs && node tests/test-pages-gate.mjs && node tests/test-regras-escopo.mjs",
+    "test": "node kit/budget.mjs && node tests/test-silencio.mjs && node tests/smoke.mjs && node tests/test-edge.mjs && node tests/test-signature.mjs && node tests/test-ensure.mjs && node tests/test-ensure-daemon.mjs && node tests/test-update.mjs && node tests/test-trust.mjs && node tests/test-rollback.mjs && node tests/test-diagnose.mjs && node tests/test-tar.mjs && node tests/test-apps.mjs && node tests/test-resolve-cache.mjs && node tests/test-doctor-exit.mjs && node tests/test-mcp-gateway-token.mjs && node tests/test-gateway-provision.mjs && node tests/test-neural-link-alignment.mjs && node tests/test-site.mjs && node tests/test-pages-branch.mjs && node tests/test-readme-versions.mjs && node tests/test-pages-gate.mjs && node tests/test-regras-escopo.mjs",
     "test:pages-live": "node tests/test-pages-gate.mjs --live",
     "test:network": "node tests/smoke.mjs --network && node tests/test-signature.mjs --network",
     "test:e2e": "node tests/e2e-install.mjs",