@theholocron/kyber 0.0.0-stage → 5.0.0-alpha.338

package/dist/secrets.mjs

@@ -0,0 +1,329 @@
+import { n as parseTokenArgs, t as TokenParseError } from "./token-args-BgrCq_kK.mjs";
+import { createRequire } from "node:module";
+import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, lstatSync, openSync, readFileSync, renameSync, unlinkSync, writeSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { parse } from "dotenv";
+import { execFileSync } from "node:child_process";
+// src/secrets/copy-to-clipboard/copy-to-clipboard.ts
+/** Puts `text` on the system clipboard through `clipboardy`, which uses the platform's own tool. Loaded only when called. */
+async function copyToClipboard(text) {
+	const { default: clipboard } = await import("clipboardy");
+	await clipboard.write(text);
+}
+// src/secrets/credential-store/credential-store.ts
+/**
+* The variables the `credentials` providers returned, kept for the life of the process.
+*
+* The plugin loader reads each provider once (`setCredentials`), and the token resolvers look a token up here
+* (`getCredential`) after the flag and the process environment and before the keyring. It is in memory only: the
+* values were already in this process when the provider returned them, and nothing here writes them anywhere.
+*
+* A source is one provider's answer for one environment. They are kept in the order they were set, which is the
+* order `holocron.config` lists the providers, and the first source that has a value wins.
+*/
+const sources = /* @__PURE__ */ new Map();
+/** Remember `variables` as what the source `source` returned. Setting a source again replaces its variables. */
+function setCredentials(source, variables) {
+	sources.set(source, variables);
+}
+/** Whether the source `source` has been read already, so a second loader in the same process does not read it again. */
+function hasCredentials(source) {
+	return sources.has(source);
+}
+/**
+* The first non-empty value for any of `names`, from the first source that has one. Sources are tried in the order
+* they were set; within a source the names are tried in the order given (the project's own variable name before the
+* vendor's). `undefined` when no source has one.
+*/
+function getCredential(...names) {
+	for (const variables of sources.values()) for (const name of names) {
+		const value = variables[name];
+		if (value) return value;
+	}
+}
+/** Forget every source. For tests, and for a process that wants the next load to read the providers again. */
+function clearCredentials() {
+	sources.clear();
+}
+// src/secrets/private-file/private-file.ts
+/**
+* Create `path` as a new file only its owner can read (mode `0600`, set again on the open file so a loose `umask`
+* cannot widen it), write `text` to it and return which file it is, with its descriptor left open. It fails if the path
+* exists, a symlink included, so nothing is written through a planted link or over a file that is there. When the
+* write fails after the file exists, it closes and removes that file, so no plaintext is left behind. `write` is how the
+* text is written; it is a parameter so a test can make the write fail.
+*/
+function createPrivateFile(path, text, write = writeSync) {
+	const fd = openSync(path, "wx", 384);
+	try {
+		write(fd, text);
+		fchmodSync(fd, 384);
+		const { dev, ino } = fstatSync(fd);
+		return {
+			dev,
+			ino,
+			fd
+		};
+	} catch (err) {
+		closeSync(fd);
+		try {
+			unlinkSync(path);
+		} catch {}
+		throw err;
+	}
+}
+// src/secrets/shred-file/shred-file.ts
+/**
+* Overwrite the file `identity` names with zeros, close it, and remove it from `path`, so the tokens it held are not
+* left in a deleted-but-recoverable file.
+*
+* The overwrite goes through the descriptor held since the file was written, not through the path, so it zeroes that
+* file wherever the path points now and never follows a symlink: a symlink or another file swapped in is not touched.
+* The path itself is removed only if it is still that file (same device and inode, which the held descriptor keeps
+* from being reused); otherwise it is left alone (`replaced`), so a file another process put there, or another
+* export's file, survives. A path that is already gone is `missing`, not an error; any other failure to remove it
+* throws, so the caller never reports a file as deleted while it is still there.
+*
+* The overwrite is best effort: a journaling or copy-on-write filesystem and an SSD may keep older blocks it does not
+* reach, which is why the file is also kept private and short-lived. One that fails does not stop the removal.
+* `remove` is how the path is deleted; it is a parameter so a test can look at the file just before it goes.
+*/
+function shredFile(path, identity, remove = unlinkSync) {
+	let missing = false;
+	let same = false;
+	try {
+		try {
+			const { size } = fstatSync(identity.fd);
+			writeSync(identity.fd, Buffer.alloc(size), 0, size, 0);
+			fsyncSync(identity.fd);
+		} catch {}
+		const stat = lstatSync(path);
+		same = stat.isFile() && stat.dev === identity.dev && stat.ino === identity.ino;
+	} catch (err) {
+		if (err.code !== "ENOENT") throw err;
+		missing = true;
+	} finally {
+		try {
+			closeSync(identity.fd);
+		} catch {}
+	}
+	if (missing) return "missing";
+	if (!same) return "replaced";
+	remove(path);
+	return "deleted";
+}
+// src/secrets/credentials-file/credentials-file.ts
+/**
+* Write `text` to `path` as a file only its owner can read (mode `0600`), and return which file that is, with its
+* descriptor still open, so cleanup can remove only it. Without `force` it will not replace a file that is already
+* there. A write that fails removes the file it had just created, so a failed write never leaves plaintext tokens behind.
+*
+* With `force` the replacement is written to a temporary file beside `path` first and then renamed over it, which is
+* atomic, so a replacement that cannot be written or swapped in leaves the old file exactly as it was. Only once the
+* new file is in place is the old file's content overwritten with zeros through a descriptor opened on it before the
+* swap, so the tokens of an earlier run are not left recoverable. A symlink at `path` is replaced, not followed.
+*
+* Windows does not honour these modes, so the caller does not use this there. `write` is how the text is written; it is
+* a parameter so a test can make the write fail after the file exists.
+*/
+function writeCredentialsFile(path, text, force = false, write = writeSync) {
+	if (!force) return createPrivateFile(path, text, write);
+	const old = openExisting(path);
+	const temp = join(dirname(path), `${basename(path)}.${randomBytes(6).toString("hex")}.tmp`);
+	let fresh;
+	try {
+		fresh = createPrivateFile(temp, text, write);
+		try {
+			renameSync(temp, path);
+		} catch (err) {
+			closeSync(fresh.fd);
+			unlinkSync(temp);
+			throw err;
+		}
+	} catch (err) {
+		if (old) closeSync(old.fd);
+		throw err;
+	}
+	if (old) shredFile(path, old);
+	return fresh;
+}
+/** A descriptor for the regular file at `path`, opened without following a symlink, or `undefined` if there is none. */
+function openExisting(path) {
+	let stat;
+	try {
+		stat = lstatSync(path);
+	} catch (err) {
+		if (err.code === "ENOENT") return void 0;
+		throw err;
+	}
+	if (!stat.isFile()) return void 0;
+	const fd = openSync(path, constants.O_WRONLY | constants.O_NOFOLLOW);
+	const { dev, ino } = fstatSync(fd);
+	return {
+		dev,
+		ino,
+		fd
+	};
+}
+// src/secrets/dotenv-file/dotenv-file.ts
+/** The name of the file, at the repo root, that holds a developer's own tokens. */
+const DOTENV_FILE = ".env";
+/**
+* Read `<repoRoot>/.env` into a record, or `null` when the file is not there (or cannot be read).
+*
+* Only the repo root is looked at, never the directory the command happens to run in, so a `.env` in a checkout you
+* cloned and ran the CLI from is not trusted. The file is optional: nothing asks for it, and a project that keeps its
+* tokens in a `credentials` provider or the keyring does not need one.
+*/
+function readDotenvFile(repoRoot) {
+	try {
+		return parse(readFileSync(join(repoRoot, DOTENV_FILE)));
+	} catch {
+		return null;
+	}
+}
+// src/secrets/dotenv-line/dotenv-line.ts
+/** A value dotenv reads back as written without any quoting: no space, quote, `#`, backslash or line break. */
+const PLAIN = /^[A-Za-z0-9_@%+=:,./-]*$/;
+/** The quotes dotenv accepts around a value, in the order they are tried. Single quotes keep the value exactly as written. */
+const QUOTES = [
+	"'",
+	"\"",
+	"`"
+];
+/**
+* `NAME=value` in a form dotenv reads back as the same value, or `null` when there is none.
+*
+* dotenv has no escape for a quote or a backslash: a double-quoted value only turns `\n` and `\r` into line breaks, and
+* leaves every other backslash, an escaped quote included, in the value. So nothing is escaped here. A plain value is
+* written bare; any other is wrapped in the first of `'`, `"` and `` ` `` it does not contain; a value with a line
+* break can only be double-quoted (with `\n` and `\r`) and so must not contain `"` or a backslash. A value that fits
+* none of these is `null`, and the caller says so rather than exporting a different token.
+*/
+function dotenvLine(name, value) {
+	if (PLAIN.test(value)) return `${name}=${value}`;
+	if (/[\r\n]/.test(value)) {
+		if (value.includes("\"") || value.includes("\\")) return null;
+		return `${name}="${value.replace(/\r/g, "\\r").replace(/\n/g, "\\n")}"`;
+	}
+	const quote = QUOTES.find((q) => !value.includes(q));
+	return quote ? `${name}=${quote}${value}${quote}` : null;
+}
+// src/secrets/git-ignored/git-ignored.ts
+/**
+* Ask git whether it ignores `path` (see {@link GitIgnoreState}). A caller that must not leave a file where it could be
+* committed accepts only `ignored` and `no-repo`. Reads only; it changes nothing.
+*/
+function isGitIgnored(path) {
+	try {
+		execFileSync("git", [
+			"check-ignore",
+			"-q",
+			"--",
+			path
+		], {
+			cwd: dirname(path),
+			stdio: [
+				"ignore",
+				"ignore",
+				"pipe"
+			]
+		});
+		return "ignored";
+	} catch (err) {
+		const { status, code, stderr } = err;
+		if (code === "ENOENT") return "no-repo";
+		if (status === 1) return "tracked";
+		return status === 128 && /not a git repository/i.test(String(stderr)) ? "no-repo" : "unknown";
+	}
+}
+// src/secrets/keyring/keyring.ts
+function loadBinding() {
+	try {
+		return createRequire(import.meta.url)("@napi-rs/keyring");
+	} catch {
+		return null;
+	}
+}
+/**
+* A tool's secrets in the OS keyring, under one service name.
+*
+* Keyring access is best-effort. Platforms without a supported credential store (some Linux CI images, sandboxed
+* environments) throw from the underlying library, and `@napi-rs/keyring` is an optional peer that may not be installed
+* at all. Every method catches that and answers `null`, `false` or an empty list rather than propagating, so a caller's
+* chain (a flag, then the environment, then the keyring) falls through to the paths that do work, which is how CI is
+* meant to run.
+*
+* Reads are remembered in memory only, for the life of the process. A cache that outlived the process would mean writing
+* secrets somewhere else, which is what the keyring is there to avoid.
+*/
+function createKeyring(options) {
+	const { service } = options;
+	const cache = /* @__PURE__ */ new Map();
+	let binding = options.binding;
+	const loaded = () => {
+		if (binding === void 0) binding = loadBinding();
+		return binding;
+	};
+	const entry = (account) => {
+		const b = loaded();
+		if (!b) throw new Error("no OS keyring available");
+		return new b.Entry(service, account);
+	};
+	return {
+		get(account) {
+			if (cache.has(account)) return cache.get(account);
+			let secret;
+			try {
+				secret = entry(account).getPassword();
+			} catch {
+				secret = null;
+			}
+			cache.set(account, secret);
+			return secret;
+		},
+		set(account, secret) {
+			try {
+				entry(account).setPassword(secret);
+				cache.set(account, secret);
+				return true;
+			} catch {
+				cache.delete(account);
+				return false;
+			}
+		},
+		delete(account) {
+			try {
+				const removed = entry(account).deletePassword();
+				cache.set(account, null);
+				return removed;
+			} catch {
+				cache.delete(account);
+				return false;
+			}
+		},
+		list() {
+			try {
+				const b = loaded();
+				return b ? b.findCredentials(service).map((c) => c.account) : [];
+			} catch {
+				return [];
+			}
+		},
+		isAvailable() {
+			try {
+				const b = loaded();
+				if (!b) return false;
+				b.findCredentials(service);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		clearCache() {
+			cache.clear();
+		}
+	};
+}
+export { DOTENV_FILE, TokenParseError, clearCredentials, copyToClipboard, createKeyring, createPrivateFile, dotenvLine, getCredential, hasCredentials, isGitIgnored, parseTokenArgs, readDotenvFile, setCredentials, shredFile, writeCredentialsFile };

package/dist/testing.d.mts

@@ -0,0 +1,83 @@
+import * as NodeModule from "node:module";
+import { Argv } from "yargs";
+/** What a run of a built CLI printed and how it ended. */
+interface CliRun {
+  /** Everything written to stdout. */
+  stdout: string;
+  /** Everything written to stderr. */
+  stderr: string;
+  /** The exit code; -1 if the process was killed by the timeout. */
+  code: number;
+}
+/** What one run of the CLI is given. */
+interface RunCliOptions {
+  /** Written to the runner's `configFile` in the working directory. A string is written as it is (for a broken file). */
+  config?: object | string;
+  /** Added to the controlled environment for this run. */
+  env?: Record<string, string>;
+  /** How long the run may take before it is killed. Default 20 seconds. */
+  timeoutMs?: number;
+}
+/** What {@link createCliRunner} needs to run a tool's built binary. */
+interface CliRunnerOptions {
+  /** The built file to run with Node, e.g. `dist/cli.mjs`. */
+  bin: string;
+  /** The name of the config file, in the working directory, that a run's `config` is written to (`tool.config.json`). */
+  configFile?: string;
+  /** Added to the controlled environment of every run, such as a switch that turns telemetry off. */
+  env?: Record<string, string>;
+  /** The start of the temporary working directory's name. Default `cli-`. */
+  prefix?: string;
+}
+/**
+ * A function that runs a tool's built binary in a fresh temporary directory with a controlled environment, and returns
+ * what it printed and how it exited. The environment is built from nothing: no tokens, no telemetry and no update check
+ * leak in from whoever runs the tests, and stdin is closed, so a command that wants a terminal behaves as it does in CI.
+ */
+export declare function createCliRunner(options: CliRunnerOptions): (args: string[], run?: RunCliOptions) => Promise<CliRun>;
+/** What {@link ensureBuilt} needs to decide whether a build is current. */
+interface EnsureBuiltOptions {
+  /** The built file the tests run, e.g. `dist/cli.mjs`. */
+  bin: string;
+  /** The source directory it is built from. A build older than any source file in it is stale. */
+  srcDir: string;
+  /** The package directory the build runs in. */
+  cwd: string;
+  /** Folders under `srcDir` whose files do not count as source (test helpers). Default `["testing"]`. */
+  ignoreDirs?: string[];
+  /** How to build. Default: run the package's own `tsdown`. */
+  build?: () => void;
+}
+/** Whether `bin` is missing or older than the newest source file under `srcDir` (tests and `ignoreDirs` not counted). */
+export declare function isStale(bin: string, srcDir: string, ignoreDirs?: readonly string[]): boolean;
+/**
+ * For a Vitest global setup: make sure the built file the tests run exists and is newer than the source, so tests of the
+ * built binary test what is checked out. It builds only when the file is missing or stale, so a pipeline that built first
+ * (turbo does) pays nothing, and a rebuild never wipes `dist` out from under another package's tests.
+ */
+export declare function ensureBuilt(options: EnsureBuiltOptions): void;
+/**
+ * A `createRequire` whose `resolve()` only finds modules under the directory it was created for.
+ *
+ * Node also resolves through `NODE_PATH`, and a test runner started by pnpm puts pnpm's hoisted
+ * dependency folder there. A test that creates a temp "repo" and expects a package not to be installed
+ * in it would then find the one hoisted for the real workspace, and its result would depend on what
+ * the workspace happens to link (a package that becomes a workspace dependency turns up there).
+ *
+ * Use it in a test that exercises "is this package installed in that repo":
+ *
+ *   vi.mock("node:module", async (importOriginal) => {
+ *     const actual = await importOriginal<typeof import("node:module")>();
+ *     const { hermeticCreateRequire } = await import("../../testing/hermetic-require.js");
+ *     return { ...actual, createRequire: hermeticCreateRequire(actual) };
+ *   });
+ */
+export declare function hermeticCreateRequire(actual: Pick<typeof NodeModule, "createRequire">): typeof NodeModule.createRequire;
+/**
+ * Runs one command module through a real yargs parse, so a test covers the command's builder and its handler together.
+ * `configure` declares the root options the real CLI has (`--cwd`, `--dry-run`, …) before the command is added. A handler
+ * that throws reaches the test as a rejection, not as a message printed by yargs. The handler's collaborators are mocked
+ * by the test.
+ */
+export declare function runCommand(module: unknown, args: string[], configure?: (parser: Argv) => Argv): Promise<Record<string, unknown>>;
+export type { CliRun, CliRunnerOptions, EnsureBuiltOptions, RunCliOptions };

package/dist/testing.mjs

@@ -0,0 +1,139 @@
+import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { dirname, join, sep } from "node:path";
+import { execFileSync, spawn } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import yargs from "yargs";
+// src/testing/cli-runner/cli-runner.ts
+/**
+* A function that runs a tool's built binary in a fresh temporary directory with a controlled environment, and returns
+* what it printed and how it exited. The environment is built from nothing: no tokens, no telemetry and no update check
+* leak in from whoever runs the tests, and stdin is closed, so a command that wants a terminal behaves as it does in CI.
+*/
+function createCliRunner(options) {
+	return async (args, run = {}) => {
+		const dir = await mkdtemp(join(tmpdir(), options.prefix ?? "cli-"));
+		try {
+			if (run.config !== void 0) {
+				if (!options.configFile) throw new Error("this runner has no configFile, so a run cannot be given a config");
+				const body = typeof run.config === "string" ? run.config : JSON.stringify(run.config);
+				await writeFile(join(dir, options.configFile), body);
+			}
+			return await new Promise((resolve, reject) => {
+				const child = spawn(process.execPath, [options.bin, ...args], {
+					cwd: dir,
+					stdio: [
+						"ignore",
+						"pipe",
+						"pipe"
+					],
+					env: {
+						PATH: process.env["PATH"] ?? "",
+						HOME: dir,
+						TMPDIR: dir,
+						FORCE_COLOR: "0",
+						NO_COLOR: "1",
+						NO_UPDATE_NOTIFIER: "1",
+						...options.env,
+						...run.env
+					}
+				});
+				let stdout = "";
+				let stderr = "";
+				child.stdout.on("data", (d) => stdout += d);
+				child.stderr.on("data", (d) => stderr += d);
+				const timer = setTimeout(() => child.kill("SIGKILL"), run.timeoutMs ?? 2e4);
+				child.on("error", reject);
+				child.on("close", (code) => {
+					clearTimeout(timer);
+					resolve({
+						stdout,
+						stderr,
+						code: code ?? -1
+					});
+				});
+			});
+		} finally {
+			await rm(dir, {
+				recursive: true,
+				force: true
+			});
+		}
+	};
+}
+// src/testing/ensure-built/ensure-built.ts
+/** The newest modification time of a source file under `dir`, ignoring tests and the folders named in `ignoreDirs`. */
+function newestSource(dir, ignoreDirs) {
+	let newest = 0;
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		const path = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			if (!ignoreDirs.includes(entry.name)) newest = Math.max(newest, newestSource(path, ignoreDirs));
+		} else if (!/\.test\.ts$/.test(entry.name)) newest = Math.max(newest, statSync(path).mtimeMs);
+	}
+	return newest;
+}
+/** Whether `bin` is missing or older than the newest source file under `srcDir` (tests and `ignoreDirs` not counted). */
+function isStale(bin, srcDir, ignoreDirs = ["testing"]) {
+	return !existsSync(bin) || statSync(bin).mtimeMs < newestSource(srcDir, ignoreDirs);
+}
+/**
+* For a Vitest global setup: make sure the built file the tests run exists and is newer than the source, so tests of the
+* built binary test what is checked out. It builds only when the file is missing or stale, so a pipeline that built first
+* (turbo does) pays nothing, and a rebuild never wipes `dist` out from under another package's tests.
+*/
+function ensureBuilt(options) {
+	if (!isStale(options.bin, options.srcDir, options.ignoreDirs)) return;
+	if (options.build) return options.build();
+	execFileSync(join(options.cwd, "node_modules", ".bin", "tsdown"), {
+		cwd: options.cwd,
+		stdio: "inherit"
+	});
+}
+// src/testing/hermetic-require/hermetic-require.ts
+/**
+* A `createRequire` whose `resolve()` only finds modules under the directory it was created for.
+*
+* Node also resolves through `NODE_PATH`, and a test runner started by pnpm puts pnpm's hoisted
+* dependency folder there. A test that creates a temp "repo" and expects a package not to be installed
+* in it would then find the one hoisted for the real workspace, and its result would depend on what
+* the workspace happens to link (a package that becomes a workspace dependency turns up there).
+*
+* Use it in a test that exercises "is this package installed in that repo":
+*
+*   vi.mock("node:module", async (importOriginal) => {
+*     const actual = await importOriginal<typeof import("node:module")>();
+*     const { hermeticCreateRequire } = await import("../../testing/hermetic-require.js");
+*     return { ...actual, createRequire: hermeticCreateRequire(actual) };
+*   });
+*/
+function hermeticCreateRequire(actual) {
+	return ((from) => {
+		const real = actual.createRequire(from);
+		const file = typeof from === "string" && !from.startsWith("file:") ? from : fileURLToPath(from);
+		let root = dirname(file);
+		try {
+			root = realpathSync(root);
+		} catch {}
+		const resolve = (id, options) => {
+			const found = real.resolve(id, options);
+			if (found !== root && !found.startsWith(root + sep)) throw Object.assign(/* @__PURE__ */ new Error(`Cannot find module '${id}' under ${root}`), { code: "MODULE_NOT_FOUND" });
+			return found;
+		};
+		return Object.assign((id) => real(id), real, { resolve: Object.assign(resolve, real.resolve) });
+	});
+}
+// src/testing/run-command/run-command.ts
+/**
+* Runs one command module through a real yargs parse, so a test covers the command's builder and its handler together.
+* `configure` declares the root options the real CLI has (`--cwd`, `--dry-run`, …) before the command is added. A handler
+* that throws reaches the test as a rejection, not as a message printed by yargs. The handler's collaborators are mocked
+* by the test.
+*/
+async function runCommand(module, args, configure = (parser) => parser) {
+	return configure(yargs(args).parserConfiguration({ "populate--": true })).command(module).fail((msg, err) => {
+		throw err ?? new Error(msg);
+	}).parseAsync();
+}
+export { createCliRunner, ensureBuilt, hermeticCreateRequire, isStale, runCommand };

