@flareapp/react-native-sourcemaps 2.6.0

package/README.md

@@ -0,0 +1,257 @@
+# @flareapp/react-native-sourcemaps
+
+Upload React Native (Metro) JavaScript sourcemaps to Flare so production stack
+traces are symbolicated.
+
+It has two halves that share one version string:
+
+1. A **Babel plugin** that inlines a build-time version into your app bundle.
+2. A **CLI** (`flare-rn-sourcemaps upload`) that uploads the `.map` under that
+   same version.
+
+> The manual CLI flow below works everywhere. For **bare React Native** you can also
+> wire the upload into the native release build so it happens automatically — see
+> "Automatic upload (bare React Native)" near the end. The Expo config plugin ships
+> separately.
+
+## Install
+
+```bash
+npm install --save-dev @flareapp/react-native-sourcemaps
+```
+
+## 1. Inline the version into your app
+
+Add the Babel plugin to `babel.config.js`:
+
+```js
+module.exports = {
+    presets: ['module:@react-native/babel-preset'],
+    plugins: ['@flareapp/react-native-sourcemaps/babel'],
+};
+```
+
+Then pass the inlined version when configuring Flare. Import `flareSourcemapVersion`
+from the package's runtime entry — it's a typed `string`, so there is no `process`
+global to type and no `@types/node` to add:
+
+```ts
+import { flare } from '@flareapp/react-native';
+import { flareSourcemapVersion } from '@flareapp/react-native-sourcemaps/runtime';
+
+flare.light(FLARE_KEY).configure({ sourcemapVersionId: flareSourcemapVersion });
+```
+
+The plugin replaces every reference to `flareSourcemapVersion` with the version it
+resolves at bundle time (and removes the import, so nothing of this package ships in
+your app bundle). Without the plugin the value is an empty string, which is harmless.
+Set the version in your build environment:
+
+```bash
+export FLARE_SOURCEMAP_VERSION="$(git rev-parse --short HEAD)"
+```
+
+If unset, it falls back to your app's `package.json` version (with a warning). Use the
+**same** version when you build the bundle and when you upload the map. If the two
+differ (for example the env var is set during the build but not during a later upload
+step, so one side falls back to `package.json`), the map will not match and
+symbolication silently fails.
+
+If your Babel config adds a generic `process.env` inliner (such as
+`babel-plugin-transform-inline-environment-variables`), list this plugin before it so
+the version token is not rewritten first. The default React Native and Expo presets do
+not inline `process.env`, so no ordering change is needed for a stock setup.
+
+## 2. Upload the sourcemap
+
+Generate a bundle + map, then upload the map under the **same** version:
+
+> Release builds use Hermes, which compiles your JS to bytecode. The map that
+> symbolicates production frames is the **Hermes-composed** map, not the plain Metro JS
+> map. Point `--sourcemap` at the composed `.map` your build emits (the one next to the
+> shipped bundle), not an intermediate Metro map.
+
+```bash
+# Example: Android, Hermes-composed map produced by your build
+npx flare-rn-sourcemaps upload \
+  --api-key "$FLARE_KEY" \
+  --sourcemap android/app/build/.../index.android.bundle.map \
+  --bundle-filename index.android.bundle \
+  --version "$FLARE_SOURCEMAP_VERSION"
+```
+
+Flags:
+
+| Flag                | Required | Description                                                                                    |
+| ------------------- | -------- | ---------------------------------------------------------------------------------------------- |
+| `--sourcemap`       | yes      | Path to the composed `.map` file.                                                              |
+| `--api-key`         | yes\*    | Flare API key. Falls back to `FLARE_API_KEY`.                                                  |
+| `--bundle-filename` | no       | `relative_filename` matched against runtime frames. Defaults to the map basename minus `.map`. |
+| `--version`         | no       | Defaults to `FLARE_SOURCEMAP_VERSION`, then `package.json` version.                            |
+| `--api-endpoint`    | no       | Defaults to `https://flareapp.io/api/sourcemaps`.                                              |
+
+\* Without a key the command warns and does nothing.
+
+## Automatic upload (bare React Native)
+
+Instead of running the CLI by hand, wire it into your native release build. Both
+hooks read a committed `flare.json` at your project root:
+
+```json
+{
+    "apiKey": "your-flare-api-key"
+}
+```
+
+To keep the key out of version control, drop it in a gitignored `.env.local` (or
+`.env`) next to `flare.json` instead — the hooks auto-load `FLARE_API_KEY` from there
+at build time:
+
+```bash
+# .env.local (gitignored)
+FLARE_API_KEY=your-flare-api-key
+```
+
+Precedence: shell env > `.env.local` > `.env` > `flare.json`. An explicit
+`FLARE_API_KEY` in the build environment wins over all of them.
+
+The version is taken **only** from `FLARE_SOURCEMAP_VERSION` here (the same variable
+the Babel plugin reads), so the inlined version and the uploaded version always match.
+Set it in your build environment:
+
+```bash
+export FLARE_SOURCEMAP_VERSION="$(git rev-parse --short HEAD)"
+```
+
+If the key or `FLARE_SOURCEMAP_VERSION` is missing, the upload is **skipped with a
+large warning banner** — your build never fails because of a sourcemap problem.
+
+### Android
+
+Add this line to `android/app/build.gradle`. It can go anywhere in the file — the script
+hooks the build lazily, so the order doesn't matter:
+
+```gradle
+apply from: "../../node_modules/@flareapp/react-native-sourcemaps/flare.gradle"
+```
+
+This uploads the Hermes-composed map after every `release` JS-bundle task.
+
+### iOS
+
+1. Tell the stock React Native bundle phase to emit a sourcemap by adding this line
+   to `ios/.xcode.env`:
+
+    ```sh
+    export SOURCEMAP_FILE="$TARGET_TEMP_DIR/main.jsbundle.map"
+    ```
+
+    Use `$TARGET_TEMP_DIR`, **not** `$CONFIGURATION_BUILD_DIR`. With Hermes,
+    `react-native-xcode.sh` writes an intermediate map to
+    `$CONFIGURATION_BUILD_DIR/main.jsbundle.map` and then deletes it after composing the
+    final map — so pointing `SOURCEMAP_FILE` there would have the composed map deleted
+    out from under the upload.
+
+2. In Xcode, add a new "Run Script" build phase named **Upload Flare sourcemaps**,
+   placed **after** "Bundle React Native code and images", with this script:
+
+    ```sh
+    set -e
+    WITH_ENVIRONMENT="../node_modules/react-native/scripts/xcode/with-environment.sh"
+    FLARE_XCODE="../node_modules/@flareapp/react-native-sourcemaps/scripts/flare-xcode.sh"
+    /bin/sh "$WITH_ENVIRONMENT" "$FLARE_XCODE"
+    ```
+
+    The `with-environment.sh` wrapper is required so the phase sees `SOURCEMAP_FILE`
+    (and any `FLARE_*` vars) exported by `.xcode.env`.
+
+3. In that build phase, **uncheck "Based on Dependency Analysis"**. With no input/output
+   files, Xcode otherwise warns that the script has ambiguous dependencies and runs on
+   every build — which is what you want for a release upload. (The Expo config plugin
+   sets this automatically.)
+
+> The key comes from `flare.json` or the auto-loaded `.env.local`, so it's there even
+> for a GUI build. The **version** (`FLARE_SOURCEMAP_VERSION`) is the one variable the
+> phase still reads from the **build's** environment, inherited from whatever launched
+> the build. `react-native run-ios`, `xcodebuild`, or Fastlane from a terminal that
+> exported it works; a build from the Xcode GUI (including Product > Archive) doesn't
+> have it, so archive from the command line or in CI for releases. The upload skips with
+> the banner if it's missing, and the build still succeeds.
+
+#### Custom build configurations (bare / brownfield)
+
+Your build configuration doesn't have to be called `Release`.
+
+The hooks upload whenever a build makes a JavaScript bundle. They skip a build only when
+its name contains `debug` (any casing).
+
+- Uploads: `Release`, `Staging`, `Production`, `AppStore`, your own Android build type
+- Skipped: `Debug`, `debug`, `StagingDebug`
+
+A debug build runs from Metro and makes no bundle, so there's nothing to upload. The hook
+skips it and your dev builds stay fast.
+
+Want a bundling config to skip the upload anyway? Put `debug` in its name. Or remove the
+Flare setup you added above — the `apply from "…/flare.gradle"` line in
+`android/app/build.gradle` on Android, or the **Upload Flare sourcemaps** build phase in
+Xcode on iOS — which turns the automatic upload off completely.
+
+### Expo (CNG / managed)
+
+For an Expo project that uses prebuild (CNG), add the config plugin to `app.json` —
+it injects the same native wiring on every prebuild, so it survives regeneration:
+
+```json
+{
+    "expo": {
+        "plugins": [["@flareapp/react-native-sourcemaps/expo", { "apiKey": "YOUR PROJECT KEY" }]]
+    }
+}
+```
+
+You still add the Babel plugin and pass `flareSourcemapVersion` (steps above), and you
+still set `FLARE_SOURCEMAP_VERSION` in the build environment (locally, or in
+`eas.json`'s `build.<profile>.env` for EAS Build). The plugin creates a `flare.json` at
+your project root and adds it to `.gitignore`. That's expected. You don't edit it; it's
+generated from your `app.json`.
+
+**Releasing without EAS?** You don't have to. The key comes from `flare.json` or the
+auto-loaded `.env.local`; the upload reads `FLARE_SOURCEMAP_VERSION` from the build's
+environment, inherited from whatever **launches** the build. So EAS Build (`eas.json`
+env), `eas build --local`, or a command-line archive (`xcodebuild` / Fastlane on iOS,
+`./gradlew bundleRelease` on Android) all work, as long as you exported the version in
+that shell.
+
+> The one exception is the version under the **Xcode / Android Studio GUI** (including
+> Product > Archive): it was launched by the OS, not your shell, so it doesn't have
+> `FLARE_SOURCEMAP_VERSION` and the upload skips with the banner. Archive from the
+> command line, or use EAS, for releases.
+
+> **`expo run:android` / `expo run:ios` are not a reliable upload path.** Both
+> eager-bundle the JS to a temp dir, and the native bundle task our hook runs after can
+> be reported **up-to-date** and skipped — so you get an installed app but no upload.
+> Changing only `FLARE_SOURCEMAP_VERSION` doesn't re-trigger it (it isn't a build
+> input). Use `expo run:*` for development, but **release and verify** through
+> `eas build` / `eas build --local` or a direct native build (`./gradlew
+:app:assembleRelease`, `xcodebuild`). When testing locally, add `--rerun-tasks` to the
+> Gradle command to force a fresh bundle and upload.
+
+> **OTA / EAS Update is not covered.** The plugin only runs during a native build
+> (`expo run:*`, EAS Build). `eas update` ships JS via `expo export` with no native
+> build phase, so it uploads no map. For OTA releases, upload the map yourself with
+> `flare-rn-sourcemaps upload` under the **same** `FLARE_SOURCEMAP_VERSION` you exported
+> with.
+
+## Expo (`expo export`)
+
+```bash
+FLARE_SOURCEMAP_VERSION="$(git rev-parse --short HEAD)" npx expo export
+npx flare-rn-sourcemaps upload \
+  --api-key "$FLARE_KEY" \
+  --sourcemap dist/_expo/static/js/ios/index-*.hbc.map \
+  --bundle-filename main.jsbundle \
+  --version "$FLARE_SOURCEMAP_VERSION"
+```
+
+> `--bundle-filename` must match how frames appear in your Flare reports. If
+> traces are not symbolicating, that is the value to adjust.

