@nan0web/ui-cli 1.0.2 → 1.1.1

package/src/ui/select.js

@@ -5,35 +5,59 @@
  */
 
 import { CancelError } from "@nan0web/ui/core"
-import createInput, { ask as baseAsk } from "./input.js"
+import createInput from "./input.js"
+
+/** @typedef {import("./input.js").Input} Input */
+/** @typedef {import("./input.js").InputFn} InputFn */
+
+/**
+ * @typedef {Object} ConsoleLike
+ * @property {(...args: any[]) => void} debug
+ * @property {(...args: any[]) => void} log
+ * @property {(...args: any[]) => void} info
+ * @property {(...args: any[]) => void} warn
+ * @property {(...args: any[]) => void} error
+ */
 
 /**
- * Configuration object for {@link select}.
- *
  * @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 {ConsoleLike} 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 {InputFn} [ask] Custom ask function (defaults to {@link createInput}).
  * @property {string} [invalidPrompt="Invalid choice, try again: "] Message shown on invalid input.
+ */
+
+/**
+ * Configuration object for {@link select}.
  *
+ * @param {SelectConfig} input
  * @returns {Promise<{index:number,value:any}>} Resolves with the selected index and its value.
+ *
+ * @throws {CancelError} When the user cancels the operation.
+ * @throws {Error} When options are missing or an incorrect value is supplied and no
+ *   `invalidPrompt` is defined.
  */
