@reliableapp/frontend-cli 1.0.0

package/README.md

@@ -0,0 +1,138 @@
+# @reliableapp/frontend-cli
+
+Reliable frontend CLI — upload sourcemaps from your CI / build pipeline so production stack traces resolve to real source code.
+
+> Frontend-only. Backend / devops uploads will live in a separate `@reliableapp/backend-cli` package later.
+
+```bash
+npx @reliableapp/frontend-cli sourcemaps upload \
+  --dist=./dist \
+  --url-prefix=https://app.example.com/
+```
+
+That's it on a supported platform — release SHA auto-detects, project IDs come from env vars.
+
+## Installation
+
+No install needed; use via `npx`:
+
+```bash
+npx @reliableapp/frontend-cli sourcemaps upload [options]
+```
+
+Or install globally:
+
+```bash
+npm i -g @reliableapp/frontend-cli
+reliableapp-frontend sourcemaps upload [options]
+```
+
+Requires Node 18+.
+
+## Setup (one-time)
+
+In the Reliable dashboard, generate an API token for your frontend project:
+
+> Project → Frontend Project → Settings → API Tokens → **Create token**
+
+Copy the `rl_fpt_...` value (shown once). Set it as a secret in your CI / deploy platform alongside the project IDs:
+
+| Variable | Description |
+|---|---|
+| `RELIABLE_TOKEN` | The `rl_fpt_...` token. **Mark as secret.** |
+| `RELIABLE_PROJECT_ID` | Master project UUID (from dashboard URL) |
+| `RELIABLE_FRONTEND_PROJECT_ID` | Frontend project UUID (from dashboard URL) |
+
+## Usage
+
+### CI step (GitHub Actions, GitLab, CircleCI, Buildkite, Jenkins…)
+
+```yaml
+- name: Upload sourcemaps
+  env:
+    RELIABLE_TOKEN:                ${{ secrets.RELIABLE_TOKEN }}
+    RELIABLE_PROJECT_ID:           ${{ vars.RELIABLE_PROJECT_ID }}
+    RELIABLE_FRONTEND_PROJECT_ID:  ${{ vars.RELIABLE_FRONTEND_PROJECT_ID }}
+  run: |
+    npx @reliableapp/frontend-cli sourcemaps upload \
+      --dist=./dist \
+      --url-prefix=https://app.example.com/
+```
+
+### `package.json` script (Vercel, Netlify, Railway, Render, Coolify, Dokploy, anything Nixpacks-based)
+
+PaaS platforms that auto-build don't have CI step injection — chain the CLI into your build script instead:
+
+```json
+{
+  "scripts": {
+    "build": "vite build && reliableapp-frontend sourcemaps upload --dist=./dist --url-prefix=https://app.example.com/"
+  }
+}
+```
+
+Set `RELIABLE_TOKEN`, `RELIABLE_PROJECT_ID`, `RELIABLE_FRONTEND_PROJECT_ID` in the platform's environment variables UI. The CLI auto-detects the commit SHA from the platform's own env vars (no `--release` needed).
+
+## Required SDK config
+
+In your application code, pass `release` to `init()` so events arrive tagged with the matching build:
+
+```ts
+import { init } from '@reliableapp/react';
+
+init({
+    publicKey: 'pk_live_...',
+    release:   process.env.GIT_SHA,  // same value the CLI uploads under
+});
+```
+
+Without `release`, events arrive but the resolver has no way to find the right map.
+
+## Options
+
+| Flag | Default | Description |
+|---|---|---|
+| `--token <token>` | `$RELIABLE_TOKEN` | API token (`rl_fpt_...`) |
+| `--project <id>` | `$RELIABLE_PROJECT_ID` | Master project UUID |
+| `--frontend-project <id>` | `$RELIABLE_FRONTEND_PROJECT_ID` | Frontend project UUID |
+| `--release <id>` | auto | Release identifier. Auto-detected on supported platforms |
+| `--dist <path>` | required | Local path to the build output folder |
+| `--url-prefix <url>` | required | Browser-visible URL prefix that maps to `--dist` root |
+| `--environment <env>` | `production` | `production` / `staging` / `development` |
+| `--api <url>` | Reliable backend | Override for self-hosted backends |
+| `--concurrency <n>` | `4` | Parallel upload workers |
+| `--force` | — | Bypass the CI safety check (use with care) |
+| `--dry-run` | — | Walk and report what would be uploaded; don't POST |
+
+## How `--url-prefix` works
+
+The CLI walks `--dist` for every `*.js.map` file. For each one, the corresponding JS file's URL is computed as:
+
+```
+url-prefix + path-relative-to-dist (with .map stripped)
+```
+
+Example:
+
+| `--dist` | file found | `--url-prefix` | computed asset URL |
+|---|---|---|---|
+| `./dist` | `dist/assets/main-abc.js.map` | `https://app.example.com/` | `https://app.example.com/assets/main-abc.js` |
+| `./.next/static` | `.next/static/chunks/page-x.js.map` | `https://app.example.com/_next/static/` | `https://app.example.com/_next/static/chunks/page-x.js` |
+
+Match the prefix to whatever URL your CDN actually serves the JS from.
+
+## Auto-detected platforms
+
+Release SHA is auto-resolved from these env vars (in order):
+
+`GITHUB_SHA` · `CI_COMMIT_SHA` · `VERCEL_GIT_COMMIT_SHA` · `COMMIT_REF` (Netlify) · `RAILWAY_GIT_COMMIT_SHA` · `RENDER_GIT_COMMIT` · `CF_PAGES_COMMIT_SHA` · `SOURCE_COMMIT` (Coolify, Heroku) · `CIRCLE_SHA1` · `BUILDKITE_COMMIT` · `BITBUCKET_COMMIT` · `BUILD_SOURCEVERSION` (Azure) · `GIT_COMMIT` · `COMMIT_SHA`
+
+Pass `--release` explicitly if your platform isn't on this list.
+
+## Safety
+
+The CLI refuses to upload when no CI env var is detected, to prevent your local builds from polluting the release index. Override with `--force` only when you know what you're doing.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/sourcemaps-upload.ts
+import { promises as fs3 } from "fs";
+import path3 from "path";
+import { red, green, yellow, cyan, gray, bold } from "kleur/colors";
+
+// src/lib/env.ts
+var CI_ENV_VARS = [
+  "CI",
+  // generic, set by most CI systems
+  "GITHUB_ACTIONS",
+  "GITLAB_CI",
+  "BUILDKITE",
+  "CIRCLECI",
+  "VERCEL",
+  "NETLIFY",
+  "CLOUDFLARE_PAGES",
+  "BITBUCKET_BUILD_NUMBER",
+  "TF_BUILD",
+  // Azure Pipelines
+  "JENKINS_URL",
+  "TEAMCITY_VERSION"
+];
+function detectCI() {
+  for (const k of CI_ENV_VARS) {
+    if (process.env[k]) return k;
+  }
+  return null;
+}
+
+// src/lib/walk.ts
+import { promises as fs } from "fs";
+import path from "path";
+async function walkForMaps(root) {
+  const out = [];
+  await walk(root, root, out);
+  return out;
+}
+async function walk(root, dir, out) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules") continue;
+      await walk(root, full, out);
+    } else if (entry.isFile() && entry.name.endsWith(".js.map")) {
+      out.push({
+        absolutePath: full,
+        relativePath: path.relative(root, full)
+      });
+    }
+  }
+}
+
+// src/lib/upload.ts
+import { promises as fs2 } from "fs";
+import path2 from "path";
+async function uploadSourcemap(input) {
+  const buffer = await fs2.readFile(input.mapPath);
+  const blob = new Blob([buffer], { type: "application/json" });
+  const form = new FormData();
+  form.append("release", input.release);
+  form.append("environment", input.environment);
+  form.append("asset_url", input.assetUrl);
+  form.append("sourcemap", blob, path2.basename(input.mapPath));
+  const url = `${input.api.replace(/\/+$/, "")}/v1/projects/${input.masterProjectId}/frontend-projects/${input.frontendProjectUuid}/sourcemaps`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${input.token}` },
+    body: form
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    const snippet = text.slice(0, 300).replace(/\s+/g, " ").trim();
+    throw new Error(`HTTP ${res.status}${snippet ? ` \u2014 ${snippet}` : ""}`);
+  }
+}
+
+// src/lib/release.ts
+var SHA_ENV_VARS = [
+  // GitHub Actions
+  "GITHUB_SHA",
+  // GitLab CI
+  "CI_COMMIT_SHA",
+  // Vercel
+  "VERCEL_GIT_COMMIT_SHA",
+  // Netlify
+  "COMMIT_REF",
+  // Railway
+  "RAILWAY_GIT_COMMIT_SHA",
+  // Render
+  "RENDER_GIT_COMMIT",
+  // Cloudflare Pages
+  "CF_PAGES_COMMIT_SHA",
+  // Coolify (older), Heroku (Nixpacks-derived)
+  "SOURCE_COMMIT",
+  // CircleCI
+  "CIRCLE_SHA1",
+  // Buildkite
+  "BUILDKITE_COMMIT",
+  // Bitbucket Pipelines
+  "BITBUCKET_COMMIT",
+  // Azure Pipelines
+  "BUILD_SOURCEVERSION",
+  // Generic
+  "GIT_COMMIT",
+  "COMMIT_SHA"
+];
+function autodetectRelease() {
+  for (const k of SHA_ENV_VARS) {
+    const v = process.env[k];
+    if (v && v.trim()) {
+      return { release: v.trim(), source: k };
+    }
+  }
+  return null;
+}
+
+// src/commands/sourcemaps-upload.ts
+async function sourcemapsUpload(opts) {
+  const ci = detectCI();
+  if (!ci && !opts.force) {
+    console.error(red("\u2717 Refusing to upload \u2014 not running in CI."));
+    console.error(gray("  No CI env var detected (CI, GITHUB_ACTIONS, VERCEL, etc)."));
+    console.error(gray("  Pass --force to override (e.g. for testing locally)."));
+    process.exit(2);
+  }
+  if (ci) console.log(gray(`CI detected via $${ci}`));
+  const explicit = opts.release?.trim();
+  const auto = explicit ? null : autodetectRelease();
+  const release = explicit ?? auto?.release ?? "";
+  const releaseSrc = explicit ? "--release flag" : auto ? `$${auto.source}` : "";
+  if (!release) {
+    console.error(red("\u2717 --release not provided and could not auto-detect."));
+    console.error(gray("  Pass --release explicitly, or run on a platform that sets one of:"));
+    console.error(gray("    GITHUB_SHA, VERCEL_GIT_COMMIT_SHA, RAILWAY_GIT_COMMIT_SHA,"));
+    console.error(gray("    RENDER_GIT_COMMIT, CF_PAGES_COMMIT_SHA, SOURCE_COMMIT, etc."));
+    process.exit(2);
+  }
+  try {
+    const stat = await fs3.stat(opts.dist);
+    if (!stat.isDirectory()) {
+      console.error(red(`\u2717 --dist is not a directory: ${opts.dist}`));
+      process.exit(2);
+    }
+  } catch {
+    console.error(red(`\u2717 --dist not found: ${opts.dist}`));
+    process.exit(2);
+  }
+  const maps = await walkForMaps(opts.dist);
+  if (maps.length === 0) {
+    console.error(yellow(`No .js.map files found under ${opts.dist}`));
+    console.error(gray("  Make sure your bundler emits sourcemaps in production."));
+    return;
+  }
+  console.log();
+  console.log(bold("Reliable sourcemap upload"));
+  console.log(`  release      ${cyan(release)} ${gray(`(${releaseSrc})`)}`);
+  console.log(`  environment  ${opts.environment}`);
+  console.log(`  found        ${maps.length} maps`);
+  console.log(`  dist         ${opts.dist}`);
+  console.log(`  url-prefix   ${opts.urlPrefix}`);
+  console.log(`  api          ${opts.api}`);
+  console.log();
+  if (opts.dryRun) {
+    for (const m of maps) {
+      const assetUrl = computeAssetUrl(opts.urlPrefix, m.relativePath);
+      console.log(gray("  [dry]"), assetUrl);
+    }
+    console.log(gray("\nDry run, no uploads sent."));
+    return;
+  }
+  const concurrency = Math.max(1, parseInt(opts.concurrency, 10) || 4);
+  const queue = [...maps];
+  const results = { ok: 0, fail: 0 };
+  async function worker() {
+    for (; ; ) {
+      const m = queue.shift();
+      if (!m) return;
+      const assetUrl = computeAssetUrl(opts.urlPrefix, m.relativePath);
+      try {
+        await uploadSourcemap({
+          api: opts.api,
+          token: opts.token,
+          masterProjectId: opts.project,
+          frontendProjectUuid: opts.frontendProject,
+          release,
+          environment: opts.environment,
+          assetUrl,
+          mapPath: m.absolutePath
+        });
+        results.ok++;
+        console.log(green("  \u2713"), assetUrl);
+      } catch (err) {
+        results.fail++;
+        const msg = err instanceof Error ? err.message : String(err);
+        console.log(red("  \u2717"), assetUrl, gray(`(${msg})`));
+      }
+    }
+  }
+  const workers = Array.from({ length: concurrency }, () => worker());
+  await Promise.all(workers);
+  console.log();
+  console.log(
+    `Uploaded ${green(String(results.ok))} \xB7 Failed ${results.fail > 0 ? red(String(results.fail)) : "0"}`
+  );
+  if (results.fail > 0) process.exit(1);
+}
+function computeAssetUrl(urlPrefix, relativePath) {
+  const cleanRel = relativePath.split(path3.sep).join("/");
+  const jsRel = cleanRel.replace(/\.map$/, "");
+  const prefix = urlPrefix.endsWith("/") ? urlPrefix : urlPrefix + "/";
+  const rel = jsRel.startsWith("/") ? jsRel.slice(1) : jsRel;
+  return prefix + rel;
+}
+
+// src/index.ts
+var program = new Command();
+program.name("reliableapp-frontend").description("Reliable frontend CLI \u2014 sourcemaps, releases, and other build-time uploads").version("1.0.0");
+var sourcemaps = program.command("sourcemaps").description("Sourcemap operations");
+sourcemaps.command("upload").description("Upload sourcemaps for a release to the Reliable backend").requiredOption(
+  "--token <token>",
+  "API token (rl_fpt_...). Falls back to $RELIABLE_TOKEN.",
+  process.env.RELIABLE_TOKEN
+).requiredOption(
+  "--project <id>",
+  "Master project UUID. Falls back to $RELIABLE_PROJECT_ID.",
+  process.env.RELIABLE_PROJECT_ID
+).requiredOption(
+  "--frontend-project <id>",
+  "Frontend project UUID. Falls back to $RELIABLE_FRONTEND_PROJECT_ID.",
+  process.env.RELIABLE_FRONTEND_PROJECT_ID
+).option(
+  "--release <id>",
+  "Release identifier. Auto-detected from common platform env vars if omitted (GITHUB_SHA, VERCEL_GIT_COMMIT_SHA, RAILWAY_GIT_COMMIT_SHA, RENDER_GIT_COMMIT, etc.)."
+).requiredOption(
+  "--dist <path>",
+  "Path to the build output folder containing .js + .js.map files."
+).requiredOption(
+  "--url-prefix <url>",
+  "URL prefix that maps to your dist root (e.g. https://app.example.com/)."
+).option(
+  "--environment <env>",
+  "production | staging | development",
+  "production"
+).option(
+  "--api <url>",
+  "API base URL.",
+  process.env.RELIABLE_API_URL ?? "https://reliablebackend.ziloris.com/api"
+).option(
+  "--concurrency <n>",
+  "How many uploads to run in parallel.",
+  "4"
+).option(
+  "--force",
+  "Bypass the CI detection check (use with care)."
+).option(
+  "--dry-run",
+  "Don't actually upload anything; just report what would be sent."
+).action(async (opts) => {
+  await sourcemapsUpload(opts);
+});
+program.parseAsync(process.argv).catch((err) => {
+  const msg = err instanceof Error ? err.message : String(err);
+  console.error(msg);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+    "name": "@reliableapp/frontend-cli",
+    "version": "1.0.0",
+    "description": "Reliable frontend CLI — upload sourcemaps and manage frontend releases from CI. Built by Ziloris · https://ziloris.com",
+    "homepage": "https://reliable.ziloris.com/docs",
+    "bugs": {
+        "url": "https://reliable.ziloris.com/docs"
+    },
+    "author": {
+        "name": "Ziloris",
+        "url": "https://ziloris.com"
+    },
+    "keywords": [
+        "reliable",
+        "ziloris",
+        "sourcemaps",
+        "error-tracking",
+        "observability",
+        "frontend",
+        "cli",
+        "ci"
+    ],
+    "type": "module",
+    "bin": {
+        "reliableapp-frontend": "./dist/index.js"
+    },
+    "main": "./dist/index.js",
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsup",
+        "dev": "tsup --watch",
+        "typecheck": "tsc --noEmit",
+        "clean": "rm -rf dist"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "dependencies": {
+        "commander": "^12.1.0",
+        "kleur": "^4.1.5"
+    },
+    "devDependencies": {
+        "@types/node": "^20.0.0",
+        "tsup": "^8.5.1",
+        "typescript": "~5.7.0"
+    }
+}