@autter/runtime-cli 1.0.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, debug ids are injected and nothing is uploaded.
+**`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
 
@@ -50,8 +111,10 @@ export default withAutterSourceMaps({ reactStrictMode: true });
 ```
 
 All three turn on hidden source maps when you haven't configured maps, inject
-debug ids after the build, upload when a key is present, and delete the maps
-they created once uploaded. Options (all optional): `release`, `urlPrefix`,
+debug ids after the build, upload when a key is present, and then delete the
+maps they created whether or not the upload succeeded (a rejected upload, an
+unreachable ingester, a dry run), printing one line that says why; without a
+key they turn none on. Maps you configured yourself are left alone. Options (all optional): `release`, `urlPrefix`,
 `endpoint`, `key`, `upload: false`, `deleteAfterUpload`, `dryRun`,
 `concurrency`, `failOnError` (default `false`: a failed upload is logged and
 never fails the build), `silent`.
@@ -65,28 +128,43 @@ 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
   `globalThis._autterDebugIds[new Error().stack] = "<id>"`, and `"debugId"` in
   the `.map`, for each `.js`/`.mjs`/`.cjs` with a map. The id is derived from
   sha256 of the bundle bytes; running it again changes nothing.
-- **upload** posts each map (without `sourcesContent`) to
-  `<endpoint>/v1/sourcemaps`, in parallel, skipping maps the ingester already
-  has. Release: `--release`, else `GITHUB_SHA`, `VERCEL_GIT_COMMIT_SHA`,
-  `CF_PAGES_COMMIT_SHA`, `GIT_SHA`, then `git rev-parse HEAD`.
+- **upload** posts each map (without `sourcesContent`, gzipped, up to 32 MB)
+  to `<endpoint>/v1/sourcemaps`, in parallel, skipping maps the ingester
+  already has. Each map carries the bundle's function scopes (`x_autter_scopes`),
+  parsed from the file as served, so frames are named after the function they
+  are in rather than their call site; a bundle that does not parse is uploaded
+  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-BXFh_jbP.d.cts → build-BqjqqeLg.d.cts}

@@ -69,8 +69,17 @@ declare function injectBundle(bundle: BundleWithMap, options?: InjectOptions): P
 declare function injectDir(dir: string, options?: InjectOptions): Promise<InjectResult[]>;
 
 declare const DEFAULT_ENDPOINT = "https://otlp.autter.dev";
-/** The ingester's `/v1/sourcemaps` body limit. */
+/** Largest map the ingester stores: characters of JSON without
+ * `sourcesContent` (otlp-ingester's SOURCE_MAP_MAX_CHARS). */
+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[];
@@ -82,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;
@@ -145,13 +155,18 @@ 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, debug ids
-     * are still injected but nothing is uploaded. */
+    /** 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;
-    /** Set false to inject debug ids only (upload later with the CLI). */
+    /** Set false to inject debug ids only (upload later with the CLI). Maps
+     * the plugin generated are then kept for that upload: don't deploy them. */
     upload?: boolean;
-    /** Delete `.map` files once uploaded so they are never deployed. Default:
-     * true when the plugin turned source maps on itself, false when you had. */
+    /** Maps the plugin generated itself are always deleted after the upload
+     * step, uploaded or not, so they are never deployed; set false to keep
+     * them (you must then keep them out of the deploy). Maps you configured
+     * yourself are deleted only when this is true, and only once uploaded. */
     deleteAfterUpload?: boolean;
     /** Log what would be uploaded without sending anything. */
     dryRun?: boolean;
