@moku-labs/common 0.1.0 → 0.2.0

package/dist/cli.mjs

@@ -0,0 +1,652 @@
+import { createInterface } from "node:readline";
+//#region src/cli/ansi.ts
+/**
+* @file `@moku-labs/common/cli` — TTY/`NO_COLOR`-aware ANSI color + box-drawing
+* primitives: the shared "brand DNA" every Moku CLI renders through (the brand pink,
+* the palette, the box/spinner/progress glyphs). Color and Unicode glyphs are emitted
+* only on a real TTY with `NO_COLOR` unset; otherwise plain ASCII so CI logs and pipes
+* stay readable. Pure: depends on nothing but `process.stdout`/`process.env` defaults,
+* so a consuming framework can build its own panels on top without pulling in any UI lib.
+*/
+/** The ANSI escape byte (ESC, `0x1b`), built so no literal control char is in source. */
+const ESC = String.fromCodePoint(27);
+/** ANSI SGR codes used by the brand renderer (each prefixed with the ESC byte). */
+const ANSI = {
+	reset: `${ESC}[0m`,
+	bold: `${ESC}[1m`,
+	dim: `${ESC}[2m`,
+	red: `${ESC}[31m`,
+	green: `${ESC}[32m`,
+	yellow: `${ESC}[33m`,
+	blue: `${ESC}[34m`,
+	magenta: `${ESC}[35m`,
+	cyan: `${ESC}[36m`,
+	gray: `${ESC}[90m`
+};
+/**
+* The Moku brand pink (`#FF1E6F`) as an RGB triple, used for 24-bit truecolor output.
+* Degrades to {@link ANSI.magenta} on a 16-color TTY and to plain text off a TTY.
+*/
+const BRAND_PINK = {
+	r: 255,
+	g: 30,
+	b: 111
+};
+/**
+* Build a 24-bit (truecolor) SGR foreground escape for the given RGB triple.
+*
+* @param r - Red channel (0–255).
+* @param g - Green channel (0–255).
+* @param b - Blue channel (0–255).
+* @returns The `ESC[38;2;r;g;bm` foreground sequence.
+* @example
+* fg24(255, 30, 111); // "\x1b[38;2;255;30;111m"
+*/
+function fg24(r, g, b) {
+	return `${ESC}[38;2;${r};${g};${b}m`;
+}
+/** ANSI: erase the entire current line, leaving the cursor where it is. */
+const CLEAR_LINE = `${ESC}[2K`;
+/** ANSI: erase from the cursor to the end of the screen (drops stale trailing rows). */
+const CLEAR_BELOW = `${ESC}[0J`;
+/**
+* Braille spinner frames for live "working…" indicators on a TTY (advance one per tick).
+* Off a TTY a renderer never animates, so this is unused in plain/CI output.
+*/
+const SPINNER_FRAMES = [
+	"⠋",
+	"⠙",
+	"⠹",
+	"⠸",
+	"⠼",
+	"⠴",
+	"⠦",
+	"⠧",
+	"⠇",
+	"⠏"
+];
+/**
+* The ANSI sequence to move the cursor up `n` lines (empty string for `n <= 0`). A
+* renderer uses it to repaint a live block in place — move up over the previous draw,
+* then rewrite each row — so progress updates a fixed region instead of scrolling lines.
+*
+* @param n - Number of lines to move the cursor up.
+* @returns The cursor-up escape sequence, or `""` when `n <= 0`.
+* @example
+* cursorUp(3); // "\x1b[3A"
+*/
+function cursorUp(n) {
+	return n > 0 ? `${ESC}[${n}A` : "";
+}
+/** Unicode rounded box glyphs used when output is a color-capable TTY. */
+const UNICODE_BOX = {
+	topLeft: "╭",
+	topRight: "╮",
+	bottomLeft: "╰",
+	bottomRight: "╯",
+	horizontal: "─",
+	vertical: "│"
+};
+/** ASCII box glyphs used when output is piped/CI (plain mode). */
+const ASCII_BOX = {
+	topLeft: "+",
+	topRight: "+",
+	bottomLeft: "+",
+	bottomRight: "+",
+	horizontal: "-",
+	vertical: "|"
+};
+/**
+* Matches every ANSI SGR escape sequence (used to measure visible width). Built from
+* the {@link ESC} byte so no literal control character appears in the source regex.
+*/
+const ANSI_PATTERN = new RegExp(String.raw`${ESC}\[[0-9;]*m`, "g");
+/**
+* Whether ANSI color/box glyphs should be emitted: a TTY stream with `NO_COLOR`
+* unset. Reads `process.stdout.isTTY` and `process.env.NO_COLOR` by default so the
+* renderer auto-degrades in CI and pipes.
+*
+* @param stream - Stream to probe for `isTTY` (defaults to `process.stdout`).
+* @param noColor - The `NO_COLOR` value (defaults to `process.env.NO_COLOR`).
+* @returns `true` when color should be used.
+* @example
+* supportsColor(); // true in an interactive terminal
+*/
+function supportsColor(stream = process.stdout, noColor = process.env.NO_COLOR) {
+	return stream.isTTY === true && noColor === void 0;
+}
+/**
+* Whether the terminal advertises 24-bit (truecolor) support via `COLORTERM`, so the
+* renderer may emit the exact brand pink ({@link BRAND_PINK}) instead of the 16-color
+* `magenta` approximation. Always layered on top of {@link supportsColor} — truecolor
+* is never used when color itself is disabled.
+*
+* @param colorTerm - The `COLORTERM` value (defaults to `process.env.COLORTERM`).
+* @returns `true` when `COLORTERM` is `truecolor` or `24bit`.
+* @example
+* supportsTruecolor("truecolor"); // true
+*/
+function supportsTruecolor(colorTerm = process.env.COLORTERM) {
+	return colorTerm === "truecolor" || colorTerm === "24bit";
+}
+/**
+* The braille spinner glyph for a given elapsed time, advancing one frame per
+* `frameMs`. Deriving the frame from wall-clock elapsed (rather than a tick counter)
+* keeps the spinner correct even when the animation ticker is briefly starved by a
+* synchronous build phase and several ticks coalesce — the glyph still reflects real
+* elapsed time instead of freezing on a stale frame.
+*
+* @param elapsedMs - Milliseconds since the live region opened.
+* @param frameMs - Milliseconds per frame (defaults to `80`).
+* @returns The active spinner glyph.
+* @example
+* spinnerFrameAt(240); // "⠹" (the 4th frame at 80ms/frame)
+*/
+function spinnerFrameAt(elapsedMs, frameMs = 80) {
+	return SPINNER_FRAMES[Math.floor(Math.max(0, elapsedMs) / frameMs) % SPINNER_FRAMES.length] ?? "⠋";
+}
+/**
+* Select the box glyph set for the given color mode (Unicode on a TTY, ASCII off it).
+*
+* @param color - Whether color/Unicode output is enabled.
+* @returns The matching {@link BoxGlyphs} set.
+* @example
+* const glyphs = boxGlyphs(supportsColor());
+*/
+function boxGlyphs(color) {
+	return color ? UNICODE_BOX : ASCII_BOX;
+}
+/**
+* The visible width of a string, ignoring any ANSI escape sequences it contains.
+*
+* @param text - The (possibly colorized) text to measure.
+* @returns The number of visible characters.
+* @example
+* visibleWidth(`${ANSI.red}hi${ANSI.reset}`); // 2
+*/
+function visibleWidth(text) {
+	return text.replaceAll(ANSI_PATTERN, "").length;
+}
+/**
+* Build a {@link Palette} bound to a fixed color mode. When `color` is `false` every
+* helper returns its input unchanged, so the same render code path produces plain
+* output in CI/pipes.
+*
+* @param color - Whether color is enabled (typically `supportsColor()`).
+* @param truecolor - Whether 24-bit output is enabled (typically `supportsTruecolor()`);
+*   only consulted by {@link Palette.pink}. Defaults to `false` (16-color magenta).
+* @returns The bound color palette.
+* @example
+* const palette = makePalette(supportsColor(), supportsTruecolor());
+* const line = palette.green("done");
+*/
+function makePalette(color, truecolor = false) {
+	return {
+		enabled: color,
+		/**
+		* Wrap text in the given ANSI code (returns it unchanged when color is off).
+		*
+		* @param code - The ANSI SGR code to apply.
+		* @param text - The text to colorize.
+		* @returns The colorized (or unchanged) text.
+		* @example
+		* palette.paint(ANSI.green, "ok");
+		*/
+		paint(code, text) {
+			return color ? `${code}${text}${ANSI.reset}` : text;
+		},
+		/**
+		* Bold the given text (no-op in plain mode).
+		*
+		* @param text - The text to embolden.
+		* @returns The bold (or unchanged) text.
+		* @example
+		* palette.bold("title");
+		*/
+		bold(text) {
+			return this.paint(ANSI.bold, text);
+		},
+		/**
+		* Dim the given text (no-op in plain mode).
+		*
+		* @param text - The text to dim.
+		* @returns The dim (or unchanged) text.
+		* @example
+		* palette.dim("· 84ms");
+		*/
+		dim(text) {
+			return this.paint(ANSI.dim, text);
+		},
+		/**
+		* Color the given text green (no-op in plain mode).
+		*
+		* @param text - The text to colorize.
+		* @returns The green (or unchanged) text.
+		* @example
+		* palette.green("✓");
+		*/
+		green(text) {
+			return this.paint(ANSI.green, text);
+		},
+		/**
+		* Color the given text yellow (no-op in plain mode).
+		*
+		* @param text - The text to colorize.
+		* @returns The yellow (or unchanged) text.
+		* @example
+		* palette.yellow("~");
+		*/
+		yellow(text) {
+			return this.paint(ANSI.yellow, text);
+		},
+		/**
+		* Color the given text red (no-op in plain mode).
+		*
+		* @param text - The text to colorize.
+		* @returns The red (or unchanged) text.
+		* @example
+		* palette.red("✗");
+		*/
+		red(text) {
+			return this.paint(ANSI.red, text);
+		},
+		/**
+		* Color the given text cyan (no-op in plain mode).
+		*
+		* @param text - The text to colorize.
+		* @returns The cyan (or unchanged) text.
+		* @example
+		* palette.cyan("http://localhost:4173");
+		*/
+		cyan(text) {
+			return this.paint(ANSI.cyan, text);
+		},
+		/**
+		* Color the given text the Moku brand pink: exact `#FF1E6F` (24-bit) when truecolor
+		* is enabled, the 16-color `magenta` approximation otherwise, unchanged in plain mode.
+		*
+		* @param text - The text to colorize.
+		* @returns The pink (or unchanged) text.
+		* @example
+		* palette.pink("▟▙ moku web");
+		*/
+		pink(text) {
+			if (!color) return text;
+			if (truecolor) return `${fg24(BRAND_PINK.r, BRAND_PINK.g, BRAND_PINK.b)}${text}${ANSI.reset}`;
+			return this.paint(ANSI.magenta, text);
+		}
+	};
+}
+/**
+* Frame a list of already-rendered content lines in a box, padding each line to the
+* widest visible line (or `minInnerWidth`, whichever is larger — so several boxes can be
+* forced to a shared width). Uses Unicode borders when `color` is enabled and ASCII
+* otherwise. Visible width ignores embedded ANSI so colored lines align.
+*
+* @param lines - The content lines (may contain ANSI color codes).
+* @param color - Whether to use Unicode borders (and assume color-capable output).
+* @param minInnerWidth - Minimum inner (content) width to pad every row to. Defaults to `0`.
+* @returns The boxed lines (top border, content rows, bottom border).
+* @example
+* box(["Local:   http://localhost:4173"], true, 62);
+*/
+function box(lines, color, minInnerWidth = 0) {
+	const glyphs = boxGlyphs(color);
+	const inner = Math.max(0, minInnerWidth, ...lines.map((line) => visibleWidth(line)));
+	const horizontal = glyphs.horizontal.repeat(inner + 2);
+	const top = `${glyphs.topLeft}${horizontal}${glyphs.topRight}`;
+	const bottom = `${glyphs.bottomLeft}${horizontal}${glyphs.bottomRight}`;
+	return [
+		top,
+		...lines.map((line) => {
+			const pad = " ".repeat(inner - visibleWidth(line));
+			return `${glyphs.vertical} ${line}${pad} ${glyphs.vertical}`;
+		}),
+		bottom
+	];
+}
+//#endregion
+//#region src/cli/console.ts
+/**
+* @file `@moku-labs/common/cli` — the branded console: the shared, **stateless** line
+* vocabulary every Moku CLI prints through so the look never drifts between projects.
+* It is the generic counterpart to a framework's own (stateful) panels: the `▟▙` lockup
+* banner, section `heading`s, `info`/`warn`/`error` lines, `✓/✗ check` rows, plus the
+* `railLine`/`box` builders a project composes its own panels from. Built entirely on the
+* {@link makePalette} primitives, TTY/`NO_COLOR`-aware, every line routed through an
+* injectable sink so tests capture output (and a non-CLI consumer can redirect it).
+*/
+/** Default total visible width the lockup rule spans and `railLine` right-aligns to. */
+const DEFAULT_WIDTH$1 = 66;
+/**
+* Create a {@link BrandConsole}. Output flows through the injected sink (default
+* `console.log`/`console.error`) and is colorized only when color is enabled, so the
+* identical render path yields branded color/Unicode on a TTY and plain ASCII in CI/pipes.
+*
+* @param options - Optional sinks, color/truecolor overrides, and width (see
+*   {@link BrandConsoleOptions}).
+* @returns The branded console.
+* @example
+* const ui = createBrandConsole();
+* ui.lockup({ wordmark: "moku tool", version: "v1.0.0" });
+* ui.check(true, "config loaded");
+*/
+function createBrandConsole(options = {}) {
+	const write = options.write ?? ((line) => console.log(line));
+	const writeError = options.writeError ?? ((line) => console.error(line));
+	const color = options.color ?? supportsColor();
+	const palette = makePalette(color, options.truecolor ?? (color && supportsTruecolor()));
+	const width = options.width ?? DEFAULT_WIDTH$1;
+	const cube = color ? "▟▙" : "*";
+	const rule = color ? "─" : "-";
+	/**
+	* Right-align `right` against `left` within `lineWidth`, measuring visible width so
+	* embedded ANSI never throws the alignment off.
+	*
+	* @param left - The left segment (may contain ANSI).
+	* @param right - The right segment (may contain ANSI).
+	* @param lineWidth - Total visible width to fill (defaults to the console width).
+	* @returns The padded line.
+	* @example
+	* railLine("left", "right", 20);
+	*/
+	const railLine = (left, right, lineWidth = width) => {
+		const gap = Math.max(1, lineWidth - visibleWidth(left) - visibleWidth(right));
+		return `${left}${" ".repeat(gap)}${right}`;
+	};
+	return {
+		palette,
+		color,
+		width,
+		/**
+		* Write a pre-rendered line verbatim through the stdout sink.
+		*
+		* @param text - The line to write (defaults to an empty line).
+		* @example
+		* ui.line("  custom row");
+		*/
+		line(text = "") {
+			write(text);
+		},
+		/**
+		* Render the `▟▙ <wordmark>` lockup (cube + bold-pink wordmark + optional label,
+		* version right-aligned), a dim hairline rule, and an optional dim facts line.
+		*
+		* @param opts - The lockup fields (see {@link LockupOptions}).
+		* @example
+		* ui.lockup({ wordmark: "moku web", label: "build", version: "v1.2.0" });
+		*/
+		lockup(opts) {
+			const wordmark = palette.pink(palette.bold(opts.wordmark));
+			const label = opts.label ? `  ${palette.dim(opts.label)}` : "";
+			write(railLine(` ${palette.pink(cube)} ${wordmark}${label}`, opts.version ? palette.dim(opts.version) : ""));
+			write(` ${palette.dim(rule.repeat(width - 1))}`);
+			if (opts.facts !== void 0) write(` ${palette.dim(opts.facts)}`);
+		},
+		/**
+		* Render a section heading: a blank line followed by a bold brand-pink label.
+		*
+		* @param text - The heading label.
+		* @example
+		* ui.heading("Diagnostics");
+		*/
+		heading(text) {
+			write("");
+			write(`  ${palette.bold(palette.pink(text))}`);
+		},
+		/**
+		* Render a neutral informational line (`› message`), indenting continuation lines.
+		*
+		* @param message - The line to print.
+		* @example
+		* ui.info("watching for changes…");
+		*/
+		info(message) {
+			const [first = "", ...rest] = message.split("\n");
+			write(`  ${palette.cyan("›")} ${first}`);
+			for (const lineText of rest) write(`    ${lineText}`);
+		},
+		/**
+		* Render a warning line (`⚠ message`, to stderr).
+		*
+		* @param message - The warning to print.
+		* @example
+		* ui.warn("deploy skipped");
+		*/
+		warn(message) {
+			writeError(`  ${palette.yellow("⚠")} ${message}`);
+		},
+		/**
+		* Render an error line (`✗ message`, to stderr), optionally with a cause beneath.
+		*
+		* @param message - The error summary to print.
+		* @param cause - Optional underlying error/value printed beneath the summary.
+		* @example
+		* ui.error("build failed", err);
+		*/
+		error(message, cause) {
+			writeError(`  ${palette.red("✗")} ${message}`);
+			if (cause !== void 0) writeError(String(cause));
+		},
+		/**
+		* Render a diagnostic line — green `✓` / red `✗` + label, with optional dim,
+		* indented detail beneath.
+		*
+		* @param ok - Whether the check passed.
+		* @param label - The check label.
+		* @param detail - Optional multi-line guidance shown indented under the line.
+		* @example
+		* ui.check(true, "config loaded");
+		*/
+		check(ok, label, detail) {
+			write(`  ${ok ? palette.green("✓") : palette.red("✗")} ${label}`);
+			if (detail !== void 0) for (const lineText of detail.split("\n")) write(`      ${palette.dim(lineText)}`);
+		},
+		railLine,
+		/**
+		* Frame the given content lines in a brand box and write the result.
+		*
+		* @param lines - The content lines (may contain ANSI).
+		* @param minInnerWidth - Minimum inner width to pad every row to. Defaults to `0`.
+		* @example
+		* ui.box(["Local    http://localhost:4173"]);
+		*/
+		box(lines, minInnerWidth = 0) {
+			for (const lineText of box(lines, color, minInnerWidth)) write(lineText);
+		}
+	};
+}
+//#endregion
+//#region src/cli/log-sink.ts
+/** Severity rank for threshold comparison (higher = more severe). Mirrors the log plugin. */
+const LEVEL_RANK = {
+	debug: 10,
+	info: 20,
+	warn: 30,
+	error: 40
+};
+/**
+* Render an entry's optional structured `data` as a compact, dim suffix. Falls back to
+* `String(data)` when it is not JSON-serializable (e.g. a circular object).
+*
+* @param ui - The brand console (for its palette).
+* @param data - The entry's structured payload.
+* @returns A leading-space dim suffix, or `""` when there is no data.
+* @example
+* formatData(ui, { count: 12 }); // ' {"count":12}' (dim)
+*/
+function formatData(ui, data) {
+	if (data === void 0) return "";
+	let text;
+	try {
+		text = JSON.stringify(data);
+	} catch {
+		text = String(data);
+	}
+	return text === void 0 ? "" : ` ${ui.palette.dim(text)}`;
+}
+/**
+* Build a branded log {@link LogSink}: routes each entry to the matching brand line —
+* `error` → `✗` (stderr), `warn` → `⚠` (stderr), `info` → `›`, `debug` → dim — with any
+* structured `data` appended dim. Entries below `minLevel` are dropped (the in-memory
+* trace still records everything). TTY/`NO_COLOR`-aware via the brand console.
+*
+* @param minLevel - Lowest severity to print. Defaults to `"debug"` (print all).
+* @returns A {@link LogSink} that writes branded lines to stdout/stderr.
+* @example
+* ctx.log.clearSinks();
+* ctx.log.addSink(brandedSink("info")); // suppress debug spam, branded output
+*/
+function brandedSink(minLevel = "debug") {
+	const threshold = LEVEL_RANK[minLevel];
+	const ui = createBrandConsole();
+	return { 
+	/**
+	* Render one entry as a branded line matching its level (dropping entries below
+	* the threshold).
+	*
+	* @param entry - The entry to emit.
+	* @example
+	* sink.write({ level: "info", event: "deploy:done", ts: 0 });
+	*/
+write(entry) {
+		if (LEVEL_RANK[entry.level] < threshold) return;
+		const message = `${entry.event}${formatData(ui, entry.data)}`;
+		switch (entry.level) {
+			case "error":
+				ui.error(message);
+				break;
+			case "warn":
+				ui.warn(message);
+				break;
+			case "debug":
+				ui.line(`  ${ui.palette.dim(message)}`);
+				break;
+			default: ui.info(message);
+		}
+	} };
+}
+//#endregion
+//#region src/cli/prompts.ts
+/**
+* @file `@moku-labs/common/cli` — branded interactive prompts (`confirm` y/N and
+* `select` one-of-N) styled with the brand `◆` marker, the dim hint, and the cyan `›`
+* caret, so a guided flow in any Moku CLI looks the same. Built on `node:readline`; the
+* input/output streams and the choices-block sink are injectable so tests drive prompts
+* without a real TTY. Off a color TTY (CI/pipes) every prompt degrades to a plain form.
+*/
+/** Default prompt rail width — matches the brand console so hints align with other rows. */
+const DEFAULT_WIDTH = 66;
+/** Matches an explicit affirmative answer (`y`/`yes`, case-insensitive). */
+const YES_PATTERN = /^y(es)?$/i;
+/**
+* Create {@link BrandPrompts} bound to a color mode + streams. Styling matches the brand
+* console (the `◆` marker, dim hints, cyan caret); off a color TTY every prompt uses the
+* plain `question [y/N]` / `question [1-N]` form.
+*
+* @param options - Optional color/width overrides and injectable streams/sink (see
+*   {@link BrandPromptsOptions}).
+* @returns The branded prompts.
+* @example
+* const prompts = createBrandPrompts();
+* const i = await prompts.select("Workflow?", ["Auto", "Manual"]);
+*/
+function createBrandPrompts(options = {}) {
+	const color = options.color ?? supportsColor();
+	const palette = makePalette(color, options.truecolor ?? (color && supportsTruecolor()));
+	const width = options.width ?? DEFAULT_WIDTH;
+	const input = options.input ?? process.stdin;
+	const output = options.output ?? process.stdout;
+	const write = options.write ?? ((block) => console.log(block));
+	/**
+	* Build the y/N prompt string: the styled `◆ question … y / N ›` rail on a color TTY,
+	* else the plain `question [y/N] ` form.
+	*
+	* @param question - The yes/no question to display.
+	* @returns The readline prompt string.
+	* @example
+	* confirmPrompt("Deploy?");
+	*/
+	const confirmPrompt = (question) => {
+		if (!color) return `${question} [y/N] `;
+		const left = `  ${palette.pink("◆")} ${question}`;
+		const right = `${palette.dim("y / N")} ${palette.cyan("›")} `;
+		const gap = Math.max(1, width - visibleWidth(left) - visibleWidth(right));
+		return `${left}${" ".repeat(gap)}${right}`;
+	};
+	/**
+	* Build the select choices block: the styled `◆ question` head + dim-numbered rows on a
+	* color TTY, else the plain `  N) label` list.
+	*
+	* @param question - The prompt shown above the choices (styled mode only).
+	* @param choices - The selectable option labels.
+	* @returns The multi-line choices block.
+	* @example
+	* choicesBlock("Pick", ["a", "b"]);
+	*/
+	const choicesBlock = (question, choices) => {
+		if (!color) return choices.map((choice, index) => `  ${index + 1}) ${choice}`).join("\n");
+		return [`  ${palette.pink("◆")} ${question}`, ...choices.map((choice, index) => `      ${palette.dim(String(index + 1))}  ${choice}`)].join("\n");
+	};
+	/**
+	* Build the select input prompt: the dim `pick 1–N ›` hint on a color TTY, else the
+	* plain `question [1-N] ` form.
+	*
+	* @param question - The prompt (used only by the plain fallback).
+	* @param count - The number of choices.
+	* @returns The readline prompt string.
+	* @example
+	* selectPrompt("Pick", 3);
+	*/
+	const selectPrompt = (question, count) => {
+		if (!color) return `${question} [1-${count}] `;
+		return `    ${palette.dim(`pick 1–${count}`)} ${palette.cyan("›")} `;
+	};
+	return {
+		/**
+		* Ask a yes/no question; resolves `true` only on an explicit `y`/`yes`.
+		*
+		* @param question - The yes/no question to display.
+		* @returns Resolves `true` when the user answered yes.
+		* @example
+		* await prompts.confirm("Deploy?");
+		*/
+		confirm(question) {
+			return new Promise((resolve) => {
+				const readline = createInterface({
+					input,
+					output
+				});
+				readline.question(confirmPrompt(question), (answer) => {
+					readline.close();
+					resolve(YES_PATTERN.test(answer.trim()));
+				});
+			});
+		},
+		/**
+		* Present `choices` numbered from 1 and resolve the chosen zero-based index.
+		*
+		* @param question - The prompt to display.
+		* @param choices - The selectable option labels.
+		* @returns Resolves the chosen zero-based index (`0` for empty/out-of-range).
+		* @example
+		* await prompts.select("Pick", ["a", "b"]);
+		*/
+		select(question, choices) {
+			return new Promise((resolve) => {
+				const readline = createInterface({
+					input,
+					output
+				});
+				write(choicesBlock(question, choices));
+				readline.question(selectPrompt(question, choices.length), (answer) => {
+					readline.close();
+					const picked = Number.parseInt(answer.trim(), 10);
+					resolve(Number.isInteger(picked) && picked >= 1 && picked <= choices.length ? picked - 1 : 0);
+				});
+			});
+		}
+	};
+}
+//#endregion
+export { ANSI, BRAND_PINK, CLEAR_BELOW, CLEAR_LINE, SPINNER_FRAMES, box, boxGlyphs, brandedSink, createBrandConsole, createBrandPrompts, cursorUp, fg24, makePalette, spinnerFrameAt, supportsColor, supportsTruecolor, visibleWidth };

