@starkscan/cli 0.1.0-alpha.0 → 0.1.0-alpha.2

package/README.md

@@ -15,6 +15,23 @@ One-off agent run:
 npx @starkscan/cli@alpha doctor
 ```
 
+For unattended agents or production services, pin a smoked exact version instead
+of floating on `@alpha`.
+
+## Trust status
+
+- npm: <https://www.npmjs.com/package/@starkscan/cli>
+- public trust docs: <https://starkscan.co/docs/build/package-trust>
+- machine-readable matrix: <https://starkscan.co/public-client-surface-matrix.json>
+- Socket signal: <https://socket.dev/npm/package/@starkscan/cli>
+
+Socket is an external package-risk signal, not a formal Starkscan security
+certificate. Starkscan package promotion also requires bundled-artifact checksum
+verification, manual passkey or Trusted Publishing/OIDC publish control, and
+the launch gates documented at the public package trust page. The canonical
+source repository is private, so public package trust links intentionally point
+to Starkscan docs instead of GitHub.
+
 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
@@ -46,10 +63,10 @@ By default, the package resolves to bundled artifacts under `artifacts/v<package
 
 - `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_RELEASE_BASE_URL`: maintainer/test release base URL override. Published public packages use bundled artifacts first; beta clients should not set this.
 - `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_RELEASE_REPO`: maintainer/test GitHub repo path override
 - `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`
 

package/artifacts/{v0.1.0-alpha.0 → v0.1.0-alpha.2}/starkscan-cli-manifest.json

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

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

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

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

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

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

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

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

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

package/package.json

@@ -1,20 +1,14 @@
 {
   "name": "@starkscan/cli",
   "private": false,
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.2",
   "description": "npm/npx launcher for the prebuilt Starkscan explorer CLI.",
   "license": "MIT",
   "type": "module",
   "publishConfig": {
-    "access": "public",
-    "provenance": true
+    "access": "public"
   },
-  "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",
+  "homepage": "https://starkscan.co/docs/ai/agent-cli",
   "keywords": [
     "starkscan",
     "starknet",

package/scripts/installer.mjs

@@ -22,9 +22,7 @@ const SUPPORTED_PLATFORMS = new Set([
   '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();
@@ -204,14 +202,9 @@ function bundledArtifactRootUrl(releaseTag) {
 }
 
 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;
+  const manifestPath = path.join(bundledArtifactRoot(), releaseTag, PUBLIC_MANIFEST_FILENAME);
+  const stat = await lstat(manifestPath).catch(() => null);
+  return Boolean(stat?.isFile());
 }
 
 export function resolveRedirectUrl(url, location, redirectsLeft) {
@@ -322,15 +315,15 @@ function validateArtifact(artifact, platform) {
   if (artifact.platform !== platform) {
     fail(`release manifest selected wrong platform: ${artifact.platform}`);
   }
-  const acceptedArchives = [`starkscan-${platform}.tar.gz`, `mezcal-${platform}.tar.gz`];
+  const expectedArchive = `starkscan-${platform}.tar.gz`;
   if (artifact.archive === undefined && artifact.name === undefined) {
-    fail(`release manifest artifact for ${platform} must use one of ${acceptedArchives.join(', ')}`);
+    fail(`release manifest artifact for ${platform} must use ${expectedArchive}`);
   }
-  if (artifact.archive !== undefined && !acceptedArchives.includes(artifact.archive)) {
-    fail(`release manifest artifact archive for ${platform} must be one of ${acceptedArchives.join(', ')}`);
+  if (artifact.archive !== undefined && artifact.archive !== expectedArchive) {
+    fail(`release manifest artifact archive for ${platform} must be ${expectedArchive}`);
   }
-  if (artifact.name !== undefined && !acceptedArchives.includes(artifact.name)) {
-    fail(`release manifest artifact name for ${platform} must be one of ${acceptedArchives.join(', ')}`);
+  if (artifact.name !== undefined && artifact.name !== expectedArchive) {
+    fail(`release manifest artifact name for ${platform} must be ${expectedArchive}`);
   }
   if (artifact.archive !== undefined && artifact.name !== undefined && artifact.archive !== artifact.name) {
     fail(`release manifest artifact name and archive for ${platform} must match`);
@@ -345,22 +338,17 @@ function validateArtifact(artifact, platform) {
 }
 
 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;
+  const manifestPath = path.join(tempDir, PUBLIC_MANIFEST_FILENAME);
+  try {
+    await downloadFile(releaseAssetUrl(rootUrl, PUBLIC_MANIFEST_FILENAME), manifestPath);
+  } catch (error) {
+    await rm(manifestPath, { force: true }).catch(() => {});
+    if (!isMissingManifestDownload(error)) {
+      fail(`release manifest ${PUBLIC_MANIFEST_FILENAME} could not be downloaded: ${errorMessage(error)}`);
     }
-    return await readDownloadedManifest(manifestPath, manifestFilename);
+    fail(`release manifest ${PUBLIC_MANIFEST_FILENAME} not found: ${errorMessage(error)}`);
   }
-  fail(`release manifest not found; tried ${attempts.join('; ')}`);
+  return await readDownloadedManifest(manifestPath, PUBLIC_MANIFEST_FILENAME);
 }
 
 async function installFromRelease({ platform, releaseTag, cachePath, rootUrl }) {
@@ -382,7 +370,7 @@ async function installFromRelease({ platform, releaseTag, cachePath, rootUrl })
     }
 
     const listing = runChecked('tar', ['-tzf', archivePath]).stdout.trim();
-    if (listing !== PUBLIC_BINARY_NAME && listing !== LEGACY_BINARY_NAME) {
+    if (listing !== PUBLIC_BINARY_NAME) {
       fail(`release artifact ${artifact.archive} must contain exactly one top-level Starkscan binary`);
     }
 
@@ -427,23 +415,6 @@ export async function ensureStarkscanBinary(options = {}) {
       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');
@@ -465,7 +436,3 @@ export async function ensureStarkscanBinary(options = {}) {
   }
   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

@@ -15,7 +15,6 @@ const SUPPORTED_PLATFORMS = [
   '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();
@@ -68,19 +67,8 @@ async function main() {
     `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 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)) {
@@ -91,7 +79,7 @@ async function main() {
   }
 
   for (const platform of SUPPORTED_PLATFORMS) {
-    const acceptedArchives = [`starkscan-${platform}.tar.gz`, `mezcal-${platform}.tar.gz`];
+    const expectedArchive = `starkscan-${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}`);
@@ -101,8 +89,8 @@ async function main() {
     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 (archiveName !== expectedArchive) {
+      fail(`artifact for ${platform} must be named ${expectedArchive}`);
     }
     if (artifact.archive !== undefined && artifact.name !== undefined && artifact.archive !== artifact.name) {
       fail(`artifact archive and name for ${platform} must match`);

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

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

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

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

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

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

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

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