@vinktarhq/cli 0.1.0

package/dist/cjs/commands/inject.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inject = inject;
+exports.audit = audit;
+const promises_1 = require("node:fs/promises");
+const debug_id_js_1 = require("../debug-id.js");
+const discover_js_1 = require("../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.
+ */
+async function inject(root, log, options = {}) {
+    const { artifacts, warnings } = await (0, discover_js_1.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 (0, promises_1.readFile)(artifact.file, 'utf8');
+        const rawMap = await (0, promises_1.readFile)(artifact.map, 'utf8');
+        if ((0, discover_js_1.isEmptyMap)(rawMap)) {
+            empty += 1;
+            continue;
+        }
+        const fromChunk = (0, debug_id_js_1.existingDebugId)(code);
+        const fromMap = (0, debug_id_js_1.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 ?? (0, debug_id_js_1.deriveDebugId)(code);
+        const complete = (0, debug_id_js_1.hasSnippet)(code) && (0, debug_id_js_1.commentDebugId)(code) === debugId;
+        if (complete && fromMap === debugId) {
+            skipped += 1;
+            continue;
+        }
+        const injection = (0, debug_id_js_1.inject)(code, debugId);
+        if (injection.code !== code) {
+            await (0, promises_1.writeFile)(artifact.file, injection.code, 'utf8');
+        }
+        if (fromMap !== debugId || injection.line !== null) {
+            await (0, promises_1.writeFile)(artifact.map, (0, debug_id_js_1.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.
+ */
+async function audit(root, options = {}) {
+    const { artifacts, warnings } = await (0, discover_js_1.discover)(root, options);
+    const entries = [];
+    let withoutMaps = 0;
+    for (const artifact of artifacts) {
+        if (artifact.map === null) {
+            withoutMaps += 1;
+            continue;
+        }
+        const code = await (0, promises_1.readFile)(artifact.file, 'utf8');
+        const rawMap = await (0, promises_1.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: (0, debug_id_js_1.existingDebugId)(code),
+            mapId: (0, debug_id_js_1.mapDebugId)(rawMap),
+            registered: (0, debug_id_js_1.hasSnippet)(code),
+            snippets: (0, debug_id_js_1.snippetCount)(code),
+            empty: (0, discover_js_1.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,
+    };
+}

package/dist/cjs/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/cjs/commands/resolve.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePosition = resolvePosition;
+const promises_1 = require("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
+ */
+async function resolvePosition(mapPath, line, column) {
+    const warnings = [];
+    const raw = await (0, promises_1.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;
+}

package/dist/cjs/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>;

package/dist/cjs/commands/upload.js

@@ -0,0 +1,254 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.upload = upload;
+const discover_js_1 = require("../discover.js");
+const limits_js_1 = require("../limits.js");
+const upload_js_1 = require("../upload.js");
+const url_js_1 = require("../url.js");
+const inject_js_1 = require("./inject.js");
+/**
+ * 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.
+ */
+async function upload(root, options, log, warn = log) {
+    let injected = 0;
+    if (options.inject !== false) {
+        if (options.dryRun) {
+            // A dry run touches nothing, but the id it prints is the one injection would derive, so
+            // the output is still what the real run will send.
+            const found = await (0, inject_js_1.audit)(root, options);
+            if (found.notInjected > 0)
+                log(`Would inject debug ids into ${found.notInjected} chunk(s).`);
+        }
+        else {
+            const result = await (0, inject_js_1.inject)(root, () => { }, options);
+            injected = result.injected;
+            if (result.injected > 0 || result.repaired > 0) {
+                log(`Injected debug ids into ${result.injected} chunk(s)` +
+                    `${result.adopted > 0 ? `, ${result.adopted} adopted from the bundler` : ''}` +
+                    `${result.repaired > 0 ? `, ${result.repaired} map(s) repaired` : ''}` +
+                    `${result.skipped > 0 ? `, ${result.skipped} already stamped` : ''}.`);
+            }
+            for (const line of result.warnings)
+                warn(`WARNING: ${line}`);
+        }
+    }
+    const { artifacts, warnings } = await (0, discover_js_1.discover)(root, options);
+    if (options.inject === false) {
+        for (const line of warnings)
+            warn(`WARNING: ${line}`);
+    }
+    const indexed = [];
+    const oversized = [];
+    const seenIds = new Map();
+    const seenMaps = new Set();
+    let skipped = 0;
+    let blank = 0;
+    let duplicates = 0;
+    for (const artifact of artifacts) {
+        // A map two chunks both point at belongs to neither of them, and `discover` has already
+        // refused it for both. This only catches the same map reached twice.
+        if (artifact.map !== null && seenMaps.has(artifact.map))
+            continue;
+        const found = await (0, upload_js_1.index)(artifact, options.urlPrefix, options);
+        if (found === null) {
+            skipped += 1;
+            continue;
+        }
+        if (found.oversized) {
+            oversized.push(found.entry);
+            continue;
+        }
+        if (found.empty) {
+            blank += 1;
+            continue;
+        }
+        // Byte-identical chunks emitted under two names derive the same id, and the server keeps one
+        // artifact per debug id: sending both means the second silently replaces the first, so the
+        // url stored for that id is whichever request happened to land last.
+        const already = seenIds.get(found.entry.debugId);
+        if (already !== undefined) {
+            duplicates += 1;
+            warn(`WARNING: ${found.entry.name} has the same debug id as ${already}; only the first is uploaded. ` +
+                'The two chunks are byte-identical, so frames from either resolve through the same map.');
+            continue;
+        }
+        seenIds.set(found.entry.debugId, found.entry.name);
+        if (artifact.map !== null)
+            seenMaps.add(artifact.map);
+        indexed.push({ artifact, entry: found.entry });
+    }
+    // Loud, but not fatal. Losing one chunk's symbolication is a bad afternoon; losing the whole
+    // build's because one chunk was large is a bad week, and that is what throwing here used to do.
+    for (const entry of oversized) {
+        warn(`WARNING: ${entry.name} is ${(0, upload_js_1.mb)(entry.bytes)}, over the ${(0, upload_js_1.mb)(limits_js_1.MAX_FILE_BYTES)} per-file limit — skipped.`);
+    }
+    const base = { skipped, injected, oversized: oversized.length, empty: blank, duplicates, warnings };
+    if (indexed.length === 0) {
+        // The single most common way this package does nothing useful, and it used to say nothing at
+        // all: a bundler with source maps switched off produces a directory full of chunks and not
+        // one map, which looks from here exactly like a directory with nothing in it.
+        if (skipped > 0) {
+            warn(`WARNING: found ${skipped} JavaScript file(s) under ${root} and no source maps. ` +
+                'Nothing can be symbolicated without them — turn source maps on in your bundler ' +
+                "(Vite `build.sourcemap`, webpack `devtool: 'source-map'`, esbuild `--sourcemap`).");
+        }
+        const summary = nothing(base);
+        summarise(log, summary);
+        return summary;
+    }
+    const uninjected = indexed.filter((item) => !item.entry.injected);
+    for (const { entry } of indexed) {
+        log(`  ${entry.name}`);
+        log(`    served as  ${(0, url_js_1.normalise)(entry.url)}`);
+        log(`    debug id   ${entry.debugId}${entry.injected ? '' : '   (not in the chunk)'}`);
+    }
+    // Loud on purpose. With `--no-inject` this is the one thing that decides whether these maps
+    // will resolve frames from a CDN-rewritten path, and it is easy to get here by running the
+    // upload on a machine that never ran `inject`.
+    if (uninjected.length > 0 && !options.dryRun) {
+        warn('');
+        for (const { entry } of uninjected) {
+            warn(`WARNING: ${entry.name.replace(/\.map$/, '')} has no debug id. Run without --no-inject, or run "sourcemaps inject" on the build first.`);
+        }
+        warn(`${uninjected.length} chunk(s) have no debug id; frames from them will only match by release + url.`);
+    }
+    if (options.dryRun) {
+        const bytes = indexed.reduce((total, item) => total + item.entry.bytes, 0);
+        log('');
+        log(`Dry run: ${indexed.length} map(s), ${(0, upload_js_1.mb)(bytes)}. Nothing was uploaded.`);
+        return {
+            ...base,
+            stored: 0,
+            uploaded: 0,
+            alreadyStored: 0,
+            bytes,
+            uninjected: uninjected.length,
+            storedMaps: [],
+        };
+    }
+    const stored = (items) => items
+        .filter((item) => item.artifact.map !== null)
+        .map((item) => ({ map: item.artifact.map, chunk: item.artifact.file, sha256: item.entry.mapSha256 }));
+    const { stored: already, limits } = await (0, upload_js_1.preflight)(options, indexed.map((item) => item.entry.sha256));
+    // The server's own ceiling, which can be smaller than the protocol's: the same deployment
+    // advertises a 20 MiB limit and a 2 MiB `upload_max_filesize`, and only one of those is true of
+    // the socket. A part over it is dropped in silence, so it is worth saying here instead.
+    const overPart = limits === null ? [] : indexed.filter((item) => item.entry.bytes > limits.maxPartBytes);
+    for (const item of overPart) {
+        warn(`WARNING: ${item.entry.name} is ${(0, upload_js_1.mb)(item.entry.bytes)} and this server accepts ${(0, upload_js_1.mb)(limits.maxPartBytes)} per file — skipped.`);
+    }
+    const accepted = overPart.length === 0 ? indexed : indexed.filter((item) => !overPart.includes(item));
+    const pending = accepted.filter((item) => !already.has(item.entry.sha256));
+    const alreadyStored = accepted.length - pending.length;
+    if (alreadyStored > 0) {
+        log(`${alreadyStored} map(s) are already on the server and were not sent again.`);
+    }
+    if (pending.length === 0) {
+        const summary = {
+            ...base,
+            oversized: oversized.length + overPart.length,
+            stored: 0,
+            uploaded: 0,
+            alreadyStored,
+            bytes: 0,
+            uninjected: uninjected.length,
+            storedMaps: stored(accepted),
+        };
+        summarise(log, summary);
+        return summary;
+    }
+    const groups = (0, upload_js_1.batch)(pending, limits);
+    const bytes = pending.reduce((total, item) => total + item.entry.bytes, 0);
+    const sent = [];
+    let done = 0;
+    let count = 0;
+    try {
+        const results = await (0, upload_js_1.pooled)(groups, options.concurrency ?? limits?.concurrency ?? upload_js_1.DEFAULT_CONCURRENCY, async (group) => {
+            // Bodies are read here, not held from the index pass: one batch's worth of maps is in memory
+            // at a time, whatever the size of the build.
+            const loaded = await Promise.all(group.map(async (item) => ({ entry: item.entry, body: await (0, upload_js_1.materialise)(item.artifact, options) })));
+            const result = await (0, upload_js_1.send)(options, loaded, limits);
+            sent.push(...group);
+            done += 1;
+            if (groups.length > 1)
+                log(`Uploaded ${done} of ${groups.length} batches.`);
+            return result;
+        });
+        count = results.reduce((total, result) => total + result.stored, 0);
+    }
+    catch (error) {
+        // Whatever did land is still on the server, and the caller may still delete those maps. The
+        // summary says how far it got before saying why it stopped.
+        summarise(log, {
+            ...base,
+            oversized: oversized.length + overPart.length,
+            stored: count,
+            uploaded: sent.length,
+            alreadyStored,
+            bytes,
+            uninjected: uninjected.length,
+            storedMaps: stored([...accepted.filter((item) => already.has(item.entry.sha256)), ...sent]),
+        });
+        throw error;
+    }
+    const summary = {
+        ...base,
+        oversized: oversized.length + overPart.length,
+        stored: count,
+        uploaded: pending.length,
+        alreadyStored,
+        bytes,
+        uninjected: uninjected.length,
+        storedMaps: stored(accepted),
+    };
+    summarise(log, summary);
+    return summary;
+}
+/** One line, always, so the last thing printed says what happened rather than what went wrong. */
+function summarise(log, summary) {
+    const parts = [`${summary.uploaded} uploaded`];
+    if (summary.uploaded > 0 && summary.stored < summary.uploaded)
+        parts.push(`${summary.stored} new`);
+    if (summary.alreadyStored > 0)
+        parts.push(`${summary.alreadyStored} already stored`);
+    if (summary.skipped > 0)
+        parts.push(`${summary.skipped} without maps`);
+    if (summary.empty > 0)
+        parts.push(`${summary.empty} empty`);
+    if (summary.duplicates > 0)
+        parts.push(`${summary.duplicates} duplicate ids`);
+    if (summary.oversized > 0)
+        parts.push(`${summary.oversized} oversized`);
+    log('');
+    log(`Source maps: ${parts.join(', ')}.`);
+}
+function nothing(partial) {
+    return {
+        ...partial,
+        stored: 0,
+        uploaded: 0,
+        alreadyStored: 0,
+        bytes: 0,
+        uninjected: 0,
+        storedMaps: [],
+    };
+}

package/dist/cjs/config.d.ts

@@ -0,0 +1,51 @@
+/**
+ * One place that decides what every setting is, and one place that refuses a bad one.
+ *
+ * ## Precedence
+ *
+ * flag → environment → `.env` file → compiled-in default, highest first, with the server's
+ * published limits filling in the sizes further down the line. It reads in that order for the
+ * reason every tool does: the thing you typed last should win, and a file checked into a repo must
+ * never quietly outrank a secret the CI supplied.
+ *
+ * ## Why blank is an error and not a default
+ *
+ * Every value is trimmed, and a value that is blank AFTER trimming is refused BY NAME rather than
+ * silently falling through to the next source. `VINKTAR_CLI_KEY=$(echo "$KEY")` leaves a trailing
+ * newline; `--release ""` from a shell variable that was never set leaves an empty string. Both
+ * used to be indistinguishable from "not set", so the CLI carried on and uploaded the whole build
+ * under the release named "".
+ */
+export interface Sources {
+    readonly flags: ReadonlyMap<string, string | boolean>;
+    /** Values of repeatable flags, in the order they were given. */
+    readonly repeated: ReadonlyMap<string, readonly string[]>;
+    readonly env: Record<string, string | undefined>;
+    /** Values read from a `.env` file, which rank BELOW the process environment. */
+    readonly dotenv?: Record<string, string>;
+}
+export interface Resolved {
+    readonly host: string;
+    readonly key: string;
+    readonly release: string;
+    readonly dist: string;
+    readonly urlPrefix: string;
+    readonly concurrency: number | undefined;
+    readonly timeoutMs: number | undefined;
+    readonly maxRetries: number | undefined;
+    readonly headers: Record<string, string>;
+    readonly ignore: string[];
+    readonly extensions: string[] | undefined;
+    readonly rewriteSources: boolean;
+    readonly quiet: boolean;
+    readonly debug: boolean;
+    readonly strict: boolean;
+    readonly allowFailure: boolean;
+    readonly dryRun: boolean;
+    readonly inject: boolean;
+    /** Fatal problems, phrased for someone who is about to fix one. */
+    readonly errors: string[];
+    /** Worth saying, not worth stopping for. */
+    readonly warnings: string[];
+}
+export declare function resolve(sources: Sources): Resolved;