package/dist/babel.cjs

@@ -0,0 +1,52 @@
+const require_version = require('./version-Z9pawNvw.cjs');
+
+//#region src/babel.ts
+const RUNTIME_SOURCE = "@flareapp/react-native-sourcemaps/runtime";
+const EXPORT_NAME = "flareSourcemapVersion";
+/**
+* Babel plugin that inlines `flareSourcemapVersion` (imported from
+* `@flareapp/react-native-sourcemaps/runtime`) with the resolved version string at
+* bundle time, then removes the now-dead import so nothing of this package ships at
+* runtime. The version is resolved once per file (lazily, only when the import is
+* present) via the shared `resolveVersion()`.
+*/
+function flareSourcemapsBabelPlugin({ types: t }) {
+	let version;
+	return {
+		name: "@flareapp/react-native-sourcemaps",
+		pre() {
+			version = void 0;
+		},
+		visitor: { ImportDeclaration(path) {
+			if (path.node.source.value !== RUNTIME_SOURCE) return;
+			const remaining = [];
+			let inlinedAny = false;
+			for (const specifier of path.node.specifiers) {
+				if (!isFlareVersionSpecifier(specifier, t)) {
+					remaining.push(specifier);
+					continue;
+				}
+				const binding = path.scope.getBinding(specifier.local.name);
+				if (!binding) {
+					remaining.push(specifier);
+					continue;
+				}
+				if (version === void 0) version = require_version.resolveVersion();
+				for (const reference of binding.referencePaths) reference.replaceWith(t.stringLiteral(version));
+				inlinedAny = true;
+			}
+			if (!inlinedAny) return;
+			if (remaining.length === 0) path.remove();
+			else path.node.specifiers = remaining;
+		} }
+	};
+}
+/** Matches `import { flareSourcemapVersion } from '.../runtime'` (named, possibly aliased). */
+function isFlareVersionSpecifier(specifier, t) {
+	if (!t.isImportSpecifier(specifier)) return false;
+	const imported = specifier.imported;
+	return (t.isIdentifier(imported) ? imported.name : imported.value) === EXPORT_NAME;
+}
+
+//#endregion
+module.exports = flareSourcemapsBabelPlugin;

