@autter/runtime-cli 1.1.0 → 1.2.0

package/README.md

@@ -5,24 +5,85 @@ content-addressed **debug id** and uploads its **source map** to the ingester,
 so minified browser frames resolve to your original source, even when the
 release your SDK reports doesn't match the upload.
 
+- `autter-runtime sourcemaps setup` wires it into a project; `verify` checks a build
 - `autter-runtime sourcemaps inject <dir>` / `upload <dir>` CLI
 - Vite/Rollup plugin: `@autter/runtime-cli/vite`
 - webpack 5 plugin: `@autter/runtime-cli/webpack`
 - Next.js wrapper: `withAutterSourceMaps` from `@autter/runtime-cli/next`
 
-No runtime dependencies; bundlers are optional peer dependencies. Debug ids
-need ingester 1.6.0+ and `@autter/runtime-browser` 1.6.0+ (older ingesters
-still match `.js` maps by release + path). Full guide:
-[docs/SOURCE-MAPS.md](../../docs/SOURCE-MAPS.md).
+Bundlers are optional peer dependencies. Debug ids need ingester 1.6.0+ and
+`@autter/runtime-browser` 1.6.0+ (older ingesters still match `.js` maps by
+release + path). Full guide: [docs/SOURCE-MAPS.md](../../docs/SOURCE-MAPS.md).
 
-## Install
+## Quick start (people and coding agents)
 
 ```bash
-npm install -D @autter/runtime-cli
+npx @autter/runtime-cli@latest sourcemaps setup          # in the app's directory
+npm run build                                             # with AUTTER_RUNTIME_KEY set
+npx autter-runtime sourcemaps verify dist                 # before deploying
 ```
 
-Set `AUTTER_RUNTIME_KEY` to a **server** ingest key (`autter_rt_…`) where your
-build runs. Without it, the plugins turn no source maps on and change nothing.
+**`setup [dir]`** is non-interactive and safe to re-run. It detects the build
+tool (Vite and the frameworks built on it: SvelteKit, Nuxt, Astro, Remix,
+React Router, Solid, Qwik; Next.js; webpack and Vue CLI; Rollup; Create React
+App; Angular CLI; Parcel; esbuild), the package manager, the CI (GitHub
+Actions, Vercel, Netlify, Cloudflare Pages, GitLab CI), the output directory,
+existing source map settings, the installed browser SDK, and whether
+`initAutterBrowser` gets a `release`. Then it:
+
+- adds `@autter/runtime-cli` to `devDependencies` and prints the install
+  command (`--install` runs it);
+- adds the Vite/Rollup or webpack plugin, or wraps the Next.js config in
+  `withAutterSourceMaps` (outermost), when the config has a shape it can edit
+  safely: `export default defineConfig({...})`, `module.exports = {...}`, a
+  config variable, a function returning an object, `withX(nextConfig)`
+  wrappers. It parses the file (JavaScript or TypeScript) and changes only
+  what it adds; anything else becomes a `manual` action with the exact snippet;
+- for builds without a plugin (CRA, Angular, Parcel, esbuild), adds a
+  `postbuild` step (appended to `build` for pnpm, Yarn 2+ and Bun, which skip
+  `postbuild`) that runs `inject`, then `upload --delete-after-upload
+  --best-effort`, and turns on hidden maps where the tool can
+  (`GENERATE_SOURCEMAP=true`, Angular `"sourceMap": { "scripts": true, "hidden": true }`);
+- reports, never edits, app code: a missing `release` gets a `manual` action
+  showing how to pass the commit SHA through the tool's public env or define
+  mechanism;
+- never writes a key. It says where to store `AUTTER_RUNTIME_KEY` for each CI
+  it found, with commands that read the value from a prompt or stdin, never
+  from argv: `gh secret set AUTTER_RUNTIME_KEY --repo <owner/repo>`,
+  `vercel env add AUTTER_RUNTIME_KEY production`, `netlify env:set …
+  "$(cat)"`, and dashboard notes for Cloudflare Pages and GitLab.
+
+`--dry-run` writes nothing; `--json` prints `{ detected, actions: [{ type:
+"edit"|"add-dependency"|"add-script"|"manual"|"set-secret", file?,
+description, snippet?, command? }], secret: { name, key, where }, next }`.
+Exit codes: `0` everything applied, `2` manual actions remain, `1` error.
+
+**`verify <dir>`** checks a production build before deploy: every JS bundle
+has a debug id (the comment and the registration snippet), no `.map` file is
+left and no `sourceMappingURL` points at a missing map (both deploy risks),
+and, when `AUTTER_RUNTIME_KEY` is set, every bundle's map is on the ingester
+(`/v1/sourcemaps/check` by debug id, ingester 1.7.0+). Without a key the
+local checks still run and the upload is reported as unverified. Files copied
+unchanged from `public/`, Next.js build manifests and polyfills, and service workers are
+skipped; `--ignore <glob>` skips more. `--allow-maps` reports leftover maps
+without failing. `--json` for machines; exit `1` on any failure, with the
+reason per file.
+
+## Keys
+
+Set `AUTTER_RUNTIME_KEY` where your build runs. The recommended key for CI is
+an **upload-only key** (`autter_rtu_…`): it can upload and check source maps
+and nothing else, so a leaked CI secret can't send telemetry. The full server
+key (`autter_rt_…`) also works. A publishable client key (`autter_rtc_…`) is
+refused. Upload keys need ingester 1.7.0+. Without a key, the plugins turn no
+source maps on and change nothing, and `upload --best-effort` uploads nothing
+and exits 0.
+
+## By hand
+
+```bash
+npm install -D @autter/runtime-cli
+```
 
 ## Vite / Rollup
 
