@vera-ai/cli 1.4.2 → 2.0.0

package/README.md

@@ -2,9 +2,9 @@
 
 Code search for AI agents. Vera indexes your codebase using tree-sitter parsing and hybrid search (BM25 + vector similarity + optional cross-encoder reranking), then returns ranked code snippets as Markdown codeblocks by default, or JSON with `--json`.
 
-This package downloads and wraps the native Vera binary for your platform. On musl-based Linux (Alpine, NixOS), the correct static binary is selected automatically. Set `VERA_TARGET` to override target detection (e.g., `VERA_TARGET=x86_64-unknown-linux-musl npm install -g @vera-ai/cli`).
+This package downloads and wraps the native Vera binary for your platform. It downloads the exact package version, checks the release archive size and SHA-256, and stores a completed binary cache. Later runs use that cache without network access. Older caches are downloaded and verified once before they can be reused offline. On Linux without glibc (such as Alpine or NixOS), the wrapper selects the musl binary. Other native targets use their platform system libraries; optional ONNX backends have additional runtime requirements. Set `VERA_TARGET` to override target detection (e.g., `VERA_TARGET=x86_64-unknown-linux-musl npm install -g @vera-ai/cli`).
 
-The default local embedding model is `minishlab/potion-code-16M-v2`; it runs locally on CPU on any supported machine, no GPU or ONNX Runtime needed. In the current Semble comparison, Vera v1.4.0 scored `0.8437` nDCG@10 versus Semble 0.5.5 at `0.8514` on Semble's own tuning corpus, and leads on the independent contamination set (`0.7674` vs `0.7655`) and on recall@5; Vera's index is 6.8x smaller (4.7 GB vs 32 GB). For the highest measured search quality, use the Qwen preset through OpenRouter. Full details live in the main repo docs.
+The default local embedding model, `minishlab/potion-code-16M-v2`, runs on CPU and works offline after its first download. API mode is also available; Qwen/OpenRouter is recommended among API presets (paid usage). The [benchmark report](https://github.com/VeraTools/Vera/blob/master/docs/benchmarks.md) separates the full 1,251-task suite from smaller screening subsets, and the [agent benchmark](https://github.com/VeraTools/Vera/blob/master/docs/benchmarks-history.md#agent-level-benchmark) records context measurements and their sample limits.
 
 ## Install
 
@@ -19,9 +19,9 @@ vera setup --potion-code --index .
 vera search "authentication logic"
 ```
 
-`vera setup` with no flags runs an interactive wizard and offers to index the current project, defaulting to yes. An interactive search also offers to create a missing index. `vera setup --api` prompts for an OpenAI-compatible endpoint and key; the wizard offers presets for OpenAI, Jina, Voyage, and Qwen via OpenRouter, with the Qwen preset needing only one shared key (`qwen/qwen3-embedding-8b` + `qwen/qwen3-reranker-8b` via `https://openrouter.ai/api/v1`). Use `--yes` with `EMBEDDING_MODEL_*` variables for non-interactive setup.
+`vera setup` runs the full wizard: configure a backend, optionally install agent skills, and optionally index. Local CPU is first and selected by default; API mode is second. Indexing defaults to Yes for local backends and No for API mode. `vera setup --api` uses the shorter API configuration flow, with Qwen/OpenRouter first and recommended (one shared key). See the [models guide](https://github.com/VeraTools/Vera/blob/master/docs/models.md#api-mode) for other providers and non-interactive setup.
 
-The preferred agent integration is the CLI plus the Vera skill: `vera agent install` installs it for supported coding agents and can add a short usage snippet to your project's `AGENTS.md`, `CLAUDE.md`, `COPILOT.md`, or editor rules file. Vera also ships an optional MCP server (`vera mcp`); see the [MCP guide](https://github.com/VeraTools/Vera/blob/master/docs/mcp.md) if your client is MCP-first.
+The preferred agent integration is the CLI plus the Vera skill: `vera agent install` installs it for supported coding agents and can add a short usage snippet to your project's `AGENTS.md`, `CLAUDE.md`, `COPILOT.md`, or editor rules file. The client selector uses Space to toggle and Enter to continue. Empty selection changes nothing; unselected installations remain intact. Vera also ships an optional MCP server (`vera mcp`); see the [MCP guide](https://github.com/VeraTools/Vera/blob/master/docs/mcp.md) if your client is MCP-first.
 
 ## Common Tasks
 

package/bin/vera.js

@@ -9,12 +9,21 @@ const http = require("node:http");
 const https = require("node:https");
 const os = require("node:os");
 const path = require("node:path");
-const { spawnSync } = require("node:child_process");
+const { spawn, spawnSync } = require("node:child_process");
+const { pipeline } = require("node:stream/promises");
+const { Transform } = require("node:stream");
+const zlib = require("node:zlib");
 
 const { version: packageVersion } = require("../package.json");
 
 const DEFAULT_REPO = "VeraTools/Vera";
 const MAX_REDIRECTS = 5;
+const REQUEST_TIMEOUT = 30_000;
+const DOWNLOAD_TIMEOUT = 180_000;
+const MAX_MANIFEST_BYTES = 1024 * 1024;
+const MAX_ARCHIVE_BYTES = 512 * 1024 * 1024;
+const MAX_BINARY_BYTES = 512 * 1024 * 1024;
+const VERSION_PATTERN = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[A-Za-z0-9.-]+)?$/;
 
 function parseArgs(argv) {
   if (argv.length === 0) {
@@ -26,20 +35,16 @@ function parseArgs(argv) {
 
 function detectMusl() {
   if (process.platform !== "linux") return false;
+  const result = spawnSync("ldd", ["--version"], {
+    stdio: ["pipe", "pipe", "pipe"], timeout: 5000,
+  });
+  const output = (result.stdout || "").toString() + (result.stderr || "").toString();
+  if (/musl/i.test(output)) return true;
+  if (!result.error && /glibc|GNU libc/i.test(output)) return false;
   try {
-    const result = spawnSync("ldd", ["--version"], {
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-    const output = (result.stdout || "").toString() + (result.stderr || "").toString();
-    return /musl/i.test(output);
+    return fs.readdirSync("/lib").some((entry) => entry.startsWith("ld-musl-"));
   } catch {
-    // Fallback: check for musl dynamic linker.
-    try {
-      const entries = fs.readdirSync("/lib");
-      return entries.some((e) => e.startsWith("ld-musl-"));
-    } catch {
-      return false;
-    }
+    return false;
   }
 }
 
@@ -78,10 +83,6 @@ function manifestUrl(version) {
   return `${defaultReleaseBaseUrl()}/releases/download/v${version}/release-manifest.json`;
 }
 
-function latestManifestUrl() {
-  return `${defaultReleaseBaseUrl()}/releases/latest/download/release-manifest.json`;
-}
-
 function defaultVeraHome() {
   return process.env.VERA_HOME || path.join(os.homedir(), ".vera");
 }
@@ -102,7 +103,8 @@ function currentInstallMethod() {
 async function readInstallMetadata() {
   try {
     const raw = await fsp.readFile(installMetadataPath(), "utf8");
-    return JSON.parse(raw);
+    const value = JSON.parse(raw);
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
   } catch {
     return {};
   }
@@ -117,6 +119,8 @@ async function writeInstallMetadata({ installMethod, version, binaryPath, target
     version: version ?? current.version ?? null,
     binary_path: binaryPath ?? current.binary_path ?? null,
     target: target ?? current.target ?? null,
+    manifest_url: process.env.VERA_MANIFEST_URL || null,
+    requested_version: packageVersion,
   };
   const tmpPath = `${metadataPath}.tmp.${process.pid}`;
   await fsp.writeFile(tmpPath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
@@ -164,71 +168,70 @@ function shimName() {
   return process.platform === "win32" ? "vera.cmd" : "vera";
 }
 
-async function fetchText(url, redirects = 0) {
-  const client = url.startsWith("https://") ? https : http;
+function openResponse(url, timeout = REQUEST_TIMEOUT, redirects = 0, deadline = Date.now() + timeout) {
+  const parsed = new URL(url);
+  if (!["http:", "https:"].includes(parsed.protocol)) {
+    throw new Error("release downloads require an HTTP or HTTPS URL");
+  }
   return new Promise((resolve, reject) => {
-    const request = client.get(url, (response) => {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return reject(new Error("release download timed out"));
+    const client = parsed.protocol === "https:" ? https : http;
+    const request = client.get(parsed, (response) => {
       const status = response.statusCode || 0;
       if ([301, 302, 303, 307, 308].includes(status) && response.headers.location) {
         if (redirects >= MAX_REDIRECTS) {
-          reject(new Error(`too many redirects fetching ${url}`));
-          return;
+          reject(new Error("too many release redirects"));
+        } else {
+          resolve(Promise.resolve().then(() => openResponse(new URL(response.headers.location, parsed).toString(), timeout, redirects + 1, deadline)));
         }
-
-        const nextUrl = new URL(response.headers.location, url).toString();
-        resolve(fetchText(nextUrl, redirects + 1));
+        response.destroy();
         return;
       }
-
       if (status < 200 || status >= 300) {
+        response.destroy();
         reject(new Error(`request failed for ${url}: ${status}`));
         return;
       }
-
-      let body = "";
-      response.setEncoding("utf8");
-      response.on("data", (chunk) => {
-        body += chunk;
-      });
-      response.on("end", () => resolve(body));
+      resolve(response);
     });
-
+    const timer = setTimeout(() => request.destroy(new Error("release download timed out")), remaining);
+    request.on("close", () => clearTimeout(timer));
     request.on("error", reject);
   });
 }
 
-async function downloadFile(url, destination, redirects = 0) {
-  const client = url.startsWith("https://") ? https : http;
-  await fsp.mkdir(path.dirname(destination), { recursive: true });
-
-  return new Promise((resolve, reject) => {
-    const request = client.get(url, (response) => {
-      const status = response.statusCode || 0;
-      if ([301, 302, 303, 307, 308].includes(status) && response.headers.location) {
-        if (redirects >= MAX_REDIRECTS) {
-          reject(new Error(`too many redirects downloading ${url}`));
-          return;
-        }
-
-        const nextUrl = new URL(response.headers.location, url).toString();
-        response.resume();
-        resolve(downloadFile(nextUrl, destination, redirects + 1));
-        return;
-      }
-
-      if (status < 200 || status >= 300) {
-        reject(new Error(`download failed for ${url}: ${status}`));
-        return;
-      }
+async function fetchText(url, timeout = REQUEST_TIMEOUT) {
+  const response = await openResponse(url, timeout);
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of response) {
+    size += chunk.length;
+    if (size > MAX_MANIFEST_BYTES) {
+      response.destroy();
+      throw new Error("release manifest exceeds its size limit");
+    }
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
 
-      const file = fs.createWriteStream(destination);
-      response.pipe(file);
-      file.on("finish", () => file.close(resolve));
-      file.on("error", reject);
+async function downloadFile(url, destination, expectedSize, timeout = DOWNLOAD_TIMEOUT) {
+  let size = 0;
+  try {
+    const response = await openResponse(url, timeout);
+    const bound = new Transform({
+      transform(chunk, encoding, callback) {
+        size += chunk.length;
+        callback(size > expectedSize ? new Error("release archive exceeds its size limit") : null, chunk);
+      },
     });
-
-    request.on("error", reject);
-  });
+    await pipeline(response, bound, fs.createWriteStream(destination, { flags: "wx" }));
+    if (size !== expectedSize) throw new Error("release archive size mismatch");
+  } catch (error) {
+    await fsp.rm(destination, { force: true });
+    throw error;
+  }
 }
 
 async function sha256(filePath) {
@@ -242,50 +245,147 @@ async function sha256(filePath) {
   });
 }
 
-function runChecked(command, args) {
-  const result = spawnSync(command, args, { stdio: "inherit" });
-  if (result.error) {
-    throw result.error;
-  }
-
-  if (result.status !== 0) {
-    throw new Error(`${command} exited with status ${result.status}`);
-  }
+function safeMember(name) {
+  return name && !name.startsWith("/") && !/[\\:\x00]/.test(name) &&
+    name.replace(/\/$/, "").split("/").every((part) => part && part !== "." && part !== "..");
 }
 
-async function extractArchive(archivePath, destination) {
-  await fsp.mkdir(destination, { recursive: true });
+async function extractArchive(archivePath, destination, target) {
+  const expected = `vera-${target}/${binaryName()}`;
   if (archivePath.endsWith(".zip")) {
-    runChecked("powershell", [
-      "-NoProfile",
-      "-Command",
-      "Import-Module Microsoft.PowerShell.Archive; Expand-Archive",
-      "-LiteralPath",
-      archivePath,
-      "-DestinationPath",
-      destination,
-      "-Force",
-    ]);
+    // .NET reads only the selected entry; archive paths never become filesystem paths.
+    const script = `
+      $ErrorActionPreference = 'Stop'
+      Add-Type -AssemblyName System.IO.Compression.FileSystem
+      $archive = [System.IO.Compression.ZipFile]::OpenRead($env:VERA_INSTALL_ARCHIVE)
+      try {
+        $matches = @()
+        $total = 0
+        $names = @{}
+        if ($archive.Entries.Count -gt 1024) { throw 'Too many release archive members' }
+        foreach ($entry in $archive.Entries) {
+          $name = $entry.FullName
+          $type = ($entry.ExternalAttributes -shr 16) -band 61440
+          $parts = $name.TrimEnd('/').Split('/')
+          if ($names.ContainsKey($name) -or !$name -or $name.StartsWith('/') -or $name.Contains('\\') -or $name.Contains(':') -or
+              ($parts | Where-Object { $_ -eq '..' -or $_ -eq '.' -or $_ -eq '' }) -or
+              ($type -ne 0 -and $type -ne 32768 -and $type -ne 16384)) { throw 'Unsafe release archive member' }
+          $names[$name] = $true
+          $total += $entry.Length
+          if ($total -gt ${MAX_BINARY_BYTES}) { throw 'Release archive exceeds its size limit' }
+          if ($name -ceq $env:VERA_INSTALL_MEMBER) {
+            if ($type -eq 16384) { throw 'Release binary must be a regular file' }
+            $matches += $entry
+          }
+        }
+        if ($matches.Count -ne 1 -or $matches[0].Length -le 0) { throw 'Release archive must contain exactly one Vera binary' }
+        $source = $matches[0].Open()
+        $output = [System.IO.File]::Open($env:VERA_INSTALL_BINARY, [System.IO.FileMode]::CreateNew)
+        try {
+          $buffer = New-Object byte[] 65536
+          $copied = 0
+          while (($count = $source.Read($buffer, 0, $buffer.Length)) -gt 0) {
+            $copied += $count
+            if ($copied -gt $matches[0].Length -or $copied -gt ${MAX_BINARY_BYTES}) { throw 'Release binary exceeds its size limit' }
+            $output.Write($buffer, 0, $count)
+          }
+        } finally { $source.Dispose(); $output.Dispose() }
+        if ((Get-Item -LiteralPath $env:VERA_INSTALL_BINARY).Length -ne $matches[0].Length) { throw 'Incomplete release binary' }
+      } finally { $archive.Dispose() }
+    `;
+    const result = spawnSync("powershell", ["-NoProfile", "-NonInteractive", "-Command", script], {
+      stdio: "inherit", timeout: 30_000,
+      env: { ...process.env, VERA_INSTALL_ARCHIVE: archivePath, VERA_INSTALL_BINARY: destination, VERA_INSTALL_MEMBER: expected },
+    });
+    if (result.error) throw result.error;
+    if (result.status !== 0) throw new Error("release ZIP extraction failed");
     return;
   }
 
-  runChecked("tar", ["-xzf", archivePath, "-C", destination]);
+  const output = await fsp.open(destination, "wx");
+  const input = fs.createReadStream(archivePath);
+  const gunzip = zlib.createGunzip();
+  input.on("error", (error) => gunzip.destroy(error));
+  input.pipe(gunzip);
+  let buffer = Buffer.alloc(0);
+  let remaining = 0;
+  let padding = 0;
+  let selected = false;
+  let matches = 0;
+  let expanded = 0;
+  let members = 0;
+  let ended = false;
+  const names = new Set();
+  try {
+    for await (const chunk of gunzip) {
+      expanded += chunk.length;
+      if (expanded > MAX_BINARY_BYTES + 1024 * 1024) throw new Error("release archive exceeds its size limit");
+      buffer = Buffer.concat([buffer, chunk]);
+      while (buffer.length) {
+        if (remaining || padding) {
+          const count = Math.min(buffer.length, remaining || padding);
+          if (remaining) {
+            if (selected) await output.writeFile(buffer.subarray(0, count));
+            remaining -= count;
+          } else padding -= count;
+          buffer = buffer.subarray(count);
+          continue;
+        }
+        if (buffer.length < 512) break;
+        const header = buffer.subarray(0, 512);
+        buffer = buffer.subarray(512);
+        if (header.every((byte) => byte === 0)) { ended = true; continue; }
+        if (ended || ++members > 1024) throw new Error("invalid release tar archive");
+        const field = (start, length) => header.subarray(start, start + length).toString("utf8").split("\0")[0];
+        const octal = (start, length) => {
+          const value = field(start, length).trim();
+          if (!/^[0-7]+$/.test(value)) throw new Error("invalid release tar header");
+          return parseInt(value, 8);
+        };
+        const checksum = octal(148, 8);
+        const actual = header.reduce((sum, byte, index) => sum + (index >= 148 && index < 156 ? 32 : byte), 0);
+        if (actual !== checksum) throw new Error("invalid release tar checksum");
+        const prefix = field(345, 155);
+        const name = (prefix ? `${prefix}/` : "") + field(0, 100);
+        const type = String.fromCharCode(header[156]);
+        if (names.has(name) || !safeMember(name) || !["0", "\0", "5"].includes(type)) throw new Error("unsafe release archive member");
+        names.add(name);
+        remaining = octal(124, 12);
+        if (remaining > MAX_BINARY_BYTES || (type === "5" && remaining)) throw new Error("invalid release tar size");
+        padding = (512 - remaining % 512) % 512;
+        selected = name === expected && type !== "5";
+        if (selected && (++matches !== 1 || remaining === 0)) throw new Error("release archive must contain exactly one Vera binary");
+      }
+    }
+    if (remaining || padding || buffer.some((byte) => byte !== 0) || !ended || matches !== 1) {
+      throw new Error("incomplete release tar archive or missing Vera binary");
+    }
+  } finally {
+    input.destroy();
+    gunzip.destroy();
+    await output.close();
+  }
 }
 
 async function createShim(binaryPath) {
   const binDir = pickUserBinDir();
   await fsp.mkdir(binDir, { recursive: true });
   const shimPath = path.join(binDir, shimName());
-
-  if (process.platform === "win32") {
-    const contents = `@echo off\r\n"${binaryPath}" %*\r\n`;
-    await fsp.writeFile(shimPath, contents, "utf8");
-  } else {
-    const contents = `#!/bin/sh\nexec "${binaryPath}" "$@"\n`;
-    await fsp.writeFile(shimPath, contents, "utf8");
-    await fsp.chmod(shimPath, 0o755);
+  if (path.join(await fsp.realpath(binDir), shimName()) === await fsp.realpath(binaryPath)) return shimPath;
+  const staging = await fsp.mkdtemp(path.join(binDir, ".vera-shim-"));
+  const stagedShim = path.join(staging, shimName());
+  try {
+    if (process.platform === "win32") {
+      const contents = `@echo off\r\nsetlocal DisableDelayedExpansion\r\n"${binaryPath.replace(/%/g, "%%")}" %*\r\n`;
+      await fsp.writeFile(stagedShim, contents, "utf8");
+    } else {
+      const quoted = "'" + binaryPath.replace(/'/g, "'\"'\"'") + "'";
+      await fsp.writeFile(stagedShim, `#!/bin/sh\nexec ${quoted} "$@"\n`, { mode: 0o755 });
+    }
+    await fsp.rename(stagedShim, shimPath);
+  } finally {
+    await fsp.rm(staging, { recursive: true, force: true });
   }
-
   return shimPath;
 }
 
@@ -294,91 +394,101 @@ function isOnPath(dirPath) {
 }
 
 async function loadManifest() {
-  const primaryUrl = manifestUrl(packageVersion);
+  const manifest = JSON.parse(await fetchText(manifestUrl(packageVersion)));
+  if (!manifest || typeof manifest.version !== "string" || !VERSION_PATTERN.test(manifest.version)) {
+    throw new Error("invalid release version");
+  }
+  if (!process.env.VERA_MANIFEST_URL && manifest.version !== packageVersion) {
+    throw new Error(`requested Vera ${packageVersion}, manifest contains ${manifest.version}`);
+  }
+  return manifest;
+}
+
+async function cachedBinary(target) {
+  let version = packageVersion;
+  if (process.env.VERA_MANIFEST_URL) {
+    const metadata = await readInstallMetadata();
+    if (metadata.manifest_url !== process.env.VERA_MANIFEST_URL || metadata.requested_version !== packageVersion) return null;
+    version = metadata.version;
+    if (typeof version !== "string" || !VERSION_PATTERN.test(version)) return null;
+  }
+  const binaryPath = path.join(defaultVeraHome(), "bin", version, target, binaryName());
   try {
-    const manifestText = await fetchText(primaryUrl);
-    return JSON.parse(manifestText);
-  } catch (error) {
-    if (process.env.VERA_MANIFEST_URL) {
-      throw error;
+    const receipt = JSON.parse(await fsp.readFile(`${binaryPath}.receipt.json`, "utf8"));
+    const stat = await fsp.lstat(binaryPath);
+    if (receipt && stat.isFile() && stat.size > 0 && receipt.version === version && receipt.target === target &&
+        receipt.size === stat.size && receipt.sha256 === await sha256(binaryPath)) {
+      return { binaryPath, version };
     }
+  } catch (error) {
+    if (!["ENOENT", "ENOTDIR"].includes(error.code) && !(error instanceof SyntaxError)) throw error;
+  }
+  return null;
+}
 
-    const fallbackText = await fetchText(latestManifestUrl());
-    return JSON.parse(fallbackText);
+async function finishInstall(binaryPath, version, target, announce = false) {
+  const shimPath = await createShim(binaryPath);
+  if (announce && !isOnPath(path.dirname(shimPath))) {
+    console.error(`Added Vera to ${path.dirname(shimPath)}. Add that directory to PATH to run \`vera\` directly.`);
   }
+  await writeInstallMetadata({ installMethod: currentInstallMethod(), version, binaryPath, target });
+  return { binaryPath, version };
 }
 
 async function ensureBinaryInstalled() {
-  const manifest = await loadManifest();
   const target = resolveTarget(process.platform, process.arch);
+  if (!/^[A-Za-z0-9_-]+$/.test(target)) throw new Error("invalid release target");
+  const cached = await cachedBinary(target);
+  if (cached) return finishInstall(cached.binaryPath, cached.version, target);
+  const manifest = await loadManifest();
   const asset = manifest.assets && manifest.assets[target];
-  if (!asset) {
-    throw new Error(`no release asset for target ${target}`);
+  if (!asset) throw new Error(`no release asset for target ${target}`);
+  const extension = target.endsWith("windows-msvc") ? ".zip" : ".tar.gz";
+  if (asset.archive !== `vera-${target}${extension}` || !Number.isSafeInteger(asset.size) ||
+      asset.size <= 0 || asset.size > MAX_ARCHIVE_BYTES || !/^[0-9a-f]{64}$/.test(asset.sha256)) {
+    throw new Error("invalid release archive metadata");
   }
-
   const version = manifest.version;
   const installDir = path.join(defaultVeraHome(), "bin", version, target);
   const binaryPath = path.join(installDir, binaryName());
-  if (fs.existsSync(binaryPath)) {
-    const stat = await fsp.stat(binaryPath);
-    if (stat.size > 1_000_000) {
-      await createShim(binaryPath);
-      await writeInstallMetadata({
-        installMethod: currentInstallMethod(),
-        version,
-        binaryPath,
-        target,
-      });
-      return { binaryPath, version };
-    }
-    // Stale or broken file (e.g. leftover shim from interrupted install).
-    await fsp.rm(binaryPath);
-  }
-
-  const tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), "vera-install-"));
+  await fsp.mkdir(installDir, { recursive: true });
+  const tempRoot = await fsp.mkdtemp(path.join(installDir, ".install-"));
   try {
     const archivePath = path.join(tempRoot, asset.archive);
-    const extractDir = path.join(tempRoot, "extract");
-
+    const stagedBinary = path.join(tempRoot, binaryName());
     console.error(`Downloading Vera ${version} for ${target}...`);
-    await downloadFile(asset.download_url, archivePath);
-
-    const actualSha = await sha256(archivePath);
-    if (actualSha !== asset.sha256) {
-      throw new Error(`checksum mismatch for ${asset.archive}`);
-    }
-
-    await extractArchive(archivePath, extractDir);
-    const extractedBinary = path.join(extractDir, `vera-${target}`, binaryName());
-    await fsp.mkdir(installDir, { recursive: true });
-    await fsp.copyFile(extractedBinary, binaryPath);
-    if (process.platform !== "win32") {
-      await fsp.chmod(binaryPath, 0o755);
-    }
-
-    const shimPath = await createShim(binaryPath);
-    if (!isOnPath(path.dirname(shimPath))) {
-      console.error(`Added Vera to ${path.dirname(shimPath)}. Add that directory to PATH to run \`vera\` directly.`);
-    }
-
-    await writeInstallMetadata({
-      installMethod: currentInstallMethod(),
-      version,
-      binaryPath,
-      target,
-    });
-    return { binaryPath, version };
+    await downloadFile(asset.download_url, archivePath, asset.size);
+    if (await sha256(archivePath) !== asset.sha256) throw new Error(`checksum mismatch for ${asset.archive}`);
+    await extractArchive(archivePath, stagedBinary, target);
+    if (process.platform !== "win32") await fsp.chmod(stagedBinary, 0o755);
+    const stat = await fsp.stat(stagedBinary);
+    if (!stat.isFile() || stat.size <= 0 || stat.size > MAX_BINARY_BYTES) throw new Error("invalid release binary");
+    const receiptPath = path.join(tempRoot, "receipt.json");
+    await fsp.writeFile(receiptPath, JSON.stringify({ version, target, size: stat.size, sha256: await sha256(stagedBinary) }));
+    await fsp.rename(stagedBinary, binaryPath);
+    await fsp.rename(receiptPath, `${binaryPath}.receipt.json`);
   } finally {
     await fsp.rm(tempRoot, { recursive: true, force: true });
   }
+  return finishInstall(binaryPath, version, target, true);
 }
 
-function runBinary(binaryPath, args) {
-  const result = spawnSync(binaryPath, args, { stdio: "inherit" });
-  if (result.error) {
-    throw result.error;
+async function runBinary(binaryPath, args) {
+  const child = spawn(binaryPath, args, { stdio: "inherit" });
+  const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+  const forward = new Map(signals.map((signal) => [signal, () => child.kill(signal)]));
+  for (const [signal, handler] of forward) process.on(signal, handler);
+  try {
+    const result = await new Promise((resolve, reject) => {
+      child.on("error", reject);
+      child.on("exit", (code, signal) => resolve({ code, signal }));
+    });
+    for (const [signal, handler] of forward) process.removeListener(signal, handler);
+    if (result.signal && process.platform !== "win32") process.kill(process.pid, result.signal);
+    else process.exitCode = result.code ?? 1;
+  } finally {
+    for (const [signal, handler] of forward) process.removeListener(signal, handler);
   }
-  process.exit(result.status ?? 0);
 }
 
 async function main() {
@@ -397,19 +507,23 @@ async function main() {
 
   if (command === "install") {
     console.error(`Vera ${version} installed.`);
-    runBinary(binaryPath, ["agent", "install", ...rest]);
+    await runBinary(binaryPath, ["agent", "install", ...rest]);
     return;
   }
 
   if (command === "help") {
-    runBinary(binaryPath, ["--help"]);
+    await runBinary(binaryPath, ["--help"]);
     return;
   }
 
-  runBinary(binaryPath, [command, ...rest]);
+  await runBinary(binaryPath, [command, ...rest]);
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
 }
 
-main().catch((error) => {
-  console.error(error.message);
-  process.exit(1);
-});
+module.exports = { detectMusl, fetchText, downloadFile, extractArchive, ensureBinaryInstalled, createShim, runBinary };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vera-ai/cli",
-  "version": "1.4.2",
+  "version": "2.0.0",
   "description": "Bootstrap installer and wrapper for the Vera CLI",
   "license": "MIT",
   "homepage": "https://github.com/VeraTools/Vera#readme",