engine-kit 0.2.2 → 0.2.3

package/CONTRATO-MOTOR.md

@@ -157,6 +157,10 @@ polui o histórico e obriga todo consumidor a decidir se atualiza — para desco
 | `embed-house` | daemon | `embed-house` | `engine-registry` ✅ | ✅ | `copilot-marketplace` |
 | `neural-link` | **cli** | `neural-link` | `engine-registry` ✅ | ✅ | `neural-link-runtime` (redirecionado) |
 | `vox-engine` | daemon (`pipe`), **self-managed** | `vox-engine` | `engine-registry` ✅ | ✅ | `copilot-marketplace` |
+| `vxk` | **cli** (shim stdio; daemon único próprio, desligado pelo `ensure` via `runtime.shutdownPath`) | `visual-explainer` | `engine-registry` ✅ | ✅ | — (nunca esteve lá) |
+| `cerne` | daemon, **self-managed** | `cerne` | `engine-registry` ✅ | ✅ | — (nunca esteve lá) |
+| `skill-engine` | **cli** | `skill-engine` | `engine-registry` ✅ | ✅ | — (nunca esteve lá) |
+| `client-harness` | **cli** (daemon único próprio, desligado pelo `ensure` via `runtime.shutdownPath`) | `harness-padroes-cliente` | `engine-registry` ✅ | ✅ | — (nunca esteve lá) |
 
 Cada repo de motor tem o próprio `publish.ps1`, que **builda** o que é específico dele e **delega**
 ao `kit/publish-base.ps1` a parte comum (identidade do `gh`, assinatura, release, manifest, prova).

package/README.md

@@ -29,9 +29,10 @@ vive num lugar só e o consumidor apenas **declara a dependência**.
 | `vox-engine` | 0.28.7 | `daemon` (pipe), **self-managed** | Motor de voz (STT/TTS) compartilhado, com auto-unload quando ocioso. Traz o próprio instalador e updater. |
 | `mcp-gateway` | 0.16.4 | `daemon` (http) | Agregador MCP: conecta uma vez em cada servidor MCP e reexpõe tudo num endpoint único. |
 | `neural-link` | 0.7.15 | `cli` | Dispatcher adaptativo de hooks: recebe o evento por stdin, pontua os handlers e devolve uma decisão composta. |
-| `vxk` | 0.18.0 | `cli` | Explicações visuais animadas e narradas como servidor MCP (stdio): devolve UM HTML autocontido e offline. A narração vem do `vox-engine`. |
+| `vxk` | 0.19.0 | `cli` | Explicações visuais animadas e narradas como servidor MCP (stdio): devolve UM HTML autocontido e offline, ou o vídeo MP4 (preset, aplicativo real, Motion) e o PDF. Um daemon único por máquina atende os agentes. A narração vem do `vox-engine`. |
 | `cerne` | 0.4.10 | `daemon`, **self-managed** | Leitura ativa de vídeo (captura, quadros, transcrição, tradução) exposta via MCP. Instalador Inno por usuário, Windows. |
 | `skill-engine` | 0.1.0 | `cli` | Gerencia skills de agentes fora de qualquer IDE: busca repositórios em quarentena, varre com regras determinísticas e só ativa o que sai limpo. |
+| `client-harness` | 0.1.1 | `cli` | Daemon local que faz o Claude Code e o Codex respeitarem os padrões de cada cliente: confere cada ação do agente contra as regras da pasta e recusa antes de gravar, com o motivo. |
 
 **Todos** são publicados aqui, assinados com Ed25519 e verificados antes de instalar.
 
@@ -42,7 +43,10 @@ Um motor pode ser de dois tipos (`kind`):
 - **`cli`** — executável invocado **por evento** (ex.: um dispatcher de hooks). Não há processo
   para manter vivo: provisionar já é entregar. O `lifecycle` devolve o caminho do binário sem
   spawn, sem health e sem runtime — forçar um daemon aqui seria inventar um ciclo de vida que o