package/dist/babel.d.cts

@@ -0,0 +1,18 @@
+import { t as index_legacy_d_exports } from "./index-legacy-aO8l3fYt.cjs";
+import * as Babel from "@babel/core";
+
+//#region src/babel.d.ts
+type Types = typeof index_legacy_d_exports;
+/**
+ * Babel plugin that inlines `flareSourcemapVersion` (imported from
+ * `@flareapp/react-native-sourcemaps/runtime`) with the resolved version string at
+ * bundle time, then removes the now-dead import so nothing of this package ships at
+ * runtime. The version is resolved once per file (lazily, only when the import is
+ * present) via the shared `resolveVersion()`.
+ */
+declare function flareSourcemapsBabelPlugin({
+  types: t
+}: {
+  types: Types;
+}): Babel.PluginObj;
+export = flareSourcemapsBabelPlugin;

package/dist/babel.d.mts

@@ -0,0 +1,19 @@
+import { t as index_legacy_d_exports } from "./index-legacy-DeTFfC6B.mjs";
+import * as Babel from "@babel/core";
+
+//#region src/babel.d.ts
+type Types = typeof index_legacy_d_exports;
+/**
+ * Babel plugin that inlines `flareSourcemapVersion` (imported from
+ * `@flareapp/react-native-sourcemaps/runtime`) with the resolved version string at
+ * bundle time, then removes the now-dead import so nothing of this package ships at
+ * runtime. The version is resolved once per file (lazily, only when the import is
+ * present) via the shared `resolveVersion()`.
+ */
+declare function flareSourcemapsBabelPlugin({
+  types: t
+}: {
+  types: Types;
+}): Babel.PluginObj;
+//#endregion
+export { flareSourcemapsBabelPlugin as default };

