@moku-labs/common 0.1.1 → 0.2.1

package/dist/cli.d.cts

@@ -0,0 +1,517 @@
+//#region src/cli/ansi.d.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.
+ */
+/** ANSI SGR codes used by the brand renderer (each prefixed with the ESC byte). */
+declare const ANSI: {
+  readonly reset: `${string}[0m`;
+  readonly bold: `${string}[1m`;
+  readonly dim: `${string}[2m`;
+  readonly red: `${string}[31m`;
+  readonly green: `${string}[32m`;
+  readonly yellow: `${string}[33m`;
+  readonly blue: `${string}[34m`;
+  readonly magenta: `${string}[35m`;
+  readonly cyan: `${string}[36m`;
+  readonly gray: `${string}[90m`;
+};
+/** A single ANSI color code from {@link ANSI}. */
+type AnsiCode = (typeof ANSI)[keyof typeof ANSI];
+/**
+ * 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.
+ */
+declare const BRAND_PINK: {
+  readonly r: 255;
+  readonly g: 30;
+  readonly 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"
+ */
+declare function fg24(r: number, g: number, b: number): string;
+/** ANSI: erase the entire current line, leaving the cursor where it is. */
+declare const CLEAR_LINE: string;
+/** ANSI: erase from the cursor to the end of the screen (drops stale trailing rows). */
+declare const CLEAR_BELOW: string;
+/**
+ * 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.
+ */
+declare const SPINNER_FRAMES: readonly ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+/**
+ * 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"
+ */
+declare function cursorUp(n: number): string;
+/**
+ * Box-drawing glyphs used to frame panels (Unicode on a TTY, ASCII fallback off it).
+ *
+ * @example
+ * const glyphs = boxGlyphs(true);
+ */
+type BoxGlyphs = {
+  /** Top-left corner. */topLeft: string; /** Top-right corner. */
+  topRight: string; /** Bottom-left corner. */
+  bottomLeft: string; /** Bottom-right corner. */
+  bottomRight: string; /** Horizontal edge. */
+  horizontal: string; /** Vertical edge. */
+  vertical: string;
+};
+/**
+ * The minimal stream shape {@link supportsColor} probes — just the `isTTY` flag.
+ *
+ * @example
+ * const stream: ColorStream = { isTTY: true };
+ */
+type ColorStream = {
+  /** Whether the stream is a TTY (color-capable). */isTTY?: boolean;
+};
+/**
+ * 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
+ */
+declare function supportsColor(stream?: ColorStream, noColor?: string | undefined): boolean;
+/**
+ * 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
+ */
+declare function supportsTruecolor(colorTerm?: string | undefined): boolean;
+/**
+ * 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)
+ */
+declare function spinnerFrameAt(elapsedMs: number, frameMs?: number): string;
+/**
+ * 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());
+ */
+declare function boxGlyphs(color: boolean): BoxGlyphs;
+/**
+ * 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
+ */
+declare function visibleWidth(text: string): number;
+/**
+ * A color palette bound to a fixed color mode. `paint` wraps text in an ANSI code
+ * when enabled (no-op in plain mode); the named accessors are thin sugar over it.
+ *
+ * @example
+ * const palette = makePalette(true);
+ * palette.green("ok");
+ */
+type Palette = {
+  /** Whether this palette emits color. */readonly enabled: boolean;
+  /**
+   * Wrap text in the given ANSI code (returns it unchanged in plain mode).
+   *
+   * @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: AnsiCode, text: string): string;
+  /**
+   * 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: string): string;
+  /**
+   * 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: string): string;
+  /**
+   * 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: string): string;
+  /**
+   * 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: string): string;
+  /**
+   * 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: string): string;
+  /**
+   * 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: string): string;
+  /**
+   * Color the given text the Moku brand pink — exact `#FF1E6F` (24-bit) when truecolor
+   * is enabled, else the 16-color `magenta` approximation, else unchanged (plain mode).
+   * The brand accent for the cube mark, the lockup wordmark, the filled progress bar,
+   * and hero numbers.
+   *
+   * @param text - The text to colorize.
+   * @returns The pink (or unchanged) text.
+   * @example
+   * palette.pink("▟▙ moku web");
+   */
+  pink(text: string): string;
+};
+/**
+ * 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");
+ */
+declare function makePalette(color: boolean, truecolor?: boolean): Palette;
+/**
+ * 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);
+ */
+declare function box(lines: string[], color: boolean, minInnerWidth?: number): string[];
+//#endregion
+//#region src/cli/console.d.ts
+/**
+ * Options for {@link createBrandConsole}. All optional: the defaults wire the console to
+ * `console.log`/`console.error` with auto-detected color/truecolor, while tests inject a
+ * capturing sink and force `color: false` for deterministic plain output.
+ *
+ * @example
+ * const lines: string[] = [];
+ * const ui = createBrandConsole({ write: line => lines.push(line), color: false });
+ */
+type BrandConsoleOptions = {
+  /** Sink for normal (stdout) lines. Defaults to `console.log`. */write?: (line: string) => void; /** Sink for warning/error (stderr) lines. Defaults to `console.error`. */
+  writeError?: (line: string) => void; /** Force color on/off. Defaults to `supportsColor()` (TTY + `NO_COLOR` unset). */
+  color?: boolean; /** Force 24-bit truecolor on/off. Defaults to `supportsTruecolor()` (`COLORTERM`). */
+  truecolor?: boolean; /** Total visible width the lockup rule spans / `railLine` aligns to. Defaults to `66`. */
+  width?: number;
+};
+/**
+ * The fields of the `▟▙ moku <name>` lockup banner. Every part is optional except the
+ * wordmark, so a one-off tool can print just `▟▙ moku tool` while a framework adds a
+ * per-command label, a version (right-aligned) and a runtime-facts line beneath the rule.
+ *
+ * @example
+ * ui.lockup({ wordmark: "moku worker", label: "deploy", version: "v1.2.0" });
+ */
+type LockupOptions = {
+  /** The product wordmark shown in bold brand pink (e.g. `moku web`). */wordmark: string; /** Optional dim per-command/context label shown beside the wordmark (e.g. `serve · dev`). */
+  label?: string; /** Optional dim version string right-aligned on the lockup line (e.g. `v1.2.0`). */
+  version?: string; /** Optional dim facts line shown beneath the rule (e.g. `node 24.3.0 · darwin arm64`). */
+  facts?: string;
+};
+/**
+ * The branded console surface: the shared brand vocabulary plus the `palette` and the
+ * `railLine`/`box` builders a project composes its own panels from.
+ *
+ * @example
+ * const ui = createBrandConsole();
+ * ui.lockup({ wordmark: "moku tool" });
+ * ui.info("ready");
+ */
+type BrandConsole = {
+  /** The bound color palette (the same one the lines are rendered with). */readonly palette: Palette; /** Whether this console emits color/Unicode. */
+  readonly color: boolean; /** The lockup/rail width this console aligns to. */
+  readonly width: number;
+  /**
+   * Write a pre-rendered line verbatim through the stdout sink.
+   *
+   * @param text - The line to write (defaults to an empty line).
+   * @returns Nothing.
+   * @example
+   * ui.line("  custom row");
+   */
+  line(text?: string): void;
+  /**
+   * Render the `▟▙ <wordmark>` lockup: the cube + bold-pink wordmark and an optional dim
+   * label on the left with the version right-aligned, a dim hairline rule, and an optional
+   * dim facts line beneath it. The cube/rule degrade to ASCII (`*`/`-`) off a TTY.
+   *
+   * @param options - The lockup fields (see {@link LockupOptions}).
+   * @returns Nothing.
+   * @example
+   * ui.lockup({ wordmark: "moku web", label: "build", version: "v1.2.0" });
+   */
+  lockup(options: LockupOptions): void;
+  /**
+   * Render a section heading: a blank line followed by a bold brand-pink label.
+   *
+   * @param text - The heading label.
+   * @returns Nothing.
+   * @example
+   * ui.heading("Diagnostics");
+   */
+  heading(text: string): void;
+  /**
+   * Render a neutral informational line (`› message`). Continuation lines (after a `\n`)
+   * are indented under the first.
+   *
+   * @param message - The line to print.
+   * @returns Nothing.
+   * @example
+   * ui.info("watching for changes…");
+   */
+  info(message: string): void;
+  /**
+   * Render a warning line (`⚠ message`, written to stderr).
+   *
+   * @param message - The warning to print.
+   * @returns Nothing.
+   * @example
+   * ui.warn("deploy skipped");
+   */
+  warn(message: string): void;
+  /**
+   * Render an error line (`✗ message`, written to stderr), optionally with a cause printed
+   * beneath it.
+   *
+   * @param message - The error summary to print.
+   * @param cause - Optional underlying error/value to print beneath the summary.
+   * @returns Nothing.
+   * @example
+   * ui.error("build failed", err);
+   */
+  error(message: string, cause?: unknown): void;
+  /**
+   * Render one diagnostic line: a green `✓` (pass) or red `✗` (fail) + label, with optional
+   * dim, indented detail beneath (e.g. a fix hint for a failing check).
+   *
+   * @param ok - Whether the check passed.
+   * @param label - The check label.
+   * @param detail - Optional multi-line guidance shown indented under the line.
+   * @returns Nothing.
+   * @example
+   * ui.check(false, "API_TOKEN is set", "Create one at …");
+   */
+  check(ok: boolean, label: string, detail?: string): void;
+  /**
+   * Right-align `right` against `left` within `width`, measuring visible width so embedded
+   * ANSI never throws the alignment off. The building block for custom rail/panel rows.
+   *
+   * @param left - The left segment (may contain ANSI).
+   * @param right - The right segment (may contain ANSI).
+   * @param width - Total visible width to fill (defaults to the console width).
+   * @returns The padded line.
+   * @example
+   * ui.railLine("  ✓ pages", "· 12ms");
+   */
+  railLine(left: string, right: string, width?: number): string;
+  /**
+   * Frame the given content lines in a brand box and write the result. Unicode borders on
+   * a TTY, ASCII off it; padded to the widest line or `minInnerWidth`.
+   *
+   * @param lines - The content lines (may contain ANSI).
+   * @param minInnerWidth - Minimum inner width to pad every row to. Defaults to `0`.
+   * @returns Nothing.
+   * @example
+   * ui.box(["Local    http://localhost:4173"]);
+   */
+  box(lines: string[], minInnerWidth?: number): void;
+};
+/**
+ * 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");
+ */
+declare function createBrandConsole(options?: BrandConsoleOptions): BrandConsole;
+//#endregion
+//#region src/plugins/log/types.d.ts
+/** Severity level for a log entry. */
+type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * A single recorded log entry.
+ */
+type LogEntry = {
+  /** Severity level. */level: LogLevel; /** Event identifier (free-form string; convention: `domain:action`). */
+  event: string; /** Optional structured payload associated with the event. */
+  data?: unknown; /** Capture timestamp in epoch milliseconds (`Date.now()` at append time). */
+  ts: number; /** Optional originating plugin name. Reserved for future enrichment. */
+  plugin?: string;
+};
+/**
+ * Pluggable output target. Implement this to add console/file/JSON/etc. sinks
+ * WITHOUT changing the log API. Each logged entry is passed to `write` once,
+ * in registration order.
+ */
+type LogSink = {
+  /**
+   * Write a single entry to this sink.
+   *
+   * @param entry - The entry to emit.
+   */
+  write(entry: LogEntry): void;
+};
+//#endregion
+//#region src/cli/log-sink.d.ts
+/**
+ * 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
+ */
+declare function brandedSink(minLevel?: LogLevel): LogSink;
+//#endregion
+//#region src/cli/prompts.d.ts
+/**
+ * Options for {@link createBrandPrompts}. All optional: the defaults read `process.stdin`
+ * and write to stdout with auto-detected color, while tests inject streams + a capturing
+ * choices-block sink.
+ *
+ * @example
+ * const prompts = createBrandPrompts({ color: false });
+ */
+type BrandPromptsOptions = {
+  /** Force color on/off. Defaults to `supportsColor()` (TTY + `NO_COLOR` unset). */color?: boolean; /** Force 24-bit truecolor on/off. Defaults to `supportsTruecolor()` (`COLORTERM`). */
+  truecolor?: boolean; /** Prompt rail width the styled hint right-aligns to. Defaults to `66`. */
+  width?: number; /** Readable stream the answer is read from. Defaults to `process.stdin`. */
+  input?: NodeJS.ReadableStream; /** Writable stream readline echoes to. Defaults to `process.stdout`. */
+  output?: NodeJS.WritableStream; /** Sink for the multi-line `select` choices block. Defaults to `console.log`. */
+  write?: (block: string) => void;
+};
+/**
+ * The branded prompts surface: a y/N {@link BrandPrompts.confirm} and a one-of-N
+ * {@link BrandPrompts.select}.
+ *
+ * @example
+ * const prompts = createBrandPrompts();
+ * if (await prompts.confirm("Deploy?")) deploy();
+ */
+type BrandPrompts = {
+  /**
+   * Ask a yes/no question; resolves `true` only on an explicit `y`/`yes` (default `No`).
+   *
+   * @param question - The yes/no question to display.
+   * @returns Resolves `true` when the user answered yes.
+   * @example
+   * await prompts.confirm("Deploy dist/ to Cloudflare Pages?");
+   */
+  confirm(question: string): Promise<boolean>;
+  /**
+   * Present `choices` numbered from 1 and resolve the chosen zero-based index (empty or
+   * out-of-range falls back to `0`).
+   *
+   * @param question - The prompt to display.
+   * @param choices - The selectable option labels.
+   * @returns Resolves the chosen zero-based index.
+   * @example
+   * await prompts.select("Trigger?", ["Auto on push", "Manual only"]);
+   */
+  select(question: string, choices: readonly string[]): Promise<number>;
+};
+/**
+ * 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"]);
+ */
+declare function createBrandPrompts(options?: BrandPromptsOptions): BrandPrompts;
+//#endregion
+export { ANSI, type AnsiCode, BRAND_PINK, type BoxGlyphs, type BrandConsole, type BrandConsoleOptions, type BrandPrompts, type BrandPromptsOptions, CLEAR_BELOW, CLEAR_LINE, type ColorStream, type LockupOptions, type Palette, SPINNER_FRAMES, box, boxGlyphs, brandedSink, createBrandConsole, createBrandPrompts, cursorUp, fg24, makePalette, spinnerFrameAt, supportsColor, supportsTruecolor, visibleWidth };