-  motor não tem.
+  motor não tem. Exceção: `vxk` (shim stdio por agente) e `client-harness` são `cli` mas delegam a
+  um daemon único por máquina. O kit não sobe nem espera esse daemon, mas o manifest declara `runtime`
+  (`run/daemon.json`, `shutdownPath`, token) para o `ensure` pedir o desligamento antes de trocar a
+  instalação — no Windows um daemon vivo segura a pasta e o swap falharia com EPERM.
 
 E pode declarar `status: "self-managed"`: o motor traz o **próprio instalador/updater** (o caso do
 `vox-engine`, um app Python). A entrada aqui é o **descritor de registro** — onde está a release,
@@ -55,7 +59,7 @@ Sem clonar o repositório, com Node 18 ou mais:
 
 ```sh
 npx engine-kit ensure vxk                     # instala ou atualiza; reusa se já estiver em dia
-npx engine-kit ensure vxk --version 0.18.0    # pin de versão
+npx engine-kit ensure vxk --version 0.19.0    # pin de versão
 ```
 
 O `npx` baixa o kit do npm e o kit baixa o motor da release, confere o **sha256**, a **assinatura Ed25519**
@@ -267,7 +271,7 @@ plataforma, e a release mora aqui, no registry público, com download **sem logi
 
 | App | Versão | Plataformas | O que faz |
 |---|---|---|---|
