@nan0web/ui-cli 1.0.0 → 1.0.2

package/src/README.md.js

@@ -1,6 +1,9 @@
+/* eslint-disable no-unused-vars */
 import { describe, it, before, beforeEach } from "node:test"
 import assert from "node:assert/strict"
 import FS from "@nan0web/db-fs"
+import Message from "@nan0web/co"
+import { UIForm } from "@nan0web/ui"
 import { NoConsole } from "@nan0web/log"
 import {
 	DatasetParser,
@@ -11,14 +14,12 @@ import {
 	CLIInputAdapter as BaseCLIInputAdapter,
 	CancelError,
 	createInput,
-	ask as baseAsk,
 	Input,
+	pause,
+	ask as baseAsk,
 	select as baseSelect,
 	next as baseNext,
-	pause,
 } from "./index.js"
-import { UIForm } from "@nan0web/ui"
-import Message from "@nan0web/co"
 
 async function ask(question) {
 	if ("Full Name *: " === question) return "John Doe"
@@ -190,8 +191,8 @@ function testRender() {
 		}
 
 		const result = await adapter.requestSelect(config)
-		console.info(result.value) // ← Message { body: "en", head: {} }
-		assert.deepStrictEqual(console.output()[0][1], Message.from({ body: "en" }))
+		console.info(result) // ← en
+		assert.deepStrictEqual(console.output()[0][1], "en")
 	})
 
 	/**

package/src/index.js

@@ -1,25 +1,47 @@
-import CLIInputAdapter from './InputAdapter.js'
-import { select, next, pause, createInput, ask, Input } from './ui/index.js'
-import { CancelError } from '@nan0web/ui/core'
+import CLIInputAdapter from "./InputAdapter.js"
+import { CancelError } from "@nan0web/ui/core"
+import CLI from "./CLI.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 { str2argv } from "./utils/parse.js"
 
-// Export CLI input adapter
 export {
-	CLIInputAdapter,
-	CancelError,
-	createInput,
-	ask,
-	Input,
 	select,
 	next,
 	pause,
+	createInput,
+	ask,
+	Input,
+} from "./ui/index.js"
+
+/** @typedef {import("./CommandHelp.js").CommandHelpField} CommandHelpField */
+
+export {
+	CLI,
+	CLIInputAdapter,
+	CancelError,
+
+	/** @deprecated */
+	Command,
+	/** @deprecated */
+	CommandError,
+	/** @deprecated */
+	CommandMessage,
+
+	CommandParser,
+	CommandHelp,
 }
 
-// Export renderers for CLI components
 export const renderers = new Map([
-	['UIProcess', (data) => {
-		// Render process information in CLI
-		return `${data.title || 'Process'}: ${data.status || 'running'}`
-	}],
+	[
+		"UIProcess",
+		data => {
+			return `${data.title || "Process"}: ${data.status || "running"}`
+		},
+	],
 ])
 
 export default CLIInputAdapter

package/src/ui/index.js

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

package/src/ui/input.js

@@ -1,33 +1,80 @@
+/**
+ * Input module – provides utilities to read user input from the console.
+ *
+ * @module ui/input
+ */
+
 import { createInterface } from "node:readline"
 import { stdin, stdout } from "node:process"
 
+/**
+ * @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 class Input {
+	/** @type {string} */
 	value = ""
+	/** @type {string[]} */
 	stops = []
 	#cancelled = false
+
+	/**
+	 * 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 = {}) {
 		const {
 			value = this.value,
 			cancelled = this.#cancelled,
 			stops = [],
 		} = input
+
 		this.value = String(value)
-		this.stops = stops.map(String)
+
+		const normalizedStops = Array.isArray(stops) ? stops : [stops].filter(Boolean)
+		this.stops = normalizedStops.map(String)
+
 		this.#cancelled = Boolean(cancelled)
 	}
+
+	/**
+	 * Returns whether the input has been cancelled either explicitly or via a stop word.
+	 *
+	 * @returns {boolean}
+	 */
 	get cancelled() {
 		return this.#cancelled || this.stops.includes(this.value)
 	}
+
+	/** @returns {string} The raw answer value. */
 	toString() {
 		return this.value
 	}
 }
 
 /**
- * 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) {
+export async function ask(question) {
 	return new Promise(resolve => {
 		const rl = createInterface({ input: stdin, output: stdout, terminal: true })
 		rl.question(question, answer => {
@@ -37,27 +84,37 @@ export function ask(question) {
 	})
 }
 
+/**
+ * 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 = []) {
 	const input = new Input({ stops })
+
 	/**
-	 * @param {string} question
-	 * @param {Function | boolean} [loop=false]
-	 * @param {Function | false} [nextQuestion=false]
+	 * Internal handler used by the factory.
+	 *
+	 * @param {string} question - Prompt displayed to the user.
+	 * @param {Function|boolean} [loop=false] - Loop‑control flag or validator.
+	 * @param {Function|false} [nextQuestion=false] - Next prompt generator.
 	 * @returns {Promise<Input>}
 	 */
 	async function fn(question, loop = false, nextQuestion = false) {
 		while (true) {
 			input.value = await ask(question)
+
 			if (false === loop || input.cancelled) return input
 			if (true === loop && input.value) return input
-			if ("function" === typeof loop) {
+			if (typeof loop === "function") {
 				if (!loop(input)) return input
 			}
-			if ("string" === typeof nextQuestion) question = nextQuestion
-			if ("function" === typeof nextQuestion) question = nextQuestion(input)
+			if (typeof nextQuestion === "string") question = nextQuestion
+			if (typeof nextQuestion === "function") question = nextQuestion(input)
 		}
 	}
 	return fn
 }
 
