@nan0web/ui-cli 1.0.0 → 1.0.2

package/types/CommandHelp.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @typedef {Object} CommandHelpField MessageBodySchema
+ * @property {string}  [help]         - Human readable description.
+ * @property {string}  [placeholder]  - Placeholder for usage (e.g. "<user>").
+ * @property {string}  [alias]        - Short alias (single‑letter).
+ * @property {any}     [defaultValue] - Default value.
+ * @property {any}     [type]         - Data type.
+ * @property {boolean} [required]     - Is field required or not.
+ * @property {RegExp}  [pattern]      - Regular expression pattern for validation.
+ */
+/**
+ * CommandHelp – generates CLI help from a Message body schema.
+ * Supports nesting via static `Children`; message‑centric.
+ *
+ * @example
+ * const help = new CommandHelp(AuthMessage)
+ * console.log(help.generate())        // → formatted help string
+ * help.print()                       // → logs to console
+ */
+export default class CommandHelp {
+    /**
+     * @param {typeof Message} MessageClass - Message class with a schema.
+     * @param {Logger} [logger=new Logger()] - Optional logger.
+     */
+    constructor(MessageClass: typeof Message, logger?: Logger | undefined);
+    /** @type {typeof Message} Message class the help is built for */
+    MessageClass: typeof Message;
+    /** @type {Logger} Logger used for printing */
+    logger: Logger;
+    /** @type {typeof Message.Body} Body class reference */
+    BodyClass: typeof Message.Body;
+    /** @returns {typeof Logger} */
+    get Logger(): typeof Logger;
+    /**
+     * Generates the full help text.
+     *
+     * @returns {string} Formatted help text.
+     */
+    generate(): string;
+    /**
+     * Prints the generated help to the logger.
+     */
+    print(): void;
+    /**
+     * @param {object} body
+     * @returns {Map<string, any>} A map of errors, empty map if no errors.
+     */
+    validate(body: object): Map<string, any>;
+    #private;
+}
+/**
+ * MessageBodySchema
+ */
+export type CommandHelpField = {
+    /**
+     * - Human readable description.
+     */
+    help?: string | undefined;
+    /**
+     * - Placeholder for usage (e.g. "<user>").
+     */
+    placeholder?: string | undefined;
+    /**
+     * - Short alias (single‑letter).
+     */
+    alias?: string | undefined;
+    /**
+     * - Default value.
+     */
+    defaultValue?: any;
+    /**
+     * - Data type.
+     */
+    type?: any;
+    /**
+     * - Is field required or not.
+     */
+    required?: boolean | undefined;
+    /**
+     * - Regular expression pattern for validation.
+     */
+    pattern?: RegExp | undefined;
+};
+import { Message } from "@nan0web/co";
+import Logger from "@nan0web/log";

package/types/CommandMessage.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @class
+ * @extends Message
+ */
+export default class CommandMessage extends Message {
+    /**
+     * Parse raw CLI input into a {@link CommandMessage}.
+     *
+     * @param {string|string[]} argv - Input string or token array.
+     * @param {typeof Object} [BodyClass] - Optional class to instantiate the body.
+     * @returns {CommandMessage}
+     * @throws {CommandError} If no input is supplied.
+     */
+    static parse(argv: string | string[], BodyClass?: ObjectConstructor | undefined): CommandMessage;
+    /**
+     * Convert a raw input into a {@link CommandMessage} instance.
+     *
+     * @param {CommandMessage|Message|Object|string|Array<string>} input
+     * @returns {CommandMessage}
+     */
+    static from(input: CommandMessage | Message | any | string | Array<string>): CommandMessage;
+    /**
+     * @param {Object} [input={}]
+     * @param {string} [input.name] - Command name.
+     * @param {string[]} [input.argv] - Positional arguments.
+     * @param {Object} [input.opts] - Options map.
+     * @param {Array<CommandMessage>} [input.children] - Nested messages.
+     * @param {Object} [input.body] - Message body payload.
+     */
+    constructor(input?: {
+        name?: string | undefined;
+        argv?: string[] | undefined;
+        opts?: any;
+        children?: CommandMessage[] | undefined;
+        body?: any;
+    } | undefined);
+    /** @param {string} v */
+    set name(arg: string);
+    /** @returns {string} */
+    get name(): string;
+    /** @param {string[]} v */
+    set argv(arg: string[]);
+    /** @returns {string[]} */
+    get argv(): string[];
+    /** @param {Object} v */
+    set opts(arg: any);
+    /** @returns {Object} */
+    get opts(): any;
+    /** @returns {Array<CommandMessage>} */
+    get children(): CommandMessage[];
+    /** @returns {Array<string>} Full command line (name + args). */
+    get args(): string[];
+    /** @returns {string} Sub‑command name of the first child, or empty string. */
+    get subCommand(): string;
+    /** @returns {CommandMessage|null} First child message, or null. */
+    get subCommandMessage(): CommandMessage | null;
+    /**
+     * Append a child {@link CommandMessage}.
+     *
+     * @param {CommandMessage|Object} msg
+     */
+    add(msg: CommandMessage | any): void;
+    #private;
+}
+import { Message } from "@nan0web/co";

