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

package/README.md

@@ -21,13 +21,16 @@ of floating on `@alpha`.
 ## Trust status
 
 - npm: <https://www.npmjs.com/package/@starkscan/cli>
-- source organization: <https://github.com/starknet-innovation>
+- 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, npm Trusted Publishing/provenance, and the launch gates documented
-at `/docs/build/package-trust` on the deployed docs host.
+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.
 
@@ -60,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.1 → v0.1.0-alpha.2}/starkscan-cli-manifest.json

@@ -1,34 +1,34 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-05-28T10:16:34Z",
+  "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": "26e55c13e3b8665ba058e0032007c8277ce187dc5710d8ac4e5e50686a46f00a"
+      "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": "46d03132446a46b54dcb9f529c2547a9c1c0f7615d5022c70caceea0ba1be014"
+      "sha256": "c99ddc5b28f6dcfab8523a6c13ab629fbc38a772c001bb75320490cb83fef382"
     },
     {
       "name": "starkscan-linux-aarch64.tar.gz",
       "platform": "linux-aarch64",
       "target": "linux-aarch64",
       "archive": "starkscan-linux-aarch64.tar.gz",
-      "sha256": "8b3a1febf6ed7c4469a2703f1e29bc64a1d28bc6af538f3c80e6d739ea89c30d"
+      "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": "4d48f2ecb220961574577b5b20c3272fddbd5c35aa4972391b8de718da85f807"
+      "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.1",
+  "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.1/starkscan-darwin-aarch64.tar.gz.sha256

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

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

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

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

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

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

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