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

package/dist/prompts.mjs

@@ -0,0 +1,263 @@
+import { t as NonInteractiveError } from "./non-interactive-error-Mm_Mn79M.mjs";
+import search from "@inquirer/search";
+import { checkbox, confirm, input, password, select } from "@inquirer/prompts";
+// src/prompts/menu/menu.ts
+/**
+* Searchable autocomplete over one menu level's `items`. `select()` would work too
+* at these list sizes, but `search()` degrades gracefully as the surface grows and
+* costs nothing when it doesn't. Resolves to the picked item's `value`.
+*/
+async function pickMenuItem(items, message = "What would you like to do?") {
+	return search({
+		message,
+		source: (term) => searchChoices(items, term)
+	});
+}
+/**
+* `@inquirer/search`'s `source` callback, factored out as a plain function —
+* unit-testable directly instead of only through a mocked `search()` call.
+* Empty/undefined `term` (nothing typed yet) returns every item.
+*/
+function searchChoices(items, term) {
+	const needle = term?.toLowerCase();
+	const pool = !needle ? items : items.filter((i) => i.haystack.includes(needle));
+	const rank = (i) => {
+		if (!needle) return 0;
+		const name = i.name.toLowerCase();
+		return name.startsWith(needle) ? 0 : name.includes(needle) ? 1 : 2;
+	};
+	return [...pool].sort((a, b) => rank(a) - rank(b)).map((i) => ({
+		name: i.name,
+		value: i.value,
+		description: i.description,
+		short: i.name.replace(/ ›$/, "")
+	}));
+}
+// src/prompts/prompt-options/prompt-options.ts
+/**
+* A required option must not resolve to an empty answer — `optionArgv`/
+* `secretEnv` (child-argv.ts) both drop an empty-string value entirely,
+* which would silently invoke the child without a flag the caller asked
+* for. Passed as `validate` so inquirer re-prompts instead of accepting it.
+*/
+const requireNonEmpty = (value) => value.trim().length > 0 || "required";
+async function promptOne(option) {
+	if (option.secret || option.type === "password") return await password({
+		message: option.message,
+		...option.required ? { validate: requireNonEmpty } : {}
+	});
+	if (option.type === "confirm") return await confirm({
+		message: option.message,
+		default: option.default
+	});
+	if (option.type === "select") {
+		const choices = typeof option.choices === "function" ? option.choices() : option.choices ?? [];
+		return await select({
+			message: option.message,
+			choices: choices.map((c) => ({ value: c }))
+		});
+	}
+	if (option.arity && option.arity > 1) {
+		const values = [];
+		for (let n = 0; n < option.arity; n++) values.push(await input({
+			message: `${option.message} (${n + 1} of ${option.arity})`,
+			...option.required ? { validate: requireNonEmpty } : {}
+		}));
+		return values;
+	}
+	return await input({
+		message: option.message,
+		default: option.default,
+		...option.required ? { validate: requireNonEmpty } : {}
+	});
+}
+/**
+* For each of `options` not already present in `argv`, resolves a value —
+* `required` ones are always included, like required positionals, never
+* behind a selector; everything else is offered through one `checkbox()`
+* ("set any options?") and only the picked ones are then prompted in
+* `options`' own declaration order. An empty list (or every optional one
+* left unpicked) means zero prompts.
+*
+* A picked option (whether required or checkbox-picked) with
+* `askLast: true` (holocron#1052 follow-up — a time-sensitive secret like
+* an OTP, which should be typed as close as possible to when it's actually
+* used, or one that's always needed for a specific operator's own account
+* but not everyone's) isn't given a value here yet: it's returned in
+* `deferred` instead, for the caller to resolve via
+* `promptForDeferredOptions` right before the real (non-dry-run) spawn.
+*
+* `when`, evaluated against answers collected so far in that same
+* declaration order, can skip a picked option entirely. Skipped this way,
+* the option is simply absent from the result, exactly as if it had never
+* been picked — acceptable for a minor, genuinely optional dependency, but
+* prefer `OptionMode` (see `promptForOptions`) when the options have a
+* real either/or relationship, so nothing contingent is shown at all.
+*/
+async function promptForFlatOptions(commandName, options, argv) {
+	if (options.length === 0) return {
+		answers: {},
+		deferred: []
+	};
+	const answers = {};
+	const deferred = [];
+	const needsPrompt = (option) => {
+		const existing = argv[option.key];
+		return existing === void 0 || existing === "";
+	};
+	const required = options.filter((o) => o.required);
+	const optional = options.filter((o) => !o.required);
+	if ((required.some(needsPrompt) || optional.some(needsPrompt)) && !process.stdin.isTTY) throw new NonInteractiveError(`\`${commandName}\` has options only settable interactively — pass them directly: holocron ${commandName} [options]`);
+	for (const option of required) {
+		if (!needsPrompt(option)) {
+			answers[option.key] = argv[option.key];
+			continue;
+		}
+		if (option.askLast) {
+			deferred.push(option);
+			continue;
+		}
+		answers[option.key] = await promptOne(option);
+	}
+	for (const option of optional) if (!needsPrompt(option)) answers[option.key] = argv[option.key];
+	const selectable = optional.filter(needsPrompt);
+	if (selectable.length === 0) return {
+		answers,
+		deferred
+	};
+	const picked = await checkbox({
+		message: "Set any options? (space to select, enter to skip)",
+		choices: selectable.map((o) => ({
+			name: o.message,
+			value: o.key
+		}))
+	});
+	if (picked.length === 0) return {
+		answers,
+		deferred
+	};
+	const pickedSet = new Set(picked);
+	for (const option of optional) {
+		if (!pickedSet.has(option.key)) continue;
+		if (option.when && !option.when(answers)) continue;
+		if (option.askLast) {
+			deferred.push(option);
+			continue;
+		}
+		answers[option.key] = await promptOne(option);
+	}
+	return {
+		answers,
+		deferred
+	};
+}
+/**
+* For a `modes`-based command (holocron#1052 follow-up): asks which
+* mutually exclusive workflow first ("What would you like to do?"), then
+* offers only that mode's own options, via the exact same
+* `promptForFlatOptions` flow. The picked mode's `flag`, if it has one, is
+* folded in as an already-resolved `confirm`-type option so
+* `buildChildArgv` renders it with no special-casing — it just sees
+* another boolean option whose answer happens to already be `true`.
+*/
+async function promptForModes(entry, modes, argv) {
+	if (!process.stdin.isTTY) throw new NonInteractiveError(`\`${entry.name}\` has options only settable interactively — pass them directly: holocron ${entry.name} [options]`);
+	const modeKey = await select({
+		message: "What would you like to do?",
+		choices: modes.map((m) => ({
+			name: m.message,
+			value: m.key,
+			description: m.description
+		}))
+	});
+	const mode = modes.find((m) => m.key === modeKey);
+	const options = mode.options ?? [];
+	const { answers, deferred } = await promptForFlatOptions(entry.name, options, argv);
+	if (!mode.flag) return {
+		options,
+		answers,
+		deferred
+	};
+	const flagOption = {
+		key: `__mode_${mode.key}`,
+		flag: mode.flag,
+		type: "confirm",
+		message: mode.message
+	};
+	return {
+		options: [flagOption, ...options],
+		answers: {
+			[flagOption.key]: true,
+			...answers
+		},
+		deferred
+	};
+}
+/**
+* Resolves `entry`'s options into a {@link ResolvedOptions} ready for
+* `buildChildArgv`/`secretEnv` — delegating to {@link promptForModes} when
+* `entry.modes` is set, or treating `entry.options` as a flat list
+* otherwise. See `promptForFlatOptions` for the flat-list prompting
+* algorithm itself. `result.deferred` still needs
+* {@link promptForDeferredOptions} before the real spawn.
+*/
+async function promptForOptions(entry, argv) {
+	if (entry.modes && entry.modes.length > 0) return promptForModes(entry, entry.modes, argv);
+	const options = entry.options ?? [];
+	const { answers, deferred } = await promptForFlatOptions(entry.name, options, argv);
+	return {
+		options,
+		answers,
+		deferred
+	};
+}
+/**
+* Collects a value for each of `deferred` — the `askLast: true` options
+* `promptForOptions` deliberately left unresolved. Call this as the very
+* last thing before the real (non-dry-run) spawn, never before: a dry-run
+* preview never reaches the real npm call these options exist for (an OTP
+* is never checked during `--dry-run`), and a time-sensitive code typed
+* any earlier — before a dry-run preview runs, before "proceed with the
+* real run?" waits on a human — risks going stale before it's actually
+* used. A no-op (no prompt at all) when `deferred` is empty.
+*/
+async function promptForDeferredOptions(deferred) {
+	const answers = {};
+	for (const option of deferred) answers[option.key] = await promptOne(option);
+	return answers;
+}
+// src/prompts/prompt-positionals/prompt-positionals.ts
+/**
+* For each of `entry.positionals` not already present in `argv`, prompts for
+* it (`input()` or `select()`, per the positional's `type`) and returns the
+* resolved values in positional order — ready to append to a spawned child's
+* argv, or to use directly in the current handler (Layer 3).
+*
+* Throws {@link NonInteractiveError} the first time it would need to prompt
+* on a non-TTY stdin, and again if a `select` positional's choices resolve
+* empty (nothing to pick from — e.g. `auth unset` with no stored tokens).
+*/
+async function promptForPositionals(entry, argv) {
+	const out = [];
+	for (const positional of entry.positionals) {
+		const existing = argv[positional.key];
+		if (existing !== void 0 && existing !== "") {
+			out.push(String(existing));
+			continue;
+		}
+		if (!process.stdin.isTTY) throw new NonInteractiveError(`\`${entry.name}\` needs "${positional.key}" — pass it directly: holocron ${entry.name} <${positional.cliArg ?? positional.key}>`);
+		if (positional.type === "select") {
+			const choices = typeof positional.choices === "function" ? positional.choices() : positional.choices ?? [];
+			if (choices.length === 0) throw new NonInteractiveError(`\`${entry.name}\`: no ${positional.key} to choose from — nothing stored yet`);
+			out.push(await select({
+				message: positional.message,
+				choices: choices.map((c) => ({ value: c }))
+			}));
+		} else out.push(await input({
+			message: positional.message,
+			...positional.validate ? { validate: positional.validate } : {}
+		}));
+	}
+	return out;
+}
+export { pickMenuItem, promptForDeferredOptions, promptForOptions, promptForPositionals, searchChoices };