package/types/CommandParser.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @class
+ */
+export default class CommandParser {
+    /**
+     * @param {Array<Function>} [Messages=[]] - Root message classes.
+     */
+    constructor(Messages?: Function[] | undefined);
+    /** @type {Array<Function>} */
+    Messages: Array<Function>;
+    /**
+     * Parse the provided input into a message hierarchy.
+     *
+     * @param {string|string[]} [input=process.argv.slice(2)] - CLI arguments.
+     * @returns {Message}
+     * @throws {Error} If no command is supplied or unknown root command.
+     */
+    parse(input?: string | string[] | undefined): Message;
+    /**
+     * Generate help text for a given message class.
+     *
+     * @param {typeof Message} MessageClass
+     * @returns {string}
+     */
+    generateHelp(MessageClass: typeof Message): string;
+    #private;
+}
+import { Message } from "@nan0web/co";

package/types/InputAdapter.d.ts

@@ -1,106 +1,49 @@
 /**
- * CLI specific adapter extending the generic {@link BaseInputAdapter}.
- * Implements concrete `ask` and `select` helpers that rely on the CLI utilities.
+ * Extends the generic {@link BaseInputAdapter} with CLI‑specific behaviour.
+ *
+ * @class
+ * @extends BaseInputAdapter
  */
 export default class CLIInputAdapter extends BaseInputAdapter {
     /**
-     * Interactively fill a {@link UIForm} field‑by‑field.
+     * Prompt the user for a full form, handling navigation and validation.
      *
-     * @param {UIForm} form – Form definition to be filled.
-     * @param {Object} options – Request options.
-     * @param {boolean} [options.silent=true] Suppress title output when `true`.
-     * @returns {Promise<FormMessage>} Message with `escaped` = true on cancel,
-     *                                 otherwise `escaped` = false and the completed form attached as `form`.
+     * @param {UIForm} form - Form definition to present.
+     * @param {Object} [options={}]
+     * @param {boolean} [options.silent=true] - Suppress console output if `true`.
+     * @returns {Promise<Object>} Result object containing form data and meta‑information.
      */
     requestForm(form: UIForm, options?: {
         silent?: boolean | undefined;
-    }): Promise<FormMessage>;
+    } | undefined): Promise<any>;
     /**
-     * Request a selection from a list of options.
+     * Prompt the user to select an option from a list.
      *
-     * @param {Object} config – Selection configuration.
-     * @param {string} config.title – Title displayed before the list.
-     * @param {string} config.prompt – Prompt text.
-     * @param {Array<string>|Map<string,string>|Array<{label:string,value:string}>} config.options – Options to choose from.
-     * @param {string} config.id – Identifier for the resulting message.
-     * @returns {Promise<BaseInputMessage>} Message containing chosen value and metadata.
+     * @param {Object} config - Configuration passed to {@link select}.
+     * @returns {Promise<any>} Selected value, or empty string on cancellation.
      */
-    requestSelect(config: {
-        title: string;
-        prompt: string;
-        options: Array<string> | Map<string, string> | Array<{
-            label: string;
-            value: string;
-        }>;
-        id: string;
-    }): Promise<BaseInputMessage>;
+    requestSelect(config: any): Promise<any>;
     /**
-     * Simple string input request.
+     * Prompt for a single string input.
      *
-     * @param {Object} config Input configuration.
-     * @param {string} config.prompt Prompt text.
-     * @param {string} config.id Identifier for the resulting message.
-     * @param {string} [config.label] Optional label used as fallback.
-     * @param {string} [config.name] Optional name used as fallback.
-     * @returns {Promise<BaseInputMessage>} Message containing the entered text.
+     * @param {Object} config - Prompt configuration.
+     * @param {string} [config.prompt] - Prompt text.
+     * @param {string} [config.label] - Optional label.
+     * @param {string} [config.name] - Optional identifier.
+     * @returns {Promise<string>} User response string.
      */
     requestInput(config: {
-        prompt: string;
-        id: string;
+        prompt?: string | undefined;
         label?: string | undefined;
         name?: string | undefined;
-    }): Promise<BaseInputMessage>;
+    }): Promise<string>;
     /** @inheritDoc */
