@autter/runtime-cli 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# @autter/runtime-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+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`
+- 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).
+
+## Install
+
+```bash
+npm install -D @autter/runtime-cli
+```
+
+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.
+
+## Vite / Rollup
+
+```ts
+import { autterSourceMaps } from "@autter/runtime-cli/vite";
+
+export default defineConfig({ plugins: [autterSourceMaps()] });
+```
+
+## webpack
+
+```js
+const { AutterSourceMapsWebpackPlugin } = require("@autter/runtime-cli/webpack");
+
+module.exports = { plugins: [new AutterSourceMapsWebpackPlugin()] };
+```
+
+## Next.js
+
+```js
+// next.config.mjs
+import { withAutterSourceMaps } from "@autter/runtime-cli/next";
+
+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`,
+`endpoint`, `key`, `upload: false`, `deleteAfterUpload`, `dryRun`,
+`concurrency`, `failOnError` (default `false`: a failed upload is logged and
+never fails the build), `silent`.
+
+## CLI
+
+```bash
+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
+```
+
+```
+autter-runtime sourcemaps inject <dir> [--dry-run]
+autter-runtime sourcemaps upload <dir> [--release <r>] [--url-prefix <prefix>]
+              [--endpoint <url>] [--concurrency <n>] [--delete-after-upload] [--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`.
+
+Exit codes: `0` ok, `1` some maps failed, `2` no key / no release / key
+rejected, `64` usage error.
+
+## Programmatic API
+
+```ts
+import { injectDir, uploadDir } from "@autter/runtime-cli";
+
+await injectDir("dist");
+const summary = await uploadDir("dist", { urlPrefix: "/", release: process.env.GIT_SHA });
+```

package/dist/build-BXFh_jbP.d.cts

