@bugsee/cli 0.0.0 → 0.7.7

package/README.md

@@ -0,0 +1,78 @@
+# @bugsee/cli
+
+The [Bugsee CLI](https://github.com/bugsee/bugsee-cli) — a cross-platform Rust
+binary that collects debug information files (dSYM, ELF, PE/PDB, R8/ProGuard
+mappings, JS source maps), resolves build-environment metadata, and uploads
+symbols to Bugsee.
+
+```sh
+npm install --save-dev @bugsee/cli
+npx bugsee-cli --version
+```
+
+## How the binary gets here
+
+The binary is **not** in this package. It ships in six per-platform packages,
+declared as `optionalDependencies`:
+
+| Package                    | `os` / `cpu`       |
+| -------------------------- | ------------------ |
+| `@bugsee/cli-darwin-arm64` | `darwin` / `arm64` |
+| `@bugsee/cli-darwin-x64`   | `darwin` / `x64`   |
+| `@bugsee/cli-linux-arm64`  | `linux` / `arm64`  |
+| `@bugsee/cli-linux-x64`    | `linux` / `x64`    |
+| `@bugsee/cli-win32-x64`    | `win32` / `x64`    |
+| `@bugsee/cli-win32-arm64`  | `win32` / `arm64`  |
+
+npm installs only the one matching your machine and skips the rest. Nothing is
+downloaded at install time, so this works with `--ignore-scripts`, with a
+lockfile-pinned CI install, and offline from a warm cache.
+
+The Linux builds link glibc and are marked `"libc": ["glibc"]`. On musl (Alpine)
+the install still succeeds, and `bugsee-cli` reports that plainly if invoked —
+use a glibc base image, or build from source.
+
+If the platform package is unavailable — `--no-optional`, a registry mirror
+that carries only this package, or an unsupported platform — a `postinstall`
+fallback downloads the release archive for your host and verifies its SHA-256
+before unpacking it into `vendor/`. That fallback **never fails the install**:
+if it cannot fetch the binary it warns and exits 0, and the error surfaces only
+if you actually invoke `bugsee-cli`.
+
+| Variable                     | Effect                                                                                                                                                                    |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BUGSEE_CLI_SKIP_DOWNLOAD=1` | Skip the fallback download entirely.                                                                                                                                      |
+| `BUGSEE_CLI_BASE_URL=<url>`  | Fetch `<url>/bugsee-cli-<triple>.<ext>` (+ `.sha256`) instead of the GitHub release — point it at an internal mirror, or at `https://download.bugsee.com/cli/v<version>`. |
+
+## Programmatic use
+
+```js
+const { spawnSync } = require("node:child_process");
+const { binaryPath } = require("@bugsee/cli");
+
+const out = spawnSync(binaryPath(), ["vcs-metadata"], { encoding: "utf8" });
+const metadata = JSON.parse(out.stdout);
+```
+
+- `binaryPath()` — absolute path to the binary; throws with a diagnostic if
+  there is none for this platform.
+- `resolveBinaryPath()` — the same lookup, returning `null` instead of throwing.
+- `version` — the CLI version this package carries.
+
+## Exit codes
+
+`bugsee-cli` exits with a
+[stable, documented code](https://github.com/bugsee/bugsee-cli#exit-code-contract)
+and the launcher forwards it unchanged (`0` success, `1`/`2` structural — the
+caller should fall back, `10`–`39` substantive failures, `40` a deliberate build
+gate). A launcher that cannot find a binary at all exits `1`, which is the
+"structural, fall back" case by that same contract.
+
+## Other install channels
+
+`@bugsee/bugsee-cli` is the same CLI published by cargo-dist as a single
+package that downloads its binary in a `postinstall`. It remains supported as
+an alias; **prefer `@bugsee/cli`** — it is the one that works under
+`--ignore-scripts`. See the
+[Distribution section](https://github.com/bugsee/bugsee-cli#distribution) for
+the shell installer, Homebrew tap, and the per-build-system bundles.

package/bin/bugsee-cli.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// Launcher for the `bugsee-cli` bin of @bugsee/cli.
+//
+// This is a pass-through, and "pass-through" is a contract here, not a
+// nicety: every integrator that shells to the CLI branches on its EXIT CODE
+// (see the exit-code contract in README.md — <= 2 means "fall back to the
+// in-language uploader", >= 10 means "a real failure, do not fall back"), and
+// the metadata commands' stdout is parsed with `json.loads`. So this wrapper
+// must forward argv verbatim, leave all three stdio streams untouched, and
+// reproduce the child's exit status exactly.
+
+"use strict";
+
+const { spawnSync } = require("child_process");
+const os = require("os");
+const { resolveBinaryPath, diagnostic } = require("../lib/index.js");
+
+const binary = resolveBinaryPath();
+if (!binary) {
+  console.error(diagnostic());
+  // Exit 1 = "structural" in the CLI's own exit-code contract: the CLI never
+  // got a fair chance to run, so a caller is expected to fall back. Any other
+  // code here would lie about what happened.
+  process.exit(1);
+}
+
+const result = spawnSync(binary, process.argv.slice(2), {
+  stdio: "inherit",
+  // No `shell: true` — it would re-parse arguments (quoting, globs, `&`) that
+  // are meant to reach clap untouched, and paths with spaces are routine here.
+  windowsHide: true,
+});
+
+if (result.error) {
+  console.error(`failed to execute ${binary}: ${result.error.message}`);
+  process.exit(1);
+}
+
+if (result.signal) {
+  // The child died from a signal, which has no exit code. Report it the way a
+  // shell does (128 + signum) so `$?` still tells a CI script what happened.
+  const signum = os.constants.signals[result.signal];
+  process.exit(signum ? 128 + signum : 1);
+}
+
+process.exit(result.status === null ? 1 : result.status);

package/lib/index.js

@@ -0,0 +1,105 @@
+// Programmatic entry point for @bugsee/cli.
+//
+//   const { binaryPath } = require("@bugsee/cli");
+//   spawnSync(binaryPath(), ["vcs-metadata"], { encoding: "utf8" });
+//
+// Exists so a Node integrator (the React Native / Cordova / Capacitor hooks)
+// can spawn the binary directly and read its stdout JSON, instead of going
+// through `bin` and paying for an extra node process just to re-exec.
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { PLATFORMS, currentTriple, isMuslLinux } = require("./platforms.js");
+
+const { version } = require("../package.json");
+
+/** Where scripts/postinstall.js parks a binary it downloaded itself. */
+function vendorPath(triple) {
+  const p = PLATFORMS[triple];
+  if (!p) return null;
+  return path.join(__dirname, "..", "vendor", p.bin);
+}
+
+/**
+ * Locate the binary, or return null.
+ *
+ * Two sources, in order:
+ *
+ *  1. The platform package installed as an optionalDependency. This is the
+ *     normal path and the whole point of the package split: npm picks exactly
+ *     one of the six by `os`/`cpu`, and it works under `--ignore-scripts`
+ *     because nothing had to run to put the binary there.
+ *  2. `vendor/`, where the postinstall fallback downloads to when (1) is
+ *     unavailable — `--no-optional`, a registry mirror that carries only the
+ *     front package, or a corporate proxy that 404s the platform scopes.
+ *
+ * Never throws: callers that want an exception want binaryPath().
+ */
+function resolveBinaryPath() {
+  const triple = currentTriple();
+  if (!triple) return null;
+  const { pkg, bin } = PLATFORMS[triple];
+
+  // Exact-file resolution: `bin/bugsee-cli` has no extension, so Node's
+  // LOAD_AS_FILE matches it verbatim. Kept as the primary lookup because it
+  // fails loudly-in-try if the package is present but was packed wrong.
+  try {
+    return require.resolve(`${pkg}/bin/${bin}`);
+  } catch {
+    /* fall through */
+  }
+
+  // Same package, resolved via its manifest. This survives a consumer that
+  // restricts subpath resolution (yarn PnP strictness, a future `exports`
+  // field on the platform packages) where the direct lookup would not.
+  try {
+    const manifest = require.resolve(`${pkg}/package.json`);
+    const candidate = path.join(path.dirname(manifest), "bin", bin);
+    if (fs.existsSync(candidate)) return candidate;
+  } catch {
+    /* fall through */
+  }
+
+  const vendored = vendorPath(triple);
+  if (vendored && fs.existsSync(vendored)) return vendored;
+
+  return null;
+}
+
+/** Human-readable reason there is no binary — used in both error paths. */
+function diagnostic() {
+  if (isMuslLinux()) {
+    return (
+      "bugsee-cli publishes glibc Linux builds only; this looks like a musl " +
+      "system (e.g. Alpine). Use a glibc base image, or build from source: " +
+      "https://github.com/bugsee/bugsee-cli"
+    );
+  }
+  const triple = currentTriple();
+  if (!triple) {
+    return (
+      `bugsee-cli has no published binary for ${process.platform}-${process.arch}. ` +
+      `Supported: ${Object.values(PLATFORMS)
+        .map((p) => `${p.os}-${p.cpu}`)
+        .join(", ")}.`
+    );
+  }
+  const { pkg } = PLATFORMS[triple];
+  return (
+    `bugsee-cli binary not found. Expected the optional dependency ${pkg} ` +
+    `(installed automatically) or a postinstall download in vendor/. ` +
+    `If you installed with --no-optional, re-run without it, or run ` +
+    `\`node node_modules/@bugsee/cli/scripts/postinstall.js\` to fetch it.`
+  );
+}
+
+/** Absolute path to the binary. Throws if there is none. */
+function binaryPath() {
+  const resolved = resolveBinaryPath();
+  if (!resolved) throw new Error(diagnostic());
+  return resolved;
+}
+
+module.exports = { binaryPath, resolveBinaryPath, diagnostic, version };

package/lib/platforms.js

@@ -0,0 +1,129 @@
+// The single source of truth for "which npm package carries which binary".
+//
+// Consumed by three things that MUST agree, or the front package resolves a
+// binary the publisher never built:
+//   - lib/index.js       (runtime resolution of the optional dependency)
+//   - scripts/postinstall.js (the download fallback, which needs the release
+//                             artifact name for the same triple)
+//   - ../../build.mjs    (the assembler, which mints one npm package per row)
+//
+// `triple` is the Rust target triple, and it is the join key with everything
+// outside this directory: `[workspace.metadata.dist].targets` in Cargo.toml
+// names these, cargo-dist names its release assets after them
+// (`bugsee-cli-<triple><archiveExt>`), and installer/install.sh builds the same
+// filename. Adding a platform here without adding the triple to `targets`
+// produces a package with nothing to put in it. (Do NOT then run
+// `dist generate`: `allow-dirty = ["ci"]` makes it a silent no-op for
+// release.yml. Check the plan with `dist plan --output-format=json` — see the
+// `allow-dirty` comment in Cargo.toml.)
+//
+// Windows arm64 (`aarch64-pc-windows-msvc`) IS published as of 0.7.7 — see
+// bugsee/bugsee-cli#20 for why it was absent before. It cross-compiles under
+// cargo-xwin only if `ring` can assemble its ARM64 Windows `.S` files, which it
+// cannot, so that leg builds NATIVELY on a `windows-11-arm` runner instead
+// (`[workspace.metadata.dist.github-custom-runners]` in Cargo.toml). ci.yml
+// build-checks the target on every PR so the leg cannot break a tag release:
+// dist's `host` job needs EVERY build-local-artifacts leg, and a failing leg
+// means no GitHub Release, hence no S3 mirror and no npm publish.
+
+"use strict";
+
+const PLATFORMS = Object.freeze({
+  "aarch64-apple-darwin": {
+    pkg: "@bugsee/cli-darwin-arm64",
+    os: "darwin",
+    cpu: "arm64",
+    bin: "bugsee-cli",
+    archiveExt: ".tar.xz",
+    label: "macOS arm64 (Apple silicon)",
+  },
+  "x86_64-apple-darwin": {
+    pkg: "@bugsee/cli-darwin-x64",
+    os: "darwin",
+    cpu: "x64",
+    bin: "bugsee-cli",
+    archiveExt: ".tar.xz",
+    label: "macOS x86_64 (Intel)",
+  },
+  "aarch64-unknown-linux-gnu": {
+    pkg: "@bugsee/cli-linux-arm64",
+    os: "linux",
+    cpu: "arm64",
+    // Our Linux builds are `unknown-linux-gnu`. npm >= 10.5 (and pnpm/yarn)
+    // honour this the way they honour os/cpu, so a musl host skips the
+    // download entirely; older npm ignores the field and installs a binary it
+    // cannot load, which is what currentTriple()'s musl check catches.
+    libc: "glibc",
+    bin: "bugsee-cli",
+    archiveExt: ".tar.xz",
+    label: "Linux arm64 (glibc)",
+  },
+  "x86_64-unknown-linux-gnu": {
+    pkg: "@bugsee/cli-linux-x64",
+    os: "linux",
+    cpu: "x64",
+    // See the note on aarch64-unknown-linux-gnu above.
+    libc: "glibc",
+    bin: "bugsee-cli",
+    archiveExt: ".tar.xz",
+    label: "Linux x86_64 (glibc)",
+  },
+  "x86_64-pc-windows-msvc": {
+    pkg: "@bugsee/cli-win32-x64",
+    os: "win32",
+    cpu: "x64",
+    bin: "bugsee-cli.exe",
+    archiveExt: ".zip",
+    label: "Windows x86_64",
+  },
+  "aarch64-pc-windows-msvc": {
+    pkg: "@bugsee/cli-win32-arm64",
+    os: "win32",
+    cpu: "arm64",
+    bin: "bugsee-cli.exe",
+    archiveExt: ".zip",
+    label: "Windows arm64",
+  },
+});
+
+/** Release-asset filename cargo-dist publishes for a triple. */
+function artifactName(triple) {
+  const p = PLATFORMS[triple];
+  return p ? `bugsee-cli-${triple}${p.archiveExt}` : null;
+}
+
+// The published Linux builds are `unknown-linux-gnu`; there is no musl target
+// (install.sh refuses musl for the same reason). Node exposes the runtime glibc
+// version in its process report ONLY when it is actually linked against glibc,
+// so an absent value means musl (or a non-glibc libc) — this is the zero-
+// dependency equivalent of the `detect-libc` call cargo-dist's installer makes.
+function isMuslLinux() {
+  if (process.platform !== "linux") return false;
+  try {
+    const report = process.report && process.report.getReport();
+    const header = report && report.header;
+    return !(header && header.glibcVersionRuntime);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Rust target triple for the host, or null when we publish nothing for it.
+ *
+ * Note this is deliberately driven by the triple Node reports for ITSELF, not
+ * by the hardware: an x64 Node under Rosetta on an arm64 Mac reports `x64` and
+ * gets the x86_64 binary, which is what runs correctly in that process tree.
+ */
+function currentTriple() {
+  const { platform, arch } = process;
+  for (const [triple, p] of Object.entries(PLATFORMS)) {
+    if (p.os === platform && p.cpu === arch) {
+      if (platform === "linux" && isMuslLinux()) return null;
+      return triple;
+    }
+  }
+  return null;
+}
+
+module.exports = { PLATFORMS, artifactName, currentTriple, isMuslLinux };

package/package.json

@@ -1,7 +1,44 @@
 {
   "name": "@bugsee/cli",
-  "version": "0.0.0",
-  "description": "Placeholder — see https://github.com/bugsee/bugsee-cli",
-  "repository": { "type": "git", "url": "git+https://github.com/bugsee/bugsee-cli.git" },
-  "license": "MIT"
+  "version": "0.7.7",
+  "description": "Bugsee CLI — cross-platform symbol collection, conversion, and upload.",
+  "keywords": [
+    "bugsee",
+    "symbols",
+    "dsym",
+    "sourcemaps",
+    "proguard",
+    "crash-reporting"
+  ],
+  "homepage": "https://github.com/bugsee/bugsee-cli",
+  "repository": "https://github.com/bugsee/bugsee-cli",
+  "author": "Bugsee",
+  "bin": {
+    "bugsee-cli": "bin/bugsee-cli.js"
+  },
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "scripts",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "engines": {
+    "node": ">=14.18"
+  },
+  "optionalDependencies": {
+    "@bugsee/cli-darwin-arm64": "0.7.7",
+    "@bugsee/cli-darwin-x64": "0.7.7",
+    "@bugsee/cli-linux-arm64": "0.7.7",
+    "@bugsee/cli-linux-x64": "0.7.7",
+    "@bugsee/cli-win32-arm64": "0.7.7",
+    "@bugsee/cli-win32-x64": "0.7.7"
+  }
 }

package/scripts/download.js

@@ -0,0 +1,197 @@
+// Install-time HTTP helper for scripts/postinstall.js. Not part of the runtime
+// surface — lib/index.js never requires it.
+//
+// Deliberately dependency-free (node:https only). The front package having
+// zero runtime dependencies is the reason it can be installed from a locked-
+// down mirror at all, and a postinstall that needed `node-fetch` would defeat
+// the fallback it exists to provide. Redirect following is required because
+// GitHub release downloads 302 to objects.githubusercontent.com; proxy support
+// is required because the CI boxes that hit the fallback path (no access to
+// the platform scopes) are usually the ones behind a proxy.
+
+"use strict";
+
+const http = require("node:http");
+const https = require("node:https");
+
+// How many redirect hops we will FOLLOW. GitHub release downloads take two
+// (release -> objects.githubusercontent.com -> the CDN), so 5 is generous.
+const MAX_REDIRECTS = 5;
+
+// HTTPS only, with one narrow exception. The artifact and its `.sha256`
+// sidecar come from the same base URL, so anyone who can rewrite a cleartext
+// hop controls BOTH and the checksum verification proves nothing. This is the
+// same stance installer/install.sh takes with `curl --proto '=https'
+// --tlsv1.2`. The exception is a loopback host, which exists so a local mirror
+// (and this repo's own checksum-mismatch test) can be served over plain HTTP
+// without a certificate; loopback cannot be intercepted by a network attacker.
+function isLoopback(hostname) {
+  const host = hostname.toLowerCase().replace(/^\[/, "").replace(/\]$/, "");
+  return (
+    host === "localhost" ||
+    host === "::1" ||
+    host === "0:0:0:0:0:0:0:1" ||
+    /^127(?:\.\d{1,3}){3}$/.test(host)
+  );
+}
+
+function proxyFor(urlString) {
+  const url = new URL(urlString);
+  const isHttps = url.protocol === "https:";
+
+  const noProxy = process.env.NO_PROXY || process.env.no_proxy || "";
+  if (noProxy === "*") return null;
+  if (noProxy) {
+    const host = url.hostname.toLowerCase();
+    for (const raw of noProxy.split(",")) {
+      const entry = raw.trim().toLowerCase();
+      if (entry && (host === entry || host.endsWith("." + entry))) return null;
+    }
+  }
+
+  const env = isHttps
+    ? process.env.HTTPS_PROXY || process.env.https_proxy
+    : process.env.HTTP_PROXY || process.env.http_proxy;
+  if (!env) return null;
+
+  const proxy = new URL(env);
+  return {
+    hostname: proxy.hostname,
+    port: proxy.port || (proxy.protocol === "https:" ? 443 : 80),
+    auth:
+      proxy.username || proxy.password
+        ? `${decodeURIComponent(proxy.username)}:${decodeURIComponent(proxy.password)}`
+        : null,
+  };
+}
+
+function connectThroughProxy(proxy, target) {
+  return new Promise((resolve, reject) => {
+    const headers = {};
+    if (proxy.auth) {
+      headers["Proxy-Authorization"] =
+        "Basic " + Buffer.from(proxy.auth).toString("base64");
+    }
+    const req = http.request({
+      hostname: proxy.hostname,
+      port: proxy.port,
+      method: "CONNECT",
+      path: `${target.hostname}:${target.port || 443}`,
+      headers,
+    });
+    req.on("connect", (res, socket) => {
+      if (res.statusCode === 200) resolve(socket);
+      else
+        reject(new Error(`proxy CONNECT failed with status ${res.statusCode}`));
+    });
+    req.on("error", reject);
+    req.end();
+  });
+}
+
+/**
+ * GET a URL, following redirects; resolves with the response stream.
+ *
+ * `httpsOnly` is latched on the FIRST hop and carried through every redirect,
+ * so an https origin can never be walked down to cleartext by a 302 — without
+ * that, re-checking each hop independently would happily follow
+ * `https://mirror/... -> http://attacker/...`.
+ */
+function get(urlString, redirectsFollowed = 0, httpsOnly = null) {
+  return new Promise((resolve, reject) => {
+    if (redirectsFollowed > MAX_REDIRECTS) {
+      return reject(new Error(`too many redirects (> ${MAX_REDIRECTS})`));
+    }
+
+    const parsed = new URL(urlString);
+    const isHttps = parsed.protocol === "https:";
+    if (!isHttps && parsed.protocol !== "http:") {
+      return reject(new Error(`unsupported protocol: ${parsed.protocol}`));
+    }
+    const secureRequired = httpsOnly === null ? isHttps : httpsOnly;
+    if (!isHttps) {
+      if (secureRequired) {
+        return reject(
+          new Error(
+            `refusing to follow an https -> http redirect: ${urlString}`,
+          ),
+        );
+      }
+      if (!isLoopback(parsed.hostname)) {
+        return reject(
+          new Error(
+            `refusing to fetch over plain HTTP from a non-loopback host: ${urlString}`,
+          ),
+        );
+      }
+    }
+    const mod = isHttps ? https : http;
+    const proxy = proxyFor(urlString);
+
+    const send = (extra) => {
+      const options = Object.assign(
+        {
+          hostname: parsed.hostname,
+          port: parsed.port || (isHttps ? 443 : 80),
+          path: parsed.pathname + parsed.search,
+          method: "GET",
+          headers: { "User-Agent": "bugsee-cli-npm-installer" },
+          timeout: 60_000,
+        },
+        extra || {},
+      );
+
+      if (proxy && !isHttps) {
+        // Plain HTTP through an HTTP proxy: absolute-URI request line.
+        options.hostname = proxy.hostname;
+        options.port = proxy.port;
+        options.path = urlString;
+        if (proxy.auth) {
+          options.headers["Proxy-Authorization"] =
+            "Basic " + Buffer.from(proxy.auth).toString("base64");
+        }
+      }
+
+      const req = mod.request(options, (res) => {
+        const { statusCode, headers } = res;
+        if (statusCode >= 300 && statusCode < 400 && headers.location) {
+          res.resume();
+          const next = new URL(headers.location, urlString).toString();
+          return get(next, redirectsFollowed + 1, secureRequired).then(
+            resolve,
+            reject,
+          );
+        }
+        if (statusCode < 200 || statusCode >= 300) {
+          res.resume();
+          return reject(new Error(`HTTP ${statusCode} from ${urlString}`));
+        }
+        resolve(res);
+      });
+      req.on("timeout", () =>
+        req.destroy(new Error(`timed out: ${urlString}`)),
+      );
+      req.on("error", reject);
+      req.end();
+    };
+
+    if (proxy && isHttps) {
+      connectThroughProxy(proxy, parsed).then(
+        (socket) => send({ socket, agent: false }),
+        reject,
+      );
+    } else {
+      send();
+    }
+  });
+}
+
+/** GET a small URL fully into a string (used for the .sha256 sidecar). */
+async function getText(urlString) {
+  const res = await get(urlString);
+  const chunks = [];
+  for await (const chunk of res) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+module.exports = { get, getText };

package/scripts/expand-archive.ps1

@@ -0,0 +1,28 @@
+# Unpack a .zip for scripts/postinstall.js on Windows, where `unzip` is not
+# present on a stock image.
+#
+# Invoked with `powershell.exe -File`, NOT `-Command`. This matters: `-Command`
+# does not bind trailing arguments to `$args` — it APPENDS them to the command
+# text and evaluates the result. An earlier version of this code passed the
+# archive and destination as trailing arguments to a `-Command` string that
+# read `$args[0]` / `$args[1]`; `$args.Count` is 0 under `-Command`, so
+# Expand-Archive ran with null paths and the Windows fallback silently produced
+# no binary. That append is also an injection shape — text from the caller
+# becomes part of the script — which `-File` avoids entirely, because
+# everything after the script path is bound as a parameter VALUE and is never
+# parsed as code.
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)][string]$LiteralPath,
+    [Parameter(Mandatory = $true)][string]$DestinationPath
+)
+
+$ErrorActionPreference = 'Stop'
+
+try {
+    Expand-Archive -LiteralPath $LiteralPath -DestinationPath $DestinationPath -Force
+    exit 0
+} catch {
+    [Console]::Error.WriteLine($_.Exception.Message)
+    exit 1
+}

package/scripts/postinstall.js

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+// Fallback binary fetch for @bugsee/cli.
+//
+// The optionalDependencies split covers the normal case. This script covers
+// the three cases it cannot:
+//
+//   - `npm install --no-optional` / `--omit=optional` (and the CI images that
+//     bake that in), where npm never even looks at the platform packages;
+//   - an internal registry mirror or proxy that carries @bugsee/cli but not
+//     the six @bugsee/cli-<platform> scopes, where npm silently skips the
+//     optional dependency and leaves nothing behind;
+//   - a platform we publish no package for at all.
+//
+// THE RULE FOR THIS FILE: it must never fail the install. `npm install` of a
+// dependency tree that happens to contain @bugsee/cli must succeed on a
+// Raspberry Pi, on Alpine, and inside an air-gapped mirror — @bugsee/cli is
+// pulled in transitively by the RN/Cordova/Capacitor integrations, and a
+// postinstall that exits non-zero there breaks an unrelated build for a tool
+// the user may never invoke. So: every failure path warns on stderr and exits
+// 0, and the missing binary is reported later, by the launcher, only if
+// someone actually tries to run it.
+//
+// Environment:
+//   BUGSEE_CLI_SKIP_DOWNLOAD=1   skip the fallback entirely (offline builds)
+//   BUGSEE_CLI_BASE_URL=<url>    download root; the artifact is fetched from
+//                                <url>/bugsee-cli-<triple>.<ext> and verified
+//                                against <that>.sha256 — the same layout the
+//                                GitHub release and download.bugsee.com/cli
+//                                both use, so an internal mirror of either
+//                                works. Default: the GitHub release for this
+//                                package's version.
+
+"use strict";
+
+// ---------------------------------------------------------------------------
+// The safety net goes FIRST — above the requires, not below them.
+//
+// Everything from here down can throw: a corrupted lib/platforms.js, a
+// half-extracted package, a Node version that chokes on the syntax. A throw
+// during a top-level `require` is an uncaught exception, and an uncaught
+// exception in a postinstall exits non-zero and FAILS THE INSTALL — precisely
+// the outcome this file exists to prevent. Registering the handler after the
+// requires (as an earlier revision did) left exactly that hole: the file
+// claimed "even a bug in this script must not take an install down" while
+// corrupting lib/platforms.js produced exit 1.
+//
+// The logging helpers are defined here too, and swallow their own failures:
+// console.warn/error write to a pipe that npm may have closed, and an EPIPE
+// thrown from inside the handler would defeat the handler.
+// ---------------------------------------------------------------------------
+
+const warn = (msg) => {
+  try {
+    console.warn(`[@bugsee/cli] ${msg}`);
+  } catch {
+    /* EPIPE / closed stderr — nothing useful left to do */
+  }
+};
+const info = (msg) => {
+  try {
+    console.error(`[@bugsee/cli] ${msg}`);
+  } catch {
+    /* as above */
+  }
+};
+
+const describe = (err) => (err && err.message) || String(err);
+
+process.on("uncaughtException", (err) => {
+  warn(`postinstall failed: ${describe(err)}`);
+  process.exit(0);
+});
+process.on("unhandledRejection", (err) => {
+  warn(`postinstall failed: ${describe(err)}`);
+  process.exit(0);
+});
+process.exitCode = 0;
+
+const crypto = require("crypto");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const {
+  PLATFORMS,
+  artifactName,
+  currentTriple,
+} = require("../lib/platforms.js");
+const { resolveBinaryPath, diagnostic } = require("../lib/index.js");
+const { version } = require("../package.json");
+
+const DEFAULT_BASE_URL = `https://github.com/bugsee/bugsee-cli/releases/download/v${version}`;
+
+function baseUrl() {
+  const override = process.env.BUGSEE_CLI_BASE_URL;
+  return override ? override.replace(/\/+$/, "") : DEFAULT_BASE_URL;
+}
+
+function sha256(file) {
+  const hash = crypto.createHash("sha256");
+  hash.update(fs.readFileSync(file));
+  return hash.digest("hex");
+}
+
+// The sidecar is `<hex>  *<filename>` (coreutils/BSD format) — install.sh
+// reads it with `awk '{print $1}'`, and so do we.
+function parseChecksum(text) {
+  const token = text.trim().split(/\s+/)[0] || "";
+  return /^[0-9a-f]{64}$/i.test(token) ? token.toLowerCase() : null;
+}
+
+function extract(archive, destDir, ext) {
+  if (ext === ".tar.xz") {
+    // The tarball has a single top-level directory; both shell installers
+    // strip one component, so we match them exactly.
+    return spawnSync(
+      "tar",
+      ["xf", archive, "--strip-components", "1", "-C", destDir],
+      {
+        stdio: ["ignore", "ignore", "pipe"],
+        encoding: "utf8",
+      },
+    );
+  }
+  if (ext === ".zip") {
+    if (process.platform === "win32") {
+      // `unzip` is not present on a stock Windows image, so shell out to
+      // Expand-Archive — via `-File` and a real script. NOT `-Command`: that
+      // appends trailing arguments to the command TEXT instead of binding them
+      // to $args, so the paths would be lost (and the append is an injection
+      // shape). See the header of expand-archive.ps1.
+      //
+      // `-ExecutionPolicy Bypass` is required because the machine policy that
+      // blocks unsigned .ps1 files is the default on Windows Server images;
+      // it applies to this one invocation only.
+      return spawnSync(
+        "powershell.exe",
+        [
+          "-NoProfile",
+          "-NonInteractive",
+          "-ExecutionPolicy",
+          "Bypass",
+          "-File",
+          path.join(__dirname, "expand-archive.ps1"),
+          "-LiteralPath",
+          archive,
+          "-DestinationPath",
+          destDir,
+        ],
+        { stdio: ["ignore", "ignore", "pipe"], encoding: "utf8" },
+      );
+    }
+    return spawnSync("unzip", ["-q", "-o", archive, "-d", destDir], {
+      stdio: ["ignore", "ignore", "pipe"],
+      encoding: "utf8",
+    });
+  }
+  return { error: new Error(`unrecognised archive extension: ${ext}`) };
+}
+
+async function main() {
+  if (process.env.BUGSEE_CLI_SKIP_DOWNLOAD === "1") {
+    info("BUGSEE_CLI_SKIP_DOWNLOAD=1 — skipping the binary download.");
+    return;
+  }
+
+  // The happy path: npm already installed the right platform package. Do not
+  // touch the network — the overwhelming majority of installs land here.
+  const existing = resolveBinaryPath();
+  if (existing) {
+    info(`using ${existing}`);
+    return;
+  }
+
+  const triple = currentTriple();
+  if (!triple) {
+    warn(diagnostic());
+    return;
+  }
+
+  const platform = PLATFORMS[triple];
+  const asset = artifactName(triple);
+  const url = `${baseUrl()}/${asset}`;
+  const vendorDir = path.join(__dirname, "..", "vendor");
+  const target = path.join(vendorDir, platform.bin);
+
+  info(
+    `${platform.pkg} is not installed (optional dependencies skipped, or not ` +
+      `available on this registry) — downloading ${asset} instead.`,
+  );
+
+  const { get, getText } = require("./download.js");
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "bugsee-cli-"));
+  try {
+    const archive = path.join(tmp, asset);
+    const res = await get(url);
+    await new Promise((resolve, reject) => {
+      const sink = fs.createWriteStream(archive);
+      res.pipe(sink);
+      sink.on("error", reject);
+      res.on("error", reject);
+      sink.on("close", resolve);
+    });
+
+    // Verify before extracting, not after: the archive is what we fetched over
+    // the wire, and `tar`/`Expand-Archive` are the things we do not want to
+    // point at unverified bytes.
+    const expected = parseChecksum(await getText(`${url}.sha256`));
+    if (!expected)
+      throw new Error(`could not read checksum from ${url}.sha256`);
+    const actual = sha256(archive);
+    if (actual !== expected) {
+      throw new Error(
+        `checksum mismatch for ${asset}: expected ${expected}, got ${actual}`,
+      );
+    }
+
+    const result = extract(archive, tmp, platform.archiveExt);
+    if (result.error) throw result.error;
+    if (result.status !== 0) {
+      throw new Error(
+        `could not extract ${asset}: ${(result.stderr || "").toString().trim()}`,
+      );
+    }
+
+    const extracted = path.join(tmp, platform.bin);
+    if (!fs.existsSync(extracted)) {
+      throw new Error(`${platform.bin} not found after extracting ${asset}`);
+    }
+
+    fs.mkdirSync(vendorDir, { recursive: true });
+    fs.copyFileSync(extracted, target);
+    fs.chmodSync(target, 0o755);
+    info(`installed ${target} (sha256 ${actual})`);
+  } catch (err) {
+    warn(`could not download the bugsee-cli binary: ${err.message}`);
+    warn(
+      `\`bugsee-cli\` will report this if it is invoked. Re-run without ` +
+        `--no-optional, or set BUGSEE_CLI_BASE_URL to an internal mirror of ` +
+        `the release assets.`,
+    );
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+// The expected-failure paths are already handled inside main(); this catch is
+// for the unexpected ones. The process-level handlers registered at the top of
+// this file cover anything that escapes even this.
+main().catch((err) => {
+  warn(`postinstall failed: ${describe(err)}`);
+});