@fixback/cli 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# @fixback/cli
+
+Fixback's build-time companion. Today it does one thing: **upload your
+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.
+
+```bash
+# after your production build, locally or in CI
+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.
+
+## How it fits together
+
+1. **Build with sourcemaps.** e.g. Vite: `build: { sourcemap: true }` (or
+   `"hidden"` to keep maps out of the served site — the CLI reads them from
+   disk either way).
+2. **Upload them per release.** The CLI scans the build directory for
+   `*.js.map` files and uploads each, keyed by a **release** — `--release`,
+   else `FIXBACK_RELEASE`, else the current git commit SHA.
+3. **Tell the SDK the same release:**
+
+   ```js
+   Fixback.init({ key: "pk_…", release: "<the same release>" });
+   ```
+
+   Captured errors then carry that release, and Fixback's analysis
+   symbolicates their stack traces against the matching maps.
+
+## Auth
+
+Uploads authenticate with your Project's **secret key** (Project settings →
+API keys), via `FIXBACK_SECRET_KEY` or `--key`. It's the server-side
+credential your CI already holds — never ship it in the page (that's what the
+publishable `pk_…` key is for).
+
+## Options
+
+| Flag | Default | |
+|---|---|---|
+| `--release <r>` | `$FIXBACK_RELEASE`, else git HEAD SHA | Build identifier (1–100 visible chars, no spaces/slashes) |
+| `--url-prefix <p>` | `~/` | Where bundles are served relative to the site root, e.g. `~/static` |
+| `--api-url <u>` | `$FIXBACK_API_URL`, else the hosted API | Self-hosted deployments point here |
+| `--key <sk_…>` | `$FIXBACK_SECRET_KEY` | Project secret key |
+| `--dry-run` | — | List what would upload; no network, no key needed |
+
+## Notes
+
+- Re-running an upload for the same release is safe — artifacts upsert.
+- Retention is bounded: Fixback keeps your newest releases and prunes the
+  oldest beyond the per-project cap.
+- Only JS maps (`.js.map` / `.mjs.map` / `.cjs.map`) upload — CSS maps can't
+  symbolicate a stack trace.

package/dist/cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { gitHeadSha, runCli } from "./main.js";
+/**
+ * The `fixback` bin entry: real deps in, exit code out. All logic lives in
+ * `runCli` (tested); this file only binds the process edges.
+ */
+runCli(process.argv.slice(2), {
+    env: process.env,
+    resolveGitSha: gitHeadSha,
+    fetch: globalThis.fetch,
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+}).then((code) => process.exit(code), (error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/main.js

@@ -0,0 +1,127 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { normaliseRelease } from "./release.js";
+import { uploadSourcemaps } from "./upload.js";
+/**
+ * The `fixback` CLI (#117, ADR-0024) — Fixback's build-time companion, Sentry-
+ * style: run it after your production build (locally or in CI) to ship the
+ * build's sourcemaps, and errors captured on that release arrive with a
+ * symbolicated code-area pointer.
+ *
+ *   FIXBACK_SECRET_KEY=sk_… npx fixback sourcemaps upload ./dist
+ *
+ * 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:
+  fixback sourcemaps upload <dir> [options]
+
+Uploads the JS sourcemaps a production build emitted so Fixback can
+symbolicate captured stack traces into code-area pointers (set the same
+release in the SDK: Fixback.init({ release: "<release>" })).
+
+Options:
+  --release <r>     Build identifier (default: $FIXBACK_RELEASE, else the git HEAD SHA)
+  --url-prefix <p>  Abstract path prefix bundles are served under (default: ~/)
+  --api-url <u>     Fixback API origin (default: $FIXBACK_API_URL, else ${DEFAULT_API_URL})
+  --key <sk_…>      Project secret key (default: $FIXBACK_SECRET_KEY)
+  --dry-run         List what would upload; no network, no key needed
+  --help            Show this help
+`;
+/** The production `resolveGitSha`: `git rev-parse HEAD`, null on any failure. */
+export async function gitHeadSha() {
+    try {
+        const { stdout } = await promisify(execFile)("git", ["rev-parse", "HEAD"]);
+        const sha = stdout.trim();
+        return sha.length > 0 ? sha : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Parsed flags: every `--name value` pair (or bare `--flag`), plus positionals. */
+function parseArgs(argv) {
+    const positionals = [];
+    const flags = new Map();
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith("--")) {
+            const name = arg.slice(2);
+            const next = argv[i + 1];
+            if (name === "dry-run" || name === "help" || next === undefined || next.startsWith("--")) {
+                flags.set(name, true);
+            }
+            else {
+                flags.set(name, next);
+                i++;
+            }
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    return { positionals, flags };
+}
+/** Run the CLI; returns the process exit code. */
+export async function runCli(argv, deps) {
+    const { positionals, flags } = parseArgs(argv);
+    if (flags.has("help") || positionals.length === 0) {
+        deps.log(USAGE);
+        return positionals.length === 0 && !flags.has("help") ? 1 : 0;
+    }
+    const [command, subcommand, dir] = positionals;
+    if (command !== "sourcemaps" || subcommand !== "upload") {
+        deps.error(`Unknown command: ${positionals.join(" ")}\n\n${USAGE}`);
+        return 1;
+    }
+    if (!dir) {
+        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).
+    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).");
+        return 1;
+    }
+    const dryRun = flags.get("dry-run") === true;
+    const flagKey = flags.get("key");
+    const secretKey = (typeof flagKey === "string" ? flagKey : undefined) ??
+        deps.env.FIXBACK_SECRET_KEY;
+    if (!secretKey && !dryRun) {
+        deps.error("No secret key. Set FIXBACK_SECRET_KEY (Project settings → API keys → secret key) or pass --key.");
+        return 1;
+    }
+    const flagApiUrl = flags.get("api-url");
+    const apiUrl = ((typeof flagApiUrl === "string" ? flagApiUrl : undefined) ??
+        deps.env.FIXBACK_API_URL ??
+        DEFAULT_API_URL).replace(/\/+$/, "");
+    const flagPrefix = flags.get("url-prefix");
+    const urlPrefix = typeof flagPrefix === "string" ? flagPrefix : "~/";
+    if (!urlPrefix.startsWith("~/") && urlPrefix !== "~") {
+        deps.error(`--url-prefix must start with ~/ (got ${JSON.stringify(urlPrefix)}).`);
+        return 1;
+    }
+    return uploadSourcemaps({
+        dir,
+        release,
+        urlPrefix,
+        apiUrl,
+        secretKey: secretKey ?? "",
+        dryRun,
+    }, deps);
+}

