@mudah-cli/console 0.1.0

package/dist/command.d.ts

@@ -0,0 +1,53 @@
+import { UsageError, type Application } from '@mudah-cli/core';
+import type { Output } from '@mudah-cli/ui';
+import { Prompts } from './prompts.js';
+import { type ParsedInput, type ParsedSignature } from './signature.js';
+/**
+ * Base class for all Mudah commands.
+ *
+ * ```ts
+ * class Greet extends Command {
+ *   signature = 'greet {name?} [--shout]';
+ *   description = 'Say hello.';
+ *
+ *   async handle() {
+ *     this.output.success(`Hello, ${this.arg('name') ?? 'world'}!`);
+ *   }
+ * }
+ * ```
+ *
+ * The kernel injects `app`, `output`, and `input` before calling
+ * `handle()`, which returns the process exit code (void = 0).
+ */
+export declare abstract class Command {
+    /** Signature string: `name {arg?} [--flag=]`. */
+    signature: string;
+    /** One-line description for help output. */
+    description: string;
+    /** The application (container, config, events). */
+    app: Application;
+    /** Styled output for the user. */
+    output: Output;
+    /** Parsed positional args and options. */
+    input: ParsedInput;
+    private prompts;
+    protected parsedSignature(): ParsedSignature;
+    /** The kernel sets this before `handle()`. */
+    __inject(app: Application, output: Output, input: ParsedInput): void;
+    /** Abstract entry point. Return an exit code, or void for 0. */
+    abstract handle(): Promise<number | void> | number | void;
+    /** A positional argument value (or its signature default). */
+    arg(name: string): string | undefined;
+    /** An option value: boolean for flags, string for `--opt=value`. */
+    option<T extends string | boolean>(name: string): T | undefined;
+    protected promptsInstance(): Prompts;
+    protected ask(question: string, defaultValue?: string): Promise<string>;
+    protected confirm(question: string, defaultValue?: boolean): Promise<boolean>;
+    protected select(question: string, choices: string[]): Promise<string>;
+    /**
+     * Render a usage error with this command's usage line. Commands call this
+     * when their own validation fails.
+     */
+    protected usageError(message: string, hint?: string): UsageError;
+}
+export { parseInput, parseSignature, ArgumentParseError, type ParsedInput, type ParsedSignature } from './signature.js';

package/dist/command.js

@@ -0,0 +1,76 @@
+import { UsageError } from '@mudah-cli/core';
+import { Prompts } from './prompts.js';
+import { parseInput, parseSignature } from './signature.js';
+/**
+ * Base class for all Mudah commands.
+ *
+ * ```ts
+ * class Greet extends Command {
+ *   signature = 'greet {name?} [--shout]';
+ *   description = 'Say hello.';
+ *
+ *   async handle() {
+ *     this.output.success(`Hello, ${this.arg('name') ?? 'world'}!`);
+ *   }
+ * }
+ * ```
+ *
+ * The kernel injects `app`, `output`, and `input` before calling
+ * `handle()`, which returns the process exit code (void = 0).
+ */
+export class Command {
+    /** Signature string: `name {arg?} [--flag=]`. */
+    signature = '';
+    /** One-line description for help output. */
+    description = '';
+    /** The application (container, config, events). */
+    app;
+    /** Styled output for the user. */
+    output;
+    /** Parsed positional args and options. */
+    input;
+    prompts = null;
+    parsedSignature() {
+        return parseSignature(this.signature);
+    }
+    /** The kernel sets this before `handle()`. */
+    __inject(app, output, input) {
+        this.app = app;
+        this.output = output;
+        this.input = input;
+    }
+    /** A positional argument value (or its signature default). */
+    arg(name) {
+        return this.input.args[name];
+    }
+    /** An option value: boolean for flags, string for `--opt=value`. */
+    option(name) {
+        return this.input.options[name];
+    }
+    promptsInstance() {
+        if (!this.prompts)
+            this.prompts = new Prompts();
+        return this.prompts;
+    }
+    ask(question, defaultValue) {
+        return this.promptsInstance().ask(question, { defaultValue });
+    }
+    confirm(question, defaultValue) {
+        return this.promptsInstance().confirm(question, { defaultValue });
+    }
+    select(question, choices) {
+        return this.promptsInstance().select(question, choices);
+    }
+    /**
+     * Render a usage error with this command's usage line. Commands call this
+     * when their own validation fails.
+     */
+    usageError(message, hint) {
+        return new UsageError(message, {
+            hint,
+            usage: this.signature,
+        });
+    }
+}
+export { parseInput, parseSignature, ArgumentParseError } from './signature.js';
+//# sourceMappingURL=command.js.map