-| — | — | — | Nenhum app registrado ainda. |
+| `agent-launcher` | 1.2.11 | `win32-x64` | Abre Claude Code, Codex e Copilot CLI nos seus projetos por qualquer host de modelos. |
 
 Um app só entra nesta tabela e em `manifest.apps` **depois** de a release pública existir e passar
 em `node kit/verify-release.mjs --app <nome>` (download anônimo de todos os assets, `.sha256` e

package/kit/lifecycle.mjs

@@ -8,7 +8,9 @@
 //   • 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.
+//              aqui seria inventar um ciclo de vida que o motor não tem. Exceção: o vxk é cli mas
+//              delega a um daemon próprio; o kit não o sobe, só o derruba (`shutdown`, via
+//              `runtime.shutdownPath`) antes de trocar a instalação.
 import { spawn } from "node:child_process";
 import { readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
@@ -63,6 +65,14 @@ async function findAlive(engine, healthCheck) {
   return health ? { runtime: rt, health } : null;
 }
 
+/** Espera o processo sair (até `ms`). true = saiu. */
+async function waitExit(pid, ms) {
+  for (const fim = Date.now() + ms; Date.now() < fim; await sleep(500)) {
+    try { process.kill(pid, 0); } catch { return true; }
+  }
+  return false;
+}
+
 /**
  * Pede ao motor que se encerre, usando SÓ o que o registry declara.
  *
@@ -74,7 +84,7 @@ async function findAlive(engine, healthCheck) {
  *
  * @returns {Promise<{ok:true, stopped:boolean} | {ok:false, reason:string}>} nunca lança.
  */
-export async function shutdown(engine, { log = () => {}, timeoutMs = 5000 } = {}) {
+export async function shutdown(engine, { log = () => {}, timeoutMs = 5000, waitBusyMs = 120000 } = {}) {
   const path = engine.runtime?.shutdownPath;
   if (!path) { return { ok: true, stopped: false }; }
 
@@ -93,10 +103,16 @@ export async function shutdown(engine, { log = () => {}, timeoutMs = 5000 } = {}
     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 ?? "?"})`);
+    // 202 = aceito, mas o motor está ocupado e só fecha quando o trabalho em curso acabar (vxk com build rodando);
+    // 503 = já está fechando. Nos dois o swap só é seguro depois que o processo sair.
+    const adiado = res.status === 202 || res.status === 503;
+    if (!res.ok && !adiado) { return { ok: false, reason: `${engine.name}: shutdown respondeu HTTP ${res.status}` }; }
+    log(`[engine-kit] ${engine.name}: shutdown pedido (pid ${rt.pid ?? "?"}, HTTP ${res.status})`);
     // O motor responde ANTES de sair. Sem esta espera, o swap ainda encontra o arquivo em uso.
     await sleep(1500);
+    if (adiado && rt.pid && !(await waitExit(rt.pid, waitBusyMs))) {
+      return { ok: false, reason: `${engine.name}: ainda ocupado após ${waitBusyMs / 1000} s (fecha ao fim do trabalho em curso); rode de novo depois` };
+    }
     return { ok: true, stopped: true };
   } catch (e) {
     return { ok: false, reason: `${engine.name}: shutdown falhou (${e?.message || e})` };

package/kit/provision.mjs

@@ -16,6 +16,16 @@ import { checkTrust, trustPath } from "./trust.mjs";
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
+// No Windows o handle de quem acabou de sair solta um instante depois: rename ocupado repete com backoff, depois lança.
+export async function renameRetry(a, b, tries = 8) {
+  for (let i = 1; ; await sleep(100 * i++)) {
+    try { return renameSync(a, b); } catch (e) { if (i >= tries || !/^(EBUSY|EPERM|EACCES)$/.test(e.code)) { throw e; } }
+  }
+}
+
+const dropFile = (p) => { try { unlinkSync(p); } catch { /* ignore */ } };
+const rmTree = (p) => rmSync(p, { recursive: true, force: true });
+
 /** Lock mais velho que isto é considerado ÓRFÃO (processo morreu antes do finally). */
 const LOCK_STALE_MS = 120000;
 
@@ -56,19 +66,13 @@ function extractTgz(tgz, dest) {
  * `openSync` e o `finally` travaria todos os consumidores para sempre.
  */
 function claimLock(lock) {
-  try {
+  const open = () => {
     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 */ }
+  };
+  try { return open(); } catch {
+    try { if (Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS) { unlinkSync(lock); return open(); } } catch { /* outro consumidor ganhou a corrida */ }
     return null;
   }
 }
@@ -305,7 +309,7 @@ export async function provision(engine, { log = () => {}, allowNetwork = true, o
     // 3) Integridade (mismatch = apaga + ABORT).
     const actual = sha256File(tgz);
     if (actual !== expected) {
-      try { unlinkSync(tgz); } catch { /* ignore */ }
+      dropFile(tgz);
       return { ok: false, reason: `${engine.name}: SHA256 mismatch (esperado ${expected.slice(0, 12)}…, obtido ${actual.slice(0, 12)}…) → ABORT` };
     }
 
@@ -313,13 +317,13 @@ export async function provision(engine, { log = () => {}, allowNetwork = true, o
     //      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 */ }
+      dropFile(tgz);
       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 });
+    rmTree(staging);
     mkdirSync(staging, { recursive: true });
     const ex = extractTgz(tgz, staging);
     if (!ex.ok) { return { ok: false, reason: `${engine.name}: ${ex.reason}` }; }
@@ -329,8 +333,8 @@ export async function provision(engine, { log = () => {}, allowNetwork = true, o
     //      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 */ }
+      rmTree(staging);
+      dropFile(tgz);
       return { ok: false, reason: `${engine.name}: o artefato diz v${got ?? "? (package.json ausente/ilegível)"} e o registry pede v${engine.version} → ABORT` };
     }
 
@@ -341,12 +345,12 @@ export async function provision(engine, { log = () => {}, allowNetwork = true, o
     if (existsSync(binDir)) {
       if (onBeforeReplace) { try { await onBeforeReplace(); } catch { /* best-effort */ } }
       aside = `${binDir}.old-${process.pid}`;
-      rmSync(aside, { recursive: true, force: true });
+      rmTree(aside);
       try {
-        renameSync(binDir, aside);
+        await renameRetry(binDir, aside);
       } catch (e) {
-        rmSync(staging, { recursive: true, force: true });
-        try { unlinkSync(tgz); } catch { /* ignore */ }
+        rmTree(staging);
+        dropFile(tgz);
         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` };
       }
     }
@@ -355,16 +359,16 @@ export async function provision(engine, { log = () => {}, allowNetwork = true, o
     // 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);
+      await renameRetry(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 }); }
+      try { rmTree(aside); }
       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 */ }