@@ -0,0 +1,187 @@
+/** A JS bundle and the source map that belongs to it. */
+interface BundleWithMap {
+    /** Absolute path of the bundle. */
+    js: string;
+    /** Absolute path of its `.map`. */
+    map: string;
+    /** Bundle path relative to the scanned directory, with `/` separators. */
+    path: string;
+}
+/** Bundles a map can be uploaded for. */
+declare const BUNDLE_RE: RegExp;
+/** The last `//# sourceMappingURL=` value in a bundle, or null. */
+declare function readSourceMappingUrl(code: string): string | null;
+/**
+ * Remove a trailing `//# sourceMappingURL=` comment (one that is followed by
+ * nothing but whitespace or other `//#` comments), so the map is no longer
+ * referenced by the served bundle. Line positions above it don't move.
+ */
+declare function stripSourceMappingUrl(code: string): string;
+/** The map file for a bundle: its relative `sourceMappingURL`, else `<file>.map`. */
+declare function mapPathFor(js: string, code: string): string | null;
+/**
+ * Every `.js`/`.mjs`/`.cjs` bundle under `dir` that has a source map, sorted
+ * by path. `files` restricts the scan to those bundles (as a bundler plugin
+ * knows exactly what it emitted).
+ */
+declare function findBundles(dir: string, files?: string[]): Promise<BundleWithMap[]>;
+
+interface InjectOptions {
+    /** Only these bundles (absolute, or relative to the directory). */
+    files?: string[];
+    /** Report what would change without writing anything. */
+    dryRun?: boolean;
+    /** Also drop the bundle's `//# sourceMappingURL=` comment (hidden maps). */
+    stripSourceMappingUrl?: boolean;
+}
+interface InjectResult {
+    /** Bundle path relative to the directory. */
+    path: string;
+    js: string;
+    map: string;
+    debugId: string;
+    /** "injected": files were (or, in a dry run, would be) changed. */
+    status: "injected" | "unchanged" | "invalid-map";
+}
+/** Source map extension field recording the generated line our snippet was
+ * inserted on (its mappings were shifted down by one line from there). */
+declare const SNIPPET_LINE_KEY = "x_autter_snippet_line";
+/**
+ * Index of the generated line the snippet goes on, or -1 to append it at the
+ * end instead. Line 0 normally (line 1 after a `#!` shebang), so the snippet
+ * runs before the bundle's own code and registers its id even when that
+ * code throws while loading. A leading directive prologue ("use strict",
+ * "use client") must stay first, so those bundles get the snippet appended.
+ */
+declare function snippetLine(code: string): number;
+/** Insert `count` empty generated lines before line `at` of a VLQ `mappings`
+ * string. Segment fields other than the column are relative across lines,
+ * so empty lines need no other change. */
+declare function shiftMappings(mappings: string, at: number, count?: number): string;
+/**
+ * Give one bundle its debug id. Idempotent: a bundle that already has our
+ * snippet and a `//# debugId=` comment is left byte-for-byte alone (its map
+ * only gains `debugId` if it lacks it). A bundle whose bundler already wrote
+ * a debug id comment keeps that id and only gains the snippet.
+ */
+declare function injectBundle(bundle: BundleWithMap, options?: InjectOptions): Promise<InjectResult>;
+/** Inject every bundle with a map under `dir` (see injectBundle). */
+declare function injectDir(dir: string, options?: InjectOptions): Promise<InjectResult[]>;
+
+declare const DEFAULT_ENDPOINT = "https://otlp.autter.dev";
+/** The ingester's `/v1/sourcemaps` body limit. */
+declare const MAX_UPLOAD_BYTES: number;
+interface UploadOptions {
+    /** Only these bundles (absolute, or relative to the directory). */
+    files?: string[];
+    /** Default: --release resolution (see resolveRelease). */
+    release?: string;
+    /** Where the directory is served from: "/" (default), "/static/", or
+     * "https://cdn.example.com/app/". Each map is stored under prefix + path. */
+    urlPrefix?: string;
+    /** 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. */
+    key?: string;
+    /** List what would be uploaded; no network, no key needed. */
+    dryRun?: boolean;
+    /** Parallel uploads (default 8). */
+    concurrency?: number;
+    /** Delete each `.map` (and its `sourceMappingURL` comment) once the
+     * ingester has it, so maps are never deployed. */
+    deleteAfterUpload?: boolean;
+    log?: (line: string) => void;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    fetch?: typeof fetch;
+}
+interface UploadItem {
+    /** Bundle path relative to the directory. */
+    path: string;
+    /** Stored filename: urlPrefix + path. */
+    filename: string;
+    debugId: string | null;
+    /** sha256 of the uploaded map JSON (what the ingester stores). */
+    hash: string;
+    bytes: number;
+}
+interface UploadSummary {
+    release: string;
+    releaseSource: string;
+    endpoint: string;
+    dryRun: boolean;
+    uploaded: UploadItem[];
+    /** Already on the ingester with the same content: not sent again. */
+    skipped: UploadItem[];
+    failed: Array<{
+        path: string;
+        filename: string;
+        error: string;
+    }>;
+    /** True when the ingester predates 1.6.0 (no `/v1/sourcemaps/check`). */
+    legacyIngester: boolean;
+    deletedMaps: string[];
+}
+/** Ingester base URL from a flag or the environment, without a trailing
+ * slash or a `/v1/...` route someone pasted in. */
+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;
+declare class FatalUploadError extends Error {
+}
+/** Upload every source map under `dir` to the ingester's `/v1/sourcemaps`. */
+declare function uploadDir(dir: string, options?: UploadOptions): Promise<UploadSummary>;
+
+/** Options shared by the Vite/Rollup, webpack and Next.js integrations. */
+interface AutterSourceMapsOptions {
+    /** Default: GITHUB_SHA, VERCEL_GIT_COMMIT_SHA, CF_PAGES_COMMIT_SHA, GIT_SHA, then `git rev-parse HEAD`. */
+    release?: string;
+    /** Where the build output is served from. Default: the bundler's public
+     * path (Vite `base`, webpack `output.publicPath`, Next `/_next/`), else "/". */
+    urlPrefix?: string;
+    /** 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. */
+    key?: string;
+    /** Set false to inject debug ids only (upload later with the CLI). */
+    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. */
+    deleteAfterUpload?: boolean;
+    /** Log what would be uploaded without sending anything. */
+    dryRun?: boolean;
+    /** Parallel uploads (default 8). */
+    concurrency?: number;
+    /** Fail the build when injecting or uploading fails (default false:
+     * telemetry never breaks a deploy; the failure is logged). */
+    failOnError?: boolean;
+    /** No log output. */
+    silent?: boolean;
+}
+interface BuildOutputResult {
+    injected: InjectResult[];
+    upload: UploadSummary | null;
+}
+/** 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`.
+ */
+declare function processBuildOutput(input: {
+    dir: string;
+    files?: string[];
+    urlPrefix: string;
+    options: AutterSourceMapsOptions;
+    /** Default for `deleteAfterUpload` (true when the plugin enabled maps). */
+    deleteAfterUpload: boolean;
+    stripSourceMappingUrl?: boolean;
+}): 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 };

package/dist/build-BXFh_jbP.d.ts