@@ -67,9 +128,13 @@ npx autter-runtime sourcemaps upload dist --dry-run
 ```
 
 ```
-autter-runtime sourcemaps inject <dir> [--dry-run]
+autter-runtime sourcemaps setup [dir] [--dry-run] [--install] [--json]
+autter-runtime sourcemaps verify <dir> [--endpoint <url>] [--url-prefix <prefix>]
+              [--ignore <glob>]... [--allow-maps] [--json]
+autter-runtime sourcemaps inject <dir> [--dry-run] [--json]
 autter-runtime sourcemaps upload <dir> [--release <r>] [--url-prefix <prefix>]
-              [--endpoint <url>] [--concurrency <n>] [--delete-after-upload] [--dry-run] [--json]
+              [--endpoint <url>] [--concurrency <n>] [--delete-after-upload]
+              [--best-effort] [--dry-run] [--json]
 ```
 
 - **inject** writes `//# debugId=<id>`, a one-line snippet that registers
@@ -84,15 +149,22 @@ autter-runtime sourcemaps upload <dir> [--release <r>] [--url-prefix <prefix>]
   without them, with a warning. Release: `--release`, else `GITHUB_SHA`,
   `VERCEL_GIT_COMMIT_SHA`, `CF_PAGES_COMMIT_SHA`, `GIT_SHA`, then
   `git rev-parse HEAD`.
+- **upload --best-effort** is for build scripts that also run locally and in
+  fork PRs: without a key, or when the upload fails, it says so and exits 0;
+  with `--delete-after-upload`, every `.map` under `<dir>` is then deleted
+  anyway, so the output is the same with or without a key and never ships
+  maps.
 
 Exit codes: `0` ok, `1` some maps failed, `2` no key / no release / key
-rejected, `64` usage error.
+rejected, `64` usage error (`--best-effort`: always `0`). `setup` and `verify`
+have their own, above.
 
 ## Programmatic API
 
 ```ts
-import { injectDir, uploadDir } from "@autter/runtime-cli";
+import { injectDir, uploadDir, verifyDir } from "@autter/runtime-cli";
 
 await injectDir("dist");
-const summary = await uploadDir("dist", { urlPrefix: "/", release: process.env.GIT_SHA });
+const summary = await uploadDir("dist", { urlPrefix: "/", release: process.env.GIT_SHA, deleteAfterUpload: true });
+const check = await verifyDir("dist"); // check.ok, check.failures, check.upload.status
 ```

package/dist/{build-CPXR9Xd3.d.cts → build-BqjqqeLg.d.cts}

