@vinktarhq/cli 0.1.0

package/dist/cjs/discover.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Finds built JavaScript and the map that belongs to it.
+ *
+ * Hand-rolled rather than a glob dependency: the package ships with zero runtime dependencies, and
+ * "walk a directory" is not worth one.
+ */
+export interface Artifact {
+    /** Absolute path to the .js file. */
+    readonly file: string;
+    /** Absolute path to its .map, when one could be resolved. */
+    readonly map: string | null;
+    /** Path relative to the upload root, which is what the URL is derived from. */
+    readonly relative: string;
+}
+export interface Discovery {
+    readonly artifacts: Artifact[];
+    /** Everything that was skipped and why. Never silent: a missing map is a minified release. */
+    readonly warnings: string[];
+}
+/** What counts as a chunk, absent `--ext`. */
+export declare const DEFAULT_EXTENSIONS: string[];
+export interface DiscoverOptions {
+    /**
+     * Globs, matched against the path relative to the root. An ignored chunk is skipped whole — it
+     * is neither stamped nor uploaded, so an ignore rule can never orphan an id by removing a map
+     * whose chunk still names it.
+     */
+    readonly ignore?: readonly string[];
+    /** Extensions to treat as chunks, without the dot. Defaults to {@link DEFAULT_EXTENSIONS}. */
+    readonly extensions?: readonly string[];
+}
+export declare function discover(root: string, options?: DiscoverOptions): Promise<Discovery>;
+/**
+ * Every file under a directory, absolute, each one once.
+ *
+ * Exported for the plugins' cleanup pass, which has to find files `discover` deliberately ignores
+ * — a `.css.map` is not a chunk, but it is still the stylesheet's sources sitting in a public
+ * directory.
+ */
+export declare function allFiles(root: string): Promise<string[]>;
+export declare function sizeOf(path: string): Promise<number>;
+/**
+ * A map that cannot resolve anything: no mappings and no sources.
+ *
+ * Vite emits one per HTML entry in a multi-page build, for a facade chunk that is nothing but
+ * imports. Stamping those produces ids no frame will ever report and uploads bytes that answer no
+ * question. "Empty" deliberately means the MAP is empty and never that the code is short: a small
+ * single-page entry chunk is real code whose frames matter.
+ */
+export declare function isEmptyMap(mapJson: string): boolean;