package/dist/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAoB,MAAM,iBAAiB,CAAC;AAE/D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,cAAc,EAA0C,MAAM,gBAAgB,CAAC;AAEpG;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAgB,OAAO;IAC3B,iDAAiD;IACjD,SAAS,GAAG,EAAE,CAAC;IAEf,4CAA4C;IAC5C,WAAW,GAAG,EAAE,CAAC;IAEjB,mDAAmD;IACnD,GAAG,CAAe;IAClB,kCAAkC;IAClC,MAAM,CAAU;IAChB,0CAA0C;IAC1C,KAAK,CAAe;IAEZ,OAAO,GAAmB,IAAI,CAAC;IAE7B,eAAe;QACvB,OAAO,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACxC,CAAC;IAED,8CAA8C;IAC9C,QAAQ,CAAC,GAAgB,EAAE,MAAc,EAAE,KAAkB;QAC3D,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAKD,8DAA8D;IAC9D,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,oEAAoE;IACpE,MAAM,CAA6B,IAAY;QAC7C,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAkB,CAAC;IACnD,CAAC;IAES,eAAe;QACvB,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;QAChD,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAES,GAAG,CAAC,QAAgB,EAAE,YAAqB;QACnD,OAAO,IAAI,CAAC,eAAe,EAAE,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC;IAChE,CAAC;IAES,OAAO,CAAC,QAAgB,EAAE,YAAsB;QACxD,OAAO,IAAI,CAAC,eAAe,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC;IACpE,CAAC;IAES,MAAM,CAAC,QAAgB,EAAE,OAAiB;QAClD,OAAO,IAAI,CAAC,eAAe,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC1D,CAAC;IAED;;;OAGG;IACO,UAAU,CAAC,OAAe,EAAE,IAAa;QACjD,OAAO,IAAI,UAAU,CAAC,OAAO,EAAE;YAC7B,IAAI;YACJ,KAAK,EAAE,IAAI,CAAC,SAAS;SACtB,CAAC,CAAC;IACL,CAAC;CACF;AAED,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,kBAAkB,EAA0C,MAAM,gBAAgB,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+import type { Output } from '@mudah-cli/ui';
+/**
+ * Render a thrown error through the styled output and return the process
+ * exit code it maps to. Shared by the `@mudah-cli/mudah` umbrella and the test harness
+ * so both render failures identically.
+ */
+export declare function renderError(error: unknown, output: Output): number;

package/dist/errors.js

