@vinktarhq/cli 0.1.0

package/dist/commands/inject.d.ts

@@ -0,0 +1,70 @@
+import { type DiscoverOptions } from '../discover.js';
+export interface InjectResult {
+    /** Chunks stamped by this run. */
+    readonly injected: number;
+    /** Chunks that already carried everything they needed. */
+    readonly skipped: number;
+    /** Chunks whose id came from a map another tool had already stamped. */
+    readonly adopted: number;
+    /** Maps rewritten to carry their chunk's id, because the two disagreed. */
+    readonly repaired: number;
+    /** Chunks with no map to pair with. */
+    readonly withoutMaps: number;
+    /** Chunks whose map resolves nothing, so there was no point stamping them. */
+    readonly empty: number;
+    readonly warnings: string[];
+}
+/**
+ * Stamp every built chunk with a debug id, and write the same id into its map.
+ *
+ * `upload` runs this itself by default, so the standalone command exists for pipelines that build
+ * on one machine and upload from another. It is idempotent: a chunk that already carries an id is
+ * left alone, so running it twice, or running it in a build that is partially cached, does not
+ * produce duplicate snippets.
+ *
+ * ## Where the id comes from
+ *
+ * The chunk first, then the map, then the chunk's bytes. Bundlers stamp maps themselves now —
+ * Rollup's `output.sourcemapDebugIds`, webpack 5.104's `debugIds`, esbuild, rolldown — and minting
+ * a competing id for a map already filed under one produced exactly the mismatch that `doctor`
+ * calls fatal: the SDK reports one id, the server stored the map under another, and nothing
+ * resolves. Adopting theirs costs nothing and keeps both sides pointing at the same artifact. The
+ * chunk wins over the map when they disagree, because the chunk is what a stack frame comes from.
+ */
+export declare function inject(root: string, log: (line: string) => void, options?: DiscoverOptions): Promise<InjectResult>;
+export interface AuditEntry {
+    readonly relative: string;
+    /** The id in the chunk, from its comment or its embedded marker, or null when never injected. */
+    readonly chunkId: string | null;
+    /** The id in the map's `debugId` field, or null when the map has none (or is not valid JSON). */
+    readonly mapId: string | null;
+    /** Whether the chunk carries the runtime registration, not merely a comment naming an id. */
+    readonly registered: boolean;
+    /** How many registrations it carries. More than one means the output was not cleaned. */
+    readonly snippets: number;
+    /** Whether the map can resolve anything at all. */
+    readonly empty: boolean;
+    /** Whether the map carries the original source text, without which frames have no context. */
+    readonly hasSourcesContent: boolean;
+}
+export interface AuditResult {
+    readonly entries: readonly AuditEntry[];
+    /** Chunks (with a map) that carry a debug id. */
+    readonly injected: number;
+    /** Chunks (with a map) that carry none. */
+    readonly notInjected: number;
+    /** Chunks whose map does not carry the same id the chunk does. */
+    readonly mismatched: number;
+    /** Chunks naming an id that nothing will report at runtime. */
+    readonly unregistered: number;
+    readonly withoutMaps: number;
+    readonly warnings: string[];
+}
+/**
+ * Read-only: what `inject` would find. Backs `doctor --dir` and the `--no-inject` warning.
+ *
+ * "Mismatched" is the dangerous state, not "not injected": a chunk without an id still matches by
+ * release and url, but a chunk whose id differs from its map's matches nothing at all, because the
+ * SDK reports one id and the server filed the map under another.
+ */
+export declare function audit(root: string, options?: DiscoverOptions): Promise<AuditResult>;

package/dist/commands/inject.js

