@shaferllc/keel 0.68.0 → 0.74.0

package/dist/core/console-ui.js

@@ -0,0 +1,187 @@
+/**
+ * Terminal UI for console commands — colors, a logger, tables, boxes, and a task
+ * runner. No dependency: ANSI codes are a dozen escape sequences, not a package.
+ *
+ *   ui.success("Migrated 3 tables");
+ *   ui.table(["Name", "Rows"]).row(["users", "42"]).render();
+ *
+ * Everything goes through the same `write`, which is what makes the whole thing
+ * testable: `createUi({ raw: true })` strips the colors and buffers the output
+ * instead of printing it, so a test can assert on exactly what a command said.
+ */
+/* -------------------------------- colors ---------------------------------- */
+const CODES = {
+    reset: 0,
+    bold: 1,
+    dim: 2,
+    italic: 3,
+    underline: 4,
+    red: 31,
+    green: 32,
+    yellow: 33,
+    blue: 34,
+    magenta: 35,
+    cyan: 36,
+    white: 37,
+    gray: 90,
+    bgRed: 41,
+    bgGreen: 42,
+    bgYellow: 43,
+};
+function makeColors(enabled) {
+    const fn = ((name, text) => enabled ? `\u001b[${CODES[name]}m${text}\u001b[0m` : text);
+    fn.enabled = enabled;
+    return fn;
+}
+/** Strip ANSI escapes — used by the raw mode, and handy in assertions. */
+export function stripAnsi(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/\u001b\[\d+m/g, "");
+}
+const SYMBOLS = {
+    info: "›",
+    success: "✔",
+    warning: "⚠",
+    error: "✖",
+    debug: "·",
+};
+export function createUi(options = {}) {
+    const raw = options.raw ?? false;
+    const useColors = options.colors ?? (!raw && !process.env.NO_COLOR);
+    const colors = makeColors(useColors);
+    const logs = [];
+    const errors = [];
+    const write = (line) => {
+        if (raw)
+            logs.push(stripAnsi(line));
+        else
+            console.log(line);
+    };
+    const writeError = (line) => {
+        if (raw)
+            errors.push(stripAnsi(line));
+        else
+            console.error(line);
+    };
+    const label = (symbol, color, message) => `${colors(color, symbol)} ${message}`;
+    const ui = {
+        colors,
+        logs,
+        errors,
+        write,
+        debug: (message) => write(label(SYMBOLS.debug, "gray", colors("gray", message))),
+        info: (message) => write(label(SYMBOLS.info, "blue", message)),
+        success: (message) => write(label(SYMBOLS.success, "green", message)),
+        warning: (message) => write(label(SYMBOLS.warning, "yellow", message)),
+        error: (message) => writeError(label(SYMBOLS.error, "red", message)),
+        fatal: (message) => writeError(label(SYMBOLS.error, "red", colors("bold", message))),
+        action(verb, target, status = "done") {
+            const color = status === "failed" ? "red" : status === "skipped" ? "yellow" : "green";
+            const line = `${colors(color, verb.toUpperCase().padEnd(8))}${target}`;
+            if (status === "failed")
+                writeError(line);
+            else
+                write(line);
+        },
+        table(head) {
+            const headers = head ? [...head] : [];
+            const body = [];
+            const table = {
+                head(...columns) {
+                    headers.length = 0;
+                    headers.push(...columns);
+                    return table;
+                },
+                row(cells) {
+                    body.push(cells);
+                    return table;
+                },
+                rows(list) {
+                    body.push(...list);
+                    return table;
+                },
+                toString() {
+                    const all = headers.length ? [headers, ...body] : body;
+                    if (!all.length)
+                        return "";
+                    const columns = Math.max(...all.map((r) => r.length));
+                    const widths = Array.from({ length: columns }, (_, i) => Math.max(...all.map((row) => stripAnsi(row[i] ?? "").length)));
+                    const line = (cells) => cells
+                        .map((cell, i) => cell + " ".repeat(Math.max(0, widths[i] - stripAnsi(cell).length)))
+                        .join("  ")
+                        .trimEnd();
+                    const out = [];
+                    if (headers.length) {
+                        out.push(line(headers.map((h) => colors("bold", h))));
+                        out.push(widths.map((w) => "─".repeat(w)).join("  "));
+                    }
+                    for (const row of body)
+                        out.push(line(row));
+                    return out.join("\n");
+                },
+                render() {
+                    const text = table.toString();
+                    if (text)
+                        write(text);
+                },
+            };
+            return table;
+        },
+        sticker(lines, title) {
+            const content = title ? [colors("bold", title), "", ...lines] : [...lines];
+            const width = Math.max(...content.map((l) => stripAnsi(l).length));
+            write(`┌─${"─".repeat(width)}─┐`);
+            for (const line of content) {
+                const pad = " ".repeat(width - stripAnsi(line).length);
+                write(`│ ${line}${pad} │`);
+            }
+            write(`└─${"─".repeat(width)}─┘`);
+        },
+        instructions(lines, title) {
+            if (title)
+                write(colors("bold", title));
+            lines.forEach((line, i) => write(`  ${colors("gray", `${i + 1}.`)} ${line}`));
+        },
+        tasks() {
+            const queue = [];
+            const runner = {
+                add(title, run) {
+                    queue.push({ title, run });
+                    return runner;
+                },
+                async run() {
+                    let ok = true;
+                    for (const { title, run } of queue) {
+                        let note = "";
+                        const handle = {
+                            update: (message) => {
+                                note = message;
+                            },
+                        };
+                        const started = Date.now();
+                        try {
+                            const result = await run(handle);
+                            const detail = result || note;
+                            const ms = Date.now() - started;
+                            ui.write(`${colors("green", SYMBOLS.success)} ${title}${detail ? ` ${colors("gray", `— ${detail}`)}` : ""} ${colors("gray", `(${ms}ms)`)}`);
+                        }
+                        catch (error) {
+                            ok = false;
+                            // Stop at the first failure: the tasks after it almost certainly
+                            // depend on it, and a cascade of red tells you nothing new.
+                            ui.error(`${title} — ${error instanceof Error ? error.message : String(error)}`);
+                            break;
+                        }
+                    }
+                    return ok;
+                },
+            };
+            return runner;
+        },
+        clear() {
+            logs.length = 0;
+            errors.length = 0;
+        },
+    };
+    return ui;
+}

