@vinktarhq/cli 0.1.0

package/dist/cjs/upload.js

@@ -0,0 +1,394 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CONCURRENCY = exports.UploadError = void 0;
+exports.index = index;
+exports.materialise = materialise;
+exports.rewrite = rewrite;
+exports.preflight = preflight;
+exports.send = send;
+exports.batch = batch;
+exports.pooled = pooled;
+exports.mb = mb;
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const node_zlib_1 = require("node:zlib");
+const debug_id_js_1 = require("./debug-id.js");
+const discover_js_1 = require("./discover.js");
+const http_js_1 = require("./http.js");
+const limits_js_1 = require("./limits.js");
+const multipart_js_1 = require("./multipart.js");
+const url_js_1 = require("./url.js");
+class UploadError extends Error {
+    status;
+    code;
+    hint;
+    constructor(message, status, code, hint) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.hint = hint;
+        this.name = 'UploadError';
+    }
+}
+exports.UploadError = UploadError;
+/**
+ * Index one artifact: what it is, what it hashes to, and how big it will be on the wire.
+ *
+ * The body is built and then DISCARDED. Holding it would mean the whole build sitting in memory
+ * before the first request left — a few hundred chunks of a real application is hundreds of
+ * megabytes — and it is cheap to rebuild from a local file at the moment it is actually sent.
+ *
+ * Returns null when there is nothing to upload, rather than throwing: a directory of chunks where
+ * only some have maps is normal, not an error.
+ */
+async function index(artifact, urlPrefix, options = {}) {
+    if (artifact.map === null)
+        return null;
+    const { body, injected, raw } = await build(artifact, options);
+    const bytes = Buffer.byteLength(body);
+    return {
+        entry: {
+            name: (0, node_path_1.basename)(artifact.map),
+            url: (0, url_js_1.toUrl)(urlPrefix, artifact.relative),
+            debugId: debugIdOf(body),
+            bytes,
+            sha256: (0, node_crypto_1.createHash)('sha256').update(body).digest('hex'),
+            mapSha256: (0, node_crypto_1.createHash)('sha256').update(raw).digest('hex'),
+            injected,
+        },
+        // Reported, not thrown. One 20 MB chunk used to abort the whole upload, so a single
+        // pathological bundle cost symbolication for every other file in the build.
+        oversized: bytes > limits_js_1.MAX_FILE_BYTES,
+        // A map with no mappings and no sources answers no question; Vite emits one per HTML entry.
+        empty: (0, discover_js_1.isEmptyMap)(raw),
+    };
+}
+/**
+ * The exact bytes that go on the wire for this artifact.
+ *
+ * Deterministic, which is what lets `index` throw the body away and this rebuild it later: the id
+ * already injected into the chunk wins, so a second call cannot produce a different map than the
+ * one that was hashed.
+ */
+async function materialise(artifact, options = {}) {
+    return (await build(artifact, options)).body;
+}
+async function build(artifact, options) {
+    if (artifact.map === null)
+        throw new Error(`${artifact.relative} has no source map`);
+    const [code, rawMap] = await Promise.all([
+        (0, promises_1.readFile)(artifact.file, 'utf8'),
+        (0, promises_1.readFile)(artifact.map, 'utf8'),
+    ]);
+    // Prefer the id already injected into the chunk: that is the one the SDK will report, and
+    // deriving a fresh one here would produce a map nothing ever asks for. The map's own id is the
+    // next best thing — a bundler that stamps ids natively writes it there and nowhere else.
+    const injected = (0, debug_id_js_1.existingDebugId)(code);
+    const debugId = injected ?? (0, debug_id_js_1.mapDebugId)(rawMap) ?? (0, debug_id_js_1.deriveDebugId)(code);
+    const prepared = options.rewriteSources === false ? rawMap : rewrite(rawMap, options.root);
+    return { body: (0, debug_id_js_1.injectIntoMap)(prepared, debugId), injected: injected !== null, raw: rawMap };
+}
+const SCHEME = /^(?:webpack|rollup|vite|ng|rspack|turbopack|file):\/{0,3}/i;
+/**
+ * Tidy `sources` in the uploaded copy, never on disk.
+ *
+ * Two things come out of a bundler that should not reach a server. `webpack:///./src/App.tsx` is
+ * a protocol nothing can open, and it is what the UI would print beside every frame. And an
+ * absolute path is the build machine's directory layout — `/home/runner/work/acme/acme/src/…`, or
+ * worse, someone's home directory — which is both noise and information the ingest never asked
+ * for.
+ *
+ * The uploaded copy only. Rewriting the file would change bytes another tool may already have
+ * hashed, and the map on disk is the one a developer opens locally, where an absolute path is
+ * exactly what they want.
+ */
+function rewrite(mapJson, root) {
+    let parsed;
+    try {
+        parsed = JSON.parse(mapJson);
+    }
+    catch {
+        return mapJson;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return mapJson;
+    const map = parsed;
+    const sources = map['sources'];
+    if (!Array.isArray(sources))
+        return mapJson;
+    return JSON.stringify({
+        ...map,
+        sources: sources.map((source) => {
+            if (typeof source !== 'string')
+                return source;
+            let value = source.replace(SCHEME, '');
+            if (root !== undefined && root !== '' && (0, node_path_1.isAbsolute)(value)) {
+                const inside = (0, node_path_1.relative)(root, value);
+                // Only when it is genuinely inside the root: `../../../home/other` is not a tidier path,
+                // it is the same path spelled less clearly.
+                if (!inside.startsWith('..') && !(0, node_path_1.isAbsolute)(inside))
+                    value = inside;
+            }
+            return value.split(node_path_1.sep).join('/').replace(/^\.\//, '');
+        }),
+    });
+}
+function debugIdOf(body) {
+    const parsed = JSON.parse(body);
+    return typeof parsed === 'object' && parsed !== null
+        ? String(parsed['debugId'] ?? '')
+        : '';
+}
+/**
+ * Ask the server which of these bodies it already holds, and what it will accept.
+ *
+ * The dedupe half is purely an optimisation, so every failure mode answers "none": an older ingest
+ * with no such route, a proxy in the way, a network blip. Uploading something the server already
+ * has is a wasted request; NOT uploading something it does not have is a build with no
+ * symbolication, and those are not the same mistake.
+ *
+ * The limits half matters more than it looks. The protocol says 20 MiB per file and 60 MiB per
+ * request, but what a deployment actually accepts is the smaller of that and its PHP
+ * `upload_max_filesize` / `post_max_size` — and a POST over `post_max_size` is not rejected, the
+ * body is silently dropped and the server answers `missing_release`, which reads like a CLI bug.
+ * Asking is the difference between a clear message and an afternoon.
+ */
+async function preflight(options, hashes) {
+    try {
+        const reply = await (0, http_js_1.send)({
+            method: 'POST',
+            url: `${options.host}/v1/sourcemaps/check`,
+            key: options.key,
+            headers: { 'Content-Type': 'application/json', ...options.headers },
+            body: JSON.stringify({ sha256: hashes }),
+            timeoutMs: options.timeoutMs ?? REQUEST_TIMEOUT_MS,
+            ...(options.plugin === undefined ? {} : { plugin: options.plugin }),
+            ...(options.env === undefined ? {} : { env: options.env }),
+        });
+        if (reply.status < 200 || reply.status >= 300)
+            return { stored: new Set(), limits: null };
+        const payload = JSON.parse(reply.text);
+        const stored = payload['stored'];
+        return {
+            stored: Array.isArray(stored) ? new Set(stored.filter((v) => typeof v === 'string')) : new Set(),
+            limits: readLimits(payload['limits']),
+        };
+    }
+    catch {
+        return { stored: new Set(), limits: null };
+    }
+}
+/**
+ * Read the server's limits defensively.
+ *
+ * Every field falls back to the compiled-in protocol value, so a deployment that publishes half
+ * the object, or an older one that publishes none of it, still gets a working client rather than
+ * a batch sized `NaN`.
+ */
+function readLimits(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const raw = value;
+    const number = (name, fallback) => {
+        const found = raw[name];
+        return typeof found === 'number' && Number.isFinite(found) && found > 0 ? found : fallback;
+    };
+    const maxFileBytes = number('maxFileBytes', limits_js_1.MAX_FILE_BYTES);
+    return {
+        maxFileBytes,
+        // `maxPartBytes` is the ini-aware one: the same deployment can advertise a 20 MiB protocol
+        // ceiling and a 2 MiB `upload_max_filesize`, and only one of those is true of the socket.
+        maxPartBytes: number('maxPartBytes', maxFileBytes),
+        maxRequestBytes: number('maxRequestBytes', limits_js_1.MAX_REQUEST_BYTES),
+        // The server calls it `maxBatchBytes`; the older draft of the protocol called it
+        // `recommendedBatchBytes`, and both spellings are read so the deploy order of the two halves
+        // is not load-bearing.
+        recommendedBatchBytes: number('maxBatchBytes', number('recommendedBatchBytes', limits_js_1.RECOMMENDED_BATCH_BYTES)),
+        concurrency: number('concurrency', exports.DEFAULT_CONCURRENCY),
+        compression: Array.isArray(raw['compression'])
+            ? raw['compression'].filter((entry) => typeof entry === 'string')
+            : [],
+    };
+}
+/** Four at a time: enough to hide the latency, few enough not to trip the ingest rate limit. */
+exports.DEFAULT_CONCURRENCY = 4;
+/**
+ * Send one batch.
+ *
+ * Batches are bounded by the request ceiling rather than by count: maps vary from kilobytes to
+ * megabytes, so a fixed count would either waste requests or overshoot.
+ *
+ * Each part is gzipped when the server says it accepts that. `Content-Encoding` does NOT survive
+ * multipart parsing — PHP hands the handler the raw part and nothing else — so a compressed part
+ * is simply a part whose bytes are gzip, which the server detects by its magic number. Source maps
+ * are JSON with long runs of repeated source text and compress by 80–90%, which is the difference
+ * between one request and six.
+ */
+async function send(options, batch, limits = null) {
+    const compress = limits?.compression.includes('gzip') === true;
+    const parts = [
+        { name: 'release', value: options.release },
+        ...(options.dist === undefined || options.dist === '' ? [] : [{ name: 'dist', value: options.dist }]),
+    ];
+    for (const { entry, body } of batch) {
+        parts.push({
+            name: 'files[]',
+            value: compress ? (0, node_zlib_1.gzipSync)(Buffer.from(body, 'utf8'), { level: 6 }) : body,
+            filename: entry.name,
+            contentType: 'application/json',
+        });
+        parts.push({ name: 'urls[]', value: entry.url });
+        parts.push({ name: 'debug_ids[]', value: entry.debugId });
+    }
+    const { body, contentType } = (0, multipart_js_1.multipart)(parts);
+    const attempts = Math.max(1, options.maxRetries ?? MAX_ATTEMPTS);
+    const isDefaultHost = options.host === limits_js_1.DEFAULT_HOST;
+    // Bounded and retried. A deploy step that hangs on a half-open socket, or fails its whole run
+    // on one 502 from a proxy in front of ingest, is worse than a build without symbolication;
+    // the response table says these are transient, so they get the protocol's retry, with backoff.
+    for (let attempt = 0;; attempt += 1) {
+        let reply;
+        try {
+            reply = await (0, http_js_1.send)({
+                method: 'POST',
+                url: `${options.host}/v1/sourcemaps`,
+                key: options.key,
+                headers: { 'Content-Type': contentType, ...options.headers },
+                body,
+                timeoutMs: (0, http_js_1.timeoutFor)(body.length, options.timeoutMs ?? REQUEST_TIMEOUT_MS),
+                ...(options.plugin === undefined ? {} : { plugin: options.plugin }),
+                ...(options.env === undefined ? {} : { env: options.env }),
+            });
+        }
+        catch (error) {
+            if (attempt < attempts - 1 && (0, http_js_1.retriable)(error, isDefaultHost)) {
+                await sleep((0, http_js_1.backoffMs)(attempt));
+                continue;
+            }
+            throw new UploadError(`Could not reach ${options.host}${attempt > 0 ? ` after ${attempt + 1} attempts` : ''}: ${error instanceof Error ? error.message : String(error)}`, 0, 'network', 'Check the host and that the machine running this can reach it.');
+        }
+        let payload = {};
+        try {
+            payload = JSON.parse(reply.text);
+        }
+        catch {
+            // A non-JSON body means something in front of the app answered — a proxy, a WAF, a 502 page.
+        }
+        if (reply.status === 201) {
+            return {
+                stored: Number(payload['stored'] ?? batch.length),
+                artifacts: Array.isArray(payload['artifacts']) ? payload['artifacts'] : [],
+            };
+        }
+        if (http_js_1.RETRIABLE_STATUS.has(reply.status) && attempt < attempts - 1) {
+            await sleep((0, http_js_1.backoffMs)(attempt, reply.header('retry-after')));
+            continue;
+        }
+        throw describe(reply.status, payload, reply.text);
+    }
+}
+/** Three tries: one for the blip, one for the restart, then the truth. */
+const MAX_ATTEMPTS = 3;
+const REQUEST_TIMEOUT_MS = 30_000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Turn a rejection into something actionable.
+ *
+ * Every one of these is a mistake someone will make, and the raw code alone tells them nothing.
+ * `cli_scope_required` in particular looks like a bad key when it is really the right key with the
+ * wrong scope, and without the hint that is a long afternoon.
+ */
+function describe(status, payload, raw) {
+    const code = String(payload['error'] ?? payload['message'] ?? '') || `http_${status}`;
+    switch (code) {
+        case 'cli_scope_required':
+            return new UploadError('That key cannot upload source maps.', status, code, `Source-map upload needs a key with the "${limits_js_1.REQUIRED_SCOPE}" scope. A write key is not enough — create one in project settings.`);
+        case 'missing_api_key':
+        case 'invalid_api_key':
+            return new UploadError('The write key was rejected.', status, code, 'Check --key, or the VINKTAR_CLI_KEY environment variable.');
+        case 'missing_release':
+            return new UploadError('A release is required.', status, code, 
+            // The second sentence is the one that saves the afternoon: an oversized POST is not
+            // rejected by PHP, the body is dropped, and the server then honestly reports no release.
+            'Pass --release with the same value your SDK reports. If you did pass one, the request was over the server\'s post_max_size and its body was discarded before PHP saw it — lower the batch size or raise post_max_size.');
+        case 'invalid_release':
+        case 'invalid_dist':
+            return new UploadError(`The ${code === 'invalid_release' ? 'release' : 'dist'} name was rejected.`, status, code, 'It must be at most 64 bytes and contain no slashes, control characters, or leading or trailing whitespace.');
+        case 'missing_url_or_debug_id':
+            return new UploadError('A file had neither a URL nor a debug id, so the whole upload was rejected.', status, code, 'This is a bug in the CLI — please report it with the command you ran.');
+        case 'quota_exceeded': {
+            const quota = Number(payload['quota_bytes'] ?? 0);
+            const used = Number(payload['used_bytes'] ?? 0);
+            return new UploadError(`Source-map storage is full: ${mb(used)} of ${mb(quota)} used.`, status, code, 'Delete old releases from project settings, or upgrade the plan for more storage.');
+        }
+        case 'file_too_large':
+            return new UploadError(`A map is over the ${mb(Number(payload['max_bytes'] ?? limits_js_1.MAX_FILE_BYTES))} per-file limit.`, status, code, 'Split the bundle, or exclude that chunk with --ignore.');
+        case 'payload_too_large':
+            return new UploadError(`The request was too large${payload['max_bytes'] === undefined ? '' : ` (the server accepts ${mb(Number(payload['max_bytes']))})`}.`, status, code, 'Lower --concurrency, or raise the server\'s post_max_size.');
+        default:
+            return new UploadError(`Ingest rejected the upload (HTTP ${status}).`, status, code, raw.slice(0, 200) || undefined);
+    }
+}
+/**
+ * Group indexed maps into requests that fit.
+ *
+ * The budget is approached with headroom, because multipart framing and the field names add bytes
+ * the file sizes do not account for, and an oversized request costs the whole batch. Sized on the
+ * UNCOMPRESSED bodies even when the parts will be gzipped: compression only ever makes the request
+ * smaller, so the bound stays true and one batch's worth of maps is still what sits in memory.
+ *
+ * Generic over whatever the caller is carrying alongside the entry, so a batch can hold the
+ * artifact each map came from and the body can be read back from disk as its batch is sent —
+ * nothing here pins the build in memory.
+ */
+function batch(items, limits = null) {
+    // Without a word from the server this stays deliberately small — see CONSERVATIVE_BATCH_BYTES.
+    const budget = limits === null
+        ? limits_js_1.CONSERVATIVE_BATCH_BYTES
+        : Math.max(1, Math.min(limits.recommendedBatchBytes, Math.floor(limits.maxRequestBytes * 0.9)));
+    const framing = (0, multipart_js_1.overheadFor)({ name: 'files[]', value: '', filename: 'x'.repeat(64), contentType: 'application/json' });
+    const batches = [];
+    let current = [];
+    let size = 0;
+    for (const item of items) {
+        const cost = item.entry.bytes + framing;
+        if (current.length > 0 && size + cost > budget) {
+            batches.push(current);
+            current = [];
+            size = 0;
+        }
+        current.push(item);
+        size += cost;
+    }
+    if (current.length > 0)
+        batches.push(current);
+    return batches;
+}
+/**
+ * Run `work` over `items` with a bounded number in flight.
+ *
+ * Source maps are large and the server is usually far away, so a build of two hundred chunks spent
+ * most of its upload waiting on a socket. Bounded rather than unbounded: an unbounded fan-out of
+ * 6 MB requests is how a deploy step gets itself rate-limited.
+ */
+async function pooled(items, limit, work) {
+    const results = new Array(items.length);
+    let next = 0;
+    const runner = async () => {
+        for (;;) {
+            const i = next;
+            next += 1;
+            if (i >= items.length)
+                return;
+            results[i] = await work(items[i], i);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, runner));
+    return results;
+}
+function mb(bytes) {
+    return `${(bytes / 1_048_576).toFixed(1)} MB`;
+}

package/dist/cjs/url.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Derives the `urls[]` value the server matches a frame against.
+ *
+ * `urls[]` is not optional in practice, and this is the one part of the contract most likely to be
+ * got wrong: `docs/API.md` omits the field entirely, but if a file's resolved debug id is empty
+ * AND its normalised url is empty, the server answers 400 and rolls back the WHOLE upload — not
+ * just that file.
+ *
+ * The server normalises what it stores by stripping the query, the fragment, and then the scheme
+ * and host, leaving a path. It applies the identical normalisation to the `file` on a runtime
+ * frame before comparing. So `https://cdn.example.com/assets/app.js?v=2` and `/assets/app.js`
+ * match, and a prefix that is a full origin is just as correct as one that is a bare path.
+ */
+/**
+ * @param prefix   what the file is served under: `/assets/`, `https://cdn.example.com/`, or `~/`
+ * @param relative the file's path relative to the upload root
+ */
+export declare function toUrl(prefix: string, relative: string): string;
+/**
+ * The server's own normalisation, reproduced so `--dry-run` can show what will actually be stored.
+ *
+ * Printing this is the difference between "the upload succeeded but nothing symbolicates" and a
+ * mismatch someone can see before spending a minute uploading.
+ */
+export declare function normalise(url: string): string;

package/dist/cjs/url.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Derives the `urls[]` value the server matches a frame against.
+ *
+ * `urls[]` is not optional in practice, and this is the one part of the contract most likely to be
+ * got wrong: `docs/API.md` omits the field entirely, but if a file's resolved debug id is empty
+ * AND its normalised url is empty, the server answers 400 and rolls back the WHOLE upload — not
+ * just that file.
+ *
+ * The server normalises what it stores by stripping the query, the fragment, and then the scheme
+ * and host, leaving a path. It applies the identical normalisation to the `file` on a runtime
+ * frame before comparing. So `https://cdn.example.com/assets/app.js?v=2` and `/assets/app.js`
+ * match, and a prefix that is a full origin is just as correct as one that is a bare path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toUrl = toUrl;
+exports.normalise = normalise;
+/**
+ * @param prefix   what the file is served under: `/assets/`, `https://cdn.example.com/`, or `~/`
+ * @param relative the file's path relative to the upload root
+ */
+function toUrl(prefix, relative) {
+    const left = prefix.endsWith('/') ? prefix : `${prefix}/`;
+    const right = relative.startsWith('/') ? relative.slice(1) : relative;
+    return `${left}${right}`;
+}
+/**
+ * The server's own normalisation, reproduced so `--dry-run` can show what will actually be stored.
+ *
+ * Printing this is the difference between "the upload succeeded but nothing symbolicates" and a
+ * mismatch someone can see before spending a minute uploading.
+ */
+function normalise(url) {
+    let value = url.split('#')[0] ?? '';
+    value = value.split('?')[0] ?? '';
+    const scheme = value.match(/^[a-z][a-z0-9+.-]*:\/\/[^/]*/i);
+    if (scheme)
+        value = value.slice(scheme[0].length);
+    // `~/` is the conventional "wherever this is served from" prefix; it is not part of the path.
+    if (value.startsWith('~'))
+        value = value.slice(1);
+    return value.startsWith('/') ? value : `/${value}`;
+}

package/dist/cjs/version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The published version, kept by hand.
+ *
+ * Its own module so the HTTP layer can put it in a `User-Agent` without importing the CLI's
+ * argument parser, which would make every plugin drag the command surface into a build.
+ *
+ * A test asserts it matches `package.json`, and `prepublishOnly` runs that test — reading the
+ * manifest at runtime instead would mean resolving a path that moves between `src` and `dist`.
+ */
+export declare const VERSION = "0.1.0";

package/dist/cjs/version.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+/**
+ * The published version, kept by hand.
+ *
+ * Its own module so the HTTP layer can put it in a `User-Agent` without importing the CLI's
+ * argument parser, which would make every plugin drag the command surface into a build.
+ *
+ * A test asserts it matches `package.json`, and `prepublishOnly` runs that test — reading the
+ * manifest at runtime instead would mean resolving a path that moves between `src` and `dist`.
+ */
+exports.VERSION = '0.1.0';

package/dist/cli.d.ts

@@ -0,0 +1,17 @@
+import { VERSION } from './version.js';
+export interface Args {
+    readonly positional: string[];
+    readonly flags: Map<string, string | boolean>;
+    /** Values of repeatable flags, in order. `--ignore` and `--header` are the two. */
+    readonly repeated: Map<string, string[]>;
+}
+export declare function parse(argv: readonly string[]): Args;
+/**
+ * Exit codes: 0 fine, 1 the thing did not work, 2 it worked and something is wrong anyway.
+ *
+ * Two rather than one for `--strict`, so a pipeline can tell "the upload failed" from "the upload
+ * succeeded and half your chunks have no maps" — which are different problems with different
+ * owners, and merging them means neither gets fixed.
+ */
+export declare function run(argv: readonly string[], log?: (message?: any, ...optionalParams: any[]) => void, fail?: (message?: any, ...optionalParams: any[]) => void): Promise<number>;
+export { VERSION };