jorgex-stack 1.9.60 → 1.9.62

package/README.md

@@ -48,7 +48,7 @@ For a fresh Engram installation, always consult the current published Stack and
 pnpm --config.dlx-cache-max-age=0 dlx jorgex-stack@latest install --engram
 ```
 
-`dlx-cache-max-age` is separate from the pnpm 11 dependency-age filter: it controls only the cached `dlx` package, while `minimumReleaseAgeExclude` applies only to the named package resolution. An explicit Stack version such as `@1.9.30` does not reuse the cache entry for another version. Do not use `@latest` for Pi; Pi consumption still requires its exact validated pin.
+`dlx-cache-max-age` is separate from the pnpm 11 dependency-age filter: it controls only the cached `dlx` package, while `minimumReleaseAgeExclude` applies only to the named package resolution. An explicit Stack version such as `@1.9.30` does not reuse the cache entry for another version. Pi `install`/`update` resolve the registry's observed published `latest` dist-tag to an exact version and verify the artifact before activation; they do not install a floating `latest` alias.
 
 Other important commands:
 
@@ -114,9 +114,9 @@ Programmatic mode does **not** provide:
 
 ### Pi runtime
 
-El canon de Stack y el paquete Pi adoptado mantienen una snapshot de 17 árboles de skills con 89 archivos de skill. La identidad, procedencia e integridad del paquete adoptado son autoritativas en `src/lib/pi-runtime-pin.json`.
+El canon de Stack y el paquete Pi mantienen una snapshot de 17 árboles de skills con 89 archivos de skill. Para instalaciones deliberadas, Stack resuelve la versión publicada observada en npm y verifica el tarball y el stage; `src/lib/pi-runtime-pin.json` y el historial conservan identidades congeladas, no un selector para futuras instalaciones.
 
-Pi combines the frozen **snapshot v2** package with a Stack-owned shared projection. The current pin is the published `jorgex-pi@0.8.28` artifact. Package identity, integrity and lifecycle are maintained in [docs/references/pi-runtime.md](docs/references/pi-runtime.md) and `src/lib/pi-runtime-pin.json`; this README does not duplicate mutable pin metadata.
+Pi combines the **snapshot v2** package with a Stack-owned shared projection. Package resolution, verification, receipt and recovery behavior are documented in [docs/references/pi-runtime.md](docs/references/pi-runtime.md); historical pins are not a promise that personal Pi installations have migrated.
 
 The following command block is retained as historical reference for that transition:
 
@@ -128,9 +128,11 @@ pnpm dlx jorgex-stack@1.9.7 sync --agents pi
 pnpm dlx jorgex-stack@1.9.7 uninstall --agents pi
 ```
 
-For the current Pi `0.8.28` pin, package identity and runner validation precede projection; the exact pending initialization diagnostic remains provisional until projection and final `sync` complete.
+For a deliberate managed install or update, Stack resolves the live published `latest` tag to an exact release, verifies its canonical tarball URL and SRI/bytes, and prepares it in an isolated stage before activation. The stage locks six dependencies and runs smoke checks; Stack then backs up state and publishes only its owned package entry. Automatic restoration covers activation/verification failures; a later projection or sync failure may need manual recovery from the retained backup. The schema 1 receipt records managed-package evidence for offline verification. `sync`, `models`, `doctor` and `uninstall` do not acquire a new version; they require an authenticated receipt/artifact, with explicit legacy recovery paths where applicable. `update --check` does not download. `--target-dir` neither downloads Pi nor touches the real HOME; with a previously verified candidate/stage injected, it can run isolated smoke/runner code inside the target. Direct Pi installation is separate and does not provide Stack's rollback guarantees.
 
