@autter/runtime-cli 1.1.0 → 1.3.0

package/README.md

@@ -2,27 +2,95 @@
 
 Readable stack traces for Autter Runtime. Gives every JS bundle a
 content-addressed **debug id** and uploads its **source map** to the ingester,
-so minified browser frames resolve to your original source, even when the
+so minified browser frames and bundled Node and edge frames resolve to your
+original source, with the lines around each frame of your code, even when the
 release your SDK reports doesn't match the upload.
 
-- `autter-runtime sourcemaps inject <dir>` / `upload <dir>` CLI
-- Vite/Rollup plugin: `@autter/runtime-cli/vite`
-- webpack 5 plugin: `@autter/runtime-cli/webpack`
+- `autter-runtime sourcemaps setup` wires it into a project; `verify` checks a build
+- `autter-runtime sourcemaps inject <dir>` / `upload <dir>` CLI, for browser
+  and server output alike (tsup, esbuild, a Worker)
+- Vite/Rollup plugin: `@autter/runtime-cli/vite` (SSR builds and server
+  environments too)
+- webpack 5 plugin: `@autter/runtime-cli/webpack` (Node targets too)
 - Next.js wrapper: `withAutterSourceMaps` from `@autter/runtime-cli/next`
+  (client and `.next/server` output)
 
-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). Server bundles and source contents need the current
+ingester. 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. `--server` checks server output (a tsup or esbuild `dist/`,
+`.next/server`), where leftover maps are a note, not a failure, and Next.js
+server manifests are skipped. `--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
 
@@ -53,10 +121,20 @@ 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 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`.
+key they turn none on. Maps you configured yourself are left alone.
+
+Server bundles get the same: Vite SSR builds and Vite 6 server environments,
+webpack builds for a Node target, and Next.js `.next/server` (Node and edge,
+webpack and Turbopack). Their maps are stored under the output directory's
+path in the project (`/dist/server/`, `/.next/server/`), which the ingester
+matches against the path the server runs them from, never under the public
+URL prefix.
+
+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`, `sourcesContent: false` (upload maps without your files' source),
+`serverBundles: false` (leave server output exactly as the bundler wrote it).
 
 ## CLI
 
@@ -64,35 +142,58 @@ never fails the build), `silent`.
 npx autter-runtime sourcemaps inject dist
 npx autter-runtime sourcemaps upload dist --url-prefix / --release "$GIT_SHA"
 npx autter-runtime sourcemaps upload dist --dry-run
+
+# A bundled Node server (tsup, esbuild): the same commands
+npx autter-runtime sourcemaps inject dist
+npx autter-runtime sourcemaps upload dist --url-prefix /dist/
+npx autter-runtime sourcemaps verify dist --server
 ```
 
 ```
-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] [--server] [--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]
+              [--no-sources-content] [--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`, 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`),
+  sha256 of the bundle bytes; running it again changes nothing. The browser
+  SDK and the Node and edge SDKs read the snippet's registry and send the ids
+  of the bundles in each exception's stack.
+- **upload** posts each map (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`,
+  without them, with a warning. It also carries the original source of your own
+  files (`sourcesContent`; never your dependencies', whole files only, as many
+  as fit the 32 MB limit), so issues show the lines around each frame;
+  `--no-sources-content` leaves it out. For server output, `--url-prefix` is
+  any tail of the path the server runs the files from (`/dist/` for
+  `/app/dist/server.js`), or `/`. 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-DGeoDkTh.d.cts}

@@ -69,12 +69,18 @@ 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";
-/** Largest map the ingester stores: characters of JSON without
- * `sourcesContent` (otlp-ingester's SOURCE_MAP_MAX_CHARS). */
+/** Largest map the ingester stores (otlp-ingester's SOURCE_MAP_MAX_CHARS):
+ * characters of JSON without `sourcesContent`; the in-app sources' content
+ * that is sent fits in what is left of it, in UTF-8 bytes (storedMapJson). */
 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 +92,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;