package/dist/babel.mjs

@@ -0,0 +1,52 @@
+import { n as resolveVersion } from "./version-DnFqflPl.mjs";
+
+//#region src/babel.ts
+const RUNTIME_SOURCE = "@flareapp/react-native-sourcemaps/runtime";
+const EXPORT_NAME = "flareSourcemapVersion";
+/**
+* Babel plugin that inlines `flareSourcemapVersion` (imported from
+* `@flareapp/react-native-sourcemaps/runtime`) with the resolved version string at
+* bundle time, then removes the now-dead import so nothing of this package ships at
+* runtime. The version is resolved once per file (lazily, only when the import is
+* present) via the shared `resolveVersion()`.
+*/
+function flareSourcemapsBabelPlugin({ types: t }) {
+	let version;
+	return {
+		name: "@flareapp/react-native-sourcemaps",
+		pre() {
+			version = void 0;
+		},
+		visitor: { ImportDeclaration(path) {
+			if (path.node.source.value !== RUNTIME_SOURCE) return;
+			const remaining = [];
+			let inlinedAny = false;
+			for (const specifier of path.node.specifiers) {
+				if (!isFlareVersionSpecifier(specifier, t)) {
+					remaining.push(specifier);
+					continue;
+				}
+				const binding = path.scope.getBinding(specifier.local.name);
+				if (!binding) {
+					remaining.push(specifier);
+					continue;
+				}
+				if (version === void 0) version = resolveVersion();
+				for (const reference of binding.referencePaths) reference.replaceWith(t.stringLiteral(version));
+				inlinedAny = true;
+			}
+			if (!inlinedAny) return;
+			if (remaining.length === 0) path.remove();
+			else path.node.specifiers = remaining;
+		} }
+	};
+}
+/** Matches `import { flareSourcemapVersion } from '.../runtime'` (named, possibly aliased). */
+function isFlareVersionSpecifier(specifier, t) {
+	if (!t.isImportSpecifier(specifier)) return false;
+	const imported = specifier.imported;
+	return (t.isIdentifier(imported) ? imported.name : imported.value) === EXPORT_NAME;
+}
+
+//#endregion
+export { flareSourcemapsBabelPlugin as default };