@@ -0,0 +1,187 @@
+/** A JS bundle and the source map that belongs to it. */
+interface BundleWithMap {
+    /** Absolute path of the bundle. */
+    js: string;
+    /** Absolute path of its `.map`. */
+    map: string;
+    /** Bundle path relative to the scanned directory, with `/` separators. */
+    path: string;
+}
+/** Bundles a map can be uploaded for. */
+declare const BUNDLE_RE: RegExp;
+/** The last `//# sourceMappingURL=` value in a bundle, or null. */
+declare function readSourceMappingUrl(code: string): string | null;
+/**
+ * Remove a trailing `//# sourceMappingURL=` comment (one that is followed by
+ * nothing but whitespace or other `//#` comments), so the map is no longer
+ * referenced by the served bundle. Line positions above it don't move.
+ */
+declare function stripSourceMappingUrl(code: string): string;
+/** The map file for a bundle: its relative `sourceMappingURL`, else `<file>.map`. */
+declare function mapPathFor(js: string, code: string): string | null;
+/**
+ * Every `.js`/`.mjs`/`.cjs` bundle under `dir` that has a source map, sorted
+ * by path. `files` restricts the scan to those bundles (as a bundler plugin
+ * knows exactly what it emitted).
+ */
+declare function findBundles(dir: string, files?: string[]): Promise<BundleWithMap[]>;
+
+interface InjectOptions {
+    /** Only these bundles (absolute, or relative to the directory). */
+    files?: string[];
+    /** Report what would change without writing anything. */
+    dryRun?: boolean;
+    /** Also drop the bundle's `//# sourceMappingURL=` comment (hidden maps). */
+    stripSourceMappingUrl?: boolean;
+}
+interface InjectResult {
+    /** Bundle path relative to the directory. */
+    path: string;
+    js: string;
+    map: string;
+    debugId: string;
+    /** "injected": files were (or, in a dry run, would be) changed. */
+    status: "injected" | "unchanged" | "invalid-map";
+}
+/** Source map extension field recording the generated line our snippet was
+ * inserted on (its mappings were shifted down by one line from there). */
+declare const SNIPPET_LINE_KEY = "x_autter_snippet_line";
+/**
+ * Index of the generated line the snippet goes on, or -1 to append it at the
+ * end instead. Line 0 normally (line 1 after a `#!` shebang), so the snippet
+ * runs before the bundle's own code and registers its id even when that
+ * code throws while loading. A leading directive prologue ("use strict",
+ * "use client") must stay first, so those bundles get the snippet appended.
+ */
+declare function snippetLine(code: string): number;
+/** Insert `count` empty generated lines before line `at` of a VLQ `mappings`
+ * string. Segment fields other than the column are relative across lines,
+ * so empty lines need no other change. */
+declare function shiftMappings(mappings: string, at: number, count?: number): string;
+/**
+ * Give one bundle its debug id. Idempotent: a bundle that already has our
+ * snippet and a `//# debugId=` comment is left byte-for-byte alone (its map
+ * only gains `debugId` if it lacks it). A bundle whose bundler already wrote
+ * a debug id comment keeps that id and only gains the snippet.
+ */
+declare function injectBundle(bundle: BundleWithMap, options?: InjectOptions): Promise<InjectResult>;
+/** Inject every bundle with a map under `dir` (see injectBundle). */
+declare function injectDir(dir: string, options?: InjectOptions): Promise<InjectResult[]>;
+
+declare const DEFAULT_ENDPOINT = "https://otlp.autter.dev";
+/** The ingester's `/v1/sourcemaps` body limit. */
+declare const MAX_UPLOAD_BYTES: number;
+interface UploadOptions {
+    /** Only these bundles (absolute, or relative to the directory). */
+    files?: string[];
+    /** Default: --release resolution (see resolveRelease). */
+    release?: string;
+    /** Where the directory is served from: "/" (default), "/static/", or
+     * "https://cdn.example.com/app/". Each map is stored under prefix + path. */
+    urlPrefix?: string;
+    /** 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. */
+    key?: string;
+    /** List what would be uploaded; no network, no key needed. */
+    dryRun?: boolean;
+    /** Parallel uploads (default 8). */
+    concurrency?: number;
+    /** Delete each `.map` (and its `sourceMappingURL` comment) once the
+     * ingester has it, so maps are never deployed. */
+    deleteAfterUpload?: boolean;
+    log?: (line: string) => void;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    fetch?: typeof fetch;
+}
+interface UploadItem {
+    /** Bundle path relative to the directory. */
+    path: string;
+    /** Stored filename: urlPrefix + path. */
+    filename: string;
+    debugId: string | null;
+    /** sha256 of the uploaded map JSON (what the ingester stores). */
+    hash: string;
+    bytes: number;
+}
+interface UploadSummary {
+    release: string;
+    releaseSource: string;
+    endpoint: string;
+    dryRun: boolean;
+    uploaded: UploadItem[];
+    /** Already on the ingester with the same content: not sent again. */
+    skipped: UploadItem[];
+    failed: Array<{
+        path: string;
+        filename: string;
+        error: string;
+    }>;
+    /** True when the ingester predates 1.6.0 (no `/v1/sourcemaps/check`). */
+    legacyIngester: boolean;
+    deletedMaps: string[];
+}
+/** Ingester base URL from a flag or the environment, without a trailing
+ * slash or a `/v1/...` route someone pasted in. */
+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;
+declare class FatalUploadError extends Error {
+}
+/** Upload every source map under `dir` to the ingester's `/v1/sourcemaps`. */
+declare function uploadDir(dir: string, options?: UploadOptions): Promise<UploadSummary>;
+
+/** Options shared by the Vite/Rollup, webpack and Next.js integrations. */
+interface AutterSourceMapsOptions {
+    /** Default: GITHUB_SHA, VERCEL_GIT_COMMIT_SHA, CF_PAGES_COMMIT_SHA, GIT_SHA, then `git rev-parse HEAD`. */
+    release?: string;
+    /** Where the build output is served from. Default: the bundler's public
+     * path (Vite `base`, webpack `output.publicPath`, Next `/_next/`), else "/". */
+    urlPrefix?: string;
+    /** 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. */
+    key?: string;
+    /** Set false to inject debug ids only (upload later with the CLI). */
+    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. */
+    deleteAfterUpload?: boolean;
+    /** Log what would be uploaded without sending anything. */
+    dryRun?: boolean;
+    /** Parallel uploads (default 8). */
+    concurrency?: number;
+    /** Fail the build when injecting or uploading fails (default false:
+     * telemetry never breaks a deploy; the failure is logged). */
+    failOnError?: boolean;
+    /** No log output. */
+    silent?: boolean;
+}
+interface BuildOutputResult {
+    injected: InjectResult[];
+    upload: UploadSummary | null;
+}
+/** 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`.
+ */
+declare function processBuildOutput(input: {
+    dir: string;
+    files?: string[];
+    urlPrefix: string;
+    options: AutterSourceMapsOptions;
+    /** Default for `deleteAfterUpload` (true when the plugin enabled maps). */
+    deleteAfterUpload: boolean;
+    stripSourceMappingUrl?: boolean;
+}): 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 };