-Stack runs provider-owned `engram setup pi` before Pi package activation on a real managed install. It backs up and verifies Pi's `settings.json`, `mcp.json` and provider-owned `npm` tree, and restores the backup on setup failure; Pi is not activated unless setup and subsequent package lifecycle succeed. The exact artifact and integrity values are authoritative in `src/lib/pi-runtime-pin.json`, while the lifecycle remains authoritative in `src/lib/pi-runtime.ts`. Pi's own package-manager invocation is the narrow runtime exception to the repository's pnpm-only rule; the Stack lifecycle never launches npm directly. A managed install then runs provider setup, `package install → projection install → package sync`. Stack projects shared resources such as the system prompt, canonical skills and `lean-audit`; it does not inject `jorgex:engram-protocol`, project Engram tools, or filter provider tools. The behavioral `engram` role remains part of the Pi contract, while the official provider owns its setup and tools. Pi registers Context7 through an isolated in-memory HTTP bridge during bootstrap; `available` means configuration permits registration and does not imply an HTTP handshake. A conflict preserves the existing MCP file and blocks managed activation. No MCP credentials are written. For the file runtimes, Context7, Playwright and DevTools use independent managed sections. The global Playwright package and Chromium cache are shared by the machine; `--playwright-runtimes` controls which runtime receives the guide. The adopted Pi package implements and tests `playwright-handoff-v1` through `PI_CODING_AGENT_DIR/jorgex-pi/playwright.v1.json`. Package ownership is recorded separately in `~/.jorgex-stack/pi-receipt.json`; projection ownership is recorded in `~/.jorgex-stack/pi-projection-receipt.json`. Package receipts reject manual, duplicate, divergent, partial, corrupt, copied-to-another-scope, or unknown-history state. Projection cleanup requires an exact scope-bound ownership receipt; DevTools conflicts preserve the handoff for review.
+The artifact values in `src/lib/pi-runtime-pin.json` describe frozen historical/reference metadata, not the live install candidate; live artifact URL, version and integrity are resolved from the published registry.
+
+Stack runs provider-owned `engram setup pi` before Pi package activation on a real managed install. It backs up and verifies Pi's `settings.json`, `mcp.json` and provider-owned `npm` tree, and restores the backup on setup failure; Pi is not activated unless setup and subsequent package lifecycle succeed. The runtime lifecycle remains authoritative in `src/lib/pi-runtime.ts`; the exact release evidence belongs to the verified receipt and tarball. Pi's own package-manager invocation is the narrow runtime exception to the repository's pnpm-only rule; the Stack lifecycle never launches npm directly. A managed install then runs provider setup, `package install → projection install → package sync`. Stack projects shared resources such as the system prompt, canonical skills and `lean-audit`; it does not inject `jorgex:engram-protocol`, project Engram tools, or filter provider tools. The behavioral `engram` role remains part of the Pi contract, while the official provider owns its setup and tools. Pi registers Context7 through an isolated in-memory HTTP bridge during bootstrap; `available` means configuration permits registration and does not imply an HTTP handshake. A conflict preserves the existing MCP file and blocks managed activation. No MCP credentials are written. For the file runtimes, Context7, Playwright and DevTools use independent managed sections. The global Playwright package and Chromium cache are shared by the machine; `--playwright-runtimes` controls which runtime receives the guide. The adopted Pi package implements and tests `playwright-handoff-v1` through `PI_CODING_AGENT_DIR/jorgex-pi/playwright.v1.json`. Package ownership is recorded separately in `~/.jorgex-stack/pi-receipt.json`; projection ownership is recorded in `~/.jorgex-stack/pi-projection-receipt.json`. Package receipts reject manual, duplicate, divergent, partial, corrupt, copied-to-another-scope, or unknown-history state. Projection cleanup requires an exact scope-bound ownership receipt; DevTools conflicts preserve the handoff for review.
 
 The static `AGENTS.md` projected by Stack does not include Context7; Pi's native bootstrap adds that section after registering the isolated bridge. Pi never writes, owns or removes MCP files. In Claude Code, Codex and OpenCode, a compatible existing Context7 entry is preserved and removed only with explicit canonical Stack ownership. During package installation only, `initialization-diagnostics-v1` permits the exact pending `doctor` envelope described in [the Pi runtime reference](docs/references/pi-runtime.md); it is provisional and does not make Pi healthy. Projection and final `sync` must still complete, and every other unhealthy or malformed result remains blocked.
 
@@ -158,9 +160,9 @@ Para Codex, Engram 2.0 ignora `CODEX_HOME` y escribe siempre en `$HOME/.codex`;
 
 La política de complementos distingue estrategias `exact` y `provider-managed`. DevTools MCP y Playwright CLI mantienen pins exactos; las integraciones oficiales de Engram son `provider-managed`/rolling, incluido Codex `main`, `pi-mcp-adapter` y el setup oficial de Pi sin pin en Stack. OpenCode 2 queda fuera de alcance y no bloquea esta integración.
 