-    ask(question: any): Promise<any>;
+    ask(question: any): Promise<string>;
     /** @inheritDoc */
-    select(config: any): Promise<{
-        index: number; /** @type {UIForm} Form data associated with the message */
-        value: string | null;
+    select(cfg: any): Promise<{
+        index: number;
+        value: any;
     }>;
 }
-export type FormMessageValue = Partial<UIForm>;
-export type InputMessageValue = Partial<Message> | null;
-import { InputAdapter as BaseInputAdapter } from '@nan0web/ui';
-import { UIForm } from '@nan0web/ui';
-/** @typedef {Partial<UIForm>} FormMessageValue */
-/** @typedef {Partial<Message> | null} InputMessageValue */
-/**
- * Extends the generic {@link BaseInputMessage} to carry a {@link UIForm}
- * instance alongside the usual input message payload.
- *
- * The original {@link BaseInputMessage} expects a `value` of type
- * {@link InputMessageValue} (a {@link Message} payload).  To remain
- * compatible we keep `value` unchanged and store the form data in a
- * separate `form` property.
- */
-declare class FormMessage extends BaseInputMessage {
-    /**
-     * Creates a {@link FormMessage} from an existing instance or plain data.
-     *
-     * @param {FormMessage|object} input – Existing message or raw data.
-     * @returns {FormMessage}
-     */
-    static from(input: FormMessage | object): FormMessage;
-    /**
-     * Creates a new {@link FormMessage}.
-     *
-     * @param {object} props - Message properties.
-     * @param {FormMessageValue} [props.form={}] UIForm instance or data.
-     * @param {InputMessageValue} [props.value=null] Retained for compatibility.
-     * @param {string[]|string} [props.options=[]] Available options.
-     * @param {boolean} [props.waiting=false] Waiting flag.
-     * @param {boolean} [props.escaped=false] Escape flag.
-     */
-    constructor(props?: {
-        form?: Partial<UIForm> | undefined;
-        value?: InputMessageValue | undefined;
-        options?: string | string[] | undefined;
-        waiting?: boolean | undefined;
-        escaped?: boolean | undefined;
-    });
-    /** @type {UIForm} Form data associated with the message */
-    form: UIForm;
-}
-import { InputMessage as BaseInputMessage } from '@nan0web/ui';
-import { Message } from '@nan0web/co';
-export {};
+import { InputAdapter as BaseInputAdapter } from "@nan0web/ui";
+import { UIForm } from "@nan0web/ui";

package/types/index.d.ts

@@ -1,11 +1,14 @@
+export { str2argv } from "./utils/parse.js";
 export const renderers: Map<string, (data: any) => string>;
 export default CLIInputAdapter;
-import CLIInputAdapter from './InputAdapter.js';
-import { CancelError } from '@nan0web/ui/core';
-import { createInput } from './ui/index.js';
-import { ask } from './ui/index.js';
-import { Input } from './ui/index.js';
-import { select } from './ui/index.js';
-import { next } from './ui/index.js';
-import { pause } from './ui/index.js';
-export { CLIInputAdapter, CancelError, createInput, ask, Input, select, next, pause };
+export type CommandHelpField = import("./CommandHelp.js").CommandHelpField;
+import CLI from "./CLI.js";
+import CLIInputAdapter from "./InputAdapter.js";
+import { CancelError } from "@nan0web/ui/core";
+import Command from "./Command.js";
+import CommandError from "./CommandError.js";
+import CommandMessage from "./CommandMessage.js";
+import CommandParser from "./CommandParser.js";
+import CommandHelp from "./CommandHelp.js";
+export { CLI, CLIInputAdapter, CancelError, Command, CommandError, CommandMessage, CommandParser, CommandHelp };
+export { select, next, pause, createInput, ask, Input } from "./ui/index.js";

package/types/ui/index.d.ts

@@ -1,4 +1,3 @@
-export { CancelError } from "@nan0web/ui/core";
-export { select } from "./select.js";
-export { Input, ask, createInput } from "./input.js";
+export { Input, createInput, ask } from "./input.js";
+export { select, default as baseSelect } from "./select.js";
 export { next, pause } from "./next.js";

