@starkscan/cli 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,56 @@
+# @starkscan/cli
+
+npm/npx launcher for the prebuilt Starkscan CLI.
+
+## Install
+
+```bash
+npm install -g @starkscan/cli@alpha
+starkscan doctor
+```
+
+One-off agent run:
+
+```bash
+npx @starkscan/cli@alpha doctor
+```
+
+The wrapper uses bundled native artifacts when they are present in the published package, verifies downloaded or bundled archives against checksums in the release manifest, rejects malformed archives, caches the native `starkscan` binary, and forwards all arguments to it. It does not require a Rust toolchain or repository access.
+
+MCP client setup uses the same package. `print-config` emits machine-readable
+Codex and Claude Code snippets with environment-variable placeholders, not
+secret values. `start` is the stable alias for serving the remote stdio bridge:
+
+```bash
+npx -y @starkscan/cli@alpha mcp print-config --transport remote
+npx -y @starkscan/cli@alpha mcp start --transport remote
+```
+
+## Environment
+
+```bash
+# Use the URL prefix that directly serves `/v1/...`.
+# Some public hosts may expose the API under `/api`; do not include `/v1`.
+export STARKSCAN_BASE_URL="https://REPLACE_WITH_STARKSCAN_API_HOST"
+export STARKSCAN_API_KEY="mzk_test_your_key_here"
+export STARKSCAN_CHAIN="SN_MAIN"
+```
+
+`STARKSCAN_*` is the public CLI environment contract. The launcher still accepts
+the old internal variable names as hidden compatibility aliases during the beta
+cutover. The CLI sends `X-Starkscan-Api-Key` to the hosted API.
+
+## Release binding
+
+By default, the package resolves to bundled artifacts under `artifacts/v<package-version>` when published with native binaries included. Maintainers can override the release source for tests or emergency rollback:
+
+- `STARKSCAN_CLI_RELEASE_TAG`: release tag, or `latest`
+- `STARKSCAN_CLI_BUNDLED_ARTIFACT_DIR`: maintainer/test override for the bundled artifact root. Use an absolute path in CI, or a cwd-relative path locally, pointing to a root that contains `artifacts/v<release-tag>/starkscan-cli-manifest.json` and matching platform archives. Example: `STARKSCAN_CLI_BUNDLED_ARTIFACT_DIR=/tmp/starkscan-cli-artifacts npx @starkscan/cli@alpha doctor`
+- `STARKSCAN_CLI_RELEASE_BASE_URL`: release base URL, default `https://github.com/starknet-innovation/starkscan/releases`
+- `STARKSCAN_CLI_CACHE_DIR`: cache root for downloaded native binaries
+- `STARKSCAN_CLI_BIN_PATH`: use an existing local `starkscan` binary and skip download
+- `STARKSCAN_CLI_RELEASE_REPO`: GitHub repo path, default `starknet-innovation/starkscan`
+- `STARKSCAN_CLI_PLATFORM_OVERRIDE`: force a specific target platform for cross-platform testing
+- `STARKSCAN_CLI_DOWNLOAD_TIMEOUT_MS`: download inactivity timeout in milliseconds, default `120000`
+
+The package expects release assets produced by `rust-exp/scripts/package-starkscan-cli.sh`: `starkscan-cli-manifest.json`, `starkscan-<platform>.tar.gz`, and matching checksums. Run native packaging and npm packaging from the repository root so `.artifacts/release/cli` is available. Publish the tarball produced by `scripts/package-starkscan-cli-npm.sh` or `scripts/publish-public-cli.sh`; do not publish the package directory directly, because that can omit native artifacts.

package/artifacts/v0.1.0-alpha.0/starkscan-cli-manifest.json