@@ -0,0 +1,120 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { commentDebugId, deriveDebugId, existingDebugId, hasSnippet, inject as injectCode, injectIntoMap, mapDebugId, snippetCount, } from '../debug-id.js';
+import { discover, isEmptyMap } from '../discover.js';
+/**
+ * Stamp every built chunk with a debug id, and write the same id into its map.
+ *
+ * `upload` runs this itself by default, so the standalone command exists for pipelines that build
+ * on one machine and upload from another. It is idempotent: a chunk that already carries an id is
+ * left alone, so running it twice, or running it in a build that is partially cached, does not
+ * produce duplicate snippets.
+ *
+ * ## Where the id comes from
+ *
+ * The chunk first, then the map, then the chunk's bytes. Bundlers stamp maps themselves now —
+ * Rollup's `output.sourcemapDebugIds`, webpack 5.104's `debugIds`, esbuild, rolldown — and minting
+ * a competing id for a map already filed under one produced exactly the mismatch that `doctor`
+ * calls fatal: the SDK reports one id, the server stored the map under another, and nothing
+ * resolves. Adopting theirs costs nothing and keeps both sides pointing at the same artifact. The
+ * chunk wins over the map when they disagree, because the chunk is what a stack frame comes from.
+ */
+export async function inject(root, log, options = {}) {
+    const { artifacts, warnings } = await discover(root, options);
+    let injected = 0;
+    let skipped = 0;
+    let adopted = 0;
+    let repaired = 0;
+    let withoutMaps = 0;
+    let empty = 0;
+    for (const artifact of artifacts) {
+        if (artifact.map === null) {
+            withoutMaps += 1;
+            continue;
+        }
+        const code = await readFile(artifact.file, 'utf8');
+        const rawMap = await readFile(artifact.map, 'utf8');
+        if (isEmptyMap(rawMap)) {
+            empty += 1;
+            continue;
+        }
+        const fromChunk = existingDebugId(code);
+        const fromMap = mapDebugId(rawMap);
+        // Derived from the code BEFORE injection, so it stays stable across repeated runs: hashing
+        // the injected output would give a different id every time.
+        const debugId = fromChunk ?? fromMap ?? deriveDebugId(code);
+        const complete = hasSnippet(code) && commentDebugId(code) === debugId;
+        if (complete && fromMap === debugId) {
+            skipped += 1;
+            continue;
+        }
+        const injection = injectCode(code, debugId);
+        if (injection.code !== code) {
+            await writeFile(artifact.file, injection.code, 'utf8');
+        }
+        if (fromMap !== debugId || injection.line !== null) {
+            await writeFile(artifact.map, injectIntoMap(rawMap, debugId, injection.line), 'utf8');
+        }
+        if (complete) {
+            // The chunk was fine; its map was filed under something else, or nothing.
+            repaired += 1;
+        }
+        else {
+            injected += 1;
+            if (fromChunk === null && fromMap !== null)
+                adopted += 1;
+        }
+        log(`  ${artifact.relative}  ${debugId}`);
+    }
+    return { injected, skipped, adopted, repaired, withoutMaps, empty, warnings };
+}
+/**
+ * Read-only: what `inject` would find. Backs `doctor --dir` and the `--no-inject` warning.
+ *
+ * "Mismatched" is the dangerous state, not "not injected": a chunk without an id still matches by
+ * release and url, but a chunk whose id differs from its map's matches nothing at all, because the
+ * SDK reports one id and the server filed the map under another.
+ */
+export async function audit(root, options = {}) {
+    const { artifacts, warnings } = await discover(root, options);
+    const entries = [];
+    let withoutMaps = 0;
+    for (const artifact of artifacts) {
+        if (artifact.map === null) {
+            withoutMaps += 1;
+            continue;
+        }
+        const code = await readFile(artifact.file, 'utf8');
+        const rawMap = await readFile(artifact.map, 'utf8');
+        let hasSourcesContent = false;
+        try {
+            const map = JSON.parse(rawMap);
+            const content = map?.['sourcesContent'];
+            hasSourcesContent = Array.isArray(content) && content.some((entry) => typeof entry === 'string');
+        }
+        catch {
+            // Not JSON: treated as carrying no id and no sources, which the counts then report.
+        }
+        entries.push({
+            relative: artifact.relative,
+            chunkId: existingDebugId(code),
+            mapId: mapDebugId(rawMap),
+            registered: hasSnippet(code),
+            snippets: snippetCount(code),
+            empty: isEmptyMap(rawMap),
+            hasSourcesContent,
+        });
+    }
+    const injected = entries.filter((entry) => entry.chunkId !== null).length;
+    const mismatched = entries.filter((entry) => entry.chunkId !== null && entry.mapId !== entry.chunkId).length;
+    const unregistered = entries.filter((entry) => entry.chunkId !== null && !entry.registered).length;
+    return {
+        entries,
+        injected,
+        notInjected: entries.length - injected,
+        mismatched,
+        unregistered,
+        withoutMaps,
+        warnings,
+    };
+}
+//# sourceMappingURL=inject.js.map