package/dist/cjs/discover.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_EXTENSIONS = void 0;
+exports.discover = discover;
+exports.allFiles = allFiles;
+exports.sizeOf = sizeOf;
+exports.isEmptyMap = isEmptyMap;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const glob_js_1 = require("./glob.js");
+// Entry names, matched against a single directory name. `.next/cache` used to be in here and
+// could never match anything, because a directory entry is never a path.
+const SKIP_DIRECTORIES = new Set(['node_modules', '.git', 'coverage', 'cache']);
+/** What counts as a chunk, absent `--ext`. */
+exports.DEFAULT_EXTENSIONS = ['js', 'cjs', 'mjs'];
+/**
+ * `//# sourceMappingURL=`, and the legacy `//@` spelling some older toolchains still emit.
+ *
+ * Matched line-anchored so the string appearing inside a bundled literal — a tool that writes these
+ * comments, bundled into an application — cannot be mistaken for a real reference.
+ */
+const SOURCE_MAPPING_COMMENT = /^\/\/[#@] sourceMappingURL=(.*)$/gm;
+/** How much of a chunk's tail is searched for the reference. It is emitted as the final line. */
+const TAIL_BYTES = 65_536;
+async function discover(root, options = {}) {
+    const warnings = [];
+    const files = await walk(root, new Set());
+    const script = extensionMatcher(options.extensions);
+    const ignore = options.ignore ?? [];
+    const scripts = files
+        .filter((file) => script.test(file))
+        .filter((file) => !(0, glob_js_1.matches)((0, node_path_1.relative)(root, file).split(node_path_1.sep).join('/'), ignore))
+        .sort((a, b) => a.localeCompare(b));
+    const present = new Set(files);
+    const resolved = [];
+    for (const file of scripts) {
+        resolved.push(await locate(file, present, warnings));
+    }
+    return { artifacts: assign(resolved, root, warnings), warnings };
+}
+/**
+ * The map for one chunk: what it says, then what sits beside it.
+ *
+ * Asking the chunk first is not a refinement, it is the difference between working and not. A
+ * build configured with `sourcemapFileNames`, webpack's `sourceMapFilename`, or any output that
+ * puts maps in their own directory has no `<file>.map` sibling at all, so guessing alone found
+ * nothing and uploaded nothing, without a word.
+ */
+async function locate(file, present, warnings) {
+    const referenced = await reference(file);
+    if (referenced !== null) {
+        if (referenced.startsWith('data:')) {
+            // Decoding it would mean rewriting the chunk to carry a map we then upload separately, for a
+            // configuration that has already chosen to ship its map to users.
+            warnings.push(`${file} has an inline source map; inline maps are not uploaded.`);
+            return { file, map: null, explicit: false };
+        }
+        // A remote or protocol-relative URL names something on a CDN, not on this disk. Joining it to
+        // the chunk's directory produced paths like `dist/https:/cdn.example.com/app.js.map`.
+        if (!/^(?:[a-z][a-z0-9+.-]*:)?\/\//i.test(referenced)) {
+            const target = clean(referenced);
+            const candidate = (0, node_path_1.isAbsolute)(target) ? target : (0, node_path_1.resolve)((0, node_path_1.dirname)(file), target);
+            if (present.has(candidate))
+                return { file, map: candidate, explicit: true };
+        }
+    }
+    const sibling = `${file}.map`;
+    return { file, map: present.has(sibling) ? sibling : null, explicit: false };
+}
+/** Strip the query and fragment a cache-busting build appends, then percent-decode. */
+function clean(url) {
+    const bare = (url.split('#')[0] ?? '').split('?')[0] ?? '';
+    try {
+        return decodeURIComponent(bare);
+    }
+    catch {
+        return bare;
+    }
+}
+/** The last `sourceMappingURL` in a chunk, read from its tail rather than its whole body. */
+async function reference(file) {
+    let tail;
+    try {
+        const handle = await (0, promises_1.open)(file, 'r');
+        try {
+            const { size } = await handle.stat();
+            const length = Math.min(size, TAIL_BYTES);
+            const buffer = Buffer.alloc(length);
+            await handle.read(buffer, 0, length, Math.max(0, size - length));
+            tail = buffer.toString('utf8');
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return null;
+    }
+    let last = null;
+    for (const match of tail.matchAll(SOURCE_MAPPING_COMMENT))
+        last = match;
+    const url = last?.[1]?.trim();
+    return url === undefined || url === '' ? null : url;
+}
+/**
+ * Turn resolved pairs into artifacts, refusing any map that more than one chunk claims.
+ *
+ * Two chunks pointing at one map is not a map serving two chunks: it is a stale reference, a copied
+ * file, or a guess that happened to land on someone else's map. Writing a debug id into it would
+ * make the last writer win, so the id in the map would disagree with the id in every chunk but one
+ * and none of them would resolve. An explicit reference beats a guess, because the chunk that named
+ * the map is the one that meant it.
+ */
+function assign(resolved, root, warnings) {
+    const claimants = new Map();
+    for (const entry of resolved) {
+        if (entry.map === null)
+            continue;
+        const list = claimants.get(entry.map) ?? [];
+        list.push({ file: entry.file, explicit: entry.explicit });
+        claimants.set(entry.map, list);
+    }
+    const owner = new Map();
+    for (const [map, list] of claimants) {
+        if (list.length === 1) {
+            owner.set(map, list[0].file);
+            continue;
+        }
+        const explicit = list.filter((entry) => entry.explicit);
+        if (explicit.length === 1) {
+            owner.set(map, explicit[0].file);
+            warnings.push(`${map} is claimed by ${list.length} chunks; using the one that references it (${explicit[0].file}).`);
+            continue;
+        }
+        owner.set(map, null);
+        warnings.push(`${map} is claimed by ${list.length} chunks and none of them names it; leaving all of them without a map.`);
+    }
+    return resolved.map((entry) => ({
+        file: entry.file,
+        map: entry.map !== null && owner.get(entry.map) === entry.file ? entry.map : null,
+        // Always forward slashes: a URL is not a Windows path.
+        relative: (0, node_path_1.relative)(root, entry.file).split(node_path_1.sep).join('/'),
+    }));
+}
+/**
+ * Every file under a directory, each one exactly once.
+ *
+ * Symlinks are followed, and the real path of each directory is remembered, because a build output
+ * that links to a shared asset directory is ordinary and a link that points back up the tree is a
+ * loop. Visiting a file twice would stamp it twice and upload a stale copy of it.
+ */
+async function walk(directory, seen) {
+    const real = await (0, promises_1.realpath)(directory).catch(() => directory);
+    if (seen.has(real))
+        return [];
+    seen.add(real);
+    const entries = await (0, promises_1.readdir)(directory, { withFileTypes: true });
+    const found = [];
+    for (const entry of entries) {
+        const path = (0, node_path_1.join)(directory, entry.name);
+        let isDirectory = entry.isDirectory();
+        let isFile = entry.isFile();
+        if (entry.isSymbolicLink()) {
+            // `readdir` reports the link, never its target, so a symlinked chunk is neither a file nor a
+            // directory here and was silently dropped from every build that used one.
+            const target = await (0, promises_1.stat)(path).catch(() => null);
+            if (target === null)
+                continue;
+            isDirectory = target.isDirectory();
+            isFile = target.isFile();
+        }
+        if (isDirectory) {
+            if (SKIP_DIRECTORIES.has(entry.name))
+                continue;
+            found.push(...(await walk(path, seen)));
+            continue;
+        }
+        if (isFile)
+            found.push(path);
+    }
+    return found;
+}
+/**
+ * Every file under a directory, absolute, each one once.
+ *
+ * Exported for the plugins' cleanup pass, which has to find files `discover` deliberately ignores
+ * — a `.css.map` is not a chunk, but it is still the stylesheet's sources sitting in a public
+ * directory.
+ */
+async function allFiles(root) {
+    return walk(root, new Set());
+}
+/**
+ * `--ext ts,mts` and friends, escaped.
+ *
+ * Escaped because the value comes from a command line, and an extension containing a regex
+ * metacharacter would otherwise quietly widen the match rather than fail — which is the kind of
+ * bug that shows up as "why did it upload that".
+ */
+function extensionMatcher(extensions = exports.DEFAULT_EXTENSIONS) {
+    const cleaned = extensions
+        .map((extension) => extension.trim().replace(/^\./, ''))
+        .filter((extension) => extension !== '')
+        .map((extension) => extension.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    if (cleaned.length === 0)
+        return new RegExp(`\\.(?:${exports.DEFAULT_EXTENSIONS.join('|')})$`);
+    return new RegExp(`\\.(?:${cleaned.join('|')})$`);
+}
+async function sizeOf(path) {
+    return (await (0, promises_1.stat)(path)).size;
+}
+/**
+ * A map that cannot resolve anything: no mappings and no sources.
+ *
+ * Vite emits one per HTML entry in a multi-page build, for a facade chunk that is nothing but
+ * imports. Stamping those produces ids no frame will ever report and uploads bytes that answer no
+ * question. "Empty" deliberately means the MAP is empty and never that the code is short: a small
+ * single-page entry chunk is real code whose frames matter.
+ */
+function isEmptyMap(mapJson) {
+    try {
+        const parsed = JSON.parse(mapJson);
+        if (typeof parsed !== 'object' || parsed === null)
+            return false;
+        const map = parsed;
+        if (Array.isArray(map['sections']))
+            return map['sections'].length === 0;
+        const mappings = map['mappings'];
+        const sources = map['sources'];
+        return ((typeof mappings !== 'string' || mappings === '') && (!Array.isArray(sources) || sources.length === 0));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cjs/env.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Reading `VINKTAR_*` out of a `.env` file.
+ *
+ * Deliberately small. This is not a dotenv replacement: it exists so a developer running the CLI
+ * by hand gets the same values their Vite build already reads, and it stops there.
+ *
+ * **No `$VAR` interpolation.** A `.env` that can reference the process environment is a `.env`
+ * that can exfiltrate it — `VINKTAR_HOST=https://$AWS_SECRET_ACCESS_KEY.example.com` is a
+ * one-line data leak in a file people paste from a README. Values are literal.
+ */
+export interface DotEnv {
+    readonly values: Record<string, string>;
+    readonly warnings: string[];
+    /** Whether the file existed at all. A missing file is not an error, and not silent either. */
+    readonly found: boolean;
+}
+/**
+ * @param path the file to read. The flag that supplies it is `--dotenv-file`, never `--env-file`:
+ *   Node has owned `--env-file` since 20.6 and swallows it before the CLI's own parser ever sees
+ *   the argument, so a user passing it would silently configure Node instead.
+ */
+export declare function loadDotEnv(path: string): Promise<DotEnv>;

package/dist/cjs/env.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadDotEnv = loadDotEnv;
+const promises_1 = require("node:fs/promises");
+/**
+ * @param path the file to read. The flag that supplies it is `--dotenv-file`, never `--env-file`:
+ *   Node has owned `--env-file` since 20.6 and swallows it before the CLI's own parser ever sees
+ *   the argument, so a user passing it would silently configure Node instead.
+ */
+async function loadDotEnv(path) {
+    let raw;
+    try {
+        raw = await (0, promises_1.readFile)(path, 'utf8');
+    }
+    catch {
+        return { values: {}, warnings: [], found: false };
+    }
+    const values = {};
+    const warnings = [];
+    raw.split(/\r?\n/).forEach((line, index) => {
+        const trimmed = line.trim();
+        if (trimmed === '' || trimmed.startsWith('#'))
+            return;
+        const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(trimmed);
+        if (match === null) {
+            // Named with the line number, because "malformed .env" and nothing else is a file people
+            // then read from the top, three times.
+            warnings.push(`${path}:${index + 1} is not NAME=value and was ignored.`);
+            return;
+        }
+        const name = match[1];
+        if (!name.startsWith('VINKTAR_'))
+            return;
+        values[name] = unquote(match[2] ?? '');
+    });
+    return { values, warnings, found: true };
+}
+/**
+ * Strip one layer of matching quotes, and the trailing comment on an unquoted value.
+ *
+ * `KEY=abc # staging` means the key is `abc`, which is the behaviour every dotenv implementation
+ * has and the one people write against. Inside quotes a `#` is part of the value.
+ */
+function unquote(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"') && trimmed.length > 1) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'") && trimmed.length > 1)) {
+        return trimmed.slice(1, -1);
+    }
+    const comment = trimmed.indexOf(' #');
+    return (comment === -1 ? trimmed : trimmed.slice(0, comment)).trim();
+}

package/dist/cjs/glob.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A glob matcher, hand-rolled.
+ *
+ * `--ignore` needs one, and every candidate dependency costs more than it is worth here: this
+ * package ships zero runtime dependencies, and the one library that would do it without pulling a
+ * tree behind it (`picomatch`) is still a download on every `npx` invocation, on every CI run.
+ * `node:fs`'s own glob support arrived in Node 22, which would move the supported floor from 18
+ * for a feature nobody upgrades Node for.
+ *
+ * Supported, which is the intersection of what a build output needs and what people actually
+ * write: `*` (anything but `/`), `**` (anything, including `/`), `?` (one character but `/`),
+ * `[abc]` and `[!abc]` classes, and `{a,b}` alternation. Brace nesting is one level, because a
+ * pattern that needs two is a pattern nobody will read twice.
+ */
+/**
+ * Compile a glob to a RegExp anchored at both ends.
+ *
+ * Written as a single left-to-right scan rather than a chain of `String.replace` calls, which is
+ * the usual shape and is wrong for the same reason every time: an earlier replacement's output
+ * becomes a later one's input, so `**` is rewritten by the `*` rule and a `\*` escape is honoured
+ * by whichever rule happens to run last.
+ */
+export declare function compile(pattern: string): RegExp;
+/**
+ * Whether a path matches any of the patterns.
+ *
+ * A bare pattern with no `/` is matched against the basename as well as the whole path, because
+ * `--ignore '*.min.js'` means "any minified file", not "a minified file at the root" — and being
+ * told the flag did nothing is not the same as being told why.
+ *
+ * Paths are compared with forward slashes, always: the patterns people write come from a shell or
+ * a config file and never contain backslashes, whatever platform they run on.
+ */
+export declare function matches(path: string, patterns: readonly string[]): boolean;

package/dist/cjs/glob.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * A glob matcher, hand-rolled.
+ *
+ * `--ignore` needs one, and every candidate dependency costs more than it is worth here: this
+ * package ships zero runtime dependencies, and the one library that would do it without pulling a
+ * tree behind it (`picomatch`) is still a download on every `npx` invocation, on every CI run.
+ * `node:fs`'s own glob support arrived in Node 22, which would move the supported floor from 18
+ * for a feature nobody upgrades Node for.
+ *
+ * Supported, which is the intersection of what a build output needs and what people actually
+ * write: `*` (anything but `/`), `**` (anything, including `/`), `?` (one character but `/`),
+ * `[abc]` and `[!abc]` classes, and `{a,b}` alternation. Brace nesting is one level, because a
+ * pattern that needs two is a pattern nobody will read twice.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compile = compile;
+exports.matches = matches;
+const SPECIAL = /[.+^${}()|[\]\\]/g;
+/**
+ * Compile a glob to a RegExp anchored at both ends.
+ *
+ * Written as a single left-to-right scan rather than a chain of `String.replace` calls, which is
+ * the usual shape and is wrong for the same reason every time: an earlier replacement's output
+ * becomes a later one's input, so `**` is rewritten by the `*` rule and a `\*` escape is honoured
+ * by whichever rule happens to run last.
+ */
+function compile(pattern) {
+    let source = '';
+    for (let i = 0; i < pattern.length; i += 1) {
+        const char = pattern[i];
+        if (char === '*') {
+            const double = pattern[i + 1] === '*';
+            if (double) {
+                i += 1;
+                // `a/**/b` must also match `a/b`: the separator after `**` is part of what it consumes.
+                if (pattern[i + 1] === '/') {
+                    i += 1;
+                    source += '(?:.*/)?';
+                    continue;
+                }
+                source += '.*';
+                continue;
+            }
+            source += '[^/]*';
+            continue;
+        }
+        if (char === '?') {
+            source += '[^/]';
+            continue;
+        }
+        if (char === '[') {
+            const end = pattern.indexOf(']', i + 1);
+            if (end === -1) {
+                source += '\\[';
+                continue;
+            }
+            const body = pattern.slice(i + 1, end);
+            source += `[${body.startsWith('!') ? `^${body.slice(1)}` : body}]`;
+            i = end;
+            continue;
+        }
+        if (char === '{') {
+            const end = pattern.indexOf('}', i + 1);
+            if (end === -1) {
+                source += '\\{';
+                continue;
+            }
+            const options = pattern.slice(i + 1, end).split(',');
+            source += `(?:${options.map((option) => compile(option).source.slice(1, -1)).join('|')})`;
+            i = end;
+            continue;
+        }
+        source += char.replace(SPECIAL, '\\$&');
+    }
+    return new RegExp(`^${source}$`);
+}
+/**
+ * Whether a path matches any of the patterns.
+ *
+ * A bare pattern with no `/` is matched against the basename as well as the whole path, because
+ * `--ignore '*.min.js'` means "any minified file", not "a minified file at the root" — and being
+ * told the flag did nothing is not the same as being told why.
+ *
+ * Paths are compared with forward slashes, always: the patterns people write come from a shell or
+ * a config file and never contain backslashes, whatever platform they run on.
+ */
+function matches(path, patterns) {
+    if (patterns.length === 0)
+        return false;
+    const target = path.split('\\').join('/');
+    const base = target.slice(target.lastIndexOf('/') + 1);
+    return patterns.some((pattern) => {
+        const expression = compiled(pattern);
+        if (expression.test(target))
+            return true;
+        if (!pattern.includes('/') && expression.test(base))
+            return true;
+        // A directory pattern covers everything under it: `--ignore vendor` should not need
+        // `vendor/**` as well, which is the first thing anyone gets wrong.
+        return compiled(pattern.endsWith('/') ? `${pattern}**` : `${pattern}/**`).test(target);
+    });
+}
+const cache = new Map();
+function compiled(pattern) {
+    const found = cache.get(pattern);
+    if (found !== undefined)
+        return found;
+    const expression = compile(pattern);
+    cache.set(pattern, expression);
+    return expression;
+}

package/dist/cjs/http.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The one place a request leaves this package.
+ *
+ * `fetch` does the work, except when it cannot: Node's `fetch` ignores `HTTPS_PROXY` entirely, and
+ * in a corporate network that is not a slow upload but an `ECONNREFUSED` from a CLI that "works on
+ * my machine" while every other tool in the pipeline succeeds. When a proxy is configured the
+ * request goes out over `node:http`/`node:https` through a CONNECT tunnel instead; when one is
+ * not — the overwhelmingly common case — nothing about the path changes.
+ */
+export interface RequestOptions {
+    readonly method: 'GET' | 'POST';
+    readonly url: string;
+    readonly key?: string;
+    readonly body?: Buffer | string;
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Whole-request deadline. Callers scale it for large bodies. */
+    readonly timeoutMs: number;
+    /** Appended to the User-Agent, e.g. `vite-plugin/0.1.0`. */
+    readonly plugin?: string;
+    readonly env?: Record<string, string | undefined>;
+}
+export interface Reply {
+    readonly status: number;
+    readonly text: string;
+    header(name: string): string | null;
+}
+/**
+ * `vinktar-cli/<version> (node/<version>)`, plus the plugin when a bundler is driving.
+ *
+ * The server logs it, and "which of these is the Vite plugin and which is a hand-run CI script" is
+ * the first question anyone asks of an ingest log.
+ */
+export declare function userAgent(plugin?: string): string;
+export declare function send(options: RequestOptions): Promise<Reply>;
+/**
+ * The proxy that should carry a request to `url`, honouring `NO_PROXY`.
+ *
+ * Lower case wins over upper case, which is what curl does and therefore what people expect:
+ * `http_proxy` is the historical spelling and the one a shell profile sets.
+ */
+export declare function proxyFor(url: string, env?: Record<string, string | undefined>): URL | null;
+/** Exposed so the retry policy can be asserted rather than inferred from a stack trace. */
+export declare const RETRIABLE_STATUS: Set<number>;
+/**
+ * Whether a failed request is worth repeating.
+ *
+ * `ENOTFOUND` is on the list only for the default host: a self-hosted URL that does not resolve is
+ * a typo, and retrying a typo three times with backoff turns a one-second error into a ten-second
+ * one and teaches nobody anything.
+ */
+export declare function retriable(error: unknown, isDefaultHost: boolean): boolean;
+/**
+ * How long to wait before trying again.
+ *
+ * `Retry-After` is honoured when the server sends one — it is the only party that knows when its
+ * rate limit resets — and capped, because a proxy answering `Retry-After: 3600` must not hang a
+ * deploy for an hour. Otherwise exponential with jitter, so two builds that fail together do not
+ * retry together.
+ */
+export declare function backoffMs(attempt: number, retryAfter?: string | null): number;
+/**
+ * The deadline for a request carrying `bytes`.
+ *
+ * One flat timeout punishes a large upload for being large: 30 s is generous for a handshake and
+ * mean for 40 MB over a hotel connection. This is the connect-and-settle allowance plus an
+ * assumption of a slow-but-real 1 Mbit/s.
+ */
+export declare function timeoutFor(bytes: number, base: number): number;