@@ -0,0 +1,34 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-05-28T07:50:25Z",
+  "artifacts": [
+    {
+      "name": "starkscan-darwin-aarch64.tar.gz",
+      "platform": "darwin-aarch64",
+      "target": "darwin-aarch64",
+      "archive": "starkscan-darwin-aarch64.tar.gz",
+      "sha256": "ab12b551feb00ea3680b098dae25345f96fb22a1715c7f576488fd02ee6120e7"
+    },
+    {
+      "name": "starkscan-darwin-x86_64.tar.gz",
+      "platform": "darwin-x86_64",
+      "target": "darwin-x86_64",
+      "archive": "starkscan-darwin-x86_64.tar.gz",
+      "sha256": "d2eb41a1a8c70cfe2ba064fcc018b4c2c34ea7b1d2fc2f61a004ed365d8a43d6"
+    },
+    {
+      "name": "starkscan-linux-aarch64.tar.gz",
+      "platform": "linux-aarch64",
+      "target": "linux-aarch64",
+      "archive": "starkscan-linux-aarch64.tar.gz",
+      "sha256": "18e93c6e3ccbce6d9084607f8f86c729b8cb6a67a65d05e566be8f8ad066e250"
+    },
+    {
+      "name": "starkscan-linux-x86_64.tar.gz",
+      "platform": "linux-x86_64",
+      "target": "linux-x86_64",
+      "archive": "starkscan-linux-x86_64.tar.gz",
+      "sha256": "1a97868b0096dc491c0b6b2f7b41e5056d9581c4117010f25ae769ee9e14bd03"
+    }
+  ]
+}

package/artifacts/v0.1.0-alpha.0/starkscan-darwin-aarch64.tar.gz.sha256

@@ -0,0 +1 @@
+ab12b551feb00ea3680b098dae25345f96fb22a1715c7f576488fd02ee6120e7  starkscan-darwin-aarch64.tar.gz

package/artifacts/v0.1.0-alpha.0/starkscan-darwin-x86_64.tar.gz.sha256

@@ -0,0 +1 @@
+d2eb41a1a8c70cfe2ba064fcc018b4c2c34ea7b1d2fc2f61a004ed365d8a43d6  starkscan-darwin-x86_64.tar.gz

package/artifacts/v0.1.0-alpha.0/starkscan-linux-aarch64.tar.gz.sha256

@@ -0,0 +1 @@
+18e93c6e3ccbce6d9084607f8f86c729b8cb6a67a65d05e566be8f8ad066e250  starkscan-linux-aarch64.tar.gz

package/artifacts/v0.1.0-alpha.0/starkscan-linux-x86_64.tar.gz.sha256

@@ -0,0 +1 @@
+1a97868b0096dc491c0b6b2f7b41e5056d9581c4117010f25ae769ee9e14bd03  starkscan-linux-x86_64.tar.gz