+    dropFile(tgz);
 
     if (!existsSync(entryPath)) {
       return { ok: false, reason: `${engine.name}: artefato extraído incompleto (sem ${engine.install.entry})` };

package/manifest.json

@@ -7,7 +7,33 @@
     "url": "https://github.com/AllanSantos-DV"
   },
   "description": "Catálogo público de motores compartilhados e aplicativos distribuídos. engine-kit consome apenas engines; apps declara versões e downloads sem instalar aplicativos automaticamente.",
-  "apps": [],
+  "apps": [
+    {
+      "name": "agent-launcher",
+      "version": "1.2.11",
+      "summary": "Abre Claude Code, Codex e Copilot CLI nos seus projetos por qualquer host de modelos. Windows.",
+      "homepage": "https://allansantos-dv.github.io/agent-launcher/",
+      "license": "MIT",
+      "platforms": [
+        "win32-x64"
+      ],
+      "release": {
+        "repo": "AllanSantos-DV/engine-registry",
+        "tag": "agent-launcher-v{version}",
+        "assets": [
+          {
+            "name": "agent-launcher-{version}-win32-x64.tgz",
+            "platform": "win32-x64",
+            "checksum": "{asset}.sha256",
+            "signature": "{asset}.sig"
+          }
+        ],
+        "publicKey": "bbfc8c1a639872d4e5fc44ac4172443886153b4579b4f3e0466220c02d09407a",
+        "signatureAlgorithm": "ed25519-sha256-raw",
+        "signatureRequired": true
+      }
+    }
+  ],
   "engines": [
     {
       "name": "embed-house",
@@ -137,9 +163,9 @@
     },
     {
       "name": "vxk",
-      "version": "0.18.0",
+      "version": "0.19.0",
       "kind": "cli",
-      "summary": "VXK — explicações visuais animadas e narradas como servidor MCP (stdio): qualquer cliente MCP (Claude Code, Codex, Copilot) compõe a biblioteca de componentes, ícones e o controle único de reprodução e recebe UM HTML autocontido e offline. A narração é assada pelo motor vox-engine.",
+      "summary": "VXK — explicações visuais animadas e narradas como servidor MCP (stdio): qualquer cliente MCP (Claude Code, Codex, Copilot) compõe a biblioteca de componentes, ícones e o controle único de reprodução e recebe UM HTML autocontido e offline, ou o vídeo MP4 da mesma explicação (por preset, do aplicativo real ou em Motion) e o PDF. A narração é assada pelo motor vox-engine.",
       "pagesUrl": "https://allansantos-dv.github.io/visual-explainer/",
       "pagesPendente": "a página no ar não oferece o caminho Ver o que o produto faz antes do vídeo",
       "home": "~/.vxk",
@@ -158,7 +184,16 @@
       "platforms": [
         "any"
       ],
-      "notes": "kind=cli: o host MCP sobe `node ~/.vxk/bin/vxk-mcp.mjs` por stdio (direto ou como backend do mcp-gateway); o build é job assíncrono porque o gateway corta chamadas em 30 s. O motor publica ~/.vxk/cli.json (mcp, builder, version) a cada arranque. Traz também o builder CLI (bin/build-artifact.mjs). Narração requer o vox-engine (Windows); sem ele o build falha alto em vez de gerar mudo."
+      "notes": "kind=cli: o host MCP sobe `node ~/.vxk/bin/vxk-mcp.mjs` por stdio (direto ou como backend do mcp-gateway); o build é job assíncrono porque o gateway corta chamadas em 30 s. Desde a 0.19.0 esse arquivo é um shim fino: quem trabalha é UM daemon por máquina e por usuário (bin/vxk-daemon.mjs, 127.0.0.1, porta derivada do usuário), que o shim sobe se não houver e compartilha entre os agentes; ele anuncia porta, pid e shutdownToken em ~/.vxk/run/daemon.json. O bloco `runtime` declara só o que o kit usa para trocar a instalação: o kit NÃO sobe nem espera esse daemon (o shim cuida disso), mas ao atualizar pede POST /shutdown com o x-shutdown-token antes do swap (ocupado, o daemon responde 202 e fecha quando o trabalho em curso termina: o kit espera o processo sair), porque no Windows o daemon vivo segura a pasta bin e a troca falharia com EPERM. O motor publica ~/.vxk/cli.json (mcp, builder, version) a cada arranque. Traz também o builder CLI (bin/build-artifact.mjs). Entrega HTML, MP4 (vxk_build target=mp4, vxk_video por preset, vxk_app_video do aplicativo real, vxk_motion) e PDF. Narração requer o vox-engine (Windows); sem ele o build falha alto em vez de gerar mudo.",
+      "runtime": {
+        "transport": "http",
+        "runtimeFile": "run/daemon.json",
+        "healthPath": "/health",
+        "shutdownPath": "/shutdown",
+        "heartbeatMs": 30000,
+        "shutdownTokenField": "shutdownToken",
+        "shutdownTokenHeader": "x-shutdown-token"
+      }
     },
     {
       "name": "cerne",
@@ -209,6 +244,38 @@
         "any"
       ],
       "notes": "kind=cli: o lifecycle entrega o binário e NÃO sobe processo. `extractTo` é aninhado como no neural-link: o home guarda ESTADO que sobrevive ao update, e só `runtimes/skill-engine` é trocado. Código-fonte no repo privado AllanSantos-DV/skill-engine; a release pública mora aqui."
+    },
+    {
+      "name": "client-harness",
+      "version": "0.1.1",
+      "kind": "cli",
+      "summary": "Daemon local que faz o Claude Code e o Codex respeitarem os padrões de cada cliente: confere cada ação do agente (hooks) contra as regras do cliente da pasta e recusa antes de gravar, em cerca de 1 ms, com o motivo e o que usar no lugar.",
+      "pagesUrl": "https://allansantos-dv.github.io/harness-padroes-cliente/",
+      "home": "~/.client-harness",
+      "install": {
+        "type": "github-release",
+        "repo": "AllanSantos-DV/engine-registry",
+        "tag": "client-harness-v{version}",
+        "asset": "client-harness-any.tgz",
+        "checksum": "{asset}.sha256",
+        "extractTo": "runtimes/client-harness",
+        "entry": "runtimes/client-harness/src/cli.mjs",
+        "publicKey": "b3624d289f9e026388ee0b2c1aba0b1e2328b546b607c7f283548e85972052c4",
+        "signatureAlgorithm": "ed25519-sha256-raw",
+        "signatureRequired": true
+      },
+      "platforms": [
+        "any"
+      ],
+      "notes": "kind=cli: o lifecycle entrega o binário e NÃO sobe processo (`client-harness start` sobe o daemon, que os hooks dos agentes consultam; o hook de SessionStart gravado por `client-harness install` o sobe a cada sessão). `extractTo` é aninhado como no neural-link e no skill-engine: o home guarda ESTADO (token, eventos, run/) que sobrevive ao update, e só `runtimes/client-harness` é trocado. Daemon único por máquina e usuário: bind numa porta derivada do usuário (47000-47999, CLIENT_HARNESS_PORT troca), run/daemon.json com porta, pid e shutdownToken. O bloco `runtime` declara só o que o kit usa para trocar a instalação: POST /shutdown?relaunch=1 com x-shutdown-token antes do swap (no Windows o daemon vivo segura a pasta); com relaunch=1 o daemon deixa um runner que sobe o daemon novo depois da troca, então um update não deixa a máquina sem checagem. O motor publica ~/.client-harness/cli.json em toda invocação do CLI sem --data. Artefato cross-platform (Node puro, sem dependências). Código-fonte no repo AllanSantos-DV/harness-padroes-cliente; a release pública mora aqui.",
+      "runtime": {
+        "transport": "http",
+        "runtimeFile": "run/daemon.json",
+        "healthPath": "/health",
+        "shutdownPath": "/shutdown?relaunch=1",
+        "shutdownTokenField": "shutdownToken",
+        "shutdownTokenHeader": "x-shutdown-token"
+      }
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engine-kit",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "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-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",
+    "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",
     "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",