-Históricamente, Stack `1.9.7` reconocía el receipt exacto de Pi `npm:jorgex-pi@0.8.4`. Usa versiones exactas, nunca `latest`, y no edites receipts o hashes ni borres `HOME`, Engram o la proyección de otro runtime para forzar confianza. El pin y los comandos actuales de transición y rollback están en [docs/references/pi-runtime.md](docs/references/pi-runtime.md).
+Los receipts históricos, incluido `jorgex-pi@0.8.24`, son evidencia para recuperación/migración y no candidatos de instalación nuevos. La selección gestionada resuelve el `latest` publicado a una versión exacta y verifica el artefacto antes de activarlo. No edites receipts o hashes ni borres `HOME`, Engram o la proyección de otro runtime para forzar confianza. La migración y rollback están en [docs/references/pi-runtime.md](docs/references/pi-runtime.md).
 
-Pi puede consumirse inmediatamente después de publicar y verificar el artefacto adoptado. El pin exacto, la procedencia, los SHA-256/SHA-512, el SRI, la compatibilidad y el procedimiento de rollback siguen siendo obligatorios; no uses `latest` ni una versión aproximada.
+Stack gestiona la selección dinámica y verificación de Pi en `install`/`update`; esto no significa que una instalación personal de Pi se haya migrado. La automatización Stack ↔ Pi es snapshot-only. La instalación directa de Pi no incluye la etapa aislada ni el rollback de Stack.
 
 `update --agents pi` only runs the Pi package lifecycle; it does not enter the global Stack updater. `update --check --agents pi` performs a read-only check of the Pi package and local registration metadata through the package runner. It does not compare Stack's projection, run the browser smoke check, or mutate Pi state; use `doctor --agents pi` for the complete package-and-projection diagnosis. Uninstall runs package cleanup, backs up Pi's settings before removal, removes only the exact receipt-owned package after verifying absence, and preserves all companion/user state. Full behavior, failure states and troubleshooting are in [docs/references/pi-runtime.md](docs/references/pi-runtime.md).
 