package/dist/core/console.d.ts

@@ -0,0 +1,188 @@
+/**
+ * The console — a real command system, not a wrapper round `process.argv`.
+ *
+ *   export const greet = defineCommand({
+ *     name: "greet",
+ *     description: "Greet someone",
+ *     args: { name: arg.string({ description: "who to greet" }) },
+ *     flags: { loud: flag.boolean({ alias: "l", description: "SHOUT IT" }) },
+ *
+ *     async run({ args, flags, ui }) {
+ *       const message = `Hello, ${args.name}!`;
+ *       ui.success(flags.loud ? message.toUpperCase() : message);
+ *     },
+ *   });
+ *
+ * `args.name` is a `string` and `flags.loud` is a `boolean` — **inferred from the
+ * spec**, not cast. Declare an arg optional and its type becomes `string |
+ * undefined`; give it a default and it's a `string` again. The types can't drift
+ * from the parsing, because the parsing is generated from them.
+ *
+ * A command gets a `ui` (colors, tables, tasks, spinners) and a `prompt` (ask,
+ * confirm, choice…), both of which switch to a captured, colorless "raw" mode
+ * under test, so you can assert on what a command printed and script its answers.
+ */
+import type { Ui } from "./console-ui.js";
+import type { Prompt } from "./console-prompt.js";
+export type ArgType = "string" | "number" | "spread";
+export type FlagType = "string" | "number" | "boolean" | "array";
+export interface ArgSpec<T = unknown> {
+    readonly kind: "arg";
+    readonly type: ArgType;
+    readonly description?: string;
+    readonly required: boolean;
+    readonly default?: T;
+    readonly parse?: (raw: string) => T;
+    /** @internal — carries the value type. */
+    readonly __value?: T;
+}
+export interface FlagSpec<T = unknown> {
+    readonly kind: "flag";
+    readonly type: FlagType;
+    readonly description?: string;
+    readonly required: boolean;
+    readonly default?: T;
+    /** A single-character shorthand: `-f`. */
+    readonly alias?: string;
+    readonly parse?: (raw: string) => T;
+    /** @internal — carries the value type. */
+    readonly __value?: T;
+}
+interface BaseOptions {
+    description?: string;
+}
+interface ArgOptions<T> extends BaseOptions {
+    /** Args are required by default. */
+    required?: boolean;
+    default?: T;
+    parse?: (raw: string) => T;
+}
+interface FlagOptions<T> extends BaseOptions {
+    /** Flags are optional by default. */
+    required?: boolean;
+    default?: T;
+    alias?: string;
+    parse?: (raw: string) => T;
+}
+/**
+ * Whether a spec's value can be absent. Required, or defaulted, means present —
+ * which is exactly what makes `args.name` a `string` rather than a
+ * `string | undefined` you have to keep checking.
+ */
+type Present<O, Fallback extends boolean> = O extends {
+    required: true;
+} ? true : O extends {
+    default: unknown;
+} ? true : O extends {
+    required: false;
+} ? false : Fallback;
+type ArgValue<O, T> = Present<O, true> extends true ? T : T | undefined;
+type FlagValue<O, T> = Present<O, false> extends true ? T : T | undefined;
+/** Positional arguments: `keel greet <name>`. */
+export declare const arg: {
+    string<const O extends ArgOptions<string> = Record<never, never>>(options?: O): ArgSpec<ArgValue<O, string>>;
+    number<const O extends ArgOptions<number> = Record<never, never>>(options?: O): ArgSpec<ArgValue<O, number>>;
+    /** Swallows every remaining value. Must be the last argument. */
+    spread<const O extends ArgOptions<string[]> = Record<never, never>>(options?: O): ArgSpec<ArgValue<O, string[]>>;
+};
+/** Named options: `--force`, `-f`, `--name=Ada`. */
+export declare const flag: {
+    /** `--force` / `-f`, and `--no-force`. Defaults to `false`, so it's never undefined. */
+    boolean<const O extends FlagOptions<boolean> = Record<never, never>>(options?: O): FlagSpec<boolean>;
+    string<const O extends FlagOptions<string> = Record<never, never>>(options?: O): FlagSpec<FlagValue<O, string>>;
+    number<const O extends FlagOptions<number> = Record<never, never>>(options?: O): FlagSpec<FlagValue<O, number>>;
+    /** Repeatable: `--tag a --tag b` gives `["a", "b"]`. Defaults to `[]`. */
+    array<const O extends FlagOptions<string[]> = Record<never, never>>(options?: O): FlagSpec<string[]>;
+};
+export type ArgsSpec = Record<string, ArgSpec<unknown>>;
+export type FlagsSpec = Record<string, FlagSpec<unknown>>;
+/** The values a spec produces — this is where `args.name: string` comes from. */
+export type Values<S extends Record<string, {
+    __value?: unknown;
+}>> = {
+    [K in keyof S]: S[K] extends {
+        __value?: infer V;
+    } ? V : never;
+};
+/** What a command's `run` receives. */
+export interface CommandContext<A extends ArgsSpec, F extends FlagsSpec> {
+    args: Values<A>;
+    flags: Values<F>;
+    /** Everything after `--`, plus any unrecognized flags. */
+    rest: string[];
+    ui: Ui;
+    prompt: Prompt;
+    /** The kernel running this command — for `keel help`, or calling a sibling. */
+    kernel: ConsoleKernel;
+}
+export interface CommandDefinition<A extends ArgsSpec = ArgsSpec, F extends FlagsSpec = FlagsSpec> {
+    /** What the user types. `:` namespaces it — `make:controller`. */
+    name: string;
+    description?: string;
+    /** Extra lines shown under `keel help <name>`. */
+    help?: string[];
+    /** Other names this command answers to. */
+    aliases?: string[];
+    args?: A;
+    flags?: F;
+    /** Don't fail on flags you didn't declare — they land in `rest`. */
+    allowUnknownFlags?: boolean;
+    /** Return a number to set the exit code. Throwing sets it to 1. */
+    run(context: CommandContext<A, F>): void | number | Promise<void | number>;
+}
+/** Any command, whatever its arg/flag types — what the kernel stores. */
+export type AnyCommand = CommandDefinition<ArgsSpec, FlagsSpec>;
+/**
+ * Define a command. The `args` and `flags` you declare become the types of
+ * `args` and `flags` inside `run` — the whole point of the exercise.
+ */
+export declare function defineCommand<A extends ArgsSpec = Record<never, never>, F extends FlagsSpec = Record<never, never>>(definition: CommandDefinition<A, F>): CommandDefinition<A, F>;
+/** Thrown when the argv doesn't fit the command's spec. */
+export declare class ConsoleError extends Error {
+    constructor(message: string);
+}
+export interface Parsed {
+    args: Record<string, unknown>;
+    flags: Record<string, unknown>;
+    rest: string[];
+}
+/**
+ * Turn argv into a command's args and flags.
+ *
+ * Handles `--flag value`, `--flag=value`, `--no-flag`, `-f value`, bundled short
+ * flags (`-abc`), repeatable array flags, a `--` terminator, and a trailing
+ * spread argument.
+ */
+export declare function parseArgv(argv: string[], definition: AnyCommand): Parsed;
+export interface ConsoleKernelOptions {
+    /** The binary's name, shown in help. Default: `"keel"`. */
+    binary?: string;
+    ui?: Ui;
+    prompt?: Prompt;
+}
+/** Registers commands, parses argv, and runs the right one. */
+export declare class ConsoleKernel {
+    private options;
+    private commands;
+    private aliases;
+    constructor(options?: ConsoleKernelOptions);
+    get binary(): string;
+    /** Register one or more commands. */
+    register(...commands: AnyCommand[]): this;
+    /** Every registered command, sorted by name. */
+    list(): AnyCommand[];
+    find(name: string): AnyCommand | undefined;
+    private ui;
+    private prompt;
+    /**
+     * Run a command from argv (without the node/script prefix). Returns the exit
+     * code: 0 for success, 1 for a failure — never throws, because a console is a
+     * bad place to surface a stack trace to a user who mistyped a flag.
+     */
+    run(argv: string[]): Promise<number>;
+    /** The `keel help` screen: every command, grouped by namespace. */
+    help(): string;
+    /** The help screen for a single command: its usage, args, and flags. */
+    commandHelp(command: AnyCommand): string;
+}
+export {};