package/dist/index.cjs

@@ -406,6 +406,19 @@ function createLogApi(ctx) {
 		*/
 		reset() {
 			state.entries.length = 0;
+		},
+		/**
+		* Remove all registered output sinks; the in-memory trace (`entries`) is
+		* unaffected, so `trace()`/`expect()` keep working.
+		*
+		* @example
+		* ```ts
+		* log.clearSinks();
+		* log.addSink(brandedSink()); // from @moku-labs/common/cli
+		* ```
+		*/
+		clearSinks() {
+			state.sinks.length = 0;
 		}
 	};
 }

package/dist/index.d.cts

@@ -137,6 +137,12 @@ type LogApi = {
    */
   addSink(sink: LogSink): void; /** Clear all recorded entries while keeping registered sinks. */
   reset(): void;
+  /**
+   * Remove all registered output sinks. The in-memory trace (`entries`) is
+   * unaffected, so `trace()`/`expect()` keep working — used to replace the default
+   * console sink (e.g. a CLI plugin swapping in a branded sink from `@moku-labs/common/cli`).
+   */
+  clearSinks(): void;
 };
 //#endregion
 //#region src/plugins/log/index.d.ts
@@ -383,4 +389,4 @@ declare function processEnv(): EnvProvider;
  */
 declare function cloudflareBindings(): EnvProvider;
 //#endregion
-export { types_d_exports as Env, types_d_exports$1 as Log, browserEnv, cloudflareBindings, dotenv, envPlugin, logPlugin, processEnv };
+export { types_d_exports as Env, type EnvApi, type EnvConfig, type EnvProvider, type EnvState, type EnvVarSpec, type ExpectChain, types_d_exports$1 as Log, type LogApi, type LogConfig, type LogEntry, type LogLevel, type LogSink, type LogState, browserEnv, cloudflareBindings, dotenv, envPlugin, logPlugin, processEnv };