package/dist/chunk-KGL5VNVZ.js

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+
+// src/lib/pi-release-resolver.ts
+import fs from "fs";
+import path from "path";
+import { createHash, randomBytes, timingSafeEqual } from "crypto";
+var REGISTRY_URL = "https://registry.npmjs.org/jorgex-pi";
+var REGISTRY_HOST = "registry.npmjs.org";
+var ACCEPT = "application/vnd.npm.install-v1+json";
+var MAX_METADATA_BYTES = 4 * 1024 * 1024;
+var FETCH_TIMEOUT_MS = 1e4;
+var STABLE_SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+function fail(message) {
+  throw new Error(`pi-release-resolver: ${message}`);
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function canonicalTarballUrl(version) {
+  return `https://registry.npmjs.org/jorgex-pi/-/jorgex-pi-${version}.tgz`;
+}
+async function readBoundedText(response) {
+  if (response.body === null) fail("missing response body");
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total >= MAX_METADATA_BYTES) {
+        await reader.cancel().catch(() => {
+        });
+        fail("metadata exceeds 4 MiB");
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk))).toString("utf8");
+}
+function assertCanonicalIntegrity(integrity) {
+  if (typeof integrity !== "string" || !integrity.startsWith("sha512-")) {
+    fail("invalid integrity (expected canonical sha512 SRI)");
+  }
+  const b64 = integrity.slice("sha512-".length);
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(b64)) fail("invalid integrity (expected canonical sha512 SRI)");
+  let bytes;
+  try {
+    bytes = Buffer.from(b64, "base64");
+  } catch {
+    fail("invalid integrity (expected canonical sha512 SRI)");
+  }
+  if (bytes.length !== 64 || bytes.toString("base64") !== b64) {
+    fail("invalid integrity (expected canonical sha512 SRI)");
+  }
+}
+async function resolveLatestPiRelease(fetchImpl) {
+  const response = await fetchImpl(REGISTRY_URL, {
+    headers: { Accept: ACCEPT },
+    redirect: "error",
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+  });
+  if (!response.ok) fail(`registry responded ${response.status}`);
+  if (response.url !== REGISTRY_URL) fail(`unexpected response URL ${response.url}`);
+  const lengthHeader = response.headers.get("content-length");
+  if (lengthHeader !== null) {
+    const trimmed = lengthHeader.trim();
+    if (!/^\d+$/.test(trimmed)) fail("invalid content-length");
+    if (Number(trimmed) > MAX_METADATA_BYTES) fail("metadata exceeds 4 MiB");
+  }
+  const text = await readBoundedText(response);
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    fail("malformed packument JSON");
+  }
+  if (!isRecord(data) || data["name"] !== "jorgex-pi") fail("malformed packument name");
+  const tags = data["dist-tags"];
+  if (!isRecord(tags) || typeof tags["latest"] !== "string") fail("missing dist-tags.latest");
+  const latest = tags["latest"];
+  if (!STABLE_SEMVER.test(latest)) fail(`unstable or malformed version ${latest}`);
+  const versions = data["versions"];
+  if (!isRecord(versions)) fail("missing versions map");
+  const entry = versions[latest];
+  if (!isRecord(entry)) fail(`missing versions[${latest}]`);
+  if (entry["name"] !== "jorgex-pi" || entry["version"] !== latest) {
+    fail("version mismatch in versions entry");
+  }
+  if (entry["deprecated"] !== void 0) fail(`version ${latest} is deprecated`);
+  const dist = entry["dist"];
+  if (!isRecord(dist)) fail("missing dist");
+  const { tarball, integrity } = dist;
+  if (typeof tarball !== "string" || typeof integrity !== "string") {
+    fail("missing dist.tarball/integrity");
+  }
+  let parsed;
+  try {
+    parsed = new URL(tarball);
+  } catch {
+    fail("foreign tarball URL");
+  }
+  if (parsed.protocol !== "https:" || parsed.host !== REGISTRY_HOST || tarball !== canonicalTarballUrl(latest)) {
+    fail("foreign tarball URL");
+  }
+  assertCanonicalIntegrity(integrity);
+  return { version: latest, tarballUrl: tarball, integrity };
+}
+var MAX_TARBALL_BYTES = 128 * 1024 * 1024;
+var TARBALL_FETCH_TIMEOUT_MS = 12e4;
+function expectedSha512Digest(integrity) {
+  assertCanonicalIntegrity(integrity);
+  return Buffer.from(integrity.slice("sha512-".length), "base64");
+}
+function assertCanonicalReleaseInput(release) {
+  if (!isRecord(release)) fail("invalid release");
+  const { version, tarballUrl, integrity } = release;
+  if (typeof version !== "string" || !STABLE_SEMVER.test(version)) fail("invalid release version");
+  if (typeof tarballUrl !== "string") fail("foreign tarball URL");
+  let parsed;
+  try {
+    parsed = new URL(tarballUrl);
+  } catch {
+    fail("foreign tarball URL");
+  }
+  if (parsed.protocol !== "https:" || parsed.host !== REGISTRY_HOST || tarballUrl !== canonicalTarballUrl(version)) {
+    fail("foreign tarball URL");
+  }
+  return { tarballUrl, expectedSha512: expectedSha512Digest(integrity) };
+}
+function readExistingArtifact(file) {
+  const stat = fs.statSync(file, { throwIfNoEntry: false });
+  if (stat === void 0) return null;
+  if (!stat.isFile()) fail("destination is not a regular file");
+  let fd;
+  try {
+    fd = fs.openSync(file, "r");
+  } catch {
+    fail("cannot read existing destination");
+  }
+  const sha256 = createHash("sha256");
+  const sha512 = createHash("sha512");
+  const buffer = Buffer.allocUnsafe(1024 * 1024);
+  let bytes = 0;
+  try {
+    for (; ; ) {
+      const read = fs.readSync(fd, buffer, 0, buffer.length, null);
+      if (read === 0) break;
+      bytes += read;
+      if (bytes >= MAX_TARBALL_BYTES) fail("existing destination exceeds tarball bound");
+      sha256.update(buffer.subarray(0, read));
+      sha512.update(buffer.subarray(0, read));
+    }
+  } finally {
+    try {
+      fs.closeSync(fd);
+    } catch {
+    }
+  }
+  return { bytes, sha256: sha256.digest("hex"), sha512: sha512.digest("hex") };
+}
+async function downloadVerifiedPiTarball(release, destination, fetchImpl) {
+  const { tarballUrl, expectedSha512 } = assertCanonicalReleaseInput(release);
+  if (typeof destination !== "string" || destination === "") fail("invalid destination");
+  const existing = readExistingArtifact(destination);
+  if (existing !== null) {
+    const existing512 = Buffer.from(existing.sha512, "hex");
+    if (existing512.length === expectedSha512.length && timingSafeEqual(existing512, expectedSha512)) {
+      return { path: destination, bytes: existing.bytes, sha256: existing.sha256, sha512: existing.sha512 };
+    }
+    fail("destination bytes do not match requested integrity");
+  }
+  let response;
+  try {
+    response = await fetchImpl(tarballUrl, {
+      headers: { accept: "application/octet-stream" },
+      redirect: "error",
+      signal: AbortSignal.timeout(TARBALL_FETCH_TIMEOUT_MS)
+    });
+  } catch (error) {
+    fail(`tarball fetch failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!response.ok) fail(`tarball responded ${response.status}`);
+  if (response.url !== tarballUrl) fail(`unexpected tarball response URL ${response.url}`);
+  const declared = response.headers.get("content-length");
+  if (declared !== null) {
+    const trimmed = declared.trim();
+    if (!/^\d+$/.test(trimmed)) fail("invalid tarball content-length");
+    if (Number(trimmed) > MAX_TARBALL_BYTES) fail("tarball exceeds 128 MiB");
+  }
+  if (response.body === null) fail("missing tarball body");
+  const tempPath = path.join(
+    path.dirname(destination),
+    `jorgex-pi-partial-${process.pid}-${randomBytes(8).toString("hex")}`
+  );
+  let fd;
+  try {
+    fd = fs.openSync(tempPath, "wx", 384);
+  } catch {
+    fail("cannot stage tarball temp");
+  }
+  let fdClosed = false;
+  const closeFd = () => {
+    if (fdClosed) return;
+    fdClosed = true;
+    try {
+      fs.closeSync(fd);
+    } catch {
+    }
+  };
+  const discardStaged = () => {
+    closeFd();
+    try {
+      fs.rmSync(tempPath, { force: true });
+    } catch {
+    }
+  };
+  try {
+    const reader = response.body.getReader();
+    const sha256 = createHash("sha256");
+    const sha512 = createHash("sha512");
+    let bytes = 0;
+    try {
+      for (; ; ) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        bytes += value.byteLength;
+        if (bytes + value.byteLength >= MAX_TARBALL_BYTES) {
+          await reader.cancel().catch(() => {
+          });
+          fail("tarball exceeds 128 MiB");
+        }
+        sha256.update(value);
+        sha512.update(value);
+        let offset = 0;
+        while (offset < value.byteLength) {
+          offset += fs.writeSync(fd, value, offset, value.byteLength - offset);
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    closeFd();
+    const actual512 = sha512.digest();
+    if (!timingSafeEqual(actual512, expectedSha512)) fail("tarball integrity mismatch");
+    try {
+      fs.linkSync(tempPath, destination);
+    } catch {
+      fail("tarball publish raced with existing destination");
+    }
+    try {
+      fs.rmSync(tempPath, { force: true });
+    } catch {
+    }
+    return { path: destination, bytes, sha256: sha256.digest("hex"), sha512: actual512.toString("hex") };
+  } catch (error) {
+    discardStaged();
+    if (error instanceof Error && error.message.startsWith("pi-release-resolver: ")) throw error;
+    fail(`tarball download failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+var PRODUCER_REF_API = "https://api.github.com/repos/jorgehn98/jorgex-pi/git/ref/tags";
+var PRODUCER_ACCEPT = "application/vnd.github+json";
+var SHA40_HEX = /^[0-9a-f]{40}$/;
+function producerTagUrl(version) {
+  return `${PRODUCER_REF_API}/v${version}`;
+}
+async function resolvePiProducerCommit(version, fetchImpl) {
+  if (typeof version !== "string" || !STABLE_SEMVER.test(version)) fail("invalid producer version");
+  const url = producerTagUrl(version);
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      headers: { accept: PRODUCER_ACCEPT },
+      redirect: "error",
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+    });
+  } catch (error) {
+    fail(`producer ref fetch failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!response.ok) fail(`producer ref responded ${response.status}`);
+  if (response.url !== url) fail(`unexpected producer ref response URL ${response.url}`);
+  const text = await readBoundedText(response);
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    fail("malformed producer ref JSON");
+  }
+  if (!isRecord(data) || data["ref"] !== `refs/tags/v${version}`) fail("producer ref mismatch");
+  const object = data["object"];
+  if (!isRecord(object) || object["type"] !== "commit") fail("producer ref is not a lightweight tag commit");
+  const sha = object["sha"];
+  if (typeof sha !== "string" || !SHA40_HEX.test(sha)) fail("invalid producer commit sha");
+  return sha;
+}
+
+export {
+  resolveLatestPiRelease,
+  downloadVerifiedPiTarball,
+  resolvePiProducerCommit
+};