package/bin/starkscan.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { constants as osConstants } from 'node:os';
+
+import { ensureStarkscanBinary } from '../scripts/installer.mjs';
+
+function exitFromResult(result) {
+  if (result.error) {
+    console.error(`starkscan: failed to launch binary: ${result.error.message}`);
+    process.exit(1);
+  }
+  if (result.signal) {
+    console.error(`starkscan: binary terminated by signal ${result.signal}`);
+    const signalCode = osConstants.signals[result.signal];
+    try {
+      process.kill(process.pid, result.signal);
+    } catch {
+      process.exit(signalCode ? 128 + signalCode : 1);
+    }
+    setTimeout(() => process.exit(signalCode ? 128 + signalCode : 1), 1000);
+    return;
+  }
+  process.exit(result.status ?? 1);
+}
+
+try {
+  const binaryPath = await ensureStarkscanBinary();
+  const result = spawnSync(binaryPath, process.argv.slice(2), {
+    stdio: 'inherit',
+  });
+  exitFromResult(result);
+} catch (error) {
+  console.error(`starkscan: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@starkscan/cli",
+  "private": false,
+  "version": "0.1.0-alpha.0",
+  "description": "npm/npx launcher for the prebuilt Starkscan explorer CLI.",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/starknet-innovation/mezcal.git",
+    "directory": "webapp/packages/cli"
+  },
+  "homepage": "https://github.com/starknet-innovation/mezcal/tree/main/webapp/packages/cli",
+  "keywords": [
+    "starkscan",
+    "starknet",
+    "explorer",
+    "cli",
+    "agent"
+  ],
+  "files": [
+    "artifacts",
+    "bin",
+    "scripts/install.mjs",
+    "scripts/installer.mjs",
+    "scripts/verify-bundled-artifacts.mjs",
+    "README.md"
+  ],
+  "bin": {
+    "starkscan": "./bin/starkscan.js"
+  },
+  "scripts": {
+    "install:binary": "node ./scripts/install.mjs",
+    "prepack": "npm run verify:bundled && npm run typecheck && npm test",
+    "prepublishOnly": "npm run verify:bundled && npm run typecheck && npm test",
+    "publish:alpha:dry-run": "./scripts/publish-public-cli.sh --tag alpha --dry-run",
+    "test": "node ./scripts/tests/cli-wrapper.mjs && ./scripts/tests/publish-public-cli.sh",
+    "typecheck": "node --check ./bin/starkscan.js && node --check ./scripts/install.mjs && node --check ./scripts/installer.mjs && node --check ./scripts/verify-bundled-artifacts.mjs && node --check ./scripts/tests/cli-wrapper.mjs",
+    "verify:bundled": "node ./scripts/verify-bundled-artifacts.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/install.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { ensureStarkscanBinary } from './installer.mjs';
+
+function usage() {
+  console.log(`Usage: node scripts/install.mjs [--force] [--print-path]\n\nDownloads and verifies the prebuilt Starkscan CLI release artifact for this platform.`);
+}
+
+let force = false;
+let printPath = false;
+for (const arg of process.argv.slice(2)) {
+  if (arg === '--force') {
+    force = true;
+  } else if (arg === '--print-path') {
+    printPath = true;
+  } else if (arg === '--help' || arg === '-h') {
+    usage();
+    process.exit(0);
+  } else {
+    console.error(`unknown argument: ${arg}`);
+    usage();
+    process.exit(2);
+  }
+}
+
+try {
+  const binaryPath = await ensureStarkscanBinary({ force });
+  if (printPath) {
+    console.log(binaryPath);
+  }
+} catch (error) {
+  console.error(`install-starkscan-cli: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+}

package/scripts/installer.mjs

@@ -0,0 +1,471 @@
+import { spawnSync } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { copyFile, chmod, lstat, mkdir, mkdtemp, readFile, rename, rm } from 'node:fs/promises';
+import { get as httpGet } from 'node:http';
+import { get as httpsGet } from 'node:https';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PACKAGE_JSON_PATH = path.join(PACKAGE_ROOT, 'package.json');
+const DEFAULT_BUNDLED_ARTIFACT_ROOT = path.join(PACKAGE_ROOT, 'artifacts');
+const DEFAULT_REPO = 'starknet-innovation/starkscan';
+const DEFAULT_DOWNLOAD_TIMEOUT_MS = 120_000;
+const MAX_REDIRECTS = 10;
+const RELEASE_TAG_RE = /^(?=.*[A-Za-z0-9])(?!-)(?!.*\.\.)[A-Za-z0-9._-]+$/;
+const SUPPORTED_PLATFORMS = new Set([
+  'darwin-aarch64',
+  'darwin-x86_64',
+  'linux-aarch64',
+  'linux-x86_64',
+]);
+const PUBLIC_BINARY_NAME = 'starkscan';
+const LEGACY_BINARY_NAME = 'mezcal';
+const PUBLIC_MANIFEST_FILENAME = 'starkscan-cli-manifest.json';
+const LEGACY_MANIFEST_FILENAME = 'mezcal-cli-manifest.json';
+
+function env(name) {
+  const value = process.env[name]?.trim();
+  return value && value.length > 0 ? value : undefined;
+}
+
+function envFirst(primaryName, legacyName) {
+  return env(primaryName) ?? env(legacyName);
+}
+
+function cliEnv(suffix) {
+  return envFirst(`STARKSCAN_CLI_${suffix}`, `MEZCAL_CLI_${suffix}`);
+}
+
+function fail(message) {
+  throw new Error(message);
+}
+
+async function packageVersion() {
+  const raw = await readFile(PACKAGE_JSON_PATH, 'utf8');
+  const parsed = JSON.parse(raw);
+  if (typeof parsed.version !== 'string' || parsed.version.length === 0) {
+    fail('package.json version is missing');
+  }
+  return parsed.version;
+}
+
+export function resolvePlatform() {
+  const override = cliEnv('PLATFORM_OVERRIDE');
+  if (override) {
+    if (!SUPPORTED_PLATFORMS.has(override)) {
+      fail(`unsupported STARKSCAN_CLI_PLATFORM_OVERRIDE: ${override}`);
+    }
+    return override;
+  }
+
+  const osName = os.platform();
+  const archName = os.arch();
+  let osPart;
+  let archPart;
+
+  if (osName === 'darwin') {
+    osPart = 'darwin';
+  } else if (osName === 'linux') {
+    osPart = 'linux';
+  } else {
+    fail(`unsupported operating system: ${osName}`);
+  }
+
+  if (archName === 'x64') {
+    archPart = 'x86_64';
+  } else if (archName === 'arm64') {
+    archPart = 'aarch64';
+  } else {
+    fail(`unsupported architecture: ${archName}`);
+  }
+
+  return `${osPart}-${archPart}`;
+}
+
+function defaultCacheRoot() {
+  const configured = cliEnv('CACHE_DIR');
+  if (configured) {
+    return configured;
+  }
+
+  if (process.platform === 'darwin') {
+    const home = env('HOME');
+    if (!home) {
+      fail('HOME is required when STARKSCAN_CLI_CACHE_DIR is not set');
+    }
+    return path.join(home, 'Library', 'Caches', 'starkscan', 'cli');
+  }
+
+  const xdgCache = env('XDG_CACHE_HOME');
+  if (xdgCache) {
+    return path.join(xdgCache, 'starkscan', 'cli');
+  }
+
+  const home = env('HOME');
+  if (!home) {
+    fail('HOME is required when STARKSCAN_CLI_CACHE_DIR is not set');
+  }
+  return path.join(home, '.cache', 'starkscan', 'cli');
+}
+
+async function validateExecutableFile(binaryPath, label) {
+  const stat = await lstat(binaryPath).catch(() => null);
+  if (!stat) {
+    fail(`${label} not found: ${binaryPath}`);
+  }
+  if (stat.isSymbolicLink()) {
+    fail(`${label} must not be a symlink: ${binaryPath}`);
+  }
+  if (!stat.isFile()) {
+    fail(`${label} must be a file: ${binaryPath}`);
+  }
+  if ((stat.mode & 0o111) === 0) {
+    fail(`${label} is not executable: ${binaryPath}`);
+  }
+}
+
+function runChecked(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    encoding: 'utf8',
+    ...options,
+  });
+  if (result.error) {
+    fail(`${command} failed: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const stderr = result.stderr?.trim();
+    fail(stderr ? `${command} failed: ${stderr}` : `${command} failed with exit ${result.status}`);
+  }
+  return result;
+}
+
+async function sha256File(filePath) {
+  return await new Promise((resolve, reject) => {
+    const hash = createHash('sha256');
+    const input = createReadStream(filePath);
+    input.on('error', reject);
+    input.on('data', (chunk) => hash.update(chunk));
+    input.on('end', () => resolve(hash.digest('hex')));
+  });
+}
+
+export function resolveDownloadTimeoutMs() {
+  const configured = cliEnv('DOWNLOAD_TIMEOUT_MS');
+  if (!configured) {
+    return DEFAULT_DOWNLOAD_TIMEOUT_MS;
+  }
+  if (!/^[0-9]+$/.test(configured)) {
+    fail(`STARKSCAN_CLI_DOWNLOAD_TIMEOUT_MS must be a positive integer: ${configured}`);
+  }
+  const timeoutMs = Number(configured);
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1_000) {
+    fail('STARKSCAN_CLI_DOWNLOAD_TIMEOUT_MS must be at least 1000');
+  }
+  return timeoutMs;
+}
+
+function releaseTagFromVersion(version) {
+  return version.startsWith('v') ? version : `v${version}`;
+}
+
+async function resolveReleaseTag() {
+  const tag = cliEnv('RELEASE_TAG') ?? env('MEZCAL_INSTALL_VERSION') ?? releaseTagFromVersion(await packageVersion());
+  if (tag !== 'latest' && !RELEASE_TAG_RE.test(tag)) {
+    fail(`unsupported release tag: ${tag}`);
+  }
+  return tag;
+}
+
+function releaseRootUrl(baseUrl, releaseTag) {
+  const normalizedBase = baseUrl.replace(/\/+$/, '');
+  if (releaseTag === 'latest') {
+    return `${normalizedBase}/latest/download`;
+  }
+  return `${normalizedBase}/download/${releaseTag}`;
+}
+
+function releaseAssetUrl(rootUrl, filename) {
+  return `${rootUrl}/${filename}`;
+}
+
+function bundledArtifactRoot() {
+  const configured = cliEnv('BUNDLED_ARTIFACT_DIR');
+  if (!configured) {
+    return DEFAULT_BUNDLED_ARTIFACT_ROOT;
+  }
+  return path.resolve(configured);
+}
+
+function bundledArtifactRootUrl(releaseTag) {
+  return pathToFileURL(path.join(bundledArtifactRoot(), releaseTag)).href;
+}
+
+async function hasBundledArtifacts(releaseTag) {
+  for (const manifestFilename of [PUBLIC_MANIFEST_FILENAME, LEGACY_MANIFEST_FILENAME]) {
+    const manifestPath = path.join(bundledArtifactRoot(), releaseTag, manifestFilename);
+    const stat = await lstat(manifestPath).catch(() => null);
+    if (stat?.isFile()) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function resolveRedirectUrl(url, location, redirectsLeft) {
+  if (redirectsLeft <= 0) {
+    fail(`too many redirects downloading ${url}`);
+  }
+  const currentUrl = new URL(url);
+  const redirectUrl = new URL(location, url);
+  if (redirectUrl.protocol !== 'https:' && redirectUrl.protocol !== 'http:') {
+    fail(`unsupported redirect URL protocol: ${redirectUrl.protocol}`);
+  }
+  if (currentUrl.protocol === 'https:' && redirectUrl.protocol === 'http:') {
+    fail(`redirect from HTTPS to HTTP is not allowed: ${redirectUrl.toString()}`);
+  }
+  return redirectUrl.toString();
+}
+
+async function downloadHttp(url, destination, redirectsLeft = MAX_REDIRECTS) {
+  await new Promise((resolve, reject) => {
+    const currentUrl = new URL(url);
+    const getter = currentUrl.protocol === 'https:' ? httpsGet : httpGet;
+    const timeoutMs = resolveDownloadTimeoutMs();
+    const request = getter(url, (response) => {
+      if (
+        response.statusCode &&
+        response.statusCode >= 300 &&
+        response.statusCode < 400 &&
+        response.headers.location
+      ) {
+        let redirectUrl;
+        try {
+          redirectUrl = resolveRedirectUrl(url, response.headers.location, redirectsLeft);
+        } catch (error) {
+          response.resume();
+          reject(error);
+          return;
+        }
+        response.resume();
+        downloadHttp(redirectUrl, destination, redirectsLeft - 1).then(resolve, reject);
+        return;
+      }
+      if (response.statusCode !== 200) {
+        response.resume();
+        reject(new Error(`download failed for ${url}: HTTP ${response.statusCode}`));
+        return;
+      }
+
+      const output = createWriteStream(destination, { flags: 'wx' });
+      output.on('error', reject);
+      output.on('finish', resolve);
+      response.pipe(output);
+    });
+    request.setTimeout(timeoutMs, () => {
+      request.destroy(new Error(`download timed out after ${timeoutMs}ms: ${url}`));
+    });
+    request.on('error', reject);
+  });
+}
+
+async function downloadFile(url, destination) {
+  const parsed = new URL(url);
+  if (parsed.protocol === 'file:') {
+    await copyFile(fileURLToPath(parsed), destination);
+    return;
+  }
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    fail(`unsupported download URL protocol: ${parsed.protocol}`);
+  }
+  await downloadHttp(url, destination);
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isMissingManifestDownload(error) {
+  if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+    return true;
+  }
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  return error.message.includes('HTTP 404') || error.message.includes('ENOENT');
+}
+
+async function readDownloadedManifest(manifestPath, manifestFilename) {
+  try {
+    const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+    if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+      fail('release manifest root must be an object');
+    }
+    if (manifest.schemaVersion !== 1) {
+      fail('release manifest schemaVersion must be 1');
+    }
+    if (!Array.isArray(manifest.artifacts)) {
+      fail('release manifest artifacts must be an array');
+    }
+    return manifest;
+  } catch (error) {
+    fail(`release manifest ${manifestFilename} is invalid: ${errorMessage(error)}`);
+  }
+}
+
+function validateArtifact(artifact, platform) {
+  if (!artifact || typeof artifact !== 'object' || Array.isArray(artifact)) {
+    fail('release manifest artifact entries must be objects');
+  }
+  if (artifact.platform !== platform) {
+    fail(`release manifest selected wrong platform: ${artifact.platform}`);
+  }
+  const acceptedArchives = [`starkscan-${platform}.tar.gz`, `mezcal-${platform}.tar.gz`];
+  if (artifact.archive === undefined && artifact.name === undefined) {
+    fail(`release manifest artifact for ${platform} must use one of ${acceptedArchives.join(', ')}`);
+  }
+  if (artifact.archive !== undefined && !acceptedArchives.includes(artifact.archive)) {
+    fail(`release manifest artifact archive for ${platform} must be one of ${acceptedArchives.join(', ')}`);
+  }
+  if (artifact.name !== undefined && !acceptedArchives.includes(artifact.name)) {
+    fail(`release manifest artifact name for ${platform} must be one of ${acceptedArchives.join(', ')}`);
+  }
+  if (artifact.archive !== undefined && artifact.name !== undefined && artifact.archive !== artifact.name) {
+    fail(`release manifest artifact name and archive for ${platform} must match`);
+  }
+  if (typeof artifact.sha256 !== 'string' || !/^[0-9a-fA-F]{64}$/.test(artifact.sha256)) {
+    fail(`release manifest artifact for ${platform} has invalid sha256`);
+  }
+  return {
+    archive: artifact.archive ?? artifact.name,
+    sha256: artifact.sha256.toLowerCase(),
+  };
+}
+
+async function readManifest(rootUrl, tempDir) {
+  const attempts = [];
+  for (const manifestFilename of [PUBLIC_MANIFEST_FILENAME, LEGACY_MANIFEST_FILENAME]) {
+    const manifestPath = path.join(tempDir, manifestFilename);
+    try {
+      await downloadFile(releaseAssetUrl(rootUrl, manifestFilename), manifestPath);
+    } catch (error) {
+      await rm(manifestPath, { force: true }).catch(() => {});
+      if (!isMissingManifestDownload(error)) {
+        fail(`release manifest ${manifestFilename} could not be downloaded: ${errorMessage(error)}`);
+      }
+      attempts.push(`${manifestFilename}: ${errorMessage(error)}`);
+      continue;
+    }
+    return await readDownloadedManifest(manifestPath, manifestFilename);
+  }
+  fail(`release manifest not found; tried ${attempts.join('; ')}`);
+}
+
+async function installFromRelease({ platform, releaseTag, cachePath, rootUrl }) {
+  const tempDir = await mkdtemp(path.join(os.tmpdir(), 'starkscan-npm-cli-'));
+  try {
+    const manifest = await readManifest(rootUrl, tempDir);
+    const matching = manifest.artifacts.filter((artifact) => artifact?.platform === platform);
+    if (matching.length !== 1) {
+      fail(`release manifest must contain exactly one artifact for ${platform}; found ${matching.length}`);
+    }
+
+    const artifact = validateArtifact(matching[0], platform);
+    const archivePath = path.join(tempDir, artifact.archive);
+    await downloadFile(releaseAssetUrl(rootUrl, artifact.archive), archivePath);
+
+    const actualSha = await sha256File(archivePath);
+    if (actualSha !== artifact.sha256) {
+      fail(`checksum mismatch for ${artifact.archive}: expected ${artifact.sha256}, actual ${actualSha}`);
+    }
+
+    const listing = runChecked('tar', ['-tzf', archivePath]).stdout.trim();
+    if (listing !== PUBLIC_BINARY_NAME && listing !== LEGACY_BINARY_NAME) {
+      fail(`release artifact ${artifact.archive} must contain exactly one top-level Starkscan binary`);
+    }
+
+    const extractDir = path.join(tempDir, 'extract');
+    await mkdir(extractDir, { recursive: true });
+    runChecked('tar', ['-C', extractDir, '-xzf', archivePath]);
+    const extractedBinary = path.join(extractDir, listing);
+    await validateExecutableFile(extractedBinary, 'release artifact Starkscan binary');
+
+    await mkdir(path.dirname(cachePath), { recursive: true });
+    const stagePath = `${cachePath}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+    try {
+      await copyFile(extractedBinary, stagePath);
+      await chmod(stagePath, 0o755);
+      await rename(stagePath, cachePath);
+    } catch (error) {
+      await rm(stagePath, { force: true }).catch(() => {});
+      throw error;
+    }
+    await validateExecutableFile(cachePath, 'cached Starkscan binary');
+    return cachePath;
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+export async function ensureStarkscanBinary(options = {}) {
+  const explicitBinary = cliEnv('BIN_PATH');
+  if (explicitBinary) {
+    await validateExecutableFile(explicitBinary, 'STARKSCAN_CLI_BIN_PATH');
+    return explicitBinary;
+  }
+
+  const platform = resolvePlatform();
+  const releaseTag = await resolveReleaseTag();
+  const cacheDir = path.join(defaultCacheRoot(), releaseTag, platform);
+  const cachePath = path.join(cacheDir, PUBLIC_BINARY_NAME);
+  const allowCacheReuse = !options.force && releaseTag !== 'latest';
+  if (allowCacheReuse) {
+    const existing = await lstat(cachePath).catch(() => null);
+    if (existing) {
+      await validateExecutableFile(cachePath, 'cached Starkscan binary');
+      return cachePath;
+    }
+    const legacyCachePath = path.join(cacheDir, LEGACY_BINARY_NAME);
+    const legacyExisting = await lstat(legacyCachePath).catch(() => null);
+    if (legacyExisting) {
+      await validateExecutableFile(legacyCachePath, 'legacy cached Starkscan binary');
+      await mkdir(cacheDir, { recursive: true });
+      const stagePath = `${cachePath}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+      try {
+        await copyFile(legacyCachePath, stagePath);
+        await chmod(stagePath, 0o755);
+        await rename(stagePath, cachePath);
+      } catch (error) {
+        await rm(stagePath, { force: true }).catch(() => {});
+        throw error;
+      }
+      await validateExecutableFile(cachePath, 'cached Starkscan binary');
+      return cachePath;
+    }
+  }
+
+  const releaseRepo = cliEnv('RELEASE_REPO');
+  const repo = releaseRepo ?? DEFAULT_REPO;
+  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) {
+    fail(`unsupported GitHub repo path: ${repo}`);
+  }
+  const releaseBaseUrl = cliEnv('RELEASE_BASE_URL');
+  let rootUrl;
+  if (
+    !releaseBaseUrl &&
+    !releaseRepo &&
+    await hasBundledArtifacts(releaseTag)
+  ) {
+    rootUrl = bundledArtifactRootUrl(releaseTag);
+  } else {
+    const baseUrl = releaseBaseUrl ?? `https://github.com/${repo}/releases`;
+    rootUrl = releaseRootUrl(baseUrl, releaseTag);
+  }
+  return installFromRelease({ platform, releaseTag, cachePath, rootUrl });
+}
+
+// Deprecated #1117/#1456 compatibility alias. New package consumers should use
+// ensureStarkscanBinary so the public API is Starkscan-named.
+export const ensureMezcalBinary = ensureStarkscanBinary;

package/scripts/verify-bundled-artifacts.mjs

@@ -0,0 +1,134 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { lstat, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PACKAGE_JSON_PATH = path.join(PACKAGE_ROOT, 'package.json');
+const DEFAULT_BUNDLED_ARTIFACT_ROOT = path.join(PACKAGE_ROOT, 'artifacts');
+const RELEASE_TAG_RE = /^(?=.*[A-Za-z0-9])(?!-)(?!.*\.\.)[A-Za-z0-9._-]+$/;
+const SUPPORTED_PLATFORMS = [
+  'darwin-aarch64',
+  'darwin-x86_64',
+  'linux-aarch64',
+  'linux-x86_64',
+];
+const PUBLIC_MANIFEST_FILENAME = 'starkscan-cli-manifest.json';
+const LEGACY_MANIFEST_FILENAME = 'mezcal-cli-manifest.json';
+
+function env(name) {
+  const value = process.env[name]?.trim();
+  return value && value.length > 0 ? value : undefined;
+}
+
+function envFirst(primaryName, legacyName) {
+  return env(primaryName) ?? env(legacyName);
+}
+
+function fail(message) {
+  throw new Error(`verify-bundled-artifacts: ${message}`);
+}
+
+function releaseTagFromVersion(version) {
+  return version.startsWith('v') ? version : `v${version}`;
+}
+
+async function sha256File(filePath) {
+  return await new Promise((resolve, reject) => {
+    const hash = createHash('sha256');
+    const input = createReadStream(filePath);
+    input.on('error', reject);
+    input.on('data', (chunk) => hash.update(chunk));
+    input.on('end', () => resolve(hash.digest('hex')));
+  });
+}
+
+async function assertFile(filePath, label, remediation) {
+  const stat = await lstat(filePath).catch(() => null);
+  if (!stat?.isFile()) {
+    fail(`${label} is missing: ${filePath}. ${remediation}`);
+  }
+}
+
+async function main() {
+  const packageJson = JSON.parse(await readFile(PACKAGE_JSON_PATH, 'utf8'));
+  if (typeof packageJson.version !== 'string' || packageJson.version.length === 0) {
+    fail('package.json version is missing');
+  }
+  const releaseTag = envFirst('STARKSCAN_CLI_RELEASE_TAG', 'MEZCAL_CLI_RELEASE_TAG') ?? releaseTagFromVersion(packageJson.version);
+  if (!RELEASE_TAG_RE.test(releaseTag)) {
+    fail(`unsupported release tag: ${releaseTag}`);
+  }
+  const artifactRoot =
+    envFirst('STARKSCAN_CLI_BUNDLED_ARTIFACT_DIR', 'MEZCAL_CLI_BUNDLED_ARTIFACT_DIR') ??
+    DEFAULT_BUNDLED_ARTIFACT_ROOT;
+  const releaseRoot = path.join(artifactRoot, releaseTag);
+  const remediation =
+    `Expected bundled artifacts under ${releaseRoot}. ` +
+    'Run native CLI packaging for every supported platform, merge the manifest, then run ' +
+    '`./webapp/packages/cli/scripts/package-starkscan-cli-npm.sh .artifacts/release/npm-cli` from the repository root.';
+  let manifestPath;
+  for (const manifestFilename of [PUBLIC_MANIFEST_FILENAME, LEGACY_MANIFEST_FILENAME]) {
+    const candidate = path.join(releaseRoot, manifestFilename);
+    const stat = await lstat(candidate).catch(() => null);
+    if (stat?.isFile()) {
+      manifestPath = candidate;
+      break;
+    }
+  }
+  if (!manifestPath) {
+    manifestPath = path.join(releaseRoot, PUBLIC_MANIFEST_FILENAME);
+    await assertFile(manifestPath, 'bundled manifest', remediation);
+  }
+
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    fail('bundled manifest root must be an object');
+  }
+  if (manifest.schemaVersion !== 1 || !Array.isArray(manifest.artifacts)) {
+    fail('bundled manifest must use schemaVersion=1 and artifacts[]');
+  }
+
+  for (const platform of SUPPORTED_PLATFORMS) {
+    const acceptedArchives = [`starkscan-${platform}.tar.gz`, `mezcal-${platform}.tar.gz`];
+    const matches = manifest.artifacts.filter((artifact) => artifact?.platform === platform);
+    if (matches.length !== 1) {
+      fail(`manifest must contain exactly one artifact for ${platform}; found ${matches.length}`);
+    }
+    const artifact = matches[0];
+    const archiveName = artifact.archive ?? artifact.name;
+    if (!archiveName) {
+      fail(`artifact for ${platform} must define archive or name`);
+    }
+    if (!acceptedArchives.includes(archiveName)) {
+      fail(`artifact for ${platform} must be named one of ${acceptedArchives.join(', ')}`);
+    }
+    if (artifact.archive !== undefined && artifact.name !== undefined && artifact.archive !== artifact.name) {
+      fail(`artifact archive and name for ${platform} must match`);
+    }
+    if (typeof artifact.sha256 !== 'string' || !/^[0-9a-fA-F]{64}$/.test(artifact.sha256)) {
+      fail(`artifact for ${platform} has invalid sha256`);
+    }
+
+    const archivePath = path.join(releaseRoot, archiveName);
+    const checksumPath = `${archivePath}.sha256`;
+    await assertFile(archivePath, archiveName, remediation);
+    await assertFile(checksumPath, `${archiveName}.sha256`, remediation);
+
+    const expectedSha = artifact.sha256.toLowerCase();
+    const checksum = (await readFile(checksumPath, 'utf8')).split(/\s+/)[0]?.toLowerCase();
+    if (checksum !== expectedSha) {
+      fail(`${archiveName}.sha256 does not match manifest sha256`);
+    }
+    const actualSha = await sha256File(archivePath);
+    if (actualSha !== expectedSha) {
+      fail(`${archiveName} bytes do not match manifest sha256`);
+    }
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(2);
+});