@siteqwality/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SiteQwality
+
+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,67 @@
+# @siteqwality/cli
+
+Candidate version 0.1.0, Node.js 22+. Not published by this change. Use local tarballs until npm publication is authorized. After publication:
+
+```sh
+npm install --save-dev @siteqwality/cli
+```
+
+## Commands
+
+Inject before uploading, then deploy the exact injected JavaScript:
+
+```sh
+npx siteqwality sourcemaps inject ./dist
+export SITEQWALITY_APP_ID='your-application-uuid'
+export SITEQWALITY_API_KEY='your-api-key'
+export SITEQWALITY_RELEASE='web-2026.10.04'
+npx siteqwality sourcemaps upload ./dist --delete-after
+npx siteqwality releases new "$SITEQWALITY_RELEASE" --commit abc123 --env production
+# Run after the application's deployment succeeds:
+npx siteqwality releases deploy "$SITEQWALITY_RELEASE" --env production
+npx siteqwality releases list
+```
+
+Store the key in your CI secret store. Mutations require `write:rum`; release listing requires `read:rum`. The API enforces application ownership. `SITEQWALITY_API_URL` changes the API base, which defaults to `https://api.siteqwality.com`. HTTPS is required except for loopback test servers. The key is read from `SITEQWALITY_API_KEY` and is sent only to the configured API, never to storage PUT URLs. Redirects are not followed.
+
+Authenticated commands accept `--app <uuid>`, `--api-url <url>`, `--retries <count>` (default 2, range 0 to 5), and `--timeout <ms>` (default 30000, maximum 300000). Upload also accepts `--release <version>`, `--commit <sha>`, `--env <environment>`, `--concurrency <count>` (default 4, range 1 to 16), and `--delete-after`. Explicit flags override environment defaults. JSON results go to stdout, errors to stderr with exit code 1. Keys are intentionally not accepted as command-line flags.
+
+Upload creates the release idempotently before presigning. With no release it uses the reserved `__debug_id__` release. `releases deploy <version>` requires an existing release and records server time. It does not deploy application files or configure the browser SDK's release value.
+
+## Injection
+
+The CLI recursively finds `.js`, `.mjs` and `.cjs` files with relative `sourceMappingURL` comments or adjacent hidden `<file>.map` files. Files without maps are skipped; a missing explicitly referenced map fails. It validates all pairs before writing. Symlinks, remote/inline maps, shared maps and paths outside the output directory are rejected.
+
+Injection preserves the shebang, strict and custom directives, original mapped positions and `sourcesContent`. IDs are deterministic UUIDv8 values derived from original JavaScript bytes. The runtime registration uses `globalThis._sqDebugIds` and a captured error stack. Its syntax requires a runtime supporting logical assignment, as used by the SDK contract. A failed registry write is contained so application code still executes.
+
+Unchanged injected pairs can be processed repeatedly. If injected JavaScript changes or a pair's IDs disagree, rebuild from clean output. Map JSON contains the same `debugId` as the JavaScript comment and runtime registration. Indexed maps are unsupported.
+
+## Upload and deletion
+
+Uploads follow the Phase 4 API contract:
+
+1. Create the app-scoped release.
+2. Presign at most 50 maps per batch, with unique filenames and Debug IDs. Declare exact gzip byte sizes and JSON/gzip headers.
+3. PUT those bytes with the returned storage headers and bounded concurrency.
+4. Confirm that batch's returned upload IDs and verify ready status, Debug IDs and byte sizes.
+5. Only after every batch succeeds, optionally remove selected maps. The CLI first checks that all selected JavaScript and map files remain unchanged.
+
+Both raw JSON and gzip output are limited to 32 MiB per map. The client retries network failures, timeouts, HTTP 408/429 and 5xx responses with bounded backoff. It respects `Retry-After` up to 30 seconds and fails for longer requested waits. A storage 403 triggers a fresh presign and re-upload, bounded by `--retries`. Other permanent failures stop the command. An incomplete or mismatched presign/confirmation response fails closed. Failed uploads may leave pending server records; retrying gets new IDs. Earlier confirmed batches may remain ready, but no local map is removed when a later batch fails.
+
+Confirmation proves storage and metadata acceptance. It does not prove live symbolication. Backend deployment and an integrated SDK/API smoke test are separate release gates.
+
+## JavaScript API
+
+```js
+import { inject, injectDirectory, uploadDirectory, ApiClient } from '@siteqwality/cli';
+const { code, map, debugId } = inject(generatedJavaScript, originalSourceMap);
+await injectDirectory('./dist');
+await uploadDirectory('./dist', {
+  app: process.env.SITEQWALITY_APP_ID,
+  apiKey: process.env.SITEQWALITY_API_KEY,
+  release: 'web-v1',
+  deleteAfter: false,
+});
+```
+
+The programmatic API takes explicit credentials. Bundler adapters and CLI commands additionally resolve environment defaults.

