@vinktarhq/cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+### Bundler plugins
+
+- Plugins for **Vite, Rollup, webpack, rspack and esbuild** over one shared core, each stamping at
+  the last point that still owns the content hash — `renderChunk` (`order: 'post'`) for Rollup and
+  Vite, `processAssets` just before `PROCESS_ASSETS_STAGE_OPTIMIZE_HASH` for webpack and rspack.
+  Every one is covered by a real fixture build, including Vite 8's Rolldown pipeline.
+- The Vite plugin exposes `import.meta.env.VINKTAR_KEY`, `VINKTAR_HOST`, `VINKTAR_ENVIRONMENT` and
+  `VINKTAR_RELEASE` to the bundle, so the release the SDK reports is the one the maps went up
+  under. The `cli` key is never exposed.
+- Source maps are **deleted from the build output by default**, and the deletion runs even when no
+  key is configured — an unset CI secret must not turn into a published copy of your source.
+- `disable` returns a no-op plugin before any environment, git or network work, for a config shared
+  with vitest or Storybook. `injectDebugIds: false` uploads without modifying a chunk, for builds
+  under a strict CSP or with integrity computed elsewhere.
+
+### Debug IDs
+
+- Each chunk is stamped with an id derived from its own bytes and registered at runtime under the
+  chunk's own stack signature, so a frame can be matched to its artifact even when the URL or the
+  release string is wrong. The id is carried both as a `//# debugId=` comment and as a string
+  literal inside the snippet, so it survives a minifier that strips comments.
+- An id another tool already stamped — Rollup's `output.sourcemapDebugIds`, webpack 5.104's
+  `debugIds`, esbuild, Rolldown — is adopted rather than replaced.
+- The snippet goes at the top of the chunk, after any hashbang and directive prologue, so a chunk
+  that throws while initialising still registers. The map is corrected exactly, by splicing one
+  empty group into `mappings`, with no dependency. Under Rolldown it is appended instead, because
+  the minifier there rebuilds the map after the plugin runs with no hook in between.
+
+### Uploads
+
+- Content-addressed pre-flight: the CLI asks which hashes ingest already holds and sends only the
+  rest, so a redeploy of an unchanged build sends nothing.
+- Batch size, per-file caps, concurrency and compression follow what the **server publishes**
+  rather than numbers compiled in here. Parts are gzipped when the server accepts them.
+- `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` are honoured over a CONNECT tunnel, which Node's own
+  `fetch` ignores.
+- Uploaded `sources` are tidied — bundler URL prefixes stripped, absolute build paths made relative
+  to the build root — in the uploaded copy only. Disable with `--no-rewrite-sources`.
+- Retries on 429 (honouring `Retry-After`), 502, 503, 504, 507, 524 and transient network errors.
+
+### CLI
+
+- `sourcemaps upload`, `sourcemaps inject`, `sourcemaps resolve` and `doctor`.
+- `resolve` decodes a position locally and prints the original line with context, so "would this
+  frame resolve, and to what" can be answered without causing a real error in production.
+- `doctor --dir` reports chunk/map id mismatches, maps missing `sourcesContent`, empty maps, ids
+  nothing registers at runtime, and chunks stamped twice.
+- Configuration by flag, environment or `.env`, in that order. A value that is blank after trimming
+  is refused by name rather than treated as unset.
+
+### Packaging
+
+- ESM and CommonJS, so a CommonJS `webpack.config.js` can `require()` the plugin. `@vinktarhq/cli/vite`
+  is ESM-only, since Vite configs are ESM and it loads Vite dynamically.
+- Zero runtime dependencies. Node 18+.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinktar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,378 @@
+# @vinktarhq/cli
+
+[![npm](https://img.shields.io/npm/v/@vinktarhq/cli.svg)](https://www.npmjs.com/package/@vinktarhq/cli)
+[![CI](https://github.com/vinktarhq/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/vinktarhq/cli/actions/workflows/ci.yml)
+[![node](https://img.shields.io/node/v/@vinktarhq/cli.svg)](https://nodejs.org)
+[![licence](https://img.shields.io/npm/l/@vinktarhq/cli.svg)](./LICENSE)
+
+Makes your production stack traces resolve to the code you wrote instead of a minified bundle.
+
+Add one plugin to your bundler. On every build it stamps each chunk with a debug id, uploads the
+source maps to Vinktar, and deletes them from the output so they are never served to users.
+
+```ts
+// vite.config.ts
+import { vinktar } from '@vinktarhq/cli/vite';
+
+export default defineConfig({ plugins: [vinktar()] });
+```
+
+```bash
+export VINKTAR_CLI_KEY=vnk_sk_…   # a key with the "cli" scope
+npm run build
+```
+
+That is the whole setup. Rollup, webpack, rspack and esbuild have the same plugin, and there is a
+CLI for pipelines that build in one place and upload from another.
+
+**Node 18+. Zero runtime dependencies** — `npx` downloads the whole manifest before it runs a
+line, so every dependency would be latency on every CI run.
+
+---
+
+## Contents
+
+- [Getting a key](#getting-a-key)
+- [Bundler plugins](#bundler-plugins)
+- [Plugin options](#plugin-options)
+- [The CLI](#the-cli)
+- [Environment variables](#environment-variables)
+- [Stack traces still minified?](#stack-traces-still-minified)
+- [How it works](#how-it-works)
+- [Compatibility](#compatibility)
+
+---
+
+## Getting a key
+
+Source-map upload needs a key with the **`cli` scope**. A write key is not enough — create one in
+your project settings. Secret keys start `vnk_sk_`; publishable ones start `vnk_pk_` and are the
+kind that belongs in a browser bundle.
+
+```bash
+export VINKTAR_CLI_KEY=vnk_sk_…
+npx @vinktarhq/cli doctor
+```
+
+```
+host  https://in.vinktar.com
+key   vnk_sk_Unyv…OP1m
+
+reachable          yes
+key accepted       yes
+upload scope       yes
+
+Ready to upload.
+```
+
+`VINKTAR_CLI_KEY` is read before `VINKTAR_KEY`. They are separate on purpose: a CI job usually
+already exports `VINKTAR_KEY` for the browser bundle, and that one is the *public* write key,
+which this endpoint refuses.
+
+**Never put a `cli` key in a bundle.** It is a build credential, not a runtime one.
+
+---
+
+## Bundler plugins
+
+Every plugin does the same two things — stamp each chunk as it is generated, upload the maps after
+the build — and takes the same [options](#plugin-options).
+
+### Vite
+
+```ts
+// vite.config.ts
+import { vinktar } from '@vinktarhq/cli/vite';
+
+export default defineConfig({
+  plugins: [vinktar()],
+});
+```
+
+Vite gets a little extra. The plugin also exposes `import.meta.env.VINKTAR_KEY`, `VINKTAR_HOST`,
+`VINKTAR_ENVIRONMENT` and `VINKTAR_RELEASE` to your bundle, so
+
+```ts
+init({ key: import.meta.env.VINKTAR_KEY, release: import.meta.env.VINKTAR_RELEASE });
+```
+
+is the whole application-side setup, and the release the SDK reports is guaranteed to be the one
+the maps were uploaded under. `VINKTAR_CLI_KEY` is never exposed — a bundle is public.
+
+It also turns on `build.sourcemap: 'hidden'` for you, which is what you want: the maps are
+generated for the upload and no `sourceMappingURL` comment points at them.
+
+Works on Vite 5 and newer; CI builds real fixtures against 7.3 and 8.2, the latter being the
+Rolldown/Oxc pipeline, where the minifier runs after the plugin and strips comments.
+
+### Rollup
+
+```js
+// rollup.config.mjs
+import { vinktarRollup } from '@vinktarhq/cli/rollup';
+
+export default { plugins: [vinktarRollup({ urlPrefix: '/assets/' })] };
+```
+
+### webpack and rspack
+
+```js
+// webpack.config.js — CommonJS, which is what webpack configs usually are
+const { vinktarWebpack } = require('@vinktarhq/cli/webpack');
+
+module.exports = {
+  devtool: 'hidden-source-map',
+  plugins: [new vinktarWebpack({ urlPrefix: '/static/' })],
+};
+```
+
+```js
+// rspack.config.js
+const { vinktarRspack } = require('@vinktarhq/cli/rspack');
+
+module.exports = { plugins: [new vinktarRspack()] };
+```
+
+`import` works too. Every entry point except `@vinktarhq/cli/vite` ships both ESM and CommonJS —
+see [Compatibility](#compatibility).
+
+### esbuild
+
+```js
+import { vinktarEsbuild } from '@vinktarhq/cli/esbuild';
+
+await esbuild.build({
+  plugins: [vinktarEsbuild()],
+  sourcemap: true,
+  metafile: true, // required — it is how the plugin finds the output
+});
+```
+
+**One honest caveat.** esbuild has no hook between generating a chunk and writing it, so this
+plugin edits the files afterwards. If your build puts `[hash]` in `entryNames` or `chunkNames`,
+that hash is computed before the debug id exists and will not match the file on disk — the plugin
+warns once when it sees this. Nothing in esbuild's API avoids it today. Vite, Rollup, webpack and
+rspack all have a hook that runs before hashing, so they have neither problem.
+
+---
+
+## Plugin options
+
+```ts
+vinktar({
+  urlPrefix: '/assets/',
+  deleteSourcemapsAfterUpload: true,
+  errorHandler: (error) => { throw error; },
+});
+```
+
+| Option | Default | |
+|---|---|---|
+| `urlPrefix` | Vite's `base`, else `~/` | What the files are served under, for release+url matching |
+| `release` | CI commit, then the full git SHA | Must match what your SDK reports |
+| `dist` | — | Build discriminator, when several builds share one release |
+| `key` | `$VINKTAR_CLI_KEY` | The `cli`-scoped key |
+| `host` | `$VINKTAR_HOST`, else `https://in.vinktar.com` | Ingest host |
+| `uploadSourcemaps` | `true` | `false` turns the whole feature off, deletion included |
+| `deleteSourcemapsAfterUpload` | `true` | Remove the maps from the build output afterwards |
+| `injectDebugIds` | `true` | `false` uploads without modifying any chunk, for strict CSP/SRI builds |
+| `disable` | `false` | Return a no-op plugin before any env, git or network work |
+| `errorHandler` | — | Called instead of failing. Throw from it to fail the build |
+| `silent` | `false` | Suppress the plugin's own output. Warnings are never silenced |
+
+### Two defaults worth knowing about
+
+**Maps are deleted from your build output.** A source map is your original source; the bundler only
+emitted one because this plugin asked it to, so leaving it in a public directory publishes your
+whole codebase to anyone who guesses `app.js.map`. Set `deleteSourcemapsAfterUpload: false` if you
+mean to serve them.
+
+**A missing key warns, it does not fail.** A contributor running `npm run build` with no key gets a
+loud warning naming the consequence — and the maps are still deleted, because "the CI secret was
+never wired up" must not become "we shipped our source". If the upload is *attempted* and fails
+while deletion is on, that **does** fail the build: there is no second chance once the maps are
+gone. Pass an `errorHandler` to opt back into warn-only.
+
+---
+
+## The CLI
+
+For pipelines that build on one machine and upload from another, or where you would rather not add
+a plugin.
+
+```bash
+npx @vinktarhq/cli sourcemaps upload ./dist --release "$GIT_SHA"
+```
+
+| Command | |
+|---|---|
+| `sourcemaps upload <dir>` | Stamp every chunk, then send the maps. Run after your bundler |
+| `sourcemaps inject <dir>` | Only the stamping, for a machine that will not do the upload |
+| `sourcemaps resolve <map> --line <n> --column <n>` | Decode one position locally and print the original line |
+| `doctor [--dir <dir>]` | Check the key, its scope, the host — and with `--dir`, the build |
+
+<details>
+<summary><strong>All flags</strong></summary>
+
+Precedence is flag → environment → `.env` file → default. Every value is trimmed, and one that is
+blank after trimming is refused *by name* rather than treated as unset: `--release "$TAG"` with an
+unset `TAG` is a release named nothing, not no release.
+
+| Flag | |
+|---|---|
+| `--key` | A `cli`-scoped key. Defaults to `$VINKTAR_CLI_KEY`, then `$VINKTAR_KEY` |
+| `--release` | Defaults to the CI commit, then the full git SHA |
+| `--dist` | Build discriminator |
+| `--host` | Ingest host |
+| `--url-prefix` | `/assets/`, `https://cdn.example.com/`, or `~/` (default) |
+| `--ignore <glob>` | Skip matching chunks entirely. Repeatable |
+| `--ext <list>` | Extensions to treat as chunks. Default `js,cjs,mjs` |
+| `--no-inject` | Upload without stamping. Those chunks match by release + url only |
+| `--no-rewrite-sources` | Send `sources` exactly as the bundler wrote them |
+| `--dry-run` | Print what would be uploaded. Sends nothing, needs no key |
+| `--strict` | Treat any warning as a failure (exit 2) |
+| `--allow-failure` | Never exit non-zero because the upload failed |
+| `--concurrency` `--timeout` `--retries` | Request shaping |
+| `--header 'Name: value'` | For a gateway in front of ingest. Repeatable |
+| `--dotenv-file <path>` | Read `VINKTAR_*` from a file. Ranks below the real environment |
+| `--quiet` `--debug` | How much it says. `--debug` redacts the key |
+
+Exit codes: `0` fine, `1` it did not work, `2` it worked and `--strict` found something anyway.
+
+</details>
+
+### In a deploy
+
+```bash
+npm run build
+npx @vinktarhq/cli sourcemaps upload ./dist --release "$GITHUB_SHA"
+```
+
+`--release` must match what your SDK reports. If they differ the upload succeeds and never matches
+a single frame — which is why the Vite plugin defines the release into your bundle for you.
+
+---
+
+## Environment variables
+
+| | |
+|---|---|
+| `VINKTAR_CLI_KEY` | The `cli`-scoped key. **Build-time only, never in a bundle** |
+| `VINKTAR_RELEASE` | Overrides detection. Must match what the SDK reports |
+| `VINKTAR_HOST` | Ingest host, for self-hosted deployments |
+| `VINKTAR_DIST` | Build discriminator |
+| `VINKTAR_IGNORE` | Comma-separated globs |
+| `VINKTAR_DISABLE` | `1` turns the plugin into a no-op |
+| `VINKTAR_UPLOAD_CONCURRENCY`, `VINKTAR_HTTP_TIMEOUT`, `VINKTAR_HTTP_MAX_RETRIES` | Request shaping |
+| `VINKTAR_QUIET`, `VINKTAR_DEBUG`, `VINKTAR_LOG_LEVEL` | Output |
+| `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` | Honoured over a CONNECT tunnel — Node's own `fetch` ignores these, so without it a corporate network gives you `ECONNREFUSED` from a tool that works everywhere else |
+
+**Using Turborepo?** Add `VINKTAR_*` to the build task's `passThroughEnv`, or the key never reaches
+the build. The plugin warns when it detects this.
+
+---
+
+## Stack traces still minified?
+
+Every failure here looks identical from the outside, which is why these tools exist:
+
+```bash
+npx @vinktarhq/cli doctor --dir ./dist
+```
+
+It separates *wrong key*, *right key wrong scope*, *wrong host*, *the build was never stamped*, and
+*fine, your maps just have not uploaded yet*. With `--dir` it also reports maps missing
+`sourcesContent`, inline maps, empty maps, chunks stamped twice (your output directory was not
+cleaned), and the one genuinely fatal state — a chunk whose debug id differs from its map's, which
+can never resolve.
+
+Then check a specific frame without causing a real error:
+
+```bash
+npx @vinktarhq/cli sourcemaps resolve ./dist/assets/app-DfK29aQx.js.map --line 1 --column 4821
+```
+
+```
+debug id  b2b1f8b1-0f3e-4a51-9a1e-7c0d9b2e1f44
+src/App.tsx:42:11  (handleSubmit)
+
+     40 |   const handleSubmit = async () => {
+     41 |     const body = serialise(form);
+>    42 |     await post('/api/orders', body);
+     43 |   };
+```
+
+The usual causes, in order:
+
+1. **The release does not match.** The SDK reports one string and the maps went up under another.
+   The Vite plugin removes this class of bug entirely.
+2. **Source maps are off.** The CLI says so loudly — "found N JavaScript files and no source maps".
+3. **No `cli` scope.** The error is `cli_scope_required`, which reads like a bad key and isn't.
+4. **The upload never ran.** No key in CI is the common one; the warning names it.
+
+---
+
+## How it works
+
+**Debug IDs.** Each chunk gets an id derived from its own bytes, written into both the chunk and
+its map. A tiny snippet at the top of the chunk registers that id at runtime under the chunk's own
+stack signature, so when an error is captured the SDK can report exactly which artifact each frame
+came from. That survives a CDN rewriting paths, a bundle served from two origins, or a release
+string being wrong — none of which release-plus-URL matching survives.
+
+The id is derived from the chunk's content, so rebuilding unchanged source produces the same id and
+re-uploading is free.
+
+**Nothing is uploaded twice.** Before sending anything the CLI asks ingest which content hashes it
+already holds. A redeploy of an unchanged build sends nothing at all.
+
+**Limits come from the server**, not from a number compiled in here, so batch size, per-file caps
+and compression follow what your deployment actually accepts. Parts are gzipped when the server
+says it accepts them.
+
+**Uploaded `sources` are tidied** — `webpack:///` prefixes stripped, absolute build-machine paths
+made relative to the build root — in the uploaded copy only. The file on disk is never touched.
+Disable with `--no-rewrite-sources`.
+
+---
+
+## Compatibility
+
+| | Supported | Built against in CI |
+|---|---|---|
+| Node | 18 and newer | 18, 20, 22, 24 |
+| Vite | >=5 | 7.3 and 8.2 (Rolldown) |
+| Rollup | >=3 | 4.63 |
+| webpack | >=5 | 5.110 |
+| rspack | >=1 | 1.7 |
+| esbuild | >=0.19 | 0.28 |
+
+Every bundler is an **optional** peer dependency — install only the one you use, and npm will tell
+you if its version is outside the range above.
+
+**Module systems.** Everything ships as both ESM and CommonJS, so a `webpack.config.js` using
+`require()` works, and so does an ESM config. The one exception is `@vinktarhq/cli/vite`, which is
+ESM-only: Vite configs are ESM and the plugin loads Vite itself dynamically, which CommonJS cannot
+do. TypeScript types ship for both, under `moduleResolution` `node16`, `nodenext` or `bundler`.
+
+The Vite, webpack and rspack fixture builds need Node 20.19+, so they run on a narrower matrix than
+the package's own floor — a fixture's requirement is not the package's.
+
+---
+
+## Programmatic use
+
+```js
+import { inject, upload, resolvePosition, doctor } from '@vinktarhq/cli';
+
+await inject('./dist', console.log);
+await upload('./dist', { host, key, release, urlPrefix: '~/', dryRun: false }, console.log);
+
+const { position } = await resolvePosition('./dist/app.js.map', 1, 4821);
+```
+
+---
+
+## Licence
+
+MIT. © Vinktar.

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * The executable. Kept separate from `cli.ts` so the command logic stays importable and testable
+ * without a side effect firing on import.
+ */
+import { run } from './cli.js';
+/**
+ * A closed pipe is not an error.
+ *
+ * `vinktar sourcemaps upload ./dist | head` closes stdout while this is still writing, and the
+ * default handler turns that into an unhandled `EPIPE` and a non-zero exit — so a deploy step
+ * that pipes the output into anything at all fails for reading its own logs.
+ */
+for (const stream of [process.stdout, process.stderr]) {
+    stream.on('error', (error) => {
+        if (error.code !== 'EPIPE')
+            throw error;
+    });
+}
+run(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    // Anything that escaped `run`'s own handling. Printed rather than thrown, because an unhandled
+    // rejection prints a stack trace of this file, which is never the interesting part.
+    process.exitCode = 1;
+    console.error(error instanceof Error ? error.message : String(error));
+});
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AAEA;;;GAGG;AACH,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B;;;;;;GAMG;AACH,KAAK,MAAM,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;IACtD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAA4B,EAAE,EAAE;QAClD,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO;YAAE,MAAM,KAAK,CAAC;IAC1C,CAAC,CAAC,CAAC;AACL,CAAC;AAED,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAC7B,CAAC,IAAI,EAAE,EAAE;IACP,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;IACjB,+FAA+F;IAC/F,oFAAoF;IACpF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACrB,OAAO,CAAC,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AACxE,CAAC,CACF,CAAC","sourcesContent":["#!/usr/bin/env node\n\n/**\n * The executable. Kept separate from `cli.ts` so the command logic stays importable and testable\n * without a side effect firing on import.\n */\nimport { run } from './cli.js';\n\n/**\n * A closed pipe is not an error.\n *\n * `vinktar sourcemaps upload ./dist | head` closes stdout while this is still writing, and the\n * default handler turns that into an unhandled `EPIPE` and a non-zero exit — so a deploy step\n * that pipes the output into anything at all fails for reading its own logs.\n */\nfor (const stream of [process.stdout, process.stderr]) {\n  stream.on('error', (error: NodeJS.ErrnoException) => {\n    if (error.code !== 'EPIPE') throw error;\n  });\n}\n\nrun(process.argv.slice(2)).then(\n  (code) => {\n    process.exitCode = code;\n  },\n  (error: unknown) => {\n    // Anything that escaped `run`'s own handling. Printed rather than thrown, because an unhandled\n    // rejection prints a stack trace of this file, which is never the interesting part.\n    process.exitCode = 1;\n    console.error(error instanceof Error ? error.message : String(error));\n  },\n);\n"]}

package/dist/bundler/core.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Everything the bundler plugins share, with no bundler in it.
+ *
+ * There are two operations and five bundlers. The operations are the part worth getting right —
+ * where the debug id comes from, when it is safe to inject, what the upload skips — and having
+ * them once means a fix lands in all five rather than in whichever one someone remembered.
+ *
+ * Written by hand rather than on `unplugin`, which is the obvious tool for this: this package
+ * ships zero runtime dependencies, and the per-bundler surface here is one hook each.
+ */
+export interface BundlerOptions {
+    /**
+     * Turn the whole plugin into a no-op, before any environment, git or network work happens.
+     *
+     * For a config that is reused by something other than a build — vitest, Storybook, a preview
+     * server — where stamping chunks and shelling out to git is pure cost. Also settable with
+     * `VINKTAR_DISABLE=1`, which is what a CI matrix can use without editing the config.
+     */
+    disable?: boolean;
+    /**
+     * Stamp debug ids into the chunks. Default true.
+     *
+     * Turn it off for a build under a strict CSP or with subresource integrity computed elsewhere,
+     * where nothing may modify a chunk after it is hashed by another tool. The maps are still
+     * uploaded; frames then match by release + url alone, which is weaker but not nothing.
+     */
+    injectDebugIds?: boolean;
+    /** What the built files are served under, for release+url matching. */
+    urlPrefix?: string;
+    /**
+     * Upload after the build. Default **true**, with a warning when no key is available.
+     *
+     * Not "true when a key is set": that made a CI job with an unwired secret indistinguishable
+     * from one that was never meant to upload, and both said nothing. Setting this to `false` turns
+     * the whole feature off, deletion included.
+     */
+    uploadSourcemaps?: boolean;
+    /**
+     * Remove the maps from the build output afterwards. Default **true**.
+     *
+     * A source map is the application's original source. The bundler only emitted one because this
+     * plugin asked it to, so leaving it in the output directory publishes the whole codebase to
+     * anyone who guesses `app.js.map` — which is how it shipped before, and what `sourcemap:
+     * 'hidden'` exists to prevent. Set `false` when the maps are meant to be served.
+     */
+    deleteSourcemapsAfterUpload?: boolean;
+    /** Build discriminator, when several builds share one release. */
+    dist?: string;
+    /** The release these maps belong to. Defaults to the CI commit, then the git SHA. */
+    release?: string;
+    /** Ingest host. Defaults to `$VINKTAR_HOST`, then the public one. */
+    host?: string;
+    /** The `cli`-scoped key. Defaults to `$VINKTAR_CLI_KEY`. */
+    key?: string;
+    /**
+     * What to do when the upload fails. Providing one makes every failure non-fatal: it is called,
+     * and the build carries on. Without one, a failed upload fails the build only when the maps are
+     * being deleted — see {@link Session.upload}.
+     */
+    errorHandler?: (error: Error) => void;
+    /** Suppress the plugin's own output. Warnings about lost symbolication are still printed. */
+    silent?: boolean;
+}
+export interface Stamped {
+    readonly code: string;
+    readonly debugId: string;
+    /**
+     * The generated line the snippet was inserted at, or `null` when it was appended. The chunk's
+     * map must gain one empty group at this index; every plugin does that for its own map.
+     */
+    readonly line: number | null;
+    /** False when the chunk already carried everything, so the caller can skip writing it back. */
+    readonly changed: boolean;
+}
+/**
+ * Stamp one chunk, and say what its map now needs.
+ *
+ * Must run AFTER minification and BEFORE the bundler hashes the output. Minifiers strip comments,
+ * so an id injected earlier loses its `//# debugId=` line; the embedded marker survives that, but
+ * the hash has to cover the snippet or the filename describes bytes that are not on disk.
+ *
+ * An id the chunk already carries is kept rather than replaced — Rollup's `output.sourcemapDebugIds`
+ * and webpack's `debugIds` stamp one themselves, and minting a competing id here would file the map
+ * under something no stack frame reports.
+ */
+export declare function stamp(code: string, options?: {
+    prepend?: boolean;
+}): Stamped;
+/**
+ * Whether the plugin should do nothing at all.
+ *
+ * Checked before the release is detected, because detecting it shells out to git — and a config
+ * shared with vitest would then run `git rev-parse` on every test file.
+ */
+export declare function disabled(options: BundlerOptions, env?: Record<string, string | undefined>): boolean;
+/**
+ * Things about the environment that will make this not work, said once.
+ *
+ * Both of these produce the same symptom — the upload silently does nothing — and both are
+ * invisible from inside the build. Turborepo in particular filters the environment down to what a
+ * task declares, so `VINKTAR_CLI_KEY` is simply absent and the plugin reports a missing key that
+ * the user can see perfectly well in their own shell.
+ */
+export declare function environmentWarnings(outDir: string, env?: Record<string, string | undefined>): string[];
+/** True when this file is one we stamp: JavaScript, not a map, not CSS. */
+export declare function isScript(name: string): boolean;
+/**
+ * The upload-then-delete half of a build, as one object per plugin instance.
+ *
+ * Split in two because Rollup and Vite are: `writeBundle` fires once per output and is the only
+ * hook that knows where the files went, while deletion has to wait until every output is on the
+ * server. A build with a client bundle and an SSR bundle would otherwise delete the first one's
+ * maps while the second was still being written.
+ */
+export interface Session {
+    /** Upload everything under `outDir`. Safe to call repeatedly; the server dedupes by content. */
+    upload(outDir: string): Promise<void>;
+    /** Remove the maps from every directory uploaded so far, if that is configured. */
+    cleanup(): Promise<void>;
+}
+export declare function session(options: BundlerOptions, env?: Record<string, string | undefined>): Session;
+/**
+ * Upload and clean up in one call, for the bundlers with a single end-of-build hook.
+ */
+export declare function finish(outDir: string, options: BundlerOptions, env?: Record<string, string | undefined>): Promise<void>;
+/** Re-export so plugins can write an id and a line shift into a map without a second import. */
+export { injectIntoMap, mapDebugId } from '../debug-id.js';
+/**
+ * The release: the commit being built.
+ *
+ * CI first. A shallow checkout — which is what every default CI clone is — often has no usable git
+ * metadata, and falling straight to git produced an EMPTY release: every frame then lost its
+ * release+url match, leaving the debug id as the only thing holding symbolication together.
+ *
+ * The FULL sha, never a short one. A short sha is a prefix whose length varies by tool (7 from
+ * `git rev-parse --short`, 8 from GitLab, 12 from some deploy scripts), and the SDK reporting one
+ * length while the CLI uploaded another is a release mismatch that looks exactly like no release
+ * at all. Both sides read the same variables, so both get the same 40 characters.
+ */
+export declare function detectRelease(env?: Record<string, string | undefined>): string;