package/dist/chunk-GGHHEUPQ.js

@@ -0,0 +1,41 @@
+import {
+  BUNDLE_RE,
+  processBuildOutput
+} from "./chunk-SIRFO2QU.js";
+
+// src/webpack.ts
+import { resolve } from "path";
+var PLUGIN_NAME = "AutterSourceMapsWebpackPlugin";
+var AutterSourceMapsWebpackPlugin = class {
+  constructor(options = {}) {
+    this.options = options;
+  }
+  options;
+  apply(compiler) {
+    const mode = compiler.options.mode ?? (process.env.NODE_ENV === "development" ? "development" : void 0);
+    if (mode === "development") return;
+    let enabledMaps = false;
+    if (!compiler.options.devtool) {
+      compiler.options.devtool = "hidden-source-map";
+      enabledMaps = true;
+    }
+    compiler.hooks.afterEmit.tapPromise(PLUGIN_NAME, async (compilation) => {
+      const dir = compilation.outputOptions.path ?? compiler.outputPath;
+      if (!dir) return;
+      const publicPath = compilation.outputOptions.publicPath;
+      const urlPrefix = typeof publicPath === "string" && publicPath !== "auto" && publicPath !== "" ? publicPath : "/";
+      const files = compilation.getAssets().map((asset) => asset.name).filter((name) => BUNDLE_RE.test(name)).map((name) => resolve(dir, name));
+      await processBuildOutput({ dir, files, urlPrefix, options: this.options, deleteAfterUpload: enabledMaps });
+    });
+  }
+};
+function autterSourceMapsWebpack(options = {}) {
+  return new AutterSourceMapsWebpackPlugin(options);
+}
+var webpack_default = AutterSourceMapsWebpackPlugin;
+
+export {
+  AutterSourceMapsWebpackPlugin,
+  autterSourceMapsWebpack,
+  webpack_default
+};