package/types/ui/input.d.ts

@@ -1,15 +1,59 @@
 /**
- * Helper to ask a question
- * @param {string} question
+ * Prompt a question and return the trimmed answer.
+ *
+ * @param {string} question - Text displayed as a prompt.
+ * @returns {Promise<string>} User answer without surrounding whitespace.
+ */
+export function ask(question: string): Promise<string>;
+/**
+ * Factory that creates a reusable async input handler.
+ *
+ * @param {string[]} [stops=[]] Words that trigger cancellation.
+ * @returns {InputFn} Async function that resolves to an {@link Input}.
+ */
+export function createInput(stops?: string[] | undefined): InputFn;
+/**
+ * @typedef {Function} InputFn
+ * @param {string} question - Prompt displayed to the user.
+ * @param {Function|boolean} [loop=false] - Loop control or validator.
+ * @param {Function|false} [nextQuestion=false] - Function to compute the next prompt.
+ * @returns {Promise<Input>} Resolves with an {@link Input} instance containing the answer.
+ */
+/**
+ * Represents a line of user input.
+ *
+ * @class
+ * @property {string} value – The raw answer string.
+ * @property {string[]} stops – Words that trigger cancellation.
+ * @property {boolean} cancelled – True when the answer matches a stop word.
  */
-export function ask(question: string): Promise<any>;
-export function createInput(stops?: any[]): (question: string, loop?: boolean | Function | undefined, nextQuestion?: false | Function | undefined) => Promise<Input>;
 export class Input {
-    constructor(input?: {});
+    /**
+     * Create a new {@link Input} instance.
+     *
+     * @param {Object} [input={}] - Optional initial values.
+     * @param {string} [input.value] - Initial answer string.
+     * @param {boolean} [input.cancelled] - Initial cancel flag.
+     * @param {string|string[]} [input.stops] - Words that trigger cancellation.
+     */
+    constructor(input?: {
+        value?: string | undefined;
+        cancelled?: boolean | undefined;
+        stops?: string | string[] | undefined;
+    } | undefined);
+    /** @type {string} */
     value: string;
-    stops: any[];
+    /** @type {string[]} */
+    stops: string[];
+    /**
+     * Returns whether the input has been cancelled either explicitly or via a stop word.
+     *
+     * @returns {boolean}
+     */
     get cancelled(): boolean;
+    /** @returns {string} The raw answer value. */
     toString(): string;
     #private;
 }
 export default createInput;
+export type InputFn = Function;

package/types/ui/next.d.ts

@@ -1,12 +1,15 @@
 /**
- * Waits for the confirmation message (input) from user
- * @param {string | string[] | undefined} conf - Confirmation message or one of messages if array or any if undefined.
- * @returns {Promise<string>}
+ * Pause execution for a given amount of milliseconds.
+ *
+ * @param {number} ms - Delay in milliseconds.
+ * @returns {Promise<true>} Resolves with `true` after the timeout.
  */
-export function next(conf?: string | string[] | undefined): Promise<string>;
+export function pause(ms: number): Promise<true>;
 /**
- * Make a pause.
- * @param {number} ms - Amount in miliseconds
- * @returns {Promise<void>}
+ * Wait for any key press (or a specific sequence).
+ *
+ * @param {string|string[]|undefined} [conf] - Expected key or sequence.
+ * @returns {Promise<string>} The captured key/sequence.
+ * @throws {Error} If stdin is already in raw mode.
  */
-export function pause(ms: number): Promise<void>;
+export function next(conf?: string | string[] | undefined): Promise<string>;

package/types/ui/select.d.ts

@@ -1,30 +1,60 @@
 /**
- * Generic selection prompt for CLI.
- * Automatically creates its own input handler.
+ * Configuration object for {@link select}.
  *
- * @param {Object} config
- * @param {string} config.title - Title shown before the list (e.g. "Select currency:")
- * @param {string} config.prompt - Main prompt text (e.g. "Choose (1-3): ")
- * @param {string} [config.invalidPrompt] - Retry message when input is invalid
- * @param {Array<string> | Map<string, string> | Array<{ label: string, value: string }>} config.options - List of displayable options
- * @param {Object} config.console - Logger (console.info, console.error, etc.)
- * @param {Function} [config.ask] - Input handler
+ * @typedef {Object} SelectConfig
+ * @property {string} title – Title displayed above the options list.
+ * @property {string} prompt – Prompt displayed for the answer.
+ * @property {Array|Map} options – Collection of selectable items.
+ * @property {Object} console – Console‑like object with an `info` method.
+ * @property {string[]} [stops=[]] Words that trigger cancellation.
+ * @property {import("./input.js").InputFn} [ask] Custom ask function (defaults to {@link createInput}).
+ * @property {string} [invalidPrompt="Invalid choice, try again: "] Message shown on invalid input.
  *
- * @returns {Promise<{ index: number, value: string | null }>} Selected option
- * @throws {CancelError} if the user cancels
+ * @returns {Promise<{index:number,value:any}>} Resolves with the selected index and its value.
  */