@@ -0,0 +1,30 @@
+import { CommandCancelled, ExitError, UsageError } from '@mudah-cli/core';
+/**
+ * Render a thrown error through the styled output and return the process
+ * exit code it maps to. Shared by the `@mudah-cli/mudah` umbrella and the test harness
+ * so both render failures identically.
+ */
+export function renderError(error, output) {
+    if (error instanceof UsageError) {
+        output.error(error.message);
+        if (error.usage)
+            output.hint(`Usage: ${error.usage}`);
+        if (error.hint)
+            output.hint(error.hint);
+        return 2;
+    }
+    if (error instanceof CommandCancelled) {
+        return 130;
+    }
+    if (error instanceof ExitError) {
+        if (error.message)
+            output.error(error.message);
+        return error.code;
+    }
+    output.error(error instanceof Error ? error.message : String(error));
+    if (process.env['MUDAH_DEBUG']) {
+        output.error(error instanceof Error ? (error.stack ?? '') : '');
+    }
+    return 1;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAG1E;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,MAAc;IACxD,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;QAChC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC5B,IAAI,KAAK,CAAC,KAAK;YAAE,MAAM,CAAC,IAAI,CAAC,UAAU,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;QACtD,IAAI,KAAK,CAAC,IAAI;YAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACxC,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,KAAK,YAAY,gBAAgB,EAAE,CAAC;QACtC,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,KAAK,YAAY,SAAS,EAAE,CAAC;QAC/B,IAAI,KAAK,CAAC,OAAO;YAAE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC/C,OAAO,KAAK,CAAC,IAAI,CAAC;IACpB,CAAC;IACD,MAAM,CAAC,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACrE,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,CAAC;QAC/B,MAAM,CAAC,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/help.d.ts

@@ -0,0 +1,9 @@
+import type { CommandEntry } from './kernel.js';
+/** The full invocation string for a command: `name {args} [options]`. */
+export declare function formatUsage(entry: CommandEntry): string;
+/** One-line command row for the command list. */
+export declare function formatCommandRow(entry: CommandEntry, width: number): string;
+/** Render the full command list. */
+export declare function renderCommandList(appName: string, version: string, entries: CommandEntry[], lines: string[]): void;
+/** Render single-command help. */
+export declare function renderCommandHelp(appName: string, entry: CommandEntry, lines: string[]): void;

package/dist/help.js

@@ -0,0 +1,69 @@
+import { visibleLength } from '@mudah-cli/ui';
+/** The full invocation string for a command: `name {args} [options]`. */
+export function formatUsage(entry) {
+    const parts = [entry.signature.name];
+    for (const arg of entry.signature.args) {
+        if (arg.optional) {
+            parts.push(arg.defaultValue !== undefined ? `{${arg.name}=${arg.defaultValue}}` : `{${arg.name}?}`);
+        }
+        else {
+            parts.push(arg.defaultValue !== undefined ? `{${arg.name}=${arg.defaultValue}}` : `{${arg.name}}`);
+        }
+    }
+    if (entry.signature.options.length > 0) {
+        parts.push(entry.signature.options
+            .map((o) => (o.takesValue ? `--${o.name}=` : `--${o.name}`))
+            .join(' '));
+    }
+    return parts.join(' ');
+}
+/** One-line command row for the command list. */
+export function formatCommandRow(entry, width) {
+    const padded = entry.name + ' '.repeat(Math.max(1, width - visibleLength(entry.name)));
+    return `  ${padded} ${entry.description}`;
+}
+/** Render the full command list. */
+export function renderCommandList(appName, version, entries, lines) {
+    lines.push(`${appName} v${version}`, '');
+    if (entries.length === 0) {
+        lines.push('No commands registered.');
+        return;
+    }
+    lines.push('Commands:');
+    const width = Math.max(...entries.map((e) => visibleLength(e.name))) + 2;
+    for (const entry of entries) {
+        lines.push(formatCommandRow(entry, width));
+    }
+    lines.push('', `Use "${appName} <command> --help" for command details.`);
+}
+/** Render single-command help. */
+export function renderCommandHelp(appName, entry, lines) {
+    lines.push(`Usage: ${appName} ${formatUsage(entry)}`, '');
+    if (entry.description) {
+        lines.push('Description');
+        lines.push(`  ${entry.description}`, '');
+    }
+    if (entry.signature.args.length > 0) {
+        lines.push('Arguments:');
+        const width = Math.max(...entry.signature.args.map((a) => a.name.length)) + 2;
+        for (const arg of entry.signature.args) {
+            const kind = arg.optional ? (arg.defaultValue !== undefined ? `optional (default: ${arg.defaultValue})` : 'optional') : 'required';
+            lines.push(`  ${arg.name + ' '.repeat(Math.max(1, width - arg.name.length))} ${kind}`);
+        }
+        lines.push('');
+    }
+    if (entry.signature.options.length > 0) {
+        lines.push('Options:');
+        for (const option of entry.signature.options) {
+            const flag = option.takesValue ? `--${option.name}=` : `--${option.name}`;
+            const note = option.takesValue
+                ? option.defaultValue !== undefined
+                    ? `(default: ${option.defaultValue})`
+                    : ''
+                : '';
+            lines.push(`  ${flag}  ${note}`.trimEnd());
+        }
+        lines.push('  --help  Show this help');
+    }
+}
+//# sourceMappingURL=help.js.map

package/dist/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { Command } from './command.js';
+export { renderError } from './errors.js';
+export { formatCommandRow, formatUsage, renderCommandHelp, renderCommandList } from './help.js';
+export { ConsoleKernel, type CommandEntry, type CommandModule } from './kernel.js';
+export { Prompts, type PromptOptions } from './prompts.js';
+export { ArgumentParseError, parseInput, parseSignature, type ParsedArg, type ParsedInput, type ParsedOption, type ParsedSignature, } from './signature.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+export { Command } from './command.js';
+export { renderError } from './errors.js';
+export { formatCommandRow, formatUsage, renderCommandHelp, renderCommandList } from './help.js';
+export { ConsoleKernel } from './kernel.js';
+export { Prompts } from './prompts.js';
+export { ArgumentParseError, parseInput, parseSignature, } from './signature.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAChG,OAAO,EAAE,aAAa,EAAyC,MAAM,aAAa,CAAC;AACnF,OAAO,EAAE,OAAO,EAAsB,MAAM,cAAc,CAAC;AAC3D,OAAO,EACL,kBAAkB,EAClB,UAAU,EACV,cAAc,GAKf,MAAM,gBAAgB,CAAC"}

package/dist/kernel.d.ts

@@ -0,0 +1,37 @@
+import { type Application, type CommandModule } from '@mudah-cli/core';
+import type { Output } from '@mudah-cli/ui';
+import { Command, type ParsedSignature } from './command.js';
+export type { CommandModule } from '@mudah-cli/core';
+export interface CommandEntry {
+    name: string;
+    signature: ParsedSignature;
+    description: string;
+    factory: () => Command;
+}
+/**
+ * The console kernel: command registry and dispatcher.
+ *
+ * Flow for `dispatch(argv)`:
+ * 1. Resolve the command by name (UsageError when unknown/missing).
+ * 2. Emit `command.before`, boot lazy providers for this command.
+ * 3. Parse argv against the command's signature.
+ * 4. Inject app/output/input and call `handle()`.
+ * 5. Emit `command.after` with the exit code and duration.
+ *
+ * Errors propagate to the caller (the `@mudah-cli/mudah` umbrella renders them and
+ * maps them to exit codes).
+ */
+export declare class ConsoleKernel {
+    private readonly app;
+    private readonly output;
+    private readonly commands;
+    constructor(app: Application, output: Output);
+    /** Register a command module (default export is the command class). */
+    register(module: CommandModule): this;
+    /** All registered commands, sorted by name. */
+    list(): CommandEntry[];
+    has(name: string): boolean;
+    get(name: string): CommandEntry | undefined;
+    /** Dispatch argv (command name + arguments). Returns the exit code. */
+    dispatch(argv: string[]): Promise<number>;
+}

package/dist/kernel.js

@@ -0,0 +1,100 @@
+import { UsageError } from '@mudah-cli/core';
+import { Command, ArgumentParseError, parseInput, parseSignature, } from './command.js';
+/**
+ * The console kernel: command registry and dispatcher.
+ *
+ * Flow for `dispatch(argv)`:
+ * 1. Resolve the command by name (UsageError when unknown/missing).
+ * 2. Emit `command.before`, boot lazy providers for this command.
+ * 3. Parse argv against the command's signature.
+ * 4. Inject app/output/input and call `handle()`.
+ * 5. Emit `command.after` with the exit code and duration.
+ *
+ * Errors propagate to the caller (the `@mudah-cli/mudah` umbrella renders them and
+ * maps them to exit codes).
+ */
+export class ConsoleKernel {
+    app;
+    output;
+    commands = new Map();
+    constructor(app, output) {
+        this.app = app;
+        this.output = output;
+    }
+    /** Register a command module (default export is the command class). */
+    register(module) {
+        const Ctor = module.default;
+        // Metadata is read from an instance: `signature`/`description` are
+        // instance fields (not prototype properties).
+        const instance = new Ctor();
+        if (typeof instance.signature !== 'string' || instance.signature.length === 0) {
+            throw new Error(`[console] Command ${Ctor.name} has no signature.`);
+        }
+        if (typeof instance.handle !== 'function') {
+            throw new Error(`[console] Command ${Ctor.name} has no handle() method.`);
+        }
+        const signature = parseSignature(instance.signature);
+        if (this.commands.has(signature.name)) {
+            throw new Error(`[console] Duplicate command name "${signature.name}".`);
+        }
+        this.commands.set(signature.name, {
+            name: signature.name,
+            signature,
+            description: instance.description ?? '',
+            factory: () => new Ctor(),
+        });
+        return this;
+    }
+    /** All registered commands, sorted by name. */
+    list() {
+        return [...this.commands.values()].sort((a, b) => a.name.localeCompare(b.name));
+    }
+    has(name) {
+        return this.commands.has(name);
+    }
+    get(name) {
+        return this.commands.get(name);
+    }
+    /** Dispatch argv (command name + arguments). Returns the exit code. */
+    async dispatch(argv) {
+        const name = argv[0];
+        if (name === undefined) {
+            throw new UsageError('No command specified.', {
+                hint: 'Run with --help to see available commands.',
+            });
+        }
+        const entry = this.commands.get(name);
+        if (!entry) {
+            throw new UsageError(`Unknown command "${name}".`, {
+                hint: 'Run with --help to see available commands.',
+            });
+        }
+        await this.app.events().emit('command.before', { command: name, argv });
+        await this.app.bootLazyForCommand(name);
+        let input;
+        try {
+            input = parseInput(entry.signature, argv.slice(1));
+        }
+        catch (error) {
+            if (error instanceof ArgumentParseError) {
+                throw new UsageError(error.message, { usage: entry.signature.name });
+            }
+            throw error;
+        }
+        const command = entry.factory();
+        command.__inject(this.app, this.output, input);
+        const startedAt = performance.now();
+        let exitCode;
+        try {
+            exitCode = (await command.handle()) ?? 0;
+        }
+        catch (error) {
+            await this.app.events().emit('command.error', { command: name, error });
+            throw error;
+        }
+        const durationMs = Math.round(performance.now() - startedAt);
+        await this.app.events().emit('command.after', { command: name, exitCode, durationMs });
+        return exitCode;
+    }
+}
+//# sourceMappingURL=kernel.js.map

package/dist/kernel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel.js","sourceRoot":"","sources":["../src/kernel.ts"],"names":[],"mappings":"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"}

package/dist/prompts.d.ts

@@ -0,0 +1,27 @@
+export interface PromptOptions {
+    input?: NodeJS.ReadStream;
+    output?: NodeJS.WritableStream;
+    /** Bypasses the raw-mode UI entirely (used in tests and non-interactive runs). */
+    forcedValue?: string;
+}
+/**
+ * Minimal interactive prompts built on `node:readline` (text/confirm) and a
+ * numbered fallback for selects. Raw-mode arrow-key selection lands in v0.2;
+ * the interface is already designed for it.
+ */
+export declare class Prompts {
+    private rl;
+    private makeReader;
+    /** Ask a free-text question. Returns the default when the user presses enter. */
+    ask(question: string, options?: PromptOptions & {
+        defaultValue?: string;
+    }): Promise<string>;
+    /** Ask a yes/no question. */
+    confirm(question: string, options?: PromptOptions & {
+        defaultValue?: boolean;
+    }): Promise<boolean>;
+    /** Pick one of the choices by index (1-based). Returns the choice value. */
+    select(question: string, choices: string[], options?: PromptOptions): Promise<string>;
+    /** Close the underlying readline interface. */
+    dispose(): void;
+}

package/dist/prompts.js

@@ -0,0 +1,65 @@
+import * as readline from 'node:readline';
+/**
+ * Minimal interactive prompts built on `node:readline` (text/confirm) and a
+ * numbered fallback for selects. Raw-mode arrow-key selection lands in v0.2;
+ * the interface is already designed for it.
+ */
+export class Prompts {
+    rl = null;
+    makeReader() {
+        if (!this.rl) {
+            this.rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: process.stdin.isTTY === true });
+        }
+        return this.rl;
+    }
+    /** Ask a free-text question. Returns the default when the user presses enter. */
+    async ask(question, options = {}) {
+        if (options.forcedValue !== undefined)
+            return options.forcedValue;
+        const rl = this.makeReader();
+        const suffix = options.defaultValue !== undefined ? ` (${options.defaultValue})` : '';
+        return new Promise((resolve) => {
+            rl.question(`${question}${suffix} `, (answer) => {
+                resolve(answer.trim() === '' && options.defaultValue !== undefined ? options.defaultValue : answer.trim());
+            });
+        });
+    }
+    /** Ask a yes/no question. */
+    async confirm(question, options = {}) {
+        if (options.forcedValue !== undefined) {
+            const value = options.forcedValue.trim().toLowerCase();
+            return value === 'y' || value === 'yes' || value === 'true' || value === '1';
+        }
+        const def = options.defaultValue ?? false;
+        const answer = await this.ask(`${question} [${def ? 'Y/n' : 'y/N'}]`, { ...options, defaultValue: undefined });
+        if (answer === '')
+            return def;
+        return answer.toLowerCase().startsWith('y');
+    }
+    /** Pick one of the choices by index (1-based). Returns the choice value. */
+    async select(question, choices, options = {}) {
+        if (options.forcedValue !== undefined) {
+            const choice = choices[Number(options.forcedValue) - 1];
+            if (!choice)
+                throw new Error(`[console] Forced select value "${options.forcedValue}" is out of range.`);
+            return choice;
+        }
+        process.stderr.write(`\n${question}\n`);
+        choices.forEach((choice, i) => {
+            process.stderr.write(`  ${i + 1}. ${choice}\n`);
+        });
+        const answer = await this.ask('Choose', options);
+        const index = Number(answer) - 1;
+        const choice = choices[index];
+        if (!choice) {
+            throw new Error(`[console] Invalid selection "${answer}".`);
+        }
+        return choice;
+    }
+    /** Close the underlying readline interface. */
+    dispose() {
+        this.rl?.close();
+        this.rl = null;
+    }
+}
+//# sourceMappingURL=prompts.js.map