-export async function select({
-	title,
-	prompt,
-	invalidPrompt = "Invalid choice, try again: ",
-	options,
-	console,
-	stops = [],
-	ask: initAsk,
-}) {
+export async function select(input) {
+	const {
+		title,
+		prompt,
+		invalidPrompt = "Invalid choice, try again: ",
+		options: initOptins,
+		console,
+		stops = [],
+		ask: initAsk,
+	} = input
+	let options = initOptins
+	/** @type {InputFn} */
 	const ask = initAsk ?? createInput(stops)
+
 	// Normalise Map → Array of {label,value}
 	if (options instanceof Map) {
-		options = Array.from(options.entries()).map(([value, label]) => ({ label, value }))
+		options = Array.from(options.entries()).map(
+			([value, label]) => ({ label, value }))
 	}
 	if (!Array.isArray(options) || options.length === 0) {
 		throw new Error("Options array is required and must not be empty")
@@ -45,24 +69,37 @@ export async function select({
 	console.info(title)
 	list.forEach(({ label }, i) => console.info(` ${i + 1}) ${label}`))
 
-	let currentPrompt = prompt
-
-	while (true) {
-		const answer = await ask(currentPrompt)
-
-		if (answer.cancelled) throw new CancelError()
-
-		const idx = Number(answer.value) - 1
-
+	/**
+	 * Validation function passed to `ask` as the *loop* argument.
+	 * @type {import("./input.js").LoopFn}
+	 */
+	const validator = async (input) => {
+		if (input.cancelled) {
+			throw new CancelError()
+		}
+		const idx = Number(input.value) - 1
 		if (isNaN(idx) || idx < 0 || idx >= list.length) {
 			if (invalidPrompt) {
-				currentPrompt = invalidPrompt
-				continue
+				return true // repeat asking
 			}
 			throw new Error("Incorrect value provided")
 		}
-		return { index: idx, value: list[idx].value }
+		// valid selection – store index for later return
+		// we reuse `idx` after ask resolves
+		return false // stop looping
 	}
+
+	// Ask with validator loop; when validator returns false we have a valid answer.
+	const answer = await ask(prompt, validator, invalidPrompt)
+
+	// After validator passes, compute the final index once more (safe)
+	const finalIdx = Number(answer.value) - 1
+	return { index: finalIdx, value: list[finalIdx].value }
 }
 
+/**
+ * Default export for convenience.
+ *
+ * @type {typeof select}
+ */
 export default select

package/types/CLI.d.ts

@@ -1,15 +1,15 @@
 /**
- * Main CLI class.
+ * Main CLi class.
  */
-export default class CLI {
+export default class CLi {
     /**
-     * Factory to create a CLI instance from various inputs.
+     * Factory to create a CLi instance from various inputs.
      *
-     * @param {CLI|Object} input - Existing CLI instance or configuration object.
-     * @returns {CLI}
-     * @throws {TypeError} If input is neither a CLI nor an object.
+     * @param {CLi|Object} input - Existing CLi instance or configuration object.
+     * @returns {CLi}
+     * @throws {TypeError} If input is neither a CLi nor an object.
      */
-    static from(input: CLI | any): CLI;
+    static from(input: CLi | any): CLi;
     /**
      * @param {Object} [input={}]
      * @param {string[]} [input.argv] - Command‑line arguments (defaults to `process.argv.slice(2)`).
@@ -32,13 +32,14 @@ export default class CLI {
     /** @returns {Map<string,Function>} The command map. */
     get commands(): Map<string, Function>;
     /**
-     * Execute the CLI workflow.
+     * Execute the CLi workflow.
      *
      * @param {Message} [msg] - Optional pre‑built message.
-     * @yields {OutputMessage|InputMessage}
+     * @returns {AsyncGenerator<OutputMessage>}
      */
-    run(msg?: Message | undefined): AsyncGenerator<any, void, unknown>;
+    run(msg?: Message | undefined): AsyncGenerator<OutputMessage>;
     #private;
 }
 import Logger from "@nan0web/log";
 import { Message } from "@nan0web/co";
+import { OutputMessage } from "@nan0web/co";

package/types/CLiMessage.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @class CLiMessage
+ * @deprecated Use UiMessage that is the same
+ * @extends UiMessage
+ */
+export default class CLiMessage extends UiMessage {
+}
+import { UiMessage } from "@nan0web/ui";

package/types/CommandMessage.d.ts

@@ -1,5 +1,6 @@
 /**
  * @class
+ * @deprecated use Message or CLiMessage instead
  * @extends Message
  */
 export default class CommandMessage extends Message {

package/types/InputAdapter.d.ts

@@ -1,49 +1,96 @@
+/** @typedef {import("./ui/select.js").InputFn} InputFn */
+/** @typedef {import("./ui/select.js").ConsoleLike} ConsoleLike */
 /**
  * Extends the generic {@link BaseInputAdapter} with CLI‑specific behaviour.
  *
  * @class
  * @extends BaseInputAdapter
  */
-export default class CLIInputAdapter extends BaseInputAdapter {
+export default class CLiInputAdapter extends BaseInputAdapter {
+    constructor(options?: {});
+    /** @returns {ConsoleLike} */
+    get console(): import("./ui/select.js").ConsoleLike;
+    /** @returns {NodeJS.WriteStream} */
+    get stdout(): NodeJS.WriteStream;
+    /**
+     * Create a handler with stop words that supports predefined answers.
+     *
+     * @param {string[]} stops - Stop words for cancellation.
+     * @returns {InputFn}
+     */
+    createHandler(stops?: string[]): InputFn;
     /**
      * Prompt the user for a full form, handling navigation and validation.
      *
-     * @param {UIForm} form - Form definition to present.
+     * @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?: {
+    requestForm(form: UiForm, options?: {
         silent?: boolean | undefined;
     } | undefined): Promise<any>;
+    /**
+     * Render a UI component in the CLI environment.
+     *
+     * The current CLI adapter only supports simple textual rendering.
+     *
+     * @param {string} component - Component name (e.g. `"Alert"`).
+     * @param {object} props - Props object passed to the component.
+     * @returns {Promise<void>}
+     */
+    render(component: string, props: object): Promise<void>;
+    /**
+     * Process a full form – thin wrapper around {@link requestForm}.
+     *
+     * @param {UiForm} form - Form definition.
+     * @param {object} [_state] - Unused, kept for compatibility with `CLiMessage`.
+     * @returns {Promise<Object>} Same shape as {@link requestForm} result.
+     */
+    processForm(form: UiForm, _state?: object): Promise<any>;
     /**
      * Prompt the user to select an option from a list.
      *
-     * @param {Object} config - Configuration passed to {@link select}.
-     * @returns {Promise<any>} Selected value, or empty string on cancellation.
+     * @param {Object} config - Configuration object.
+     * @returns {Promise<string>} Selected value (or empty string on cancel).
      */
-    requestSelect(config: any): Promise<any>;
+    requestSelect(config: any): Promise<string>;
     /**
      * Prompt for a single string input.
      *
      * @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 | undefined;
-        label?: string | undefined;
-        name?: string | undefined;
-    }): Promise<string>;
-    /** @inheritDoc */
-    ask(question: any): Promise<string>;
+    requestInput(config: any): Promise<string>;
+    /**
+     * Asks user a question or form and returns the completed form
+     * @param {string | UiForm} question
+     * @param {object} [options={}]
+     *
+     */
+    ask(question: string | UiForm, options?: object): Promise<any>;
     /** @inheritDoc */
     select(cfg: any): Promise<{
         index: number;
         value: any;
     }>;
+    /**
+     * **New API** – Require input for a {@link UiMessage} instance.
+     *
+     * This method mirrors the previous `UiMessage.requireInput` logic, but is now
+     * owned by the UI adapter. It validates the message according to its static
+     * {@link UiMessage.Body} schema, presents a generated {@link UiForm} and
+     * returns the updated body.  Cancellation results in a {@link CancelError}.
+     *
+     * @param {UiMessage} msg - Message instance needing input.
+     * @returns {Promise<any>} Updated message body.
+     * @throws {CancelError} When user cancels the input process.
+     */
+    requireInput(msg: UiMessage): Promise<any>;
+    #private;
 }
+export type InputFn = import("./ui/select.js").InputFn;
+export type ConsoleLike = import("./ui/select.js").ConsoleLike;
 import { InputAdapter as BaseInputAdapter } from "@nan0web/ui";
-import { UIForm } from "@nan0web/ui";
+import { UiForm } from "@nan0web/ui";
+import { UiMessage } from "@nan0web/ui";

package/types/OutputAdapter.d.ts

@@ -0,0 +1,29 @@
+/**
+ * OutputAdapter handles UI output operations in command-line environment.
+ * @class
+ */
+export default class OutputAdapter {
+    /**
+     * Creates new output adapter.
+     * @param {Object} [options] - Configuration options.
+     * @param {any} [options.console] - Console implementation.
+     * @param {Map<string, () => Promise<Function>>} [options.components] - Component loaders.
+     */
+    constructor(options?: {
+        console?: any;
+        components?: Map<string, () => Promise<Function>> | undefined;
+    } | undefined);
+    /** @returns {any} */
+    get console(): any;
+    /**
+     * Render a UI component in the CLI environment.
+     *
+     * The current implementation supports simple textual rendering.
+     *
+     * @param {string} component - Component name (e.g. `"Alert"`).
+     * @param {object} props - Props object passed to the component.
+     * @returns {Promise<void>}
+     */
+    render(component: string, props: object): Promise<void>;
+    #private;
+}

package/types/UiMessage.d.ts

@@ -0,0 +1,40 @@
+/** @typedef {import("@nan0web/co").MessageBodySchema} MessageBodySchema */
+/** @typedef {import("./InputAdapter.js").default} InputAdapter */
+/** @typedef {import("./OutputAdapter.js").default} OutputAdapter */
+/**
+ * Represents a message with UI input requirements.
+ * @template {Record<string, any>} T
+ * @class
+ * @extends {Message}
+ */
+export default class UiMessage<T extends Record<string, any>> extends Message {
+    constructor(input?: import("../node_modules/@nan0web/co/types/Message.js").MessageInput | undefined);
+    /**
+     * Validates the message body against its schema.
+     *
+     * NOTE: The signature must exactly match `Message.validate` – it returns a
+     * `Map<string,string>` regardless of the generic type, otherwise TypeScript
+     * reports incompatibility with the base class.
+     *
+     * @param {any} [body=this.body] - Optional body to validate.
+     * @returns {Map<string,string>} Map of validation errors (empty if valid).
+     */
+    validate(body?: any): Map<string, string>;
+    /**
+     * Requires input via UI adapter. Validates fields according to the static `Body` schema.
+     *
+     * @param {Object} ui - UI adapter with input/output capabilities.
+     * @param {InputAdapter} ui.input - Input adapter for prompts.
+     * @param {OutputAdapter} [ui.output] - Optional output adapter for rendering.
+     * @returns {Promise<T>} Resolves with updated body or rejects if cancelled.
+     * @throws {CancelError} When user cancels the input process.
+     */
+    requireInput(ui: {
+        input: InputAdapter;
+        output?: import("./OutputAdapter.js").default | undefined;
+    }): Promise<T>;
+}
+export type MessageBodySchema = import("@nan0web/co").MessageBodySchema;
+export type InputAdapter = import("./InputAdapter.js").default;
+export type OutputAdapter = import("./OutputAdapter.js").default;
+import { Message } from "@nan0web/co";

package/types/components/Alert.d.ts

@@ -0,0 +1,15 @@
+/** @typedef {import("../InputAdapter.js").default} InputAdapter */
+/**
+ * Alert component for CLI rendering.
+ *
+ * @this {InputAdapter}
+ * @param {Object} input - Component props.
+ * @param {string} [input.variant="info"] - Alert variant (maps to console method).
+ * @param {string} [input.content=""] - Alert message content.
+ * @throws {Error} If variant maps to undefined console method.
+ */
+export default function _default(this: import("../InputAdapter.js").default, input?: {
+    variant?: string | undefined;
+    content?: string | undefined;
+}): void;
+export type InputAdapter = import("../InputAdapter.js").default;

package/types/index.d.ts

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

package/types/test/PlaygroundTest.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @typedef {object} PlaygroundTestConfig
+ * @property {NodeJS.ProcessEnv} env Environment variables for the child process.
+ * @property {{ includeDebugger?: boolean }} [config={}] Configuration options.
+ */
+/**
+ * Utility class to run playground demos and capture output.
+ *
+ * Updated behaviour:
+ *   – When `PLAY_DEMO_SEQUENCE` is defined, the values are streamed to the
+ *     child process **asynchronously** with a short delay between writes.
+ *   – Errors caused by writing to a closed stdin (EPIPE) are ignored, allowing
+ *     the child process to exit cleanly when a demo cancels early.
+ *   – After execution, leading whitespace on each output line is stripped so
+ *     that the test suite can compare raw lines without dealing with logger
+ *       formatting (e.g. logger prefixes, indentation).
+ */
+export default class PlaygroundTest {
+    /**
+     * @param {NodeJS.ProcessEnv} env Environment variables for the child process.
+     * @param {{ includeDebugger?: boolean, includeEmptyLines?: boolean }} [config={}] Configuration options.
+     */
+    constructor(env: NodeJS.ProcessEnv, config?: {
+        includeDebugger?: boolean | undefined;
+        includeEmptyLines?: boolean | undefined;
+    } | undefined);
+    env: NodeJS.ProcessEnv;
+    /** @type {boolean} Include debugger lines in output (default: false). */
+    includeDebugger: boolean;
+    incldeEmptyLines: boolean;
+    /**
+     * Subscribe to an event.
+     */
+    on(event: any, fn: any): void;
+    /**
+     * Unsubscribe from an event.
+     */
+    off(event: any, fn: any): void;
+    /**
+     * Emit an event.
+     */
+    emit(event: any, data: any): Promise<EventContext<any>>;
+    /**
+     * Filter debugger related lines.
+     */
+    filterDebugger(str: any): any;
+    /**
+     * Slice lines from stdout or stderr.
+     */
+    slice(target: any, start: any, end: any): any;
+    /**
+     * Executes the playground script.
+     *
+     * @param {string[]} [args=["play/main.js"]] Arguments passed to the node process.
+     */
+    run(args?: string[] | undefined): Promise<{
+        stdout: any;
+        stderr: any;
+        exitCode: any;
+    }>;
+    recentResult: {
+        stdout: any;
+        stderr: any;
+        exitCode: any;
+    } | undefined;
+    #private;
+}
+export type PlaygroundTestConfig = {
+    /**
+     * Environment variables for the child process.
+     */
+    env: NodeJS.ProcessEnv;
+    /**
+     * Configuration options.
+     */
+    config?: {
+        includeDebugger?: boolean | undefined;
+    } | undefined;
+};
+import { EventContext } from "@nan0web/event";

package/types/test/index.d.ts

@@ -0,0 +1,3 @@
+export { PlaygroundTest };
+export default PlaygroundTest;
+import PlaygroundTest from "./PlaygroundTest.js";

package/types/ui/Adapter.d.ts

@@ -0,0 +1 @@
+export {};

package/types/ui/form.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Generates a UiForm instance from a Body class static schema.
+ *
+ * @param {Function} BodyClass Class containing static field definitions.
+ * @param {Object} [options={}] Options.
+ * @param {Object} [options.initialState={}] Initial values for the form fields.
+ * @param {Function} [options.t] Optional translation function.
+ * @returns {UiForm} UiForm populated with fields derived from the schema.
+ *
+ * The function inspects static properties of `BodyClass` (e.g., `static username = { … }`)
+ * and maps each to a {@link FormInput}. The generated {@link UiForm} title defaults
+ * to `BodyClass.name` unless overridden via the schema.
+ */
+export function generateForm(BodyClass: Function, options?: {
+    initialState?: any;
+    t?: Function | undefined;
+} | undefined): UiForm;
+/**
+ * CLI-specific form handler that introspects a model class for static field schemas.
+ *
+ * @class
+ */
+export default class Form {
+    /**
+     * Creates a {@link Form} instance directly from a Body schema.
+     *
+     * @param {typeof Object} BodyClass Class with static schema definitions.
+     * @param {Object} [initialModel={}] Optional initial model data.
+     * @param {Object} [options={}] Same options as the constructor.
+     * @returns {Form} New Form instance.
+     *
+     * @example
+     *   const form = Form.createFromBodySchema(UserBody, { username: "bob" })
+     */
+    static createFromBodySchema(BodyClass: typeof Object, initialModel?: any, options?: any): Form;
+    /**
+     * @param {Object} model - Model instance (e.g., new User({ username: argv[3] })).
+     * @param {Object} [options={}] - Options.
+     * @param {string[]} [options.stops=["quit", "cancel", "exit"]] - Stop words.
+     * @param {(prompt: string) => Promise<Input>} [options.inputFn] - Custom input function.
+     * @throws {TypeError} If model is not an object with a constructor.
+     */
+    constructor(model: any, options?: {
+        stops?: string[] | undefined;
+        inputFn?: ((prompt: string) => Promise<Input>) | undefined;
+    } | undefined);
+    /** @type {Function} Input handler with cancellation support. */
+    handler: Function;
+    /**
+     * Prompts for selection using the provided configuration.
+     *
+     * @param {Object} config - Selection configuration.
+     * @returns {Promise<{index:number, value:any}>} Selected option.
+     */
+    select(config: any): Promise<{
+        index: number;
+        value: any;
+    }>;
+    /**
+     * Prompts for input using the internal handler.
+     *
+     * @param {string} prompt - Input prompt.
+     * @returns {Promise<Input>} Input result.
+     */
+    input(prompt: string): Promise<Input>;
+    /**
+     * Prompts for input, validates, and updates the model.
+     * Uses `ask` for text fields and `select` for option-based fields.
+     * Supports cancellation via stop words.
+     *
+     * @returns {Promise<{cancelled:boolean}>} Result indicating if cancelled.
+     * @throws {Error} Propagates non-cancellation errors.
+     */
+    requireInput(): Promise<{
+        cancelled: boolean;
+    }>;
+    /**
+     * Converts raw input value based on field schema.
+     *
+     * @param {Object} field - Field config.
+     * @param {string} value - Raw string value.
+     * @returns {string|number|boolean} Typed value.
+     */
+    convertValue(field: any, value: string): string | number | boolean;
+    /** @returns {Object} The updated model instance. */
+    get body(): any;
+    #private;
+}
+import { UiForm } from "@nan0web/ui";
+import { Input } from "./input.js";