-export function select({ title, prompt, invalidPrompt, options, console, ask, }: {
-    title: string;
-    prompt: string;
+export function select({ title, prompt, invalidPrompt, options, console, stops, ask: initAsk, }: {
+    title: any;
+    prompt: any;
     invalidPrompt?: string | undefined;
-    options: Array<string> | Map<string, string> | Array<{
-        label: string;
-        value: string;
-    }>;
+    options: any;
     console: any;
-    ask?: Function | undefined;
+    stops?: any[] | undefined;
+    ask: any;
 }): Promise<{
     index: number;
-    value: string | null;
+    value: any;
 }>;
 export default select;
+/**
+ * Configuration object for {@link select }.
+ */
+export type SelectConfig = {
+    /**
+     * – Title displayed above the options list.
+     */
+    title: string;
+    /**
+     * – Prompt displayed for the answer.
+     */
+    prompt: string;
+    /**
+     * – Collection of selectable items.
+     */
+    options: any[] | Map<any, any>;
+    /**
+     * – Console‑like object with an `info` method.
+     */
+    console: any;
+    /**
+     * Words that trigger cancellation.
+     */
+    stops?: string[] | undefined;
+    /**
+     * Custom ask function (defaults to {@link createInput }).
+     */
+    ask?: Function | undefined;
+    /**
+     * Message shown on invalid input.
+     */
+    invalidPrompt?: string | undefined;
+};

package/types/utils/parse.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Utility functions for parsing command‑line strings.
+ *
+ * @module utils/parse
+ */
+/**
+ * Parses a string into an argv array (handles quotes).
+ *
+ * @param {string} str - Raw command line.
+ * @returns {string[]} Tokenized arguments.
+ * @throws {Error} If a quote is left unmatched.
+ */
+export function str2argv(str: string): string[];

package/.editorconfig

@@ -1,20 +0,0 @@
-root = true
-
-[*]
-indent_style = tab
-indent_size = 2
-charset = utf-8
-end_of_line = lf
-trim_trailing_whitespace = true
-insert_final_newline = true
-
-[*.md]
-trim_trailing_whitespace = false
-
-[*.jsx]
-indent_style = tab
-indent_size = 2
-
-[*.{md,nano,yaml}]
-indent_style = space
-indent_size = 2

package/CONTRIBUTING.md

@@ -1,42 +0,0 @@
-# Contributing
-
-## Developer Certificate of Origin and License
-By contributing, You accept and agree to the following terms and conditions for your present and future contributions submitted.  
-Except for the license granted herein, You reserve all right, title, and interest in and to your Contributions.  
-All contributions are subject to the Developer Certificate of Origin and license as set out in the LICENSE file.
-
-## Code of Conduct
-As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.  
-
-We are committed to making participation in this project a harassment-free experience for everyone, regardless of:
-- Level of experience,
-- Gender,
-- Gender identity and expression,
-- Sexual orientation,
-- Disability,
-- Personal appearance,
-- Body size,
-- Race,
-- Ethnicity,
-- Age,
-- Religion.
-
-> We recognize all people as the foundation of humanity, and our actions contribute to the continued existence and growth of our shared humanity.
-
-### Release versioning
-- Keep releases close to the minor versions and publish patches only if required.
-
-### Examples of unacceptable behavior by participants:
-- Use of sexual language or imagery.
-- Derogatory comments or personal attacks.
-- Trolling, public or private harassment.
-- Insults or other unprofessional conduct.
-
-### Enforcement
-Project maintainers have the right and responsibility to:
-- Remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions not aligned with this Code of Conduct.
-- Remove maintainers who violate this Code of Conduct.
-
-Instances of unacceptable behavior can be reported by contacting the project team.
-
-This Code of Conduct is adapted from the [Contributor Covenant, version 1.1.0](https://contributor-covenant.org/version/1/1/0/).