@@ -166,13 +181,19 @@ interface AutterSourceMapsOptions {
 interface BuildOutputResult {
     injected: InjectResult[];
     upload: UploadSummary | null;
+    /** Maps the plugin generated and deleted (paths relative to the directory). */
+    removedMaps: string[];
 }
 /** Human-readable lines for an upload summary (CLI and plugins). */
 declare function formatUploadSummary(summary: UploadSummary): string[];
 /**
  * What every bundler integration does after a build: inject debug ids into
  * the emitted bundles, then upload their maps when a key is present.
- * Failures are logged, and thrown only with `failOnError`.
+ * Failures are logged, and thrown only with `failOnError`. When the
+ * integration turned source maps on itself (`ownMaps`), every map it made
+ * is deleted afterwards whatever happened to the upload (no key, a failed
+ * or partial upload, an unreachable ingester, a dry run), with the
+ * sourceMappingURL comments that name them, so none is deployed.
  */
 declare function processBuildOutput(input: {
     dir: string;
@@ -182,6 +203,11 @@ declare function processBuildOutput(input: {
     /** Default for `deleteAfterUpload` (true when the plugin enabled maps). */
     deleteAfterUpload: boolean;
     stripSourceMappingUrl?: boolean;
+    /** The integration turned source maps on itself: none may be deployed. */
+    ownMaps?: boolean;
+    /** Map files the build emitted (absolute), when the bundler lists them;
+     * the maps of `files` (or of every bundle under `dir`) are added. */
+    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_UPLOAD_BYTES as M, SNIPPET_LINE_KEY as S, type UploadItem as U, type BuildOutputResult as a, type BundleWithMap as b, type InjectResult as c, type UploadOptions as d, type UploadSummary as e, findBundles as f, formatUploadSummary as g, injectDir as h, injectBundle as i, resolveEndpoint as j, shiftMappings as k, snippetLine as l, mapPathFor as m, storedMapJson as n, stripSourceMappingUrl as o, processBuildOutput as p, 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-BXFh_jbP.d.ts → build-BqjqqeLg.d.ts}

@@ -69,8 +69,17 @@ declare function injectBundle(bundle: BundleWithMap, options?: InjectOptions): P
 declare function injectDir(dir: string, options?: InjectOptions): Promise<InjectResult[]>;
 
 declare const DEFAULT_ENDPOINT = "https://otlp.autter.dev";
-/** The ingester's `/v1/sourcemaps` body limit. */
+/** Largest map the ingester stores: characters of JSON without
+ * `sourcesContent` (otlp-ingester's SOURCE_MAP_MAX_CHARS). */
+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[];
@@ -82,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;
@@ -145,13 +155,18 @@ 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, debug ids
-     * are still injected but nothing is uploaded. */
+    /** 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;
-    /** Set false to inject debug ids only (upload later with the CLI). */
+    /** Set false to inject debug ids only (upload later with the CLI). Maps
+     * the plugin generated are then kept for that upload: don't deploy them. */
     upload?: boolean;
-    /** Delete `.map` files once uploaded so they are never deployed. Default:
-     * true when the plugin turned source maps on itself, false when you had. */
+    /** Maps the plugin generated itself are always deleted after the upload
+     * step, uploaded or not, so they are never deployed; set false to keep
+     * them (you must then keep them out of the deploy). Maps you configured
+     * yourself are deleted only when this is true, and only once uploaded. */
     deleteAfterUpload?: boolean;
     /** Log what would be uploaded without sending anything. */
     dryRun?: boolean;
@@ -166,13 +181,19 @@ interface AutterSourceMapsOptions {
 interface BuildOutputResult {
     injected: InjectResult[];
     upload: UploadSummary | null;
+    /** Maps the plugin generated and deleted (paths relative to the directory). */
+    removedMaps: string[];
 }
 /** Human-readable lines for an upload summary (CLI and plugins). */
 declare function formatUploadSummary(summary: UploadSummary): string[];
 /**
  * What every bundler integration does after a build: inject debug ids into
  * the emitted bundles, then upload their maps when a key is present.
- * Failures are logged, and thrown only with `failOnError`.
+ * Failures are logged, and thrown only with `failOnError`. When the
+ * integration turned source maps on itself (`ownMaps`), every map it made
+ * is deleted afterwards whatever happened to the upload (no key, a failed
+ * or partial upload, an unreachable ingester, a dry run), with the
+ * sourceMappingURL comments that name them, so none is deployed.
  */
 declare function processBuildOutput(input: {
     dir: string;
@@ -182,6 +203,11 @@ declare function processBuildOutput(input: {
     /** Default for `deleteAfterUpload` (true when the plugin enabled maps). */
     deleteAfterUpload: boolean;
     stripSourceMappingUrl?: boolean;
+    /** The integration turned source maps on itself: none may be deployed. */
+    ownMaps?: boolean;
+    /** Map files the build emitted (absolute), when the bundler lists them;
+     * the maps of `files` (or of every bundle under `dir`) are added. */
+    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_UPLOAD_BYTES as M, SNIPPET_LINE_KEY as S, type UploadItem as U, type BuildOutputResult as a, type BundleWithMap as b, type InjectResult as c, type UploadOptions as d, type UploadSummary as e, findBundles as f, formatUploadSummary as g, injectDir as h, injectBundle as i, resolveEndpoint as j, shiftMappings as k, snippetLine as l, mapPathFor as m, storedMapJson as n, stripSourceMappingUrl as o, processBuildOutput as p, 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 };