package/dist/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"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"}

package/dist/signature.d.ts

@@ -0,0 +1,37 @@
+export interface ParsedArg {
+    name: string;
+    optional: boolean;
+    defaultValue?: string;
+}
+export interface ParsedOption {
+    name: string;
+    /** Takes a value (`--env=production`). */
+    takesValue: boolean;
+    defaultValue?: string;
+}
+export interface ParsedSignature {
+    name: string;
+    args: ParsedArg[];
+    options: ParsedOption[];
+}
+export interface ParsedInput {
+    args: Record<string, string>;
+    options: Record<string, string | boolean>;
+}
+/**
+ * Parse a command signature string:
+ *
+ * ```
+ * deploy {branch?} {ref=main} [--force] [--env=production]
+ * ```
+ */
+export declare function parseSignature(signature: string): ParsedSignature;
+/**
+ * Parse raw argv (everything after the command name) against a parsed
+ * signature. Positional values fill args in order; `--name` / `--name=value`
+ * fill options. Throws `ArgumentParseError` on violations.
+ */
+export declare function parseInput(signature: ParsedSignature, argv: string[]): ParsedInput;
+export declare class ArgumentParseError extends Error {
+    constructor(message: string);
+}

package/dist/signature.js

@@ -0,0 +1,99 @@
+/**
+ * Parse a command signature string:
+ *
+ * ```
+ * deploy {branch?} {ref=main} [--force] [--env=production]
+ * ```
+ */
+export function parseSignature(signature) {
+    const result = { name: '', args: [], options: [] };
+    const trimmed = signature.trim();
+    const firstSpace = trimmed.search(/\s/);
+    result.name = firstSpace === -1 ? trimmed : trimmed.slice(0, firstSpace);
+    for (const match of trimmed.matchAll(/\{([^{}]+)\}/g)) {
+        const inner = match[1];
+        const parsed = /^([a-zA-Z][\w:.-]*)(\?)?(?:=(.*))?$/.exec(inner);
+        if (!parsed) {
+            throw new Error(`[console] Invalid argument syntax "{${inner}}" in signature "${signature}".`);
+        }
+        result.args.push({
+            name: parsed[1],
+            optional: parsed[2] === '?',
+            defaultValue: parsed[3],
+        });
+    }
+    for (const match of trimmed.matchAll(/\[-{2}([a-zA-Z][\w-]*)(?:=([^}\]]*))?\]/g)) {
+        const name = match[1];
+        const takesValue = match[2] !== undefined;
+        result.options.push({
+            name,
+            takesValue,
+            defaultValue: takesValue ? match[2] : undefined,
+        });
+    }
+    return result;
+}
+/**
+ * Parse raw argv (everything after the command name) against a parsed
+ * signature. Positional values fill args in order; `--name` / `--name=value`
+ * fill options. Throws `ArgumentParseError` on violations.
+ */
+export function parseInput(signature, argv) {
+    const input = { args: {}, options: {} };
+    const positionals = [];
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '--') {
+            positionals.push(...argv.slice(i + 1));
+            break;
+        }
+        if (token.startsWith('--')) {
+            const eq = token.indexOf('=');
+            if (eq === -1) {
+                input.options[token.slice(2)] = true;
+            }
+            else {
+                input.options[token.slice(2, eq)] = token.slice(eq + 1);
+            }
+            continue;
+        }
+        positionals.push(token);
+    }
+    // Validate unknown options.
+    const knownOptions = new Set(signature.options.map((o) => o.name));
+    for (const name of Object.keys(input.options)) {
+        if (!knownOptions.has(name)) {
+            throw new ArgumentParseError(`Unknown option "--${name}" for command "${signature.name}".`);
+        }
+    }
+    // Fill args.
+    if (positionals.length > signature.args.length) {
+        throw new ArgumentParseError(`Too many arguments for "${signature.name}": expected at most ${signature.args.length}.`);
+    }
+    signature.args.forEach((arg, index) => {
+        const value = positionals[index];
+        if (value !== undefined) {
+            input.args[arg.name] = value;
+        }
+        else if (arg.defaultValue !== undefined) {
+            input.args[arg.name] = arg.defaultValue;
+        }
+        else if (!arg.optional) {
+            throw new ArgumentParseError(`Missing required argument "${arg.name}" for command "${signature.name}".`);
+        }
+    });
+    // Fill options with defaults.
+    for (const option of signature.options) {
+        if (input.options[option.name] === undefined) {
+            input.options[option.name] = option.takesValue ? (option.defaultValue ?? '') : false;
+        }
+    }
+    return input;
+}
+export class ArgumentParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ArgumentParseError';
+    }
+}
+//# sourceMappingURL=signature.js.map

package/dist/signature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.js","sourceRoot":"","sources":["../src/signature.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@mudah-cli/console",
+  "version": "0.1.0",
+  "description": "Command system: string signatures, typed dispatch, interactive prompts, and help rendering.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=26"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@mudah-cli/animation": "^0.1.0",
+    "@mudah-cli/core": "^0.1.0",
+    "@mudah-cli/terminal": "^0.1.0",
+    "@mudah-cli/ui": "^0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}