-export default createInput
+export default createInput

package/src/ui/next.js

@@ -1,42 +1,49 @@
+/**
+ * Utility functions for handling pauses and key‑press continuations.
+ *
+ * @module ui/next
+ */
+
 import process from "node:process"
 
 /**
- * Make a pause.
- * @param {number} ms - Amount in miliseconds
- * @returns {Promise<void>}
+ * Pause execution for a given amount of milliseconds.
+ *
+ * @param {number} ms - Delay in milliseconds.
+ * @returns {Promise<true>} Resolves with `true` after the timeout.
  */
-const pause = async (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+export async function pause(ms) {
+	return new Promise(resolve => setTimeout(() => resolve(true), ms))
+}
 
 /**
- * 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>}
+ * 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.
  */
-const next = async (conf = undefined) => {
+export async function next(conf = undefined) {
 	return new Promise((resolve, reject) => {
 		if (process.stdin.isRaw) {
-			reject(new Error('stdin is already in raw mode'))
+			reject(new Error("stdin is already in raw mode"))
 			return
 		}
+		let buffer = ""
 
-		let buffer = ''
-
-		const onData = (chunk) => {
+		const onData = chunk => {
 			const str = chunk.toString()
 			buffer += str
 
-			// Будь-яка клавіша
 			if (conf === undefined) {
 				cleanup()
 				resolve(str)
-			}
-			else if (typeof conf === 'string') {
+			} else if (typeof conf === "string") {
 				if (buffer === conf || buffer.endsWith(conf)) {
 					cleanup()
 					resolve(buffer)
 				}
-			}
-			else if (Array.isArray(conf)) {
+			} else if (Array.isArray(conf)) {
 				for (const seq of conf) {
 					if (buffer === seq || buffer.endsWith(seq)) {
 						cleanup()
@@ -47,24 +54,21 @@ const next = async (conf = undefined) => {
 			}
 		}
 
-		const errorHandler = (err) => {
+		const errorHandler = err => {
 			cleanup()
 			reject(err)
 		}
 
 		const cleanup = () => {
-			process.stdin.off('data', onData)
-			process.stdin.off('error', errorHandler)
+			process.stdin.off("data", onData)
+			process.stdin.off("error", errorHandler)
 			process.stdin.setRawMode(false)
 			process.stdin.resume()
 		}
 
 		process.stdin.setRawMode(true)
 		process.stdin.resume()
-
-		process.stdin.once('error', errorHandler)
-		process.stdin.on('data', onData)
+		process.stdin.once("error", errorHandler)
+		process.stdin.on("data", onData)
 	})
-}
-
-export { next, pause }
+}

package/src/ui/select.js

@@ -1,20 +1,25 @@
-import createInput from "./input.js"
-import { CancelError } from '@nan0web/ui/core'
+/**
+ * Select module – renders a numbered list of options and returns the chosen value.
+ *
+ * @module ui/select
+ */
+
+import { CancelError } from "@nan0web/ui/core"
+import createInput, { ask as baseAsk } from "./input.js"
 
 /**
- * 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 async function select({
 	title,
@@ -22,36 +27,41 @@ export async function select({
 	invalidPrompt = "Invalid choice, try again: ",
 	options,
 	console,
-	ask = createInput(["0"]),
+	stops = [],
+	ask: initAsk,
 }) {
+	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 }))
 	}
 	if (!Array.isArray(options) || options.length === 0) {
 		throw new Error("Options array is required and must not be empty")
 	}
-
-	/** @type {Array<{ label: string, value: string }>} */
-	const list = options.map(el => "string" === typeof el ? ({ label: el, value: el }) : el)
+	const list = options.map(el =>
+		typeof el === "string" ? { label: el, value: el } : el,
+	)
 
 	console.info(title)
-	list.forEach(({ label }, i) => {
-		console.info(` ${i + 1}) ${label}`)
-	})
+	list.forEach(({ label }, i) => console.info(` ${i + 1}) ${label}`))
 
-	const input = await ask(prompt, (input) => {
-		const idx = Number(input.value) - 1
-		return idx < 0 || idx >= list.length
-	}, invalidPrompt)
+	let currentPrompt = prompt
 
-	if (input.cancelled) {
-		throw new CancelError()
-	}
+	while (true) {
+		const answer = await ask(currentPrompt)
+
+		if (answer.cancelled) throw new CancelError()
+
+		const idx = Number(answer.value) - 1
 
-	const index = Number(input.value) - 1
-	return {
-		index,
-		value: list[index].value,
+		if (isNaN(idx) || idx < 0 || idx >= list.length) {
+			if (invalidPrompt) {
+				currentPrompt = invalidPrompt
+				continue
+			}
+			throw new Error("Incorrect value provided")
+		}
+		return { index: idx, value: list[idx].value }
 	}
 }
 

package/src/utils/parse.js

@@ -0,0 +1,41 @@
+/**
+ * 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) {
+	const parts = []
+	let i = 0
+	str = String(str).trim()
+
+	while (i < str.length) {
+		while (i < str.length && str[i] === ' ') i++
+		if (i >= str.length) break
+
+		if (str[i] === '"' || str[i] === "'") {
+			const quote = str[i]
+			i++
+			let start = i
+			while (i < str.length && str[i] !== quote) i++
+			if (i < str.length) {
+				parts.push(str.slice(start, i))
+				i++
+			} else {
+				throw new Error(`Unmatched quote in argument: ${str}`)
+			}
+		} else {
+			let start = i
+			while (i < str.length && str[i] !== ' ') i++
+			parts.push(str.slice(start, i))
+		}
+	}
+	return parts
+}

package/types/CLI.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Main CLI class.
+ */
+export default class CLI {
+    /**
+     * 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.
+     */
+    static from(input: CLI | any): CLI;
+    /**
+     * @param {Object} [input={}]
+     * @param {string[]} [input.argv] - Command‑line arguments (defaults to `process.argv.slice(2)`).
+     * @param {Object} [input.commands] - Map of command names to handlers.
+     * @param {Logger} [input.logger] - Optional logger instance.
+     * @param {Array<Function>} [input.Messages] - Message classes for root commands.
+     */
+    constructor(input?: {
+        argv?: string[] | undefined;
+        commands?: any;
+        logger?: Logger | undefined;
+        Messages?: Function[] | undefined;
+    } | undefined);
+    /** @type {string[]} */
+    argv: string[];
+    /** @type {Logger} */
+    logger: Logger;
+    /** @type {Array<Function>} */
+    Messages: Array<Function>;
+    /** @returns {Map<string,Function>} The command map. */
+    get commands(): Map<string, Function>;
+    /**
+     * Execute the CLI workflow.
+     *
+     * @param {Message} [msg] - Optional pre‑built message.
+     * @yields {OutputMessage|InputMessage}
+     */
+    run(msg?: Message | undefined): AsyncGenerator<any, void, unknown>;
+    #private;
+}
+import Logger from "@nan0web/log";
+import { Message } from "@nan0web/co";

package/types/Command.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Represents a command definition.
+ *
+ * @class
+ * @deprecated Use CLI instead
+ */
+export default class Command {
+    /**
+     * @param {Object} config - Command configuration.
+     * @param {string} [config.name] - Command name.
+     * @param {string} [config.help] - Help description.
+     * @param {Object} [config.options] - Options map (`{ flag: [type, default, help] }`).
+     * @param {Function} [config.run] - Async generator handling execution.
+     * @param {Command[]} [config.children] - Sub‑commands.
+     */
+    constructor(config: {
+        name?: string | undefined;
+        help?: string | undefined;
+        options?: any;
+        run?: Function | undefined;
+        children?: Command[] | undefined;
+    });
+    /** @type {string} */ name: string;
+    /** @type {string} */ help: string;
+    /** @type {Object} */ options: any;
+    /** @type {Function} */ run: Function;
+    /** @type {Command[]} */ children: Command[];
+    /**
+     * Add a sub‑command.
+     *
+     * @param {Command} command - Sub‑command instance.
+     * @returns {this}
+     */
+    addSubcommand(command: Command): this;
+    /**
+     * Find a sub‑command by name.
+     *
+     * @param {string} name - Sub‑command name.
+     * @returns {Command|null}
+     */
+    findSubcommand(name: string): Command | null;
+    /**
+     * Parse argv into a {@link CommandMessage}.
+     *
+     * @param {string[]|string} argv - Arguments array or string.
+     * @returns {CommandMessage}
+     */
+    parse(argv: string[] | string): CommandMessage;
+    /**
+     * Generate a short help string.
+     *
+     * @returns {string}
+     */
+    generateHelp(): string;
+    /**
+     * Execute the command's run generator.
+     *
+     * @param {Message} message - Message passed to the runner.
+     * @yields {any}
+     * @throws {CommandError}
+     */
+    execute(message: Message): AsyncGenerator<any, void, any>;
+    /**
+     * Apply default values from the options definition to the parsed message.
+     *
+     * @param {CommandMessage} msg
+     * @private
+     */
+    private _applyDefaults;
+}
+import CommandMessage from "./CommandMessage.js";
+import { Message } from "@nan0web/co";

package/types/CommandError.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CommandError – error class representing a failure during command execution.
+ *
+ * @module CommandError
+ */
+/**
+ * @class
+ * @extends Error
+ */
+export default class CommandError extends Error {
+    /**
+     * Creates a command execution error.
+     *
+     * @param {string} message - Message that opens the path.
+     * @param {Object} [data=null] - Data to help find correct resonance.
+     */
+    constructor(message: string, data?: any);
+    data: any;
+}