@@ -95,6 +102,11 @@ interface UploadOptions {
     /** Delete each `.map` (and its `sourceMappingURL` comment) once the
      * ingester has it, so maps are never deployed. */
     deleteAfterUpload?: boolean;
+    /** Send the original source of your own files (`sourcesContent`, when the
+     * bundler wrote it), so issues show the lines around each frame of your
+     * code. Dependencies' sources are never sent. Default true; false sends
+     * maps without it (`--no-sources-content`). */
+    sourcesContent?: boolean;
     log?: (line: string) => void;
     env?: NodeJS.ProcessEnv;
     cwd?: string;
@@ -132,8 +144,23 @@ interface UploadSummary {
 declare function resolveEndpoint(flag?: string, env?: NodeJS.ProcessEnv): string;
 /** prefix + path, with exactly one "/" between. "~/" (Sentry's spelling) means "/". */
 declare function servedFilename(urlPrefix: string | undefined, path: string): string;
-/** The map as the ingester stores it: `sourcesContent` removed, compact JSON. */
-declare function storedMapJson(map: Record<string, unknown>): string;
+/** Whether a map's `sources` entry is the app's own code (the ingester's in-app path rule). */
+declare function isInAppSource(path: string): boolean;
+/**
+ * The `sourcesContent` the ingester keeps, or null to leave it out: in-app
+ * sources only (not ignore-listed, not under node_modules/ etc.), whole
+ * files, smallest first, while the JSON fits `limit` UTF-8 bytes given the
+ * `baseBytes` of the map without it.
+ */
+declare function storedSourcesContent(fields: Record<string, unknown>, baseBytes: number, limit?: number): Array<string | null> | null;
+/**
+ * The map as the ingester stores it, compact JSON: every field as given,
+ * then `sourcesContent` bounded by storedSourcesContent (left out when
+ * nothing is kept, or with `sourcesContent: false`).
+ */
+declare function storedMapJson(map: Record<string, unknown>, options?: {
+    sourcesContent?: boolean;
+}): string;
 declare class FatalUploadError extends Error {
 }
 /** Upload every source map under `dir` to the ingester's `/v1/sourcemaps`. */
@@ -149,7 +176,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;
@@ -170,7 +198,26 @@ interface AutterSourceMapsOptions {
     failOnError?: boolean;
     /** No log output. */
     silent?: boolean;
+    /** Send your own files' original source with each map (`sourcesContent`,
+     * when the bundler wrote it), so issues show the lines around each frame
+     * of your code. Dependencies' sources are never sent. Default true. */
+    sourcesContent?: boolean;
+    /** Server bundles too (default true): Vite SSR builds and server
+     * environments, webpack builds for a Node target, and Next.js server
+     * output get debug ids and their maps uploaded, so errors in your backend
+     * resolve to its original files and lines. False leaves server output
+     * exactly as the bundler wrote it. */
+    serverBundles?: boolean;
 }
+/**
+ * Where a server bundle directory's maps are stored: its path relative to
+ * the project (`/dist/server/`, `/.next/server/`), never the public URL
+ * prefix. The ingester matches a stored path as a suffix of the path the
+ * process runs the bundle from (`/app/dist/server/entry.js`,
+ * `/var/task/.next/server/app/page.js`), and the directory keeps server and
+ * browser maps of one release apart. "/" for a directory outside the project.
+ */
+declare function serverUrlPrefix(projectRoot: string, dir: string): string;
 interface BuildOutputResult {
     injected: InjectResult[];
     upload: UploadSummary | null;
@@ -201,6 +248,9 @@ declare function processBuildOutput(input: {
     /** 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[];
+    /** Server output (RF-05): `urlPrefix` is serverUrlPrefix(), which the
+     * public `options.urlPrefix` never overrides. */
+    server?: boolean;
 }): 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, isInAppSource as m, mapPathFor as n, resolveEndpoint as o, processBuildOutput as p, serverUrlPrefix as q, readSourceMappingUrl as r, servedFilename as s, shiftMappings as t, snippetLine as u, storedMapJson as v, storedSourcesContent as w, stripSourceMappingUrl as x, uploadDir as y };

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

@@ -69,12 +69,18 @@ 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";
-/** Largest map the ingester stores: characters of JSON without
- * `sourcesContent` (otlp-ingester's SOURCE_MAP_MAX_CHARS). */
+/** Largest map the ingester stores (otlp-ingester's SOURCE_MAP_MAX_CHARS):
+ * characters of JSON without `sourcesContent`; the in-app sources' content
+ * that is sent fits in what is left of it, in UTF-8 bytes (storedMapJson). */
 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 +92,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;
@@ -95,6 +102,11 @@ interface UploadOptions {
     /** Delete each `.map` (and its `sourceMappingURL` comment) once the
      * ingester has it, so maps are never deployed. */
     deleteAfterUpload?: boolean;
+    /** Send the original source of your own files (`sourcesContent`, when the
+     * bundler wrote it), so issues show the lines around each frame of your
+     * code. Dependencies' sources are never sent. Default true; false sends
+     * maps without it (`--no-sources-content`). */
+    sourcesContent?: boolean;
     log?: (line: string) => void;
     env?: NodeJS.ProcessEnv;
     cwd?: string;
@@ -132,8 +144,23 @@ interface UploadSummary {
 declare function resolveEndpoint(flag?: string, env?: NodeJS.ProcessEnv): string;
 /** prefix + path, with exactly one "/" between. "~/" (Sentry's spelling) means "/". */
 declare function servedFilename(urlPrefix: string | undefined, path: string): string;
-/** The map as the ingester stores it: `sourcesContent` removed, compact JSON. */
-declare function storedMapJson(map: Record<string, unknown>): string;
+/** Whether a map's `sources` entry is the app's own code (the ingester's in-app path rule). */
+declare function isInAppSource(path: string): boolean;
+/**
+ * The `sourcesContent` the ingester keeps, or null to leave it out: in-app
+ * sources only (not ignore-listed, not under node_modules/ etc.), whole
+ * files, smallest first, while the JSON fits `limit` UTF-8 bytes given the
+ * `baseBytes` of the map without it.
+ */
+declare function storedSourcesContent(fields: Record<string, unknown>, baseBytes: number, limit?: number): Array<string | null> | null;
+/**
+ * The map as the ingester stores it, compact JSON: every field as given,
+ * then `sourcesContent` bounded by storedSourcesContent (left out when
+ * nothing is kept, or with `sourcesContent: false`).
+ */
+declare function storedMapJson(map: Record<string, unknown>, options?: {
+    sourcesContent?: boolean;
+}): string;
 declare class FatalUploadError extends Error {
 }
 /** Upload every source map under `dir` to the ingester's `/v1/sourcemaps`. */
@@ -149,7 +176,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;
@@ -170,7 +198,26 @@ interface AutterSourceMapsOptions {
     failOnError?: boolean;
     /** No log output. */
     silent?: boolean;
+    /** Send your own files' original source with each map (`sourcesContent`,
+     * when the bundler wrote it), so issues show the lines around each frame
+     * of your code. Dependencies' sources are never sent. Default true. */
+    sourcesContent?: boolean;
+    /** Server bundles too (default true): Vite SSR builds and server
+     * environments, webpack builds for a Node target, and Next.js server
+     * output get debug ids and their maps uploaded, so errors in your backend
+     * resolve to its original files and lines. False leaves server output
+     * exactly as the bundler wrote it. */
+    serverBundles?: boolean;
 }
+/**
+ * Where a server bundle directory's maps are stored: its path relative to
+ * the project (`/dist/server/`, `/.next/server/`), never the public URL
+ * prefix. The ingester matches a stored path as a suffix of the path the
+ * process runs the bundle from (`/app/dist/server/entry.js`,
+ * `/var/task/.next/server/app/page.js`), and the directory keeps server and
+ * browser maps of one release apart. "/" for a directory outside the project.
+ */
+declare function serverUrlPrefix(projectRoot: string, dir: string): string;
 interface BuildOutputResult {
     injected: InjectResult[];
     upload: UploadSummary | null;
@@ -201,6 +248,9 @@ declare function processBuildOutput(input: {
     /** 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[];
+    /** Server output (RF-05): `urlPrefix` is serverUrlPrefix(), which the
+     * public `options.urlPrefix` never overrides. */
+    server?: boolean;
 }): 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, isInAppSource as m, mapPathFor as n, resolveEndpoint as o, processBuildOutput as p, serverUrlPrefix as q, readSourceMappingUrl as r, servedFilename as s, shiftMappings as t, snippetLine as u, storedMapJson as v, storedSourcesContent as w, stripSourceMappingUrl as x, uploadDir as y };

package/dist/{chunk-DQLLM2NT.js → chunk-Q23FB5X3.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;
@@ -680,9 +684,56 @@ function servedFilename(urlPrefix, path) {
   if (!/^[a-z][\w+.-]*:\/\//i.test(prefix) && !prefix.startsWith("/")) prefix = `/${prefix}`;
   return `${prefix.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
 }
-function storedMapJson(map) {
-  const { sourcesContent: _omitted, ...safe } = map;
-  return JSON.stringify(safe);
+var NOT_IN_APP_PATH_PARTS = ["node_modules/", "/site-packages/", "/dist-packages/", "/vendor/", "/.pnpm/"];
+var NOT_IN_APP_PATH_PREFIXES = ["node:", "internal/"];
+var EXTENSION_SCHEMES = ["chrome-extension:", "moz-extension:", "safari-extension:", "safari-web-extension:", "webkit-masked-url:"];
+function isInAppSource(path) {
+  if (!path) return true;
+  const normalized = path.replace(/\\/g, "/");
+  if (NOT_IN_APP_PATH_PARTS.some((part) => normalized.includes(part))) return false;
+  if (NOT_IN_APP_PATH_PREFIXES.some((prefix) => normalized.startsWith(prefix))) return false;
+  const lower = normalized.toLowerCase();
+  return !EXTENSION_SCHEMES.some((scheme) => lower.startsWith(scheme));
+}
+var SOURCES_CONTENT_WRAPPER_BYTES = Buffer.byteLength(',"sourcesContent":[]');
+var NULL_ENTRY_BYTES = 4;
+function storedSourcesContent(fields, baseBytes, limit = MAX_MAP_CHARS) {
+  const { sources, sourcesContent } = fields;
+  if (!Array.isArray(sources) || !Array.isArray(sourcesContent) || sources.length === 0) return null;
+  const ignored = /* @__PURE__ */ new Set();
+  for (const list of [fields.ignoreList, fields.x_google_ignoreList]) {
+    if (!Array.isArray(list)) continue;
+    for (const index of list) if (Number.isInteger(index)) ignored.add(index);
+  }
+  const count = sources.length;
+  const candidates = [];
+  for (let index = 0; index < count; index++) {
+    const source = sources[index];
+    const content = sourcesContent[index];
+    if (typeof source !== "string" || typeof content !== "string") continue;
+    if (ignored.has(index) || !isInAppSource(source)) continue;
+    candidates.push({ index, content, bytes: Buffer.byteLength(JSON.stringify(content)) });
+  }
+  if (candidates.length === 0) return null;
+  candidates.sort((a, b) => a.bytes - b.bytes || a.index - b.index);
+  let remaining = limit - baseBytes - SOURCES_CONTENT_WRAPPER_BYTES - NULL_ENTRY_BYTES * count - (count - 1);
+  const kept = new Array(count).fill(null);
+  let any = false;
+  for (const candidate of candidates) {
+    const extra = candidate.bytes - NULL_ENTRY_BYTES;
+    if (extra > remaining) break;
+    remaining -= extra;
+    kept[candidate.index] = candidate.content;
+    any = true;
+  }
+  return any ? kept : null;
+}
+function storedMapJson(map, options = {}) {
+  const { sourcesContent: _content, ...rest } = map;
+  const base = JSON.stringify(rest);
+  if (options.sourcesContent === false) return base;
+  const content = storedSourcesContent(map, Buffer.byteLength(base));
+  return content ? JSON.stringify({ ...rest, sourcesContent: content }) : base;
 }
 function bytesOf(buffer) {
   return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
@@ -693,7 +744,7 @@ function fits(json, body) {
 function uploadBody(release, filename, debugId, json) {
   return `{"release":${JSON.stringify(release)},"filename":${JSON.stringify(filename)},${debugId ? `"debugId":${JSON.stringify(debugId)},` : ""}"map":${json}}`;
 }
-async function prepare(bundle, urlPrefix, release, log, compress) {
+async function prepare(bundle, urlPrefix, release, log, compress, sourcesContent) {
   let map;
   try {
     map = JSON.parse(await readFile3(bundle.map, "utf8"));
@@ -708,9 +759,10 @@ async function prepare(bundle, urlPrefix, release, log, compress) {
   const filename = servedFilename(urlPrefix, bundle.path);
   const { [SCOPES_KEY]: _stale, ...plain } = map;
   const scopes = computeScopes(code, map);
-  let json = storedMapJson(plain);
+  const stored = { sourcesContent };
+  let json = storedMapJson(plain, stored);
   if ("scopes" in scopes) {
-    const scoped = storedMapJson({ ...plain, [SCOPES_KEY]: scopes.scopes });
+    const scoped = storedMapJson({ ...plain, [SCOPES_KEY]: scopes.scopes }, stored);
     if (fits(scoped, uploadBody(release, filename, debugId, scoped))) json = scoped;
     else if (fits(json, uploadBody(release, filename, debugId, json))) {
       log(`warning: ${bundle.path}: its map is over 32 MB with function scopes, so it is uploaded without them (frames keep call-site names)`);
@@ -757,7 +809,7 @@ async function uploadDir(dir, options = {}) {
   };
   const items = [];
   for (const bundle of await findBundles(dir, options.files)) {
-    const prepared = await prepare(bundle, options.urlPrefix, release, log, !options.dryRun);
+    const prepared = await prepare(bundle, options.urlPrefix, release, log, !options.dryRun, options.sourcesContent !== false);
     if ("error" in prepared) {
       summary.failed.push({ path: bundle.path, filename: servedFilename(options.urlPrefix, bundle.path), error: prepared.error });
     } else if (prepared.mapChars > MAX_MAP_CHARS || prepared.bytes > MAX_UPLOAD_BYTES) {
@@ -775,10 +827,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 +855,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 +886,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;
@@ -876,7 +929,11 @@ function strip(item) {
 
 // src/build.ts
 import { existsSync as existsSync2 } from "fs";
-import { relative as relative2, sep as sep2 } from "path";
+import { isAbsolute, relative as relative2, sep as sep2 } from "path";
+function serverUrlPrefix(projectRoot, dir) {
+  const rel = relative2(projectRoot, dir).split(sep2).join("/");
+  return !rel || rel.startsWith("..") || isAbsolute(rel) ? "/" : `/${rel.replace(/\/+$/, "")}/`;
+}
 function buildKey(options) {
   const key = (options.key ?? process.env.AUTTER_RUNTIME_KEY ?? "").trim();
   return key || null;
@@ -939,12 +996,13 @@ async function processBuildOutput(input) {
       result.upload = await uploadDir(input.dir, {
         files: input.files,
         release: options.release,
-        urlPrefix: options.urlPrefix ?? input.urlPrefix,
+        urlPrefix: input.server ? input.urlPrefix : options.urlPrefix ?? input.urlPrefix,
         endpoint: options.endpoint,
         key: key ?? void 0,
         dryRun: options.dryRun,
         concurrency: options.concurrency,
         deleteAfterUpload: options.deleteAfterUpload ?? input.deleteAfterUpload,
+        ...options.sourcesContent === false ? { sourcesContent: false } : {},
         log
       });
       for (const line of formatUploadSummary(result.upload)) log(line);
@@ -1023,11 +1081,18 @@ export {
   DEFAULT_ENDPOINT,
   MAX_MAP_CHARS,
   MAX_UPLOAD_BYTES,
+  UPLOAD_KEY_PREFIX,
+  SERVER_KEY_PREFIX,
+  CLIENT_KEY_PREFIX,
+  KEY_ADVICE,
   resolveEndpoint,
   servedFilename,
+  isInAppSource,
+  storedSourcesContent,
   storedMapJson,
   FatalUploadError,
   uploadDir,
+  serverUrlPrefix,
   shouldGenerateMaps,
   logMapsNotGenerated,
   formatUploadSummary,