package/dist/commands/inject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inject.js","sourceRoot":"","sources":["../../src/commands/inject.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFile, writeFile } from 'node:fs/promises';\n\nimport {\n  commentDebugId,\n  deriveDebugId,\n  existingDebugId,\n  hasSnippet,\n  inject as injectCode,\n  injectIntoMap,\n  mapDebugId,\n  snippetCount,\n} from '../debug-id.js';\nimport { discover, isEmptyMap, type DiscoverOptions } from '../discover.js';\n\nexport interface InjectResult {\n  /** Chunks stamped by this run. */\n  readonly injected: number;\n  /** Chunks that already carried everything they needed. */\n  readonly skipped: number;\n  /** Chunks whose id came from a map another tool had already stamped. */\n  readonly adopted: number;\n  /** Maps rewritten to carry their chunk's id, because the two disagreed. */\n  readonly repaired: number;\n  /** Chunks with no map to pair with. */\n  readonly withoutMaps: number;\n  /** Chunks whose map resolves nothing, so there was no point stamping them. */\n  readonly empty: number;\n  readonly warnings: string[];\n}\n\n/**\n * Stamp every built chunk with a debug id, and write the same id into its map.\n *\n * `upload` runs this itself by default, so the standalone command exists for pipelines that build\n * on one machine and upload from another. It is idempotent: a chunk that already carries an id is\n * left alone, so running it twice, or running it in a build that is partially cached, does not\n * produce duplicate snippets.\n *\n * ## Where the id comes from\n *\n * The chunk first, then the map, then the chunk's bytes. Bundlers stamp maps themselves now —\n * Rollup's `output.sourcemapDebugIds`, webpack 5.104's `debugIds`, esbuild, rolldown — and minting\n * a competing id for a map already filed under one produced exactly the mismatch that `doctor`\n * calls fatal: the SDK reports one id, the server stored the map under another, and nothing\n * resolves. Adopting theirs costs nothing and keeps both sides pointing at the same artifact. The\n * chunk wins over the map when they disagree, because the chunk is what a stack frame comes from.\n */\nexport async function inject(\n  root: string,\n  log: (line: string) => void,\n  options: DiscoverOptions = {},\n): Promise<InjectResult> {\n  const { artifacts, warnings } = await discover(root, options);\n  let injected = 0;\n  let skipped = 0;\n  let adopted = 0;\n  let repaired = 0;\n  let withoutMaps = 0;\n  let empty = 0;\n\n  for (const artifact of artifacts) {\n    if (artifact.map === null) {\n      withoutMaps += 1;\n      continue;\n    }\n\n    const code = await readFile(artifact.file, 'utf8');\n    const rawMap = await readFile(artifact.map, 'utf8');\n\n    if (isEmptyMap(rawMap)) {\n      empty += 1;\n      continue;\n    }\n\n    const fromChunk = existingDebugId(code);\n    const fromMap = mapDebugId(rawMap);\n    // Derived from the code BEFORE injection, so it stays stable across repeated runs: hashing\n    // the injected output would give a different id every time.\n    const debugId = fromChunk ?? fromMap ?? deriveDebugId(code);\n\n    const complete = hasSnippet(code) && commentDebugId(code) === debugId;\n    if (complete && fromMap === debugId) {\n      skipped += 1;\n      continue;\n    }\n\n    const injection = injectCode(code, debugId);\n\n    if (injection.code !== code) {\n      await writeFile(artifact.file, injection.code, 'utf8');\n    }\n    if (fromMap !== debugId || injection.line !== null) {\n      await writeFile(artifact.map, injectIntoMap(rawMap, debugId, injection.line), 'utf8');\n    }\n\n    if (complete) {\n      // The chunk was fine; its map was filed under something else, or nothing.\n      repaired += 1;\n    } else {\n      injected += 1;\n      if (fromChunk === null && fromMap !== null) adopted += 1;\n    }\n\n    log(`  ${artifact.relative}  ${debugId}`);\n  }\n\n  return { injected, skipped, adopted, repaired, withoutMaps, empty, warnings };\n}\n\nexport interface AuditEntry {\n  readonly relative: string;\n  /** The id in the chunk, from its comment or its embedded marker, or null when never injected. */\n  readonly chunkId: string | null;\n  /** The id in the map's `debugId` field, or null when the map has none (or is not valid JSON). */\n  readonly mapId: string | null;\n  /** Whether the chunk carries the runtime registration, not merely a comment naming an id. */\n  readonly registered: boolean;\n  /** How many registrations it carries. More than one means the output was not cleaned. */\n  readonly snippets: number;\n  /** Whether the map can resolve anything at all. */\n  readonly empty: boolean;\n  /** Whether the map carries the original source text, without which frames have no context. */\n  readonly hasSourcesContent: boolean;\n}\n\nexport interface AuditResult {\n  readonly entries: readonly AuditEntry[];\n  /** Chunks (with a map) that carry a debug id. */\n  readonly injected: number;\n  /** Chunks (with a map) that carry none. */\n  readonly notInjected: number;\n  /** Chunks whose map does not carry the same id the chunk does. */\n  readonly mismatched: number;\n  /** Chunks naming an id that nothing will report at runtime. */\n  readonly unregistered: number;\n  readonly withoutMaps: number;\n  readonly warnings: string[];\n}\n\n/**\n * Read-only: what `inject` would find. Backs `doctor --dir` and the `--no-inject` warning.\n *\n * \"Mismatched\" is the dangerous state, not \"not injected\": a chunk without an id still matches by\n * release and url, but a chunk whose id differs from its map's matches nothing at all, because the\n * SDK reports one id and the server filed the map under another.\n */\nexport async function audit(root: string, options: DiscoverOptions = {}): Promise<AuditResult> {\n  const { artifacts, warnings } = await discover(root, options);\n  const entries: AuditEntry[] = [];\n  let withoutMaps = 0;\n\n  for (const artifact of artifacts) {\n    if (artifact.map === null) {\n      withoutMaps += 1;\n      continue;\n    }\n\n    const code = await readFile(artifact.file, 'utf8');\n    const rawMap = await readFile(artifact.map, 'utf8');\n\n    let hasSourcesContent = false;\n    try {\n      const map: unknown = JSON.parse(rawMap);\n      const content = (map as Record<string, unknown> | null)?.['sourcesContent'];\n      hasSourcesContent = Array.isArray(content) && content.some((entry) => typeof entry === 'string');\n    } catch {\n      // Not JSON: treated as carrying no id and no sources, which the counts then report.\n    }\n\n    entries.push({\n      relative: artifact.relative,\n      chunkId: existingDebugId(code),\n      mapId: mapDebugId(rawMap),\n      registered: hasSnippet(code),\n      snippets: snippetCount(code),\n      empty: isEmptyMap(rawMap),\n      hasSourcesContent,\n    });\n  }\n\n  const injected = entries.filter((entry) => entry.chunkId !== null).length;\n  const mismatched = entries.filter((entry) => entry.chunkId !== null && entry.mapId !== entry.chunkId).length;\n  const unregistered = entries.filter((entry) => entry.chunkId !== null && !entry.registered).length;\n\n  return {\n    entries,\n    injected,\n    notInjected: entries.length - injected,\n    mismatched,\n    unregistered,\n    withoutMaps,\n    warnings,\n  };\n}\n"]}

package/dist/commands/resolve.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Decode one position through a source map, locally.
+ *
+ * This is the question everybody actually has — "would this frame resolve, and to what" — and
+ * without it the only way to answer is to cause a real error in production and look at what comes
+ * back. It decodes the same way the server does, deliberately: if the two disagree, one of them is
+ * wrong, and this is the one you can run in a loop.
+ */
+export interface Position {
+    readonly source: string;
+    readonly line: number;
+    readonly column: number;
+    readonly name: string | null;
+    /** The original line's text, when the map carries `sourcesContent`. */
+    readonly text: string | null;
+}
+export interface ResolveResult {
+    readonly position: Position | null;
+    /** Lines of context around the position, when the source text is available. */
+    readonly context: Array<{
+        line: number;
+        text: string;
+        here: boolean;
+    }>;
+    readonly debugId: string | null;
+    readonly warnings: string[];
+}
+/**
+ * @param line   1-based, as a stack frame reports it
+ * @param column 1-based, as a stack frame reports it
+ */
+export declare function resolvePosition(mapPath: string, line: number, column: number): Promise<ResolveResult>;

package/dist/commands/resolve.js

@@ -0,0 +1,128 @@
+import { readFile } from 'node:fs/promises';
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/**
+ * @param line   1-based, as a stack frame reports it
+ * @param column 1-based, as a stack frame reports it
+ */
+export async function resolvePosition(mapPath, line, column) {
+    const warnings = [];
+    const raw = await readFile(mapPath, 'utf8');
+    const map = JSON.parse(raw);
+    const debugId = typeof map.debugId === 'string' ? map.debugId : typeof map.debug_id === 'string' ? map.debug_id : null;
+    if (Array.isArray(map.sections)) {
+        return {
+            position: null,
+            context: [],
+            debugId,
+            warnings: ['This is an indexed source map (it has `sections`), which is not decoded here.'],
+        };
+    }
+    if (typeof map.mappings !== 'string' || map.mappings === '') {
+        return { position: null, context: [], debugId, warnings: ['The map has no mappings, so it resolves nothing.'] };
+    }
+    const sources = Array.isArray(map.sources) ? map.sources : [];
+    const names = Array.isArray(map.names) ? map.names : [];
+    const contents = Array.isArray(map.sourcesContent) ? map.sourcesContent : [];
+    const root = typeof map.sourceRoot === 'string' && map.sourceRoot !== '' ? map.sourceRoot.replace(/\/?$/, '/') : '';
+    const found = trace(map.mappings, line - 1, column - 1);
+    if (found === null) {
+        return {
+            position: null,
+            context: [],
+            debugId,
+            warnings: [`Nothing is mapped at line ${line}, column ${column}. The map may belong to a different build.`],
+        };
+    }
+    const source = typeof sources[found.source] === 'string' ? `${root}${String(sources[found.source])}` : '(unknown)';
+    const text = typeof contents[found.source] === 'string' ? String(contents[found.source]) : null;
+    if (text === null)
+        warnings.push('The map carries no sourcesContent, so there is no source text to show.');
+    const lines = text?.split(/\r?\n/) ?? [];
+    const context = lines
+        .map((value, index) => ({ line: index + 1, text: value, here: index === found.line }))
+        .filter((entry) => Math.abs(entry.line - (found.line + 1)) <= 2);
+    return {
+        position: {
+            source,
+            line: found.line + 1,
+            column: found.column + 1,
+            name: found.name === null ? null : (typeof names[found.name] === 'string' ? String(names[found.name]) : null),
+            text: lines[found.line] ?? null,
+        },
+        context,
+        debugId,
+        warnings,
+    };
+}
+/**
+ * Find the segment covering a generated position.
+ *
+ * The LAST segment at or before the column, not the nearest: a source map names where each run of
+ * generated code starts, so a column in the middle of a run belongs to the run that began before
+ * it. Searching for the closest instead resolves the second half of every minified line to
+ * whatever comes next, which looks plausible and is wrong.
+ */
+function trace(mappings, line, column) {
+    const groups = mappings.split(';');
+    if (line < 0 || line >= groups.length)
+        return null;
+    // The deltas run across the whole map, so every earlier line has to be decoded to know what the
+    // values on this one mean.
+    let source = 0;
+    let originalLine = 0;
+    let originalColumn = 0;
+    let name = 0;
+    let answer = null;
+    for (let index = 0; index <= line; index += 1) {
+        let generated = 0;
+        for (const field of (groups[index] ?? '').split(',')) {
+            if (field === '')
+                continue;
+            const values = decode(field);
+            if (values.length === 0)
+                continue;
+            generated += values[0];
+            if (values.length < 4)
+                continue;
+            source += values[1];
+            originalLine += values[2];
+            originalColumn += values[3];
+            if (values.length > 4)
+                name += values[4];
+            if (index !== line)
+                continue;
+            if (generated > column)
+                continue;
+            answer = {
+                generated,
+                source,
+                line: originalLine,
+                column: originalColumn,
+                name: values.length > 4 ? name : null,
+            };
+        }
+    }
+    return answer;
+}
+/** Base64 VLQ: five data bits per character, the sixth saying whether more follow. */
+function decode(field) {
+    const values = [];
+    let shift = 0;
+    let value = 0;
+    for (const character of field) {
+        const digit = ALPHABET.indexOf(character);
+        if (digit === -1)
+            return [];
+        value += (digit & 31) << shift;
+        if ((digit & 32) !== 0) {
+            shift += 5;
+            continue;
+        }
+        // The low bit is the sign, which is why this is not a plain shift.
+        values.push((value & 1) === 1 ? -(value >>> 1) : value >>> 1);
+        shift = 0;
+        value = 0;
+    }
+    return values;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/commands/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/commands/resolve.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFile } from 'node:fs/promises';\n\n/**\n * Decode one position through a source map, locally.\n *\n * This is the question everybody actually has — \"would this frame resolve, and to what\" — and\n * without it the only way to answer is to cause a real error in production and look at what comes\n * back. It decodes the same way the server does, deliberately: if the two disagree, one of them is\n * wrong, and this is the one you can run in a loop.\n */\n\nexport interface Position {\n  readonly source: string;\n  readonly line: number;\n  readonly column: number;\n  readonly name: string | null;\n  /** The original line's text, when the map carries `sourcesContent`. */\n  readonly text: string | null;\n}\n\nexport interface ResolveResult {\n  readonly position: Position | null;\n  /** Lines of context around the position, when the source text is available. */\n  readonly context: Array<{ line: number; text: string; here: boolean }>;\n  readonly debugId: string | null;\n  readonly warnings: string[];\n}\n\nconst ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';\n\n/**\n * @param line   1-based, as a stack frame reports it\n * @param column 1-based, as a stack frame reports it\n */\nexport async function resolvePosition(mapPath: string, line: number, column: number): Promise<ResolveResult> {\n  const warnings: string[] = [];\n  const raw = await readFile(mapPath, 'utf8');\n  const map = JSON.parse(raw) as {\n    mappings?: unknown;\n    sources?: unknown;\n    sourcesContent?: unknown;\n    names?: unknown;\n    sourceRoot?: unknown;\n    sections?: unknown;\n    debugId?: unknown;\n    debug_id?: unknown;\n  };\n\n  const debugId = typeof map.debugId === 'string' ? map.debugId : typeof map.debug_id === 'string' ? map.debug_id : null;\n\n  if (Array.isArray(map.sections)) {\n    return {\n      position: null,\n      context: [],\n      debugId,\n      warnings: ['This is an indexed source map (it has `sections`), which is not decoded here.'],\n    };\n  }\n\n  if (typeof map.mappings !== 'string' || map.mappings === '') {\n    return { position: null, context: [], debugId, warnings: ['The map has no mappings, so it resolves nothing.'] };\n  }\n\n  const sources = Array.isArray(map.sources) ? map.sources : [];\n  const names = Array.isArray(map.names) ? map.names : [];\n  const contents = Array.isArray(map.sourcesContent) ? map.sourcesContent : [];\n  const root = typeof map.sourceRoot === 'string' && map.sourceRoot !== '' ? map.sourceRoot.replace(/\\/?$/, '/') : '';\n\n  const found = trace(map.mappings, line - 1, column - 1);\n  if (found === null) {\n    return {\n      position: null,\n      context: [],\n      debugId,\n      warnings: [`Nothing is mapped at line ${line}, column ${column}. The map may belong to a different build.`],\n    };\n  }\n\n  const source = typeof sources[found.source] === 'string' ? `${root}${String(sources[found.source])}` : '(unknown)';\n  const text = typeof contents[found.source] === 'string' ? String(contents[found.source]) : null;\n  if (text === null) warnings.push('The map carries no sourcesContent, so there is no source text to show.');\n\n  const lines = text?.split(/\\r?\\n/) ?? [];\n  const context = lines\n    .map((value, index) => ({ line: index + 1, text: value, here: index === found.line }))\n    .filter((entry) => Math.abs(entry.line - (found.line + 1)) <= 2);\n\n  return {\n    position: {\n      source,\n      line: found.line + 1,\n      column: found.column + 1,\n      name: found.name === null ? null : (typeof names[found.name] === 'string' ? String(names[found.name]) : null),\n      text: lines[found.line] ?? null,\n    },\n    context,\n    debugId,\n    warnings,\n  };\n}\n\ninterface Segment {\n  readonly generated: number;\n  readonly source: number;\n  readonly line: number;\n  readonly column: number;\n  readonly name: number | null;\n}\n\n/**\n * Find the segment covering a generated position.\n *\n * The LAST segment at or before the column, not the nearest: a source map names where each run of\n * generated code starts, so a column in the middle of a run belongs to the run that began before\n * it. Searching for the closest instead resolves the second half of every minified line to\n * whatever comes next, which looks plausible and is wrong.\n */\nfunction trace(mappings: string, line: number, column: number): Segment | null {\n  const groups = mappings.split(';');\n  if (line < 0 || line >= groups.length) return null;\n\n  // The deltas run across the whole map, so every earlier line has to be decoded to know what the\n  // values on this one mean.\n  let source = 0;\n  let originalLine = 0;\n  let originalColumn = 0;\n  let name = 0;\n  let answer: Segment | null = null;\n\n  for (let index = 0; index <= line; index += 1) {\n    let generated = 0;\n\n    for (const field of (groups[index] ?? '').split(',')) {\n      if (field === '') continue;\n\n      const values = decode(field);\n      if (values.length === 0) continue;\n\n      generated += values[0]!;\n      if (values.length < 4) continue;\n\n      source += values[1]!;\n      originalLine += values[2]!;\n      originalColumn += values[3]!;\n      if (values.length > 4) name += values[4]!;\n\n      if (index !== line) continue;\n      if (generated > column) continue;\n\n      answer = {\n        generated,\n        source,\n        line: originalLine,\n        column: originalColumn,\n        name: values.length > 4 ? name : null,\n      };\n    }\n  }\n\n  return answer;\n}\n\n/** Base64 VLQ: five data bits per character, the sixth saying whether more follow. */\nfunction decode(field: string): number[] {\n  const values: number[] = [];\n  let shift = 0;\n  let value = 0;\n\n  for (const character of field) {\n    const digit = ALPHABET.indexOf(character);\n    if (digit === -1) return [];\n\n    value += (digit & 31) << shift;\n\n    if ((digit & 32) !== 0) {\n      shift += 5;\n      continue;\n    }\n\n    // The low bit is the sign, which is why this is not a plain shift.\n    values.push((value & 1) === 1 ? -(value >>> 1) : value >>> 1);\n    shift = 0;\n    value = 0;\n  }\n\n  return values;\n}\n"]}

package/dist/commands/upload.d.ts

@@ -0,0 +1,74 @@
+import { type DiscoverOptions } from '../discover.js';
+import { type Limits, type UploadOptions } from '../upload.js';
+/** One map the server is known to hold after this run, and the bytes it was holding it for. */
+export interface StoredMap {
+    /** Absolute path to the .map file. */
+    readonly map: string;
+    /** Absolute path to the chunk it belongs to. */
+    readonly chunk: string;
+    /** sha256 of the map file as it was read. A plugin re-checks this before deleting it. */
+    readonly sha256: string;
+}
+export interface UploadSummary {
+    /** Newly stored server-side. Zero on a re-run of the same build, which is not a failure. */
+    readonly stored: number;
+    /** Maps actually sent in this run. */
+    readonly uploaded: number;
+    /** Files with no `.map` beside them. */
+    readonly skipped: number;
+    /** Maps the server already held, so they were not sent again. */
+    readonly alreadyStored: number;
+    /** Maps over the per-file ceiling. Skipped, never fatal. */
+    readonly oversized: number;
+    /** Chunks whose map resolves nothing at all, so there was no point sending it. */
+    readonly empty: number;
+    /** Chunks dropped because another chunk in the same build carries the same debug id. */
+    readonly duplicates: number;
+    /** Bytes actually sent. */
+    readonly bytes: number;
+    /** Chunks stamped by this run (zero on a re-run, or with `inject: false`). */
+    readonly injected: number;
+    /** Chunks sent without a debug id in them. Only ever non-zero with `inject: false`. */
+    readonly uninjected: number;
+    /**
+     * The maps that are on the server after this run — the ones just sent plus the ones it already
+     * held. What a caller may safely delete from the build output; deleting by a fresh directory
+     * sweep instead is how the Vite plugin used to throw away maps it never touched.
+     */
+    readonly storedMaps: StoredMap[];
+    /** Everything discovery skipped, and why. */
+    readonly warnings: string[];
+    /** What the server said it accepts, when it said anything. */
+    readonly limits?: Limits | null;
+}
+export interface UploadCommandOptions extends UploadOptions, DiscoverOptions {
+    readonly dryRun: boolean;
+    /**
+     * Stamp the chunks and maps before uploading. Default true: a map uploaded from an un-injected
+     * chunk can only ever match by release + url, and the server cannot link the two after the fact.
+     */
+    readonly inject?: boolean;
+}
+/**
+ * Upload every map under `root`, injecting debug ids first unless told not to.
+ *
+ * Three passes, in this order for a reason:
+ *
+ * 1. **Index.** Every map is built, measured and hashed, then thrown away. A build of two hundred
+ *    chunks is hundreds of megabytes; keeping all of it resident until the first request went out
+ *    was the previous shape.
+ * 2. **Ask.** One request tells us which bodies the server already has. A redeploy of an unchanged
+ *    build then sends nothing at all, which is the difference between a source-map quota that
+ *    lasts and one that fills up in a week.
+ * 3. **Send.** Batches, bounded by bytes, several in flight, each map read back from disk as its
+ *    batch goes.
+ *
+ * Prints the NORMALISED url alongside each file, because that is the string the server will
+ * actually compare a runtime frame against. A mismatch between what you expect to be serving and
+ * what will be stored is otherwise invisible until stack traces silently stay minified, and by
+ * then the deploy is done and nobody connects the two.
+ *
+ * A summary line is printed on every exit path, including a thrown one. A build step whose last
+ * output is a stack trace tells you it failed and not what it had managed to do first.
+ */
+export declare function upload(root: string, options: UploadCommandOptions, log: (line: string) => void, warn?: (line: string) => void): Promise<UploadSummary>;