package/dist/bin.cjs

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+const require_uploadSourcemaps = require('./uploadSourcemaps-D6J5FWDO.cjs');
+const require_version = require('./version-Z9pawNvw.cjs');
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+
+//#region src/banner.ts
+const BORDER = "=".repeat(60);
+/**
+* Mask an API key for display in a build log, which CI commonly archives. A key
+* long enough to stay unguessable keeps a short head/tail so the user can still
+* recognise WHICH key it was; a short key is fully masked. Never returns the key
+* in full, so the secret cannot leak through the failure banner.
+*/
+function maskApiKey(apiKey) {
+	if (apiKey.length <= 12) return "*".repeat(apiKey.length);
+	return `${apiKey.slice(0, 4)}${"*".repeat(8)}${apiKey.slice(-4)}`;
+}
+/**
+* The deliberately large failure banner. A one-line "failed to upload" is too easy
+* to miss in a long native-build log, so this is a bordered block surrounded by
+* blank lines. Resolved values are interpolated into the re-run command so the
+* user can copy-paste it; unknown values show a labelled placeholder (in the
+* version-unset case `version` stays a placeholder — it is the value to supply).
+* The API key is the one exception: it is MASKED, never printed in full, because
+* this banner lands in the native build log.
+*/
+function formatFailureBanner(info) {
+	const sourcemap = info.sourcemap ?? "<path-to-map>";
+	const bundleFilename = info.bundleFilename ?? "<bundle-filename>";
+	const version = info.version && info.version.length > 0 ? info.version : "<flare-sourcemap-version>";
+	const hasApiKey = !!(info.apiKey && info.apiKey.length > 0);
+	const apiKey = hasApiKey ? maskApiKey(info.apiKey) : "<your-flare-api-key>";
+	const endpointFlag = info.apiEndpoint ? ` --api-endpoint ${info.apiEndpoint}` : "";
+	const lines = [
+		"",
+		BORDER,
+		"  FLARE SOURCEMAP UPLOAD FAILED",
+		`  Reason: ${info.reason}`,
+		"  Your release will report minified stack traces until the",
+		"  sourcemap is uploaded. Re-run manually:",
+		`    npx flare-rn-sourcemaps upload --sourcemap ${sourcemap} \\`,
+		`      --bundle-filename ${bundleFilename} --version ${version} --api-key ${apiKey}${endpointFlag}`
+	];
+	if (hasApiKey) lines.push("  (the --api-key above is masked; pass your full Flare key, or set FLARE_API_KEY, when re-running)");
+	lines.push(BORDER, "");
+	return lines.join("\n");
+}
+function printFailureBanner(info) {
+	console.error(formatFailureBanner(info));
+}
+
+//#endregion
+//#region src/config.ts
+/**
+* Read flare.json from an EXPLICIT path. The hooks run from android/ or ios/, so
+* resolving relative to process.cwd() would read the wrong file — callers always
+* pass --config. Missing or malformed file → empty config, so resolution falls
+* through to env, then to the no-key skip-with-banner. Any `version` key is
+* deliberately ignored: in the auto path the version flows only through
+* FLARE_SOURCEMAP_VERSION (see resolveAutoVersion / the design doc).
+*/
+function readFlareConfig(configPath) {
+	if (!configPath) return {};
+	try {
+		const raw = JSON.parse((0, node_fs.readFileSync)(configPath, "utf8"));
+		const config = {};
+		const apiKey = asString(raw.apiKey);
+		const apiEndpoint = asString(raw.apiEndpoint);
+		if (apiKey !== void 0) config.apiKey = apiKey;
+		if (apiEndpoint !== void 0) config.apiEndpoint = apiEndpoint;
+		return config;
+	} catch {
+		return {};
+	}
+}
+function asString(value) {
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+
+//#endregion
+//#region src/env.ts
+const ENV_FILES = [".env.local", ".env"];
+/**
+* Load FLARE_* variables from .env.local / .env in `rootDir` into process.env,
+* without overwriting anything already set.
+*
+* The native build hooks run in a fresh process whose environment often does NOT
+* carry the upload key: the app's .env files are loaded by Metro at JS runtime, not
+* at native build time, and a build launched from an IDE — or served by a reused
+* Gradle daemon with a stale environment — won't see a key you exported in your
+* shell. Reading the key from the FILE here makes "drop FLARE_API_KEY in .env.local"
+* work the way developers expect, on both platforms, without re-exporting it per
+* build.
+*
+* Only FLARE_-prefixed keys are read, so this never pulls unrelated secrets from the
+* file into the process. Minimal parser (no dependency): `KEY=value`, an optional
+* `export ` prefix, surrounding single/double quotes stripped, blank and `#` comment
+* lines ignored. Inline comments are NOT stripped (a `#` is treated as part of the
+* value), which is fine for the alphanumeric keys Flare issues.
+*/
+function loadEnvFiles(rootDir) {
+	for (const file of ENV_FILES) {
+		let raw;
+		try {
+			raw = (0, node_fs.readFileSync)((0, node_path.join)(rootDir, file), "utf8");
+		} catch {
+			continue;
+		}
+		for (const [key, value] of parseFlareEnv(raw)) if (process.env[key] === void 0) process.env[key] = value;
+	}
+}
+function parseFlareEnv(raw) {
+	const out = [];
+	for (const line of raw.split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (trimmed === "" || trimmed.startsWith("#")) continue;
+		const body = trimmed.startsWith("export ") ? trimmed.slice(7).trim() : trimmed;
+		const eq = body.indexOf("=");
+		if (eq === -1) continue;
+		const key = body.slice(0, eq).trim();
+		if (!key.startsWith("FLARE_")) continue;
+		let value = body.slice(eq + 1).trim();
+		if ((value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) && value.length >= 2) value = value.slice(1, -1);
+		out.push([key, value]);
+	}
+	return out;
+}
+
+//#endregion
+//#region src/cli.ts
+const USAGE = "Usage: flare-rn-sourcemaps upload --sourcemap <path> [--api-key <key>] [--bundle-filename <name>] [--version <v>] [--api-endpoint <url>] [--config <flare.json>] [--auto]";
+/** Minimal `--flag value` / `--flag` parser. No external dependency. */
+function parseArgs(argv) {
+	const [command, ...rest] = argv;
+	const flags = {};
+	for (let i = 0; i < rest.length; i++) {
+		const arg = rest[i];
+		if (!arg.startsWith("--")) continue;
+		const body = arg.slice(2);
+		const eq = body.indexOf("=");
+		if (eq !== -1) {
+			flags[body.slice(0, eq)] = body.slice(eq + 1);
+			continue;
+		}
+		const key = body;
+		const next = rest[i + 1];
+		if (next !== void 0 && !next.startsWith("--")) {
+			flags[key] = next;
+			i++;
+		} else flags[key] = "true";
+	}
+	return {
+		command,
+		flags
+	};
+}
+async function runCli(argv) {
+	const { command, flags } = parseArgs(argv);
+	if (command !== "upload") {
+		console.error(`${require_version.LOG_PREFIX}: Unknown command "${command ?? ""}".\n${USAGE}`);
+		process.exitCode = 1;
+		return;
+	}
+	const sourcemap = flags.sourcemap;
+	if (!sourcemap) {
+		console.error(`${require_version.LOG_PREFIX}: --sourcemap is required.\n${USAGE}`);
+		process.exitCode = 1;
+		return;
+	}
+	if (flags.auto === "true") loadEnvFiles(flags.config ? (0, node_path.dirname)(flags.config) : process.cwd());
+	const config = readFlareConfig(flags.config);
+	const apiKey = flags["api-key"] ?? process.env.FLARE_API_KEY ?? config.apiKey ?? "";
+	const apiEndpoint = flags["api-endpoint"] ?? process.env.FLARE_API_ENDPOINT ?? config.apiEndpoint;
+	const bundleFilename = flags["bundle-filename"];
+	if (flags.auto === "true") {
+		await runAutoUpload({
+			apiKey,
+			sourcemap,
+			bundleFilename,
+			apiEndpoint,
+			version: flags.version
+		});
+		return;
+	}
+	await require_uploadSourcemaps.uploadSourcemaps({
+		apiKey,
+		sourcemap,
+		bundleFilename,
+		version: flags.version,
+		apiEndpoint
+	});
+}
+/**
+* The build-hook upload path. It NEVER throws and NEVER sets a non-zero exit code
+* (a Gradle doLast / Xcode run-script phase would abort the build on a non-zero
+* child). Every failure mode — no key, unresolved version, upload error — prints the
+* loud banner and returns, leaving the build green. Only arg misuse (handled in
+* runCli before we get here) exits non-zero.
+*/
+async function runAutoUpload(options) {
+	const { apiKey, sourcemap, bundleFilename, apiEndpoint } = options;
+	if (!apiKey) {
+		printFailureBanner({
+			reason: "No Flare API key. Set FLARE_API_KEY (shell, .env.local, or .env) or add \"apiKey\" to flare.json.",
+			sourcemap,
+			bundleFilename,
+			apiKey,
+			apiEndpoint
+		});
+		return;
+	}
+	const version = require_version.resolveAutoVersion(options.version);
+	if (!version) {
+		printFailureBanner({
+			reason: "FLARE_SOURCEMAP_VERSION is not set (required for the automatic upload).",
+			sourcemap,
+			bundleFilename,
+			apiKey,
+			apiEndpoint
+		});
+		return;
+	}
+	try {
+		await require_uploadSourcemaps.uploadSourcemaps({
+			apiKey,
+			sourcemap,
+			bundleFilename,
+			version,
+			apiEndpoint
+		});
+	} catch (error) {
+		printFailureBanner({
+			reason: error instanceof Error ? error.message : String(error),
+			sourcemap,
+			bundleFilename,
+			version,
+			apiKey,
+			apiEndpoint
+		});
+	}
+}
+
+//#endregion
+//#region src/bin.ts
+runCli(process.argv.slice(2)).catch((error) => {
+	console.error(error);
+	process.exitCode = 1;
+});
+
+//#endregion

package/dist/bin.d.cts

@@ -0,0 +1 @@
+export { };

package/dist/bin.d.mts

@@ -0,0 +1 @@
+export { };