@fixback/cli 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fixback
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,6 +5,8 @@ production build's sourcemaps** so the Issues Fixback captures on your site
 arrive with a symbolicated **code-area pointer** — the original `file:line`
 (with source context) where the error likely lives, not a minified frame.
 
+> 📖 **Full documentation: [docs.fixback.dev/sdk/sourcemaps](https://docs.fixback.dev/sdk/sourcemaps)** — the source maps guide and the CLI reference.
+
 ```bash
 # after your production build, locally or in CI
 FIXBACK_SECRET_KEY=sk_… npx @fixback/cli sourcemaps upload ./dist
@@ -13,6 +15,11 @@ FIXBACK_SECRET_KEY=sk_… npx @fixback/cli sourcemaps upload ./dist
 That's the whole integration. If a release has no uploaded sourcemaps, nothing
 changes — the feature is simply off for it.
 
+> **Using Vite?** [`@fixback/vite-plugin`](../vite-plugin) does this automatically
+> as part of `vite build`, so there's no separate CI step to add or forget. Reach
+> for this CLI when your build isn't Vite, or when you want the upload decoupled
+> from the build.
+
 ## How it fits together
 
 1. **Build with sourcemaps.** e.g. Vite: `build: { sourcemap: true }` (or

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@fixback/cli` doubles as the **build-time sourcemap library** shared with the
+ * bundler plugins (e.g. `@fixback/vite-plugin`): the one implementation of
+ * sourcemap discovery, the (release, `~/`-abstract path) upload wire (ADR-0024),
+ * the upload loop, and release resolution. The `fixback` bin (`cli.ts`) is a thin
+ * command wrapper over these same functions — importing this module runs none of it.
+ */
+export { discoverSourcemaps, postSourcemap, toArtifactPath, uploadAll, uploadSourcemaps, } from "./upload.js";
+export type { DiscoveredMap, PostSourcemapOptions, PostSourcemapResult, UploadAllDeps, UploadAllResult, UploadDeps, UploadOptions, } from "./upload.js";
+export { normaliseRelease, RELEASE_MAX_LENGTH, resolveRelease, } from "./release.js";
+export type { ResolveReleaseInput, ResolveReleaseResult } from "./release.js";
+export { gitHeadSha } from "./main.js";
+export { DEFAULT_API_URL } from "@fixback/sdk-core";

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * `@fixback/cli` doubles as the **build-time sourcemap library** shared with the
+ * bundler plugins (e.g. `@fixback/vite-plugin`): the one implementation of
+ * sourcemap discovery, the (release, `~/`-abstract path) upload wire (ADR-0024),
+ * the upload loop, and release resolution. The `fixback` bin (`cli.ts`) is a thin
+ * command wrapper over these same functions — importing this module runs none of it.
+ */
+export { discoverSourcemaps, postSourcemap, toArtifactPath, uploadAll, uploadSourcemaps, } from "./upload.js";
+export { normaliseRelease, RELEASE_MAX_LENGTH, resolveRelease, } from "./release.js";
+export { gitHeadSha } from "./main.js";
+// The hosted API origin is defined once in the shared core (ADR-0028); re-exported
+// here so the bundler plugins take their default from the same constant the SDKs do.
+export { DEFAULT_API_URL } from "@fixback/sdk-core";

package/dist/main.d.ts

@@ -0,0 +1,11 @@
+import { type UploadDeps } from "./upload.js";
+/** Everything the CLI touches outside its own logic — injectable for tests. */
+export interface CliDeps extends UploadDeps {
+    readonly env: NodeJS.ProcessEnv;
+    /** Resolve the git HEAD SHA of the working directory, or null when not a repo. */
+    readonly resolveGitSha: () => Promise<string | null>;
+}
+/** The production `resolveGitSha`: `git rev-parse HEAD`, null on any failure. */
+export declare function gitHeadSha(): Promise<string | null>;
+/** Run the CLI; returns the process exit code. */
+export declare function runCli(argv: readonly string[], deps: CliDeps): Promise<number>;

package/dist/main.js

@@ -1,6 +1,7 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { normaliseRelease } from "./release.js";
+import { DEFAULT_API_URL } from "@fixback/sdk-core";
+import { resolveRelease } from "./release.js";
 import { uploadSourcemaps } from "./upload.js";
 /**
  * The `fixback` CLI (#117, ADR-0024) — Fixback's build-time companion, Sentry-
@@ -13,8 +14,6 @@ import { uploadSourcemaps } from "./upload.js";
  * Everything is injectable (`CliDeps`) so the command is tested without a
  * network, a repo, or real env.
  */
-/** The hosted API origin, mirrored by value from the SDK's `DEFAULT_API_URL`. */
-const DEFAULT_API_URL = "https://api.fixback.dev";
 const USAGE = `fixback — Fixback's build-time CLI
 
 Usage:
@@ -82,22 +81,22 @@ export async function runCli(argv, deps) {
         deps.error(`Missing <dir> — the build output directory to scan.\n\n${USAGE}`);
         return 1;
     }
-    // Release: flag > env > git HEAD SHA (Sentry's propose-version equivalent).
+    // Release: flag > env > git HEAD SHA — the precedence the bundler plugins share
+    // (`resolveRelease`), so a plugin upload and a CLI upload key maps identically.
     const flagRelease = flags.get("release");
-    const rawRelease = (typeof flagRelease === "string" ? flagRelease : undefined) ??
-        deps.env.FIXBACK_RELEASE ??
-        (await deps.resolveGitSha()) ??
-        undefined;
-    if (!rawRelease) {
-        deps.error("No release given and no git repository found. Pass --release <r> or set FIXBACK_RELEASE.");
-        return 1;
-    }
-    const release = normaliseRelease(rawRelease);
-    if (!release) {
-        deps.error(`Invalid release ${JSON.stringify(rawRelease)} — use 1-100 visible characters ` +
-            "with no whitespace or slashes (e.g. a git SHA or semver).");
+    const resolved = await resolveRelease({
+        release: typeof flagRelease === "string" ? flagRelease : undefined,
+        env: deps.env,
+        resolveGitSha: deps.resolveGitSha,
+    });
+    if (!resolved.ok) {
+        deps.error(resolved.reason === "missing"
+            ? "No release given and no git repository found. Pass --release <r> or set FIXBACK_RELEASE."
+            : `Invalid release ${JSON.stringify(resolved.raw)} — use 1-100 visible characters ` +
+                "with no whitespace or slashes (e.g. a git SHA or semver).");
         return 1;
     }
+    const release = resolved.release;
     const dryRun = flags.get("dry-run") === true;
     const flagKey = flags.get("key");
     const secretKey = (typeof flagKey === "string" ? flagKey : undefined) ??

package/dist/release.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Resolving a build's **Release** — the one precedence rule shared by the
+ * `fixback` CLI and the bundler plugins (`@fixback/vite-plugin`).
+ *
+ * A release is only useful if the value the build uploads maps under is the value
+ * the SDK stamps on its captures (#117, ADR-0024). Two things have to agree for
+ * that: the *validation* (which lives once in `@fixback/sdk-core`, shared with the
+ * SDKs themselves) and the *precedence* — an explicit value, else `FIXBACK_RELEASE`,
+ * else the git HEAD SHA (Sentry's propose-version equivalent). The precedence used
+ * to be written out twice, once per caller; it is {@link resolveRelease} now.
+ */
+import { normaliseRelease, RELEASE_MAX_LENGTH } from "@fixback/sdk-core";
+export { normaliseRelease, RELEASE_MAX_LENGTH };
+/** What {@link resolveRelease} reads, in precedence order. */
+export interface ResolveReleaseInput {
+    /** An explicitly configured release (a `--release` flag, a plugin option). */
+    readonly release?: string;
+    /** The process environment — `FIXBACK_RELEASE` is the second source. */
+    readonly env: {
+        readonly FIXBACK_RELEASE?: string | undefined;
+    };
+    /** The git HEAD SHA, or `null` when the build is not in a repo — the fallback. */
+    readonly resolveGitSha: () => Promise<string | null>;
+}
+/**
+ * A resolved release, or *why* there is none — `missing` (nothing configured and
+ * no repo to fall back on) versus `invalid` (a value that would be discarded
+ * server-side). The two need different messages, so they stay distinct rather than
+ * collapsing to `undefined`.
+ */
+export type ResolveReleaseResult = {
+    readonly ok: true;
+    readonly release: string;
+} | {
+    readonly ok: false;
+    readonly reason: "missing";
+} | {
+    readonly ok: false;
+    readonly reason: "invalid";
+    readonly raw: string;
+};
+/**
+ * Resolve the release to upload under: an explicit value, else `FIXBACK_RELEASE`,
+ * else the git HEAD SHA — then validate it with the shared rules.
+ */
+export declare function resolveRelease(input: ResolveReleaseInput): Promise<ResolveReleaseResult>;

package/dist/release.js

@@ -1,22 +1,27 @@
 /**
- * Release validation, mirrored **by value** from the server's shared rules
- * (`@fixback/shared`'s `isValidRelease`) — the CLI publishes standalone and the
- * shared package is workspace-private, so the slice it needs is vendored, the
- * same rule the SDK follows. Keep in lock-step with the server: 1–100 visible
- * characters, no whitespace / control characters / path separators, not a
- * reserved name.
+ * Resolving a build's **Release** — the one precedence rule shared by the
+ * `fixback` CLI and the bundler plugins (`@fixback/vite-plugin`).
+ *
+ * A release is only useful if the value the build uploads maps under is the value
+ * the SDK stamps on its captures (#117, ADR-0024). Two things have to agree for
+ * that: the *validation* (which lives once in `@fixback/sdk-core`, shared with the
+ * SDKs themselves) and the *precedence* — an explicit value, else `FIXBACK_RELEASE`,
+ * else the git HEAD SHA (Sentry's propose-version equivalent). The precedence used
+ * to be written out twice, once per caller; it is {@link resolveRelease} now.
  */
-const RELEASE_MAX_LENGTH = 100;
-const RESERVED_RELEASES = new Set([".", "..", "latest"]);
-/** Trim + validate a release; `undefined` when unusable. */
-export function normaliseRelease(value) {
-    const trimmed = value.trim();
-    if (trimmed.length === 0 || trimmed.length > RELEASE_MAX_LENGTH)
-        return undefined;
-    if (RESERVED_RELEASES.has(trimmed))
-        return undefined;
-    // eslint-disable-next-line no-control-regex
-    if (/[\s/\\\u0000-\u001f\u007f]/.test(trimmed))
-        return undefined;
-    return trimmed;
+import { normaliseRelease, RELEASE_MAX_LENGTH } from "@fixback/sdk-core";
+// Release validation is the shared core's (ADR-0028) — the SDKs validate what they
+// stamp with the very same function. Re-exported so `@fixback/cli` consumers (and
+// the bundler plugins) keep one import path for it.
+export { normaliseRelease, RELEASE_MAX_LENGTH };
+/**
+ * Resolve the release to upload under: an explicit value, else `FIXBACK_RELEASE`,
+ * else the git HEAD SHA — then validate it with the shared rules.
+ */
+export async function resolveRelease(input) {
+    const raw = input.release ?? input.env.FIXBACK_RELEASE ?? (await input.resolveGitSha()) ?? undefined;
+    if (!raw)
+        return { ok: false, reason: "missing" };
+    const release = normaliseRelease(raw);
+    return release ? { ok: true, release } : { ok: false, reason: "invalid", raw };
 }

package/dist/upload.d.ts

@@ -0,0 +1,94 @@
+/** One discovered sourcemap: where it is on disk, and the bundle path it maps. */
+export interface DiscoveredMap {
+    /** Absolute path of the `.map` file on disk. */
+    readonly filePath: string;
+    /** The generated bundle's path relative to the build dir, POSIX-separated (no `.map`). */
+    readonly bundlePath: string;
+}
+/**
+ * Walk a build directory for JS sourcemaps. The bundle path is the map's
+ * relative path minus `.map` (a `.js.map` maps the `.js` beside it), normalised
+ * to POSIX separators — ready to be joined onto the `~/` prefix.
+ */
+export declare function discoverSourcemaps(dir: string): Promise<DiscoveredMap[]>;
+/** Join the `~/` URL prefix and a bundle-relative path into the abstract path. */
+export declare function toArtifactPath(urlPrefix: string, bundlePath: string): string;
+export interface UploadOptions {
+    readonly dir: string;
+    readonly release: string;
+    /** The abstract prefix bundles are served under. Defaults to `~/`. */
+    readonly urlPrefix: string;
+    readonly apiUrl: string;
+    readonly secretKey: string;
+    /** List what would upload without any network. */
+    readonly dryRun: boolean;
+}
+export interface UploadDeps {
+    readonly fetch: typeof globalThis.fetch;
+    readonly log: (line: string) => void;
+    readonly error: (line: string) => void;
+}
+/** Just the fields `postSourcemap` needs — a structural subset of {@link UploadOptions}. */
+export interface PostSourcemapOptions {
+    readonly release: string;
+    readonly urlPrefix: string;
+    readonly apiUrl: string;
+    readonly secretKey: string;
+}
+/** The outcome of one artifact POST. */
+export interface PostSourcemapResult {
+    readonly ok: boolean;
+    /** The HTTP status, or `0` if the request itself never completed. */
+    readonly status: number;
+    /** The `~/`-abstract path the artifact was keyed under. */
+    readonly artifactPath: string;
+    /** A human-readable failure reason; present only when `ok` is false. */
+    readonly message?: string;
+}
+/**
+ * POST one discovered sourcemap to `POST /api/sourcemaps`, keyed by
+ * (release, `~/`-abstract path) and authenticated with the Project's secret key.
+ * The single implementation of the ADR-0024 upload wire — shared by the CLI's
+ * {@link uploadSourcemaps} loop and the bundler plugins (`@fixback/vite-plugin`),
+ * so both key artifacts identically. It never throws on an API error (that is
+ * reported through the result); a transport failure still rejects, for the caller
+ * to handle.
+ */
+export declare function postSourcemap(map: DiscoveredMap, options: PostSourcemapOptions, deps: Pick<UploadDeps, "fetch">): Promise<PostSourcemapResult>;
+/** The outcome of an {@link uploadAll} run. */
+export interface UploadAllResult {
+    /** The `.map` files that landed, by absolute path — what a caller may prune. */
+    readonly uploaded: string[];
+    /** How many maps failed (an API refusal or a transport error). */
+    readonly failed: number;
+    /** Whether the loop stopped early on a `401` (every remaining map would fail too). */
+    readonly stoppedOnAuth: boolean;
+}
+/** Injectable collaborators for {@link uploadAll}. */
+export interface UploadAllDeps {
+    readonly fetch: typeof globalThis.fetch;
+    /**
+     * Called once per map with its outcome, so each caller reports in its own voice
+     * (the CLI logs lines and returns an exit code; the plugin warns through Vite's
+     * logger). A transport failure arrives here as a `status: 0` result rather than
+     * a throw, so one unreachable request never abandons the remaining maps.
+     */
+    readonly onResult?: (map: DiscoveredMap, result: PostSourcemapResult) => void;
+}
+/**
+ * POST every discovered map for one release — the single upload loop behind both
+ * `fixback sourcemaps upload` and the bundler plugins, so a plugin upload and a
+ * CLI upload keep byte-for-byte identical wire behaviour (ADR-0024).
+ *
+ * It reports rather than decides: no logging, no exit code, no pruning. A `401`
+ * **breaks the loop** — an invalid secret key would fail identically for every
+ * remaining map, and hammering the API with the rest tells no one anything new.
+ */
+export declare function uploadAll(maps: readonly DiscoveredMap[], options: PostSourcemapOptions, deps: UploadAllDeps): Promise<UploadAllResult>;
+/**
+ * Upload every discovered map for one release. Returns a process exit code:
+ * `0` when everything (or a clean dry run) succeeded, `1` when nothing was
+ * found or any upload failed — CI should fail loudly rather than silently
+ * shipping a release without symbolication.
+ */
+export declare function uploadSourcemaps(options: UploadOptions, deps: UploadDeps): Promise<number>;

package/dist/upload.js

@@ -51,6 +51,74 @@ async function apiErrorMessage(response) {
     }
     return response.statusText || `HTTP ${response.status}`;
 }
+/**
+ * POST one discovered sourcemap to `POST /api/sourcemaps`, keyed by
+ * (release, `~/`-abstract path) and authenticated with the Project's secret key.
+ * The single implementation of the ADR-0024 upload wire — shared by the CLI's
+ * {@link uploadSourcemaps} loop and the bundler plugins (`@fixback/vite-plugin`),
+ * so both key artifacts identically. It never throws on an API error (that is
+ * reported through the result); a transport failure still rejects, for the caller
+ * to handle.
+ */
+export async function postSourcemap(map, options, deps) {
+    const path = toArtifactPath(options.urlPrefix, map.bundlePath);
+    const body = new FormData();
+    body.set("payload", JSON.stringify({ release: options.release, path }));
+    body.set("map", new Blob([await readFile(map.filePath)], { type: "application/json" }), `${map.bundlePath.split("/").pop() ?? "bundle.js"}.map`);
+    const response = await deps.fetch(`${options.apiUrl}/api/sourcemaps`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${options.secretKey}` },
+        body,
+    });
+    if (response.ok)
+        return { ok: true, status: response.status, artifactPath: path };
+    return {
+        ok: false,
+        status: response.status,
+        artifactPath: path,
+        message: await apiErrorMessage(response),
+    };
+}
+/**
+ * POST every discovered map for one release — the single upload loop behind both
+ * `fixback sourcemaps upload` and the bundler plugins, so a plugin upload and a
+ * CLI upload keep byte-for-byte identical wire behaviour (ADR-0024).
+ *
+ * It reports rather than decides: no logging, no exit code, no pruning. A `401`
+ * **breaks the loop** — an invalid secret key would fail identically for every
+ * remaining map, and hammering the API with the rest tells no one anything new.
+ */
+export async function uploadAll(maps, options, deps) {
+    const uploaded = [];
+    let failed = 0;
+    let stoppedOnAuth = false;
+    for (const map of maps) {
+        let result;
+        try {
+            result = await postSourcemap(map, options, { fetch: deps.fetch });
+        }
+        catch (error) {
+            result = {
+                ok: false,
+                status: 0,
+                artifactPath: toArtifactPath(options.urlPrefix, map.bundlePath),
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+        deps.onResult?.(map, result);
+        if (result.ok) {
+            uploaded.push(map.filePath);
+            continue;
+        }
+        failed += 1;
+        // 401 means every remaining upload will fail identically — stop early.
+        if (result.status === 401) {
+            stoppedOnAuth = true;
+            break;
+        }
+    }
+    return { uploaded, failed, stoppedOnAuth };
+}
 /**
  * Upload every discovered map for one release. Returns a process exit code:
  * `0` when everything (or a clean dry run) succeeded, `1` when nothing was
@@ -64,36 +132,24 @@ export async function uploadSourcemaps(options, deps) {
             "Enable them in your build (e.g. Vite: build.sourcemap = true) and re-run.");
         return 1;
     }
-    let failed = 0;
-    for (const map of maps) {
-        const path = toArtifactPath(options.urlPrefix, map.bundlePath);
-        if (options.dryRun) {
-            deps.log(`would upload ${map.bundlePath}.map as ${path}`);
-            continue;
-        }
-        const body = new FormData();
-        body.set("payload", JSON.stringify({ release: options.release, path }));
-        body.set("map", new Blob([await readFile(map.filePath)], { type: "application/json" }), `${map.bundlePath.split("/").pop() ?? "bundle.js"}.map`);
-        const response = await deps.fetch(`${options.apiUrl}/api/sourcemaps`, {
-            method: "POST",
-            headers: { Authorization: `Bearer ${options.secretKey}` },
-            body,
-        });
-        if (response.ok) {
-            deps.log(`uploaded ${map.bundlePath}.map as ${path}`);
-        }
-        else {
-            failed += 1;
-            deps.error(`failed ${map.bundlePath}.map (${response.status}): ${await apiErrorMessage(response)}`);
-            // 401 means every remaining upload will fail identically — stop early.
-            if (response.status === 401)
-                break;
-        }
-    }
     if (options.dryRun) {
+        for (const map of maps) {
+            deps.log(`would upload ${map.bundlePath}.map as ${toArtifactPath(options.urlPrefix, map.bundlePath)}`);
+        }
         deps.log(`Dry run: ${maps.length} sourcemap(s) would upload for release ${options.release}.`);
         return 0;
     }
+    const { failed } = await uploadAll(maps, options, {
+        fetch: deps.fetch,
+        onResult: (map, result) => {
+            if (result.ok) {
+                deps.log(`uploaded ${map.bundlePath}.map as ${result.artifactPath}`);
+            }
+            else {
+                deps.error(`failed ${map.bundlePath}.map (${result.status}): ${result.message ?? "upload failed"}`);
+            }
+        },
+    });
     if (failed > 0) {
         deps.error(`${failed} upload(s) failed for release ${options.release}.`);
         return 1;

package/package.json

@@ -1,24 +1,54 @@
 {
   "name": "@fixback/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Fixback's build-time CLI — upload sourcemaps per release so Issues gain symbolicated code-area pointers.",
   "license": "MIT",
+  "homepage": "https://docs.fixback.dev/sdk/sourcemaps",
   "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "fixback": "./dist/cli.js"
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=20.12"
   },
   "devDependencies": {
-    "@types/node": "^22.18.13",
+    "@types/node": "^22.20.1",
     "typescript": "5.9.3",
     "vitest": "^4.1.10"
   },
+  "sideEffects": false,
+  "keywords": [
+    "fixback",
+    "sourcemaps",
+    "source-maps",
+    "cli",
+    "symbolication"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wemuda/fixback.git",
+    "directory": "packages/cli"
+  },
+  "bugs": "https://docs.fixback.dev",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@fixback/sdk-core": "0.3.0"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "lint": "eslint .",