package/dist/release.js

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+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;
+}

package/dist/upload.js

@@ -0,0 +1,104 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+/**
+ * Sourcemap discovery + upload (#117, ADR-0024) — the working half of
+ * `fixback sourcemaps upload`. Discovers the `.js.map` files a production build
+ * emitted and posts each to the Fixback API (`POST /api/sourcemaps`), keyed by
+ * (release, `~/`-abstract bundle path) and authenticated with the Project's
+ * secret key. One request per artifact: bounded, retryable, idempotent — a
+ * re-run of the same CI job upserts rather than duplicates.
+ */
+/** The sourcemap suffixes worth uploading — JS bundles only (CSS maps can't symbolicate a stack). */
+const MAP_SUFFIXES = [".js.map", ".mjs.map", ".cjs.map"];
+/**
+ * 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 async function discoverSourcemaps(dir) {
+    const entries = await readdir(dir, { recursive: true, withFileTypes: true });
+    const found = [];
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        if (!MAP_SUFFIXES.some((suffix) => entry.name.endsWith(suffix)))
+            continue;
+        const filePath = join(entry.parentPath, entry.name);
+        const bundleRelative = relative(dir, filePath).split(sep).join("/");
+        found.push({
+            filePath,
+            bundlePath: bundleRelative.slice(0, -".map".length),
+        });
+    }
+    return found.sort((a, b) => a.bundlePath.localeCompare(b.bundlePath));
+}
+/** Join the `~/` URL prefix and a bundle-relative path into the abstract path. */
+export function toArtifactPath(urlPrefix, bundlePath) {
+    const prefix = urlPrefix.endsWith("/") ? urlPrefix : `${urlPrefix}/`;
+    return `${prefix}${bundlePath}`;
+}
+/** Pull a useful message out of an API error response, best-effort. */
+async function apiErrorMessage(response) {
+    try {
+        const body = (await response.json());
+        if (typeof body.message === "string")
+            return body.message;
+        if (Array.isArray(body.message))
+            return body.message.join("; ");
+    }
+    catch {
+        /* fall through to the status line */
+    }
+    return response.statusText || `HTTP ${response.status}`;
+}
+/**
+ * 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 async function uploadSourcemaps(options, deps) {
+    const maps = await discoverSourcemaps(options.dir);
+    if (maps.length === 0) {
+        deps.error(`No JS sourcemaps found under ${options.dir}. ` +
+            "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) {
+        deps.log(`Dry run: ${maps.length} sourcemap(s) would upload for release ${options.release}.`);
+        return 0;
+    }
+    if (failed > 0) {
+        deps.error(`${failed} upload(s) failed for release ${options.release}.`);
+        return 1;
+    }
+    deps.log(`Uploaded ${maps.length} sourcemap(s) for release ${options.release} — ` +
+        "code-area pointers are enabled for errors captured on this release.");
+    return 0;
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@fixback/cli",
+  "version": "0.1.0",
+  "description": "Fixback's build-time CLI — upload sourcemaps per release so Issues gain symbolicated code-area pointers.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "fixback": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.12"
+  },
+  "devDependencies": {
+    "@types/node": "^22.18.13",
+    "typescript": "5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}