package/bin/siteqwality.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import { Command, InvalidArgumentError } from 'commander';
+import { ApiClient, injectDirectory, uploadDirectory } from '../src/index.js';
+
+const program = new Command()
+  .name('siteqwality')
+  .version('0.1.0')
+  .description('SiteQwality Debug ID source maps and releases');
+const integer = (value) => {
+  if (!/^\d+$/.test(value)) throw new InvalidArgumentError('Expected an integer');
+  return Number(value);
+};
+function authenticated(command) {
+  return command
+    .option('--app <uuid>', 'Application UUID', process.env.SITEQWALITY_APP_ID)
+    .option('--api-url <url>', 'SiteQwality API base URL', process.env.SITEQWALITY_API_URL)
+    .option('--retries <count>', 'Transient retries per request, 0 to 5', integer, 2)
+    .option('--timeout <ms>', 'Request timeout, 1 to 300000 milliseconds', integer, 30000);
+}
+function options(command) {
+  return {
+    ...command,
+    apiKey: process.env.SITEQWALITY_API_KEY,
+    apiBase: command.apiUrl,
+    timeoutMs: command.timeout,
+  };
+}
+const print = (result) => process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+const maps = program
+  .command('sourcemaps')
+  .description('Inject Debug IDs and upload matching external source maps');
+maps
+  .command('inject <directory>')
+  .description('Inject deterministic IDs into JavaScript and matching maps')
+  .action(async (directory) => print(await injectDirectory(directory)));
+authenticated(
+  maps
+    .command('upload <directory>')
+    .description('Gzip, presign, PUT and confirm previously injected maps'),
+)
+  .option(
+    '--release <version>',
+    'Product release; defaults to __debug_id__',
+    process.env.SITEQWALITY_RELEASE,
+  )
+  .option('--commit <sha>', 'Release commit SHA')
+  .option('--env <environment>', 'Release environment')
+  .option('--concurrency <count>', 'Parallel PUT requests, 1 to 16', integer, 4)
+  .option('--delete-after', 'Delete maps only after every upload is confirmed', false)
+  .action(async (directory, opts) => print(await uploadDirectory(directory, options(opts))));
+const releases = program.command('releases').description('Manage app-scoped releases');
+authenticated(releases.command('new <version>').description('Create or update a release'))
+  .option('--commit <sha>', 'Commit SHA')
+  .option('--env <environment>', 'Release environment')
+  .action(async (version, opts) =>
+    print(await new ApiClient(options(opts)).createRelease(version, opts)),
+  );
+authenticated(
+  releases
+    .command('deploy <version>')
+    .description('Record server deployment time for an existing release'),
+)
+  .option('--env <environment>', 'Release environment')
+  .action(async (version, opts) =>
+    print(await new ApiClient(options(opts)).deployRelease(version, opts.env)),
+  );
+authenticated(releases.command('list').description('List releases, newest created first')).action(
+  async (opts) => print(await new ApiClient(options(opts)).listReleases()),
+);
+try {
+  await program.parseAsync();
+} catch (error) {
+  process.stderr.write(`siteqwality: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@siteqwality/cli",
+  "version": "0.1.0",
+  "description": "SiteQwality release and Debug ID source-map tooling",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "bin": {
+    "siteqwality": "./bin/siteqwality.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/siteqwality/sdk-cli.git",
+    "directory": "packages/cli"
+  },
+  "dependencies": {
+    "@ampproject/remapping": "^2.3.0",
+    "acorn": "^8.15.0",
+    "commander": "^14.0.0",
+    "magic-string": "^0.30.19"
+  }
+}

package/src/api.js

@@ -0,0 +1,141 @@
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const isUuid = (value) =>
+  typeof value === 'string' && UUID.test(value) && !/^0{8}-0{4}-0{4}-0{4}-0{12}$/.test(value);
+export function safeUrl(value) {
+  const url = new URL(value);
+  const local = ['127.0.0.1', '[::1]', 'localhost'].includes(url.hostname);
+  if (
+    (url.protocol !== 'https:' && !(url.protocol === 'http:' && local)) ||
+    url.username ||
+    url.password ||
+    url.hash
+  )
+    throw new Error('Use HTTPS (or loopback HTTP for local tests) without URL credentials');
+  return url;
+}
+export function releaseName(version) {
+  if (
+    typeof version !== 'string' ||
+    !version.trim() ||
+    [...version].length > 255 ||
+    ['.', '..'].includes(version) ||
+    /[\x00-\x1f\x7f]/.test(version)
+  )
+    throw new Error('Invalid release version');
+  return encodeURIComponent(version);
+}
+export class HttpError extends Error {
+  constructor(status, retryAfter) {
+    super(`Request failed with HTTP ${status}`);
+    this.status = status;
+    this.retryAfter = retryAfter;
+  }
+}
+export class ApiClient {
+  constructor(options = {}) {
+    const base = safeUrl(options.apiBase || 'https://api.siteqwality.com');
+    if (base.search) throw new Error('API base must not contain query parameters');
+    if (!isUuid(options.app)) throw new Error('A valid application UUID is required');
+    if (
+      typeof options.apiKey !== 'string' ||
+      !options.apiKey.trim() ||
+      /[\r\n]/.test(options.apiKey)
+    )
+      throw new Error('An API key is required');
+    this.base = base.href.replace(/\/+$/, '');
+    this.app = options.app;
+    this.key = options.apiKey;
+    this.retries = options.retries ?? 2;
+    this.retryDelayMs = options.retryDelayMs ?? 500;
+    this.timeoutMs = options.timeoutMs ?? 30_000;
+    if (!Number.isInteger(this.retries) || this.retries < 0 || this.retries > 5)
+      throw new Error('retries must be 0 to 5');
+    if (!Number.isFinite(this.retryDelayMs) || this.retryDelayMs < 0 || this.retryDelayMs > 30_000)
+      throw new Error('Invalid retry delay');
+    if (!Number.isInteger(this.timeoutMs) || this.timeoutMs < 1 || this.timeoutMs > 300_000)
+      throw new Error('Invalid request timeout');
+  }
+  async request(url, init, json = false) {
+    for (let attempt = 0; ; attempt++) {
+      try {
+        const response = await fetch(url, {
+          ...init,
+          redirect: 'manual',
+          credentials: 'omit',
+          signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!response.ok) {
+          const after = response.headers.get('retry-after');
+          await response.body?.cancel();
+          throw new HttpError(response.status, after);
+        }
+        if (!json) {
+          await response.body?.cancel();
+          return;
+        }
+        const body = await response.json();
+        if (!body || !Object.hasOwn(body, 'data')) throw new Error('Invalid API response envelope');
+        return body.data;
+      } catch (err) {
+        const transient =
+          err instanceof HttpError
+            ? [408, 429].includes(err.status) || err.status >= 500
+            : err instanceof TypeError || err.name === 'TimeoutError';
+        if (!transient || attempt >= this.retries) {
+          if (err instanceof HttpError) throw err;
+          throw new Error('Request failed or returned an invalid response');
+        }
+        let wait = this.retryDelayMs * 2 ** attempt;
+        if (err.retryAfter) {
+          const parsed = /^\d+$/.test(err.retryAfter)
+            ? Number(err.retryAfter) * 1000
+            : Date.parse(err.retryAfter) - Date.now();
+          if (Number.isFinite(parsed)) wait = Math.max(wait, parsed);
+        }
+        if (wait > 30_000)
+          throw new Error('Server requested a long retry delay; retry this command later');
+        await new Promise((resolve) => setTimeout(resolve, wait));
+      }
+    }
+  }
+  api(suffix, method = 'GET', body) {
+    return this.request(
+      `${this.base}/rum/${this.app}${suffix}`,
+      {
+        method,
+        headers: { Authorization: `Bearer ${this.key}`, 'Content-Type': 'application/json' },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      },
+      true,
+    );
+  }
+  async createRelease(version, { commit, env } = {}) {
+    releaseName(version);
+    for (const value of [commit, env])
+      if (value !== undefined && (typeof value !== 'string' || [...value].length > 64))
+        throw new Error('Release metadata is limited to 64 characters');
+    return this.api('/releases', 'POST', {
+      version,
+      ...(commit === undefined ? {} : { commit_sha: commit }),
+      ...(env === undefined ? {} : { env }),
+    });
+  }
+  async deployRelease(version, env) {
+    const name = releaseName(version);
+    if (env !== undefined && (typeof env !== 'string' || [...env].length > 64))
+      throw new Error('Release environment is limited to 64 characters');
+    return this.api(`/releases/${name}/deploy`, 'POST', env === undefined ? {} : { env });
+  }
+  listReleases() {
+    return this.api('/releases');
+  }
+  presign(version, files) {
+    return this.api(`/releases/${releaseName(version)}/sourcemaps`, 'POST', { files });
+  }
+  confirm(ids) {
+    return this.api('/sourcemaps/confirm', 'POST', { ids });
+  }
+  put(url, headers, body) {
+    return this.request(safeUrl(url).href, { method: 'PUT', headers, body });
+  }
+}

package/src/comments.js

@@ -0,0 +1,17 @@
+import { tokenizer } from 'acorn';
+/** Read real comments, excluding lookalikes in strings and template literals. */
+export function sourceMapReference(code) {
+  let reference;
+  const tokens = tokenizer(code, {
+    ecmaVersion: 'latest',
+    allowHashBang: true,
+    onComment(_block, text) {
+      const match = text.match(/^\s*[@#]\s*sourceMappingURL=(\S+)\s*$/);
+      if (match) reference = match[1];
+    },
+  });
+  while (tokens.getToken().type.label !== 'eof') {
+    /* Consume comments across the whole file. */
+  }
+  return reference;
+}

package/src/files.js

@@ -0,0 +1,85 @@
+import { readdir, readFile, realpath, lstat, writeFile, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { inject } from './inject.js';
+import { sourceMapReference } from './comments.js';
+
+export function inside(root, file) {
+  const relative = path.relative(root, file);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+    throw new Error('File is outside output directory');
+  return relative;
+}
+
+export async function collectPairs(directory) {
+  const root = await realpath(directory);
+  const files = [];
+  async function walk(dir) {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isSymbolicLink()) throw new Error('Output directory contains a symlink');
+      if (entry.isDirectory()) await walk(full);
+      else if (entry.isFile() && /\.(?:c|m)?js$/.test(entry.name)) files.push(full);
+    }
+  }
+  await walk(root);
+  const pairs = [];
+  const seen = new Set();
+  for (const jsPath of files.sort()) {
+    const code = await readFile(jsPath, 'utf8');
+    const reference = sourceMapReference(code);
+    if (reference && /^[a-z][a-z\d+.-]*:|^\/|[?#\\]/i.test(reference))
+      throw new Error('Unsupported external or inline source map');
+    const mapPath = reference
+      ? path.resolve(path.dirname(jsPath), decodeURIComponent(reference))
+      : `${jsPath}.map`;
+    inside(root, mapPath);
+    let stat;
+    try {
+      stat = await lstat(mapPath);
+    } catch (err) {
+      if (!reference && err.code === 'ENOENT') continue;
+      throw err;
+    }
+    if (stat.isSymbolicLink()) throw new Error('Source map is a symlink');
+    if (!stat.isFile()) throw new Error('Expected a source map file');
+    inside(root, await realpath(mapPath));
+    if (seen.has(mapPath))
+      throw new Error('Multiple JavaScript files reference the same source map');
+    seen.add(mapPath);
+    const rawMap = await readFile(mapPath, 'utf8');
+    pairs.push({
+      jsPath,
+      mapPath,
+      filename: inside(root, mapPath).split(path.sep).join('/'),
+      code,
+      rawMap,
+    });
+  }
+  if (!pairs.length) throw new Error('No JavaScript files with external source maps found');
+  return pairs;
+}
+
+async function atomicWrite(file, text) {
+  const tmp = `${file}.sq-${randomUUID()}.tmp`;
+  const { mode } = await lstat(file);
+  try {
+    await writeFile(tmp, text, { flag: 'wx', mode });
+    await rename(tmp, file);
+  } finally {
+    await rm(tmp, { force: true });
+  }
+}
+
+export async function injectDirectory(directory) {
+  const pairs = await collectPairs(directory);
+  // Validate and transform every pair before changing any file.
+  const outputs = pairs.map((pair) => ({ ...pair, ...inject(pair.code, pair.rawMap) }));
+  for (const output of outputs) {
+    const mapText = JSON.stringify(output.map);
+    if (output.code !== pairs.find((p) => p.jsPath === output.jsPath).code)
+      await atomicWrite(output.jsPath, output.code);
+    if (mapText !== output.rawMap) await atomicWrite(output.mapPath, mapText);
+  }
+  return outputs.map(({ filename, debugId }) => ({ filename, debugId }));
+}

package/src/index.d.ts

@@ -0,0 +1,96 @@
+export interface SourceMap {
+  version: 3;
+  file?: string;
+  sourceRoot?: string;
+  sources: string[];
+  names: string[];
+  mappings: string;
+  sourcesContent?: (string | null)[];
+  debugId?: string;
+  [key: string]: unknown;
+}
+export interface ApiOptions {
+  app: string;
+  apiKey: string;
+  apiBase?: string;
+  retries?: number;
+  retryDelayMs?: number;
+  timeoutMs?: number;
+}
+export interface ReleaseMetadata {
+  commit?: string;
+  env?: string;
+}
+export interface UploadOptions extends ApiOptions, ReleaseMetadata {
+  release?: string;
+  concurrency?: number;
+  deleteAfter?: boolean;
+}
+export interface Release {
+  id: string;
+  application_id: string;
+  version: string;
+  created_at: string;
+  source_map_count: number;
+  commit_sha: string | null;
+  env: string | null;
+  deployed_at: string | null;
+  first_seen_at: string | null;
+  last_seen_at: string | null;
+}
+export interface UploadFile {
+  filename: string;
+  debug_id: string;
+  size_bytes: number;
+  content_type: 'application/json';
+  content_encoding: 'gzip';
+}
+export interface PresignedFile extends UploadFile {
+  id: string;
+  upload_url: string;
+  s3_key: string;
+  expires_in_seconds: number;
+  headers: Record<string, string>;
+}
+export interface ConfirmedFile {
+  id: string;
+  status: 'ready';
+  debug_id: string;
+  size_bytes: number;
+}
+export interface UploadResult {
+  uploaded: number;
+  debugIds: string[];
+}
+export interface FilePair {
+  jsPath: string;
+  mapPath: string;
+  filename: string;
+  code: string;
+  rawMap: string;
+}
+export function validateMap(map: unknown): asserts map is SourceMap;
+export function inject(
+  code: string,
+  inputMap: SourceMap | string,
+): { code: string; map: SourceMap; debugId: string };
+export function collectPairs(directory: string): Promise<FilePair[]>;
+export function injectDirectory(
+  directory: string,
+): Promise<{ filename: string; debugId: string }[]>;
+export function uploadMaps(
+  maps: { filename: string; map: SourceMap }[],
+  options: UploadOptions,
+): Promise<UploadResult>;
+export function uploadDirectory(directory: string, options: UploadOptions): Promise<UploadResult>;
+export class ApiClient {
+  constructor(options: ApiOptions);
+  createRelease(version: string, metadata?: ReleaseMetadata): Promise<Release>;
+  deployRelease(version: string, env?: string): Promise<Release>;
+  listReleases(): Promise<Release[]>;
+  presign(version: string, files: UploadFile[]): Promise<{ files: PresignedFile[] }>;
+  confirm(ids: string[]): Promise<{ files: ConfirmedFile[] }>;
+  put(url: string, headers: Record<string, string>, body: Uint8Array): Promise<void>;
+}
+
+export function sourceMapReference(code: string): string | undefined;

package/src/index.js

@@ -0,0 +1,6 @@
+export { inject, validateMap } from './inject.js';
+export { injectDirectory, collectPairs } from './files.js';
+export { ApiClient } from './api.js';
+export { uploadMaps, uploadDirectory } from './upload.js';
+
+export { sourceMapReference } from './comments.js';

package/src/inject.js

@@ -0,0 +1,93 @@
+import { createHash } from 'node:crypto';
+import { parse } from 'acorn';
+import MagicString from 'magic-string';
+import remapping from '@ampproject/remapping';
+
+function debugId(code) {
+  const bytes = createHash('sha256')
+    .update('siteqwality-debug-id-v1\0')
+    .update(code)
+    .digest()
+    .subarray(0, 16);
+  bytes[6] = (bytes[6] & 15) | 128;
+  bytes[8] = (bytes[8] & 63) | 128;
+  const hex = bytes.toString('hex');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+function registrationFor(id) {
+  return `\n/* sq-debug-id:${id} */\n;try{(globalThis._sqDebugIds ||= {})[new Error().stack]="${id}"}catch{}\n/* sq-debug-id:end */\n`;
+}
+
+export function validateMap(map) {
+  if (
+    !map ||
+    map.version !== 3 ||
+    map.sections ||
+    !Array.isArray(map.sources) ||
+    !Array.isArray(map.names) ||
+    typeof map.mappings !== 'string'
+  ) {
+    throw new Error('Expected a flat version 3 source map');
+  }
+}
+
+/** Insert after directives, composing an edit map with the original map. */
+export function inject(code, inputMap) {
+  const map = typeof inputMap === 'string' ? JSON.parse(inputMap) : inputMap;
+  validateMap(map);
+  const existing = code.match(
+    /\n\/\* sq-debug-id:([0-9a-f-]{36}) \*\/\n;try\{[^\n]+\}catch\{\}\n\/\* sq-debug-id:end \*\/\n/,
+  );
+  if (existing) {
+    const id = existing[1];
+    if (existing[0] !== registrationFor(id))
+      throw new Error('Injected registration changed; rebuild before injecting');
+    const suffix = `\n//# debugId=${id}\n`;
+    if (!code.endsWith(suffix) || map.debugId !== id) throw new Error('Debug ID pair mismatch');
+    const original =
+      code.slice(0, existing.index) +
+      code.slice(existing.index + existing[0].length, -suffix.length);
+    if (debugId(original) !== id)
+      throw new Error('Injected JavaScript changed; rebuild before injecting');
+    return { code, map, debugId: id };
+  }
+  if (map.debugId || /sq-debug-id:|\/\/[@#]\s*debugId=/.test(code))
+    throw new Error('Unrecognized Debug ID; start from a clean build');
+  const parserOptions = {
+    ecmaVersion: 'latest',
+    allowHashBang: true,
+    allowReturnOutsideFunction: true,
+  };
+  let ast;
+  try {
+    ast = parse(code, { ...parserOptions, sourceType: 'script' });
+  } catch {
+    ast = parse(code, { ...parserOptions, sourceType: 'module' });
+  }
+  let offset = code.startsWith('#!')
+    ? code.indexOf('\n') === -1
+      ? code.length
+      : code.indexOf('\n') + 1
+    : 0;
+  for (const statement of ast.body) {
+    if (statement.type !== 'ExpressionStatement' || typeof statement.directive !== 'string') break;
+    offset = statement.end;
+  }
+  const id = debugId(code);
+  const registration = registrationFor(id);
+  const edit = new MagicString(code);
+  edit.appendLeft(offset, registration);
+  edit.append(`\n//# debugId=${id}\n`);
+  const composed = remapping(
+    [
+      JSON.parse(edit.generateMap({ hires: true, source: map.file || 'bundle.js' }).toString()),
+      map,
+    ],
+    () => null,
+  );
+  const outputMap = { ...map, ...JSON.parse(composed.toString()), debugId: id };
+  // remapping resolves sourceRoot into sources; retaining it would resolve paths twice.
+  delete outputMap.sourceRoot;
+  return { code: edit.toString(), map: outputMap, debugId: id };
+}

package/src/upload.js

@@ -0,0 +1,165 @@
+import { gzipSync } from 'node:zlib';
+import { readFile, unlink, lstat, realpath } from 'node:fs/promises';
+import { ApiClient, isUuid, safeUrl } from './api.js';
+import { collectPairs } from './files.js';
+import { inject, validateMap } from './inject.js';
+
+function filename(value) {
+  if (
+    typeof value !== 'string' ||
+    !value ||
+    Buffer.byteLength(value) > 1024 ||
+    /[\x00-\x1f\x7f\\]/.test(value) ||
+    value.split('/').some((part) => !part || part === '.' || part === '..')
+  )
+    throw new Error('Invalid source-map filename');
+}
+async function concurrent(items, limit, work) {
+  let next = 0,
+    failure;
+  await Promise.all(
+    Array.from({ length: Math.min(limit, items.length) }, async () => {
+      while (!failure && next < items.length) {
+        const item = items[next++];
+        try {
+          await work(item);
+        } catch (err) {
+          failure ||= err;
+        }
+      }
+    }),
+  );
+  if (failure) throw failure;
+}
+function validatePresign(data, batch) {
+  if (!Array.isArray(data?.files) || data.files.length !== batch.length)
+    throw new Error('Incomplete presign response');
+  const ids = new Set();
+  return batch.map((file) => {
+    const matches = data.files.filter((item) => item.filename === file.filename);
+    const row = matches[0];
+    if (
+      matches.length !== 1 ||
+      !isUuid(row.id) ||
+      ids.has(row.id) ||
+      row.debug_id !== file.debug_id
+    )
+      throw new Error('Presign response mismatch');
+    ids.add(row.id);
+    safeUrl(row.upload_url);
+    if (!row.headers || typeof row.headers !== 'object' || Array.isArray(row.headers))
+      throw new Error('Missing upload headers');
+    const headers = Object.entries(row.headers);
+    const lowered = Object.fromEntries(headers.map(([k, v]) => [k.toLowerCase(), v]));
+    if (
+      headers.some(
+        ([k, v]) =>
+          !['content-type', 'content-encoding'].includes(k.toLowerCase()) || typeof v !== 'string',
+      ) ||
+      headers.length !== 2 ||
+      lowered['content-type'] !== 'application/json' ||
+      lowered['content-encoding'] !== 'gzip'
+    )
+      throw new Error('Unexpected presigned upload header');
+    return { ...row, bytes: file.bytes, size_bytes: file.size_bytes };
+  });
+}
+
+export async function uploadMaps(maps, options) {
+  if (!Array.isArray(maps) || maps.length === 0) throw new Error('No source maps to upload');
+  const concurrency = options.concurrency ?? 4;
+  if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 16)
+    throw new Error('concurrency must be 1 to 16');
+  const names = new Set(),
+    debugIds = new Set();
+  const files = maps.map(({ filename: name, map }) => {
+    filename(name);
+    validateMap(map);
+    if (!isUuid(map.debugId)) throw new Error('Inject Debug IDs before uploading maps');
+    if (names.has(name) || debugIds.has(map.debugId))
+      throw new Error('Duplicate filename or Debug ID');
+    names.add(name);
+    debugIds.add(map.debugId);
+    const json = Buffer.from(JSON.stringify(map));
+    if (json.length > 33_554_432) throw new Error('Source map exceeds 32 MB inflated limit');
+    const bytes = gzipSync(json);
+    if (bytes.length > 33_554_432) throw new Error('Source map exceeds 32 MB upload limit');
+    return {
+      filename: name,
+      debug_id: map.debugId,
+      size_bytes: bytes.length,
+      content_type: 'application/json',
+      content_encoding: 'gzip',
+      bytes,
+    };
+  });
+  const client = new ApiClient(options);
+  const version = options.release ?? '__debug_id__';
+  await client.createRelease(version, { commit: options.commit, env: options.env });
+  const allIds = new Set();
+  for (let offset = 0; offset < files.length; offset += 50) {
+    const batch = files.slice(offset, offset + 50);
+    let uploads;
+    for (let generation = 0; ; generation++) {
+      uploads = validatePresign(
+        await client.presign(
+          version,
+          batch.map(({ bytes, ...metadata }) => metadata),
+        ),
+        batch,
+      );
+      for (const item of uploads) {
+        if (allIds.has(item.id)) throw new Error('Duplicate upload ID across batches');
+        allIds.add(item.id);
+      }
+      try {
+        await concurrent(uploads, concurrency, (file) =>
+          client.put(file.upload_url, file.headers, file.bytes),
+        );
+        break;
+      } catch (err) {
+        // S3 URLs expire. Request new IDs/URLs, rather than retrying an expired signature.
+        if (err.status !== 403 || generation >= client.retries) throw err;
+      }
+    }
+    const confirmed = await client.confirm(uploads.map((file) => file.id));
+    if (!Array.isArray(confirmed?.files) || confirmed.files.length !== uploads.length)
+      throw new Error('Incomplete confirmation response');
+    for (const file of uploads) {
+      const matching = confirmed.files.filter((item) => item.id === file.id);
+      if (
+        matching.length !== 1 ||
+        matching[0].status !== 'ready' ||
+        matching[0].debug_id !== file.debug_id ||
+        matching[0].size_bytes !== file.size_bytes
+      )
+        throw new Error('Confirmation metadata mismatch');
+    }
+  }
+  return { uploaded: files.length, debugIds: [...debugIds] };
+}
+
+export async function uploadDirectory(directory, options) {
+  const pairs = await collectPairs(directory);
+  const maps = pairs.map((pair) => {
+    const map = JSON.parse(pair.rawMap);
+    if (!map.debugId) throw new Error('Run sourcemaps inject before upload');
+    inject(pair.code, map); // Verify the existing ID still describes these exact JavaScript bytes.
+    return { filename: pair.filename, map };
+  });
+  const result = await uploadMaps(maps, options);
+  if (options.deleteAfter) {
+    // Validate every file before deleting any, including changes made during network requests.
+    for (const pair of pairs) {
+      if (
+        (await lstat(pair.mapPath)).isSymbolicLink() ||
+        (await realpath(pair.mapPath)) !== pair.mapPath ||
+        (await readFile(pair.mapPath, 'utf8')) !== pair.rawMap ||
+        (await readFile(pair.jsPath, 'utf8')) !== pair.code
+      )
+        throw new Error('Output changed during upload; maps were not deleted');
+    }
+    for (const pair of pairs) await unlink(pair.mapPath);
+  }
+  return result;
+}