@@ -75,6 +75,11 @@ declare const MAX_MAP_CHARS: number;
 /** The ingester's `/v1/sourcemaps` body limit, counted after the gzip body
  * is inflated: the map plus room for the rest of the request. */
 declare const MAX_UPLOAD_BYTES: number;
+/** Keys `upload` accepts, and the one it refuses before sending anything. */
+declare const UPLOAD_KEY_PREFIX = "autter_rtu_";
+declare const SERVER_KEY_PREFIX = "autter_rt_";
+declare const CLIENT_KEY_PREFIX = "autter_rtc_";
+declare const KEY_ADVICE: string;
 interface UploadOptions {
     /** Only these bundles (absolute, or relative to the directory). */
     files?: string[];
@@ -86,7 +91,8 @@ interface UploadOptions {
     /** Ingester base URL. Default: $AUTTER_ENDPOINT, $AUTTER_RUNTIME_ENDPOINT,
      * $OTEL_EXPORTER_OTLP_ENDPOINT, else https://otlp.autter.dev. */
     endpoint?: string;
-    /** Server ingest key. Default: $AUTTER_RUNTIME_KEY. */
+    /** Upload key (`autter_rtu_…`, recommended for CI) or server key
+     * (`autter_rt_…`). Default: $AUTTER_RUNTIME_KEY. */
     key?: string;
     /** List what would be uploaded; no network, no key needed. */
     dryRun?: boolean;
@@ -149,7 +155,8 @@ interface AutterSourceMapsOptions {
     /** Ingester base URL. Default: $AUTTER_ENDPOINT, $AUTTER_RUNTIME_ENDPOINT,
      * $OTEL_EXPORTER_OTLP_ENDPOINT, else https://otlp.autter.dev. */
     endpoint?: string;
-    /** Server ingest key. Default: $AUTTER_RUNTIME_KEY. Without one (and
+    /** Upload-only key (`autter_rtu_…`, recommended for CI) or server key
+     * (`autter_rt_…`). Default: $AUTTER_RUNTIME_KEY. Without one (and
      * without `upload: false` or `dryRun`), the plugin generates no source
      * maps it would have to delete again: the build is left as it was. */
     key?: string;
@@ -203,4 +210,4 @@ declare function processBuildOutput(input: {
     maps?: string[];
 }): Promise<BuildOutputResult>;
 
-export { type AutterSourceMapsOptions as A, BUNDLE_RE as B, DEFAULT_ENDPOINT as D, FatalUploadError as F, type InjectOptions as I, MAX_MAP_CHARS as M, SNIPPET_LINE_KEY as S, type UploadItem as U, type BuildOutputResult as a, type BundleWithMap as b, type InjectResult as c, MAX_UPLOAD_BYTES as d, type UploadOptions as e, type UploadSummary as f, findBundles as g, formatUploadSummary as h, injectBundle as i, injectDir as j, resolveEndpoint as k, shiftMappings as l, mapPathFor as m, snippetLine as n, storedMapJson as o, processBuildOutput as p, stripSourceMappingUrl as q, readSourceMappingUrl as r, servedFilename as s, uploadDir as u };
+export { type AutterSourceMapsOptions as A, BUNDLE_RE as B, CLIENT_KEY_PREFIX as C, DEFAULT_ENDPOINT as D, FatalUploadError as F, type InjectOptions as I, KEY_ADVICE as K, MAX_MAP_CHARS as M, SERVER_KEY_PREFIX as S, UPLOAD_KEY_PREFIX as U, type BuildOutputResult as a, type BundleWithMap as b, type InjectResult as c, MAX_UPLOAD_BYTES as d, SNIPPET_LINE_KEY as e, type UploadItem as f, type UploadOptions as g, type UploadSummary as h, findBundles as i, formatUploadSummary as j, injectBundle as k, injectDir as l, mapPathFor as m, resolveEndpoint as n, shiftMappings as o, processBuildOutput as p, snippetLine as q, readSourceMappingUrl as r, servedFilename as s, storedMapJson as t, stripSourceMappingUrl as u, uploadDir as v };

package/dist/{build-CPXR9Xd3.d.ts → build-BqjqqeLg.d.ts}

@@ -75,6 +75,11 @@ declare const MAX_MAP_CHARS: number;
 /** The ingester's `/v1/sourcemaps` body limit, counted after the gzip body
  * is inflated: the map plus room for the rest of the request. */
 declare const MAX_UPLOAD_BYTES: number;
+/** Keys `upload` accepts, and the one it refuses before sending anything. */
+declare const UPLOAD_KEY_PREFIX = "autter_rtu_";
+declare const SERVER_KEY_PREFIX = "autter_rt_";
+declare const CLIENT_KEY_PREFIX = "autter_rtc_";
+declare const KEY_ADVICE: string;
 interface UploadOptions {
     /** Only these bundles (absolute, or relative to the directory). */
     files?: string[];
@@ -86,7 +91,8 @@ interface UploadOptions {
     /** Ingester base URL. Default: $AUTTER_ENDPOINT, $AUTTER_RUNTIME_ENDPOINT,
      * $OTEL_EXPORTER_OTLP_ENDPOINT, else https://otlp.autter.dev. */
     endpoint?: string;
-    /** Server ingest key. Default: $AUTTER_RUNTIME_KEY. */
+    /** Upload key (`autter_rtu_…`, recommended for CI) or server key
+     * (`autter_rt_…`). Default: $AUTTER_RUNTIME_KEY. */
     key?: string;
     /** List what would be uploaded; no network, no key needed. */
     dryRun?: boolean;
@@ -149,7 +155,8 @@ interface AutterSourceMapsOptions {
     /** Ingester base URL. Default: $AUTTER_ENDPOINT, $AUTTER_RUNTIME_ENDPOINT,
      * $OTEL_EXPORTER_OTLP_ENDPOINT, else https://otlp.autter.dev. */
     endpoint?: string;
-    /** Server ingest key. Default: $AUTTER_RUNTIME_KEY. Without one (and
+    /** Upload-only key (`autter_rtu_…`, recommended for CI) or server key
+     * (`autter_rt_…`). Default: $AUTTER_RUNTIME_KEY. Without one (and
      * without `upload: false` or `dryRun`), the plugin generates no source
      * maps it would have to delete again: the build is left as it was. */
     key?: string;
@@ -203,4 +210,4 @@ declare function processBuildOutput(input: {
     maps?: string[];
 }): Promise<BuildOutputResult>;
 
-export { type AutterSourceMapsOptions as A, BUNDLE_RE as B, DEFAULT_ENDPOINT as D, FatalUploadError as F, type InjectOptions as I, MAX_MAP_CHARS as M, SNIPPET_LINE_KEY as S, type UploadItem as U, type BuildOutputResult as a, type BundleWithMap as b, type InjectResult as c, MAX_UPLOAD_BYTES as d, type UploadOptions as e, type UploadSummary as f, findBundles as g, formatUploadSummary as h, injectBundle as i, injectDir as j, resolveEndpoint as k, shiftMappings as l, mapPathFor as m, snippetLine as n, storedMapJson as o, processBuildOutput as p, stripSourceMappingUrl as q, readSourceMappingUrl as r, servedFilename as s, uploadDir as u };
+export { type AutterSourceMapsOptions as A, BUNDLE_RE as B, CLIENT_KEY_PREFIX as C, DEFAULT_ENDPOINT as D, FatalUploadError as F, type InjectOptions as I, KEY_ADVICE as K, MAX_MAP_CHARS as M, SERVER_KEY_PREFIX as S, UPLOAD_KEY_PREFIX as U, type BuildOutputResult as a, type BundleWithMap as b, type InjectResult as c, MAX_UPLOAD_BYTES as d, SNIPPET_LINE_KEY as e, type UploadItem as f, type UploadOptions as g, type UploadSummary as h, findBundles as i, formatUploadSummary as j, injectBundle as k, injectDir as l, mapPathFor as m, resolveEndpoint as n, shiftMappings as o, processBuildOutput as p, snippetLine as q, readSourceMappingUrl as r, servedFilename as s, storedMapJson as t, stripSourceMappingUrl as u, uploadDir as v };

package/dist/{chunk-DQLLM2NT.js → chunk-KIQRQY3X.js}

@@ -667,6 +667,10 @@ var DEFAULT_ENDPOINT = "https://otlp.autter.dev";
 var MAX_MAP_CHARS = 32 * 1024 * 1024;
 var MAX_UPLOAD_BYTES = MAX_MAP_CHARS + 1024 * 1024;
 var LEGACY_MAX_BYTES = 5 * 1024 * 1024;
+var UPLOAD_KEY_PREFIX = "autter_rtu_";
+var SERVER_KEY_PREFIX = "autter_rt_";
+var CLIENT_KEY_PREFIX = "autter_rtc_";
+var KEY_ADVICE = "set AUTTER_RUNTIME_KEY to an upload-only key (autter_rtu_\u2026, recommended for CI: it can only upload source maps) or the full server key (autter_rt_\u2026, also works)";
 var gzip = promisify(gzipCallback);
 var CHECK_BATCH = 500;
 var MAX_ATTEMPTS = 3;
@@ -775,10 +779,13 @@ async function uploadDir(dir, options = {}) {
     return summary;
   }
   const key = (options.key ?? env.AUTTER_RUNTIME_KEY ?? "").trim();
-  if (!key) throw new FatalUploadError("no ingest key: set AUTTER_RUNTIME_KEY to a server key (autter_rt_\u2026)");
-  if (key.startsWith("autter_rtc_")) {
-    throw new FatalUploadError("AUTTER_RUNTIME_KEY is a publishable client key (autter_rtc_\u2026); uploads need a server key (autter_rt_\u2026)");
+  if (!key) throw new FatalUploadError(`no ingest key: ${KEY_ADVICE}`);
+  if (key.startsWith(CLIENT_KEY_PREFIX)) {
+    throw new FatalUploadError(`AUTTER_RUNTIME_KEY is a publishable client key (autter_rtc_\u2026), which cannot upload source maps: ${KEY_ADVICE}`);
   }
+  const rejected = (status, detail) => new FatalUploadError(
+    `the ingester rejected the key (${status}): ${detail}` + (key.startsWith(UPLOAD_KEY_PREFIX) ? " (upload keys, autter_rtu_\u2026, need ingester 1.7.0 or later; the server key works with any)" : "")
+  );
   const headers = { "content-type": "application/json", authorization: `Bearer ${key}` };
   const uploadHeaders = { ...headers, "content-encoding": "gzip" };
   const skipped = /* @__PURE__ */ new Set();
@@ -800,9 +807,7 @@ async function uploadDir(dir, options = {}) {
         );
         break;
       }
-      if (res.status === 401 || res.status === 403) {
-        throw new FatalUploadError(`the ingester rejected the key (${res.status}): ${(await res.text()).slice(0, 300)}`);
-      }
+      if (res.status === 401 || res.status === 403) throw rejected(res.status, (await res.text()).slice(0, 300));
       if (!res.ok) throw new Error(`HTTP ${res.status}`);
       const body = await res.json();
       const present = new Set(Array.isArray(body.present) ? body.present : []);
@@ -833,7 +838,7 @@ async function uploadDir(dir, options = {}) {
         detail = err.message;
       }
       if (status === 401 || status === 403) {
-        fatal = new FatalUploadError(`the ingester rejected the key (${status}): ${detail}`);
+        fatal = rejected(status, detail);
         return;
       }
       const retryable = status === 0 || status === 429 || status >= 500;
@@ -1023,6 +1028,10 @@ export {
   DEFAULT_ENDPOINT,
   MAX_MAP_CHARS,
   MAX_UPLOAD_BYTES,
+  UPLOAD_KEY_PREFIX,
+  SERVER_KEY_PREFIX,
+  CLIENT_KEY_PREFIX,
+  KEY_ADVICE,
   resolveEndpoint,
   servedFilename,
   storedMapJson,

package/dist/{chunk-I2743JCN.js → chunk-SIL3WZZ3.js}

@@ -3,7 +3,7 @@ import {
   logMapsNotGenerated,
   processBuildOutput,
   shouldGenerateMaps
-} from "./chunk-DQLLM2NT.js";
+} from "./chunk-KIQRQY3X.js";
 
 // src/webpack.ts
 import { resolve } from "path";