package/dist/secrets.d.mts

@@ -0,0 +1,191 @@
+import { t as ParsedTokenArgs } from "./token-args.type-arNIDKsQ.mjs";
+export declare class TokenParseError extends Error {
+  name: string;
+}
+/**
+ * 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.
+ */
+export declare function parseTokenArgs(tokens: string[]): ParsedTokenArgs;
+/** Puts `text` on the system clipboard through `clipboardy`, which uses the platform's own tool. Loaded only when called. */
+export declare function copyToClipboard(text: string): Promise<void>;
+/**
+ * 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.
+ */
+/** Remember `variables` as what the source `source` returned. Setting a source again replaces its variables. */
+export declare function setCredentials(source: string, variables: Record<string, string>): void;
+/** Whether the source `source` has been read already, so a second loader in the same process does not read it again. */
+export declare function hasCredentials(source: string): boolean;
+/**
+ * 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.
+ */
+export declare function getCredential(...names: string[]): string | undefined;
+/** Forget every source. For tests, and for a process that wants the next load to read the providers again. */
+export declare function clearCredentials(): void;
+/**
+ * The file {@link writeCredentialsFile} wrote: its device and inode, and an open descriptor for it. The descriptor is
+ * held until cleanup, so the inode cannot be freed and handed to some other file, which makes comparing device and inode
+ * a sound way to tell this file from one that has since taken its path. Whoever receives it must give it to
+ * {@link shredFile}, or close `fd`.
+ */
+interface FileIdentity {
+  /** The device the file is on. */
+  dev: number;
+  /** The file's inode number on that device. */
+  ino: number;
+  /** An open, writable descriptor for the file, used to overwrite its contents wherever the path points by then. */
+  fd: number;
+}
+/**
+ * What {@link shredFile} did: `deleted` the file it was told about, found it `missing` (already gone), or left the
+ * path alone because it is no longer that file (`replaced`: another process swapped it, or it is not a regular file).
+ */
+type ShredOutcome = "deleted" | "missing" | "replaced";
+/**
+ * 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.
+ */
+export declare function writeCredentialsFile(path: string, text: string, force?: boolean, write?: (fd: number, text: string) => unknown): FileIdentity;
+/** The name of the file, at the repo root, that holds a developer's own tokens. */
+export declare 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.
+ */
+export declare function readDotenvFile(repoRoot: string): Record<string, string> | null;
+/**
+ * `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.
+ */
+export declare function dotenvLine(name: string, value: string): string | null;
+/**
+ * What git says about a path: `ignored` when a rule ignores it, `tracked` when git would track it, `no-repo` when the
+ * path is not in a git repository (or git is not installed, in which case nothing can commit it), and `unknown` when
+ * git failed in some other way.
+ */
+type GitIgnoreState = "ignored" | "tracked" | "no-repo" | "unknown";
+/**
+ * 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.
+ */
+export declare function isGitIgnored(path: string): GitIgnoreState;
+/** One stored secret, as the OS keyring binding hands it out. */
+interface KeyringEntry {
+  /** Store or replace the secret. Throws when the platform has no credential store. */
+  setPassword(password: string): void;
+  /** The secret, or `null` when nothing is stored. Throws when the platform has no credential store. */
+  getPassword(): string | null;
+  /** Remove the secret, and say whether there was one. Throws when the platform has no credential store. */
+  deletePassword(): boolean;
+}
+/** The part of `@napi-rs/keyring` that {@link createKeyring} uses, so a test can stand in for the OS. */
+interface KeyringBinding {
+  /** A handle on one secret: a service (the scope) and an account (the name within it). */
+  Entry: new (service: string, account: string) => KeyringEntry;
+  /** Every secret stored under `service`. Throws when the platform has no credential store. */
+  findCredentials(service: string): Array<{
+    account: string;
+  }>;
+}
+/** What {@link createKeyring} needs. */
+interface KeyringOptions {
+  /**
+   * The scope every secret is stored under, usually a reverse-DNS name (`com.example.tool`), so one tool's secrets
+   * do not mix with another's.
+   */
+  service: string;
+  /**
+   * The OS keyring binding. Default: `@napi-rs/keyring`, loaded the first time it is needed; a keyring that cannot be
+   * loaded behaves like one the platform does not support.
+   */
+  binding?: KeyringBinding | null;
+}
+/** A tool's secrets in the OS keyring. Every method is best-effort: where the keyring cannot be used it answers `null`, `false` or an empty list and never throws. */
+interface Keyring {
+  /**
+   * The secret stored for `account`, or `null` for both "not stored" and "keyring unavailable". The answer, a miss
+   * included, is remembered for the life of the process, so the keyring (which can prompt on every read) is asked once
+   * per account.
+   */
+  get(account: string): string | null;
+  /** Store or replace the secret for `account`. `true` on success, `false` when the keyring is unavailable. */
+  set(account: string, secret: string): boolean;
+  /** Remove the secret for `account`. `true` when one was removed, `false` when there was none or the keyring is unavailable. */
+  delete(account: string): boolean;
+  /** The accounts that have a secret under this service. */
+  list(): string[];
+  /** Whether the OS keyring can be used at all, for a caller that must tell an outage from an empty keyring. */
+  isAvailable(): boolean;
+  /** Forget what `get` remembered, so the next read asks the keyring again. For a test, or after the keyring was changed from outside the process. */
+  clearCache(): void;
+}
+/**
+ * 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.
+ */
+export declare function createKeyring(options: KeyringOptions): Keyring;
+/**
+ * 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.
+ */
+export declare function createPrivateFile(path: string, text: string, write?: (fd: number, text: string) => unknown): FileIdentity;
+/**
+ * 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.
+ */
+export declare function shredFile(path: string, identity: FileIdentity, remove?: (path: string) => void): ShredOutcome;
+export type { FileIdentity, GitIgnoreState, Keyring, KeyringBinding, KeyringEntry, KeyringOptions, ParsedTokenArgs, ShredOutcome };