package/dist/token-args-BgrCq_kK.mjs

@@ -0,0 +1,38 @@
+// src/secrets/token-args/token-args.ts
+var TokenParseError = class extends Error {
+	name = "TokenParseError";
+};
+/**
+* Converts raw --token CLI values into a typed result.
+*
+* Bare form:   --token ghp_xxx            → { cliToken: "ghp_xxx" }
+* Keyed form:  --token github=ghp_xxx     → { cliTokens: { github: "ghp_xxx" } }
+* Mixed:       --token github=ghp_xxx --token v_yyy
+*                                         → { cliToken: "v_yyy", cliTokens: { github: "ghp_xxx" } }
+*
+* Values may contain "=" (e.g. base64 strings) — only the first "=" is treated as a separator.
+*/
+function parseTokenArgs(tokens) {
+	if (tokens.length === 0) return {};
+	const cliTokens = {};
+	const bare = [];
+	for (const raw of tokens) {
+		const eqIdx = raw.indexOf("=");
+		if (eqIdx === -1) {
+			bare.push(raw);
+			continue;
+		}
+		const vendor = raw.slice(0, eqIdx);
+		const value = raw.slice(eqIdx + 1);
+		if (vendor.trim() === "") throw new TokenParseError(`invalid --token value "${raw}": vendor name must not be empty`);
+		if (/\s/.test(vendor)) throw new TokenParseError(`invalid --token value "${raw}": vendor name must not contain whitespace`);
+		if (value === "") throw new TokenParseError(`invalid --token value "${raw}": token value must not be empty`);
+		cliTokens[vendor] = value;
+	}
+	if (bare.length > 1) throw new TokenParseError(`only one bare --token value is allowed; got ${bare.length.toString()} — use vendor=value form for multiple tokens`);
+	const result = {};
+	if (bare.length === 1) result.cliToken = bare[0];
+	if (Object.keys(cliTokens).length > 0) result.cliTokens = cliTokens;
+	return result;
+}
+export { parseTokenArgs as n, TokenParseError as t };

package/dist/token-args.type-arNIDKsQ.d.mts

@@ -0,0 +1,7 @@
+interface ParsedTokenArgs {
+  /** Set when a bare (unkeyed) --token value was passed. Used as fallback for all plugins. */
+  cliToken?: string;
+  /** Set when one or more vendor=value pairs were passed. */
+  cliTokens?: Record<string, string>;
+}
+export { ParsedTokenArgs as t };