@nan0web/ui-cli 1.0.0 → 1.0.2

package/README.md

@@ -4,9 +4,7 @@ A tiny, zero‑dependency UI input adapter for Java•Script projects.
 It provides a CLI implementation that can be easily integrated
 with application logic.
 
-|[Status](https://github.com/nan0web/monorepo/blob/main/system.md#написання-сценаріїв)|Documentation|Test coverage|Features|Npm version|
-|---|---|---|---|---|
- |🟢 `96.1%` |🧪 [English 🏴󠁧󠁢󠁥󠁮󠁧󠁿](https://github.com/nan0web/ui-cli/blob/main/README.md)<br />[Українською 🇺🇦](https://github.com/nan0web/ui-cli/blob/main/docs/uk/README.md) |🟡 `77.9%` |✅ d.ts 📜 system.md 🕹️ playground |— |
+<!-- %PACKAGE_STATUS% -->
 
 ## Description
 
@@ -78,9 +76,7 @@ const form = UIForm.from({
 	state: {},
 	validate: () => ({ isValid: true, errors: {} }),
 })
-
 const result = await adapter.requestForm(form, { silent: true })
-
 console.info(result.form.state) // ← { name: "John Doe", email: "John.Doe@example.com" }
 ```
 
@@ -97,9 +93,8 @@ const config = {
 		["uk", "Ukrainian"],
 	]),
 }
-
 const result = await adapter.requestSelect(config)
-console.info(result.value) // ← Message { body: "en", head: {} }
+console.info(result) // ← en
 ```
 ### Input Utilities
 
@@ -114,7 +109,6 @@ const input = new Input({ value: "test", stops: ["quit"] })
 console.info(String(input)) // ← test
 console.info(input.value) // ← test
 console.info(input.cancelled) // ← false
-
 input.value = "quit"
 console.info(input.cancelled) // ← true
 ```
@@ -125,7 +119,6 @@ Prompts the user with a question and returns a promise with the answer.
 How to ask a question with ask()?
 ```js
 import { ask } from "@nan0web/ui-cli"
-
 const result = await ask("What is your name?")
 console.info(result)
 ```
@@ -152,7 +145,6 @@ const config = {
 	options: ["Option A", "Option B", "Option C"],
 	console: console,
 }
-
 const result = await select(config)
 console.info(result.value)
 ```
@@ -163,7 +155,6 @@ Waits for a keypress to continue the process.
 How to pause and wait for keypress with next()?
 ```js
 import { next } from '@nan0web/ui-cli'
-
 const result = await next()
 console.info(typeof result === "string")
 ```

package/package.json

@@ -1,19 +1,25 @@
 {
 	"name": "@nan0web/ui-cli",
-	"version": "1.0.0",
+	"version": "1.0.2",
 	"description": "NaN•Web UI CLI. Command line interface for One application logic (algorithm) and many UI.",
 	"main": "src/index.js",
 	"types": "types/index.d.ts",
 	"type": "module",
+	"files": [
+		"src/**/*.js",
+		"!src/**/*.test.js",
+		"types/**/*.d.ts"
+	],
 	"scripts": {
 		"build": "tsc",
-		"test": "node --test --test-timeout=3333 \"src/**/*.test.js\" | nan0test parse --fail",
+		"test": "node --test --test-timeout=3333 \"src/**/*.test.js\"",
+		"test:nan0test": "node --test --test-timeout=3333 \"src/**/*.test.js\" | nan0test parse --fail",
 		"test:coverage": "node --experimental-test-coverage --test-coverage-include=\"src/**/*.js\" --test-coverage-exclude=\"src/**/*.test.js\" --test \"src/**/*.test.js\"",
 		"test:coverage:collect": "nan0test coverage",
 		"test:docs": "node --test --test-timeout=3333 src/README.md.js",
 		"test:release": "node --test \"releases/**/*.test.js\"",
 		"test:status": "nan0test status --hide-name --debug",
-		"playground": "node playground/main.js",
+		"play": "node play/main.js",
 		"precommit": "npm test",
 		"prepush": "npm test",
 		"prepare": "husky",
@@ -30,9 +36,13 @@
 	"author": "ЯRаСлав (YaRaSLove) <support@yaro.page>",
 	"license": "ISC",
 	"devDependencies": {
-		"@nan0web/log": "workspace:*",
-		"@nan0web/test": "workspace:*",
-		"@nan0web/ui": "workspace:*",
-		"@nan0web/db-fs": "workspace:*"
+		"@nan0web/db-fs": "1.0.0",
+		"@nan0web/i18n": "^1.0.1",
+		"@nan0web/log": "1.0.1",
+		"@nan0web/test": "1.1.0",
+		"@nan0web/ui": "1.0.3"
+	},
+	"dependencies": {
+		"@nan0web/co": "^1.1.3"
 	}
 }

package/src/CLI.js

@@ -0,0 +1,141 @@
+/**
+ * CLI – top‑level runner that orchestrates command execution and help generation.
+ *
+ * @module CLI
+ */
+
+import { Message, InputMessage, OutputMessage } from "@nan0web/co"
+import Logger from "@nan0web/log"
+import CommandParser from "./CommandParser.js"
+import CommandHelp from "./CommandHelp.js"
+
+/**
+ * Main CLI class.
+ */
+export default class CLI {
+	/** @type {string[]} */
+	argv = []
+	#commands = new Map()
+	/** @type {Logger} */
+	logger
+	/** @type {Array<Function>} */
+	Messages = []
+
+	/**
+	 * @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 = {}) {
+		const {
+			argv = process.argv.slice(2),
+			commands = {},
+			logger,
+			Messages = [],
+		} = input
+		this.argv = argv.map(String).filter(Boolean)
+		this.logger = logger ?? new Logger({ level: Logger.detectLevel(this.argv) })
+		this.Messages = Messages
+		this.#commands = new Map(Object.entries(commands))
+		this.#commands.set("help", () => this.#help())
+		if (Messages.length > 0) this.#registerMessageCommands(Messages)
+	}
+
+	/** @returns {Map<string,Function>} The command map. */
+	get commands() {
+		return this.#commands
+	}
+
+	/**
+	 * Register message‑based commands derived from classes.
+	 *
+	 * @param {any} cmdClasses - Array of Message classes exposing a `run` generator.
+	 */
+	#registerMessageCommands(cmdClasses) {
+		cmdClasses.forEach(Class => {
+			const cmd = Class.name.toLowerCase()
+			this.#commands.set(cmd, async function* (msg) {
+				const validated = new Class(msg.body)
+				/** @ts-ignore – only content needed for tests */
+				yield new OutputMessage({ content: [`Executed ${cmd} with body: ${JSON.stringify(validated.body)}`] })
+				if (typeof Class.run === "function") yield* Class.run(validated)
+			})
+		})
+	}
+
+	/**
+	 * Execute the CLI workflow.
+	 *
+	 * @param {Message} [msg] - Optional pre‑built message.
+	 * @yields {OutputMessage|InputMessage}
+	 */
+	async * run(msg) {
+		// @ts-ignore – `Message` may carry a `value` wrapper in some contexts
+		const command = msg?.value?.body?.command ?? this.#parseCommandName()
+		const fn = this.#commands.get(command)
+
+		if (!fn) {
+			yield { content: `Unknown command: ${command}` }
+			return
+		}
+
+		let fullMsg
+		if (this.Messages.length > 0) {
+			const parser = new CommandParser(this.Messages)
+			fullMsg = parser.parse(this.argv)
+			yield new InputMessage({ value: { body: { command } } })
+		} else {
+			fullMsg = msg ?? new InputMessage({ value: { body: { command } } })
+		}
+
+		for await (const out of fn(fullMsg)) {
+			if (out.isError) this.logger.error(out.content)
+			else this.logger.info(out.content)
+			yield out
+		}
+	}
+
+	/**
+	 * Determine the command name from the positional arguments.
+	 *
+	 * @returns {string}
+	 */
+	#parseCommandName() {
+		return this.argv.find(arg => !arg.startsWith("-")) || "help"
+	}
+
+	/**
+	 * Generate help output for all registered commands.
+	 *
+	 * @yields {OutputMessage}
+	 */
+	async * #help() {
+		const lines = ["Available commands:"]
+		for (const [name] of this.#commands) lines.push(`  ${name}`)
+		if (this.Messages.length > 0) {
+			lines.push("\nMessage‑based commands:")
+			this.Messages.forEach(Class => {
+				// @ts-ignore – `CommandHelp` expects a class extending `Message`; casting to any silences TS
+				const help = new CommandHelp(Class).generate().split("\n")[0]
+				lines.push(`  ${Class.name.toLowerCase()}: ${help}`)
+			})
+		}
+		/** @ts-ignore – output only needs `content` */
+		yield new OutputMessage({ content: lines })
+	}
+
+	/**
+	 * 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) {
+		if (input instanceof CLI) return input
+		if (input && typeof input === "object") return new CLI(input)
+		throw new TypeError("CLI.from expects an object or CLI instance")
+	}
+}

package/src/Command.js

@@ -0,0 +1,210 @@
+/**
+ * Command – defines a CLI command with options, sub‑commands and execution logic.
+ *
+ * @module Command
+ */
+
+import { Message } from "@nan0web/co"
+import CommandMessage from "./CommandMessage.js"
+import CommandError from "./CommandError.js"
+
+/**
+ * Represents a command definition.
+ *
+ * @class
+ * @deprecated Use CLI instead
+ */
+export default class Command {
+	/** @type {string} */ name = ""
+	/** @type {string} */ help = ""
+	/** @type {Object} */ options = {}
+	/** @type {Function} */ run = async function* () {}
+	/** @type {Command[]} */ children = []
+
+	/**
+	 * @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) {
+		this.name = config.name || ""
+		this.help = config.help || ""
+		this.options = config.options || {}
+		this.run = config.run || (async function* () {})
+		this.children = config.children || []
+	}
+
+	/**
+	 * Add a sub‑command.
+	 *
+	 * @param {Command} command - Sub‑command instance.
+	 * @returns {this}
+	 */
+	addSubcommand(command) {
+		this.children.push(command)
+		return this
+	}
+
+	/**
+	 * Find a sub‑command by name.
+	 *
+	 * @param {string} name - Sub‑command name.
+	 * @returns {Command|null}
+	 */
+	findSubcommand(name) {
+		return this.children.find(c => c.name === name) || null
+	}
+
+	/**
+	 * Parse argv into a {@link CommandMessage}.
+	 *
+	 * @param {string[]|string} argv - Arguments array or string.
+	 * @returns {CommandMessage}
+	 */
+	parse(argv) {
+		const args = Array.isArray(argv) ? argv : [argv]
+		const msg = new CommandMessage({ name: "", argv: [], opts: {} })
+		let i = 0
+		while (i < args.length) {
+			const cur = args[i]
+			if (cur.startsWith("--")) {
+				handleLongOption(msg, args, i)
+				i = updateIndexAfterOption(args, i)
+			} else if (cur.startsWith("-")) {
+				handleShortOption(msg, args, i)
+				i = updateIndexAfterOption(args, i)
+			} else {
+				if (!msg.name) msg.name = cur
+				else msg.argv.push(cur)
+				i++
+			}
+		}
+		if (msg.name === this.name) {
+			msg.argv = [...msg.argv]
+			msg.name = ""
+		}
+		if (msg.argv.length > 0) {
+			const subName = msg.argv[0]
+			const sub = this.findSubcommand(subName)
+			if (sub) {
+				const subMsg = sub.parse(msg.argv.slice(1))
+				msg.add(subMsg)
+				msg.name = subName
+				msg.argv = []
+			}
+		}
+		this._applyDefaults(msg)
+		return msg
+	}
+
+	/**
+	 * Generate a short help string.
+	 *
+	 * @returns {string}
+	 */
+	generateHelp() {
+		const parts = []
+		if (this.help) parts.push(this.help)
+		const optFlags = Object.keys(this.options).map(k => `--${k}`).join(" ")
+		parts.push(optFlags ? `Usage: ${this.name} ${optFlags}` : `Usage: ${this.name}`)
+		return parts.join("\n")
+	}
+
+	/**
+	 * Execute the command's run generator.
+	 *
+	 * @param {Message} message - Message passed to the runner.
+	 * @yields {any}
+	 * @throws {CommandError}
+	 */
+	async * execute(message) {
+		try {
+			if (typeof this.run === "function") yield* this.run(message)
+		} catch (e) {
+			if (e instanceof CommandError) throw e
+			/** @ts-ignore */
+			throw new CommandError("Command execution failed", { message: e.message, stack: e.stack })
+		}
+	}
+
+	/**
+	 * Apply default values from the options definition to the parsed message.
+	 *
+	 * @param {CommandMessage} msg
+	 * @private
+	 */
+	_applyDefaults(msg) {
+		for (const [opt, [type, def]] of Object.entries(this.options)) {
+			if (!(opt in msg.opts)) {
+				msg.opts[opt] = def !== undefined ? def : type === Boolean ? false : ""
+			}
+		}
+	}
+}
+
+/* ---------- helpers ---------- */
+
+/**
+ * Process a long option (`--flag` or `--flag=value`).
+ *
+ * @param {CommandMessage} msg
+ * @param {string[]} argv
+ * @param {number} index
+ * @private
+ */
+function handleLongOption(msg, argv, index) {
+	const cur = argv[index]
+	const eq = cur.indexOf("=")
+	if (eq > -1) {
+		const k = cur.slice(2, eq)
+		const v = cur.slice(eq + 1)
+		msg.opts[k] = v
+	} else {
+		const k = cur.slice(2)
+		if (index + 1 < argv.length && !argv[index + 1].startsWith("-")) {
+			msg.opts[k] = argv[index + 1]
+		} else {
+			msg.opts[k] = true
+		}
+	}
+}
+
+/**
+ * Process a short option (`-f` or combined `-abc`).
+ *
+ * @param {CommandMessage} msg
+ * @param {string[]} argv
+ * @param {number} index
+ * @private
+ */
+function handleShortOption(msg, argv, index) {
+	const cur = argv[index].slice(1)
+	if (cur.length > 1) {
+		for (const ch of cur) msg.opts[ch] = true
+	} else {
+		const k = cur
+		if (index + 1 < argv.length && !argv[index + 1].startsWith("-")) {
+			msg.opts[k] = argv[index + 1]
+		} else {
+			msg.opts[k] = true
+		}
+	}
+}
+
+/**
+ * Compute the next index after an option token.
+ *
+ * @param {string[]} argv
+ * @param {number} index
+ * @returns {number}
+ * @private
+ */
+function updateIndexAfterOption(argv, index) {
+	const cur = argv[index]
+	if (cur.includes("=")) return index + 1
+	const hasVal = index + 1 < argv.length && !argv[index + 1].startsWith("-")
+	return hasVal ? index + 2 : index + 1
+}

package/src/CommandError.js

@@ -0,0 +1,35 @@
+/**
+ * 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, data = null) {
+		super(message)
+		this.name = "CommandError"
+		this.data = data
+		Error.captureStackTrace(this, CommandError)
+	}
+
+	/**
+	 * Render the error as a string, optionally including attached data.
+	 *
+	 * @returns {string}
+	 */
+	toString() {
+		return this.data
+			? `${this.message}\n${JSON.stringify(this.data, null, 2)}`
+			: this.message
+	}
+}

package/src/CommandHelp.js

@@ -0,0 +1,204 @@
+import { Message } from "@nan0web/co"
+import Logger from "@nan0web/log"
+
+/**
+ * @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 {
+	/** @type {typeof Message} Message class the help is built for */
+	MessageClass
+	/** @type {Logger} Logger used for printing */
+	logger
+	/** @type {typeof Message.Body} Body class reference */
+	BodyClass
+
+	/**
+	 * @param {typeof Message} MessageClass - Message class with a schema.
+	 * @param {Logger} [logger=new Logger()] - Optional logger.
+	 */
+	constructor(MessageClass, logger = new Logger()) {
+		this.MessageClass = MessageClass
+		this.logger = logger
+		this.BodyClass = MessageClass.Body
+	}
+
+	/** @returns {typeof Logger} */
+	get Logger() {
+		return /** @type {typeof Logger} */ (this.logger.constructor)
+	}
+
+	/**
+	 * Generates the full help text.
+	 *
+	 * @returns {string} Formatted help text.
+	 */
+	generate() {
+		const lines = []
+		this.#header(lines)
+		this.#usage(lines)
+		this.#options(lines)
+		this.#subcommands(lines)
+		return lines.join("\n")
+	}
+
+	/**
+	 * Prints the generated help to the logger.
+	 */
+	print() {
+		this.logger.info(this.generate())
+	}
+
+	/**
+	 * Adds a coloured header.
+	 *
+	 * @param {string[]} lines - Accumulator array.
+	 */
+	#header(lines) {
+		const name = this.MessageClass.name.toLowerCase()
+		const help = this.MessageClass['help'] || ""
+		lines.push([
+			`${this.Logger.style(name, { color: this.Logger.MAGENTA })}`,
+			help
+		].filter(Boolean).join(" • "))
+		lines.push("")
+	}
+
+	/**
+	 * Constructs the usage line.
+	 *
+	 * @param {string[]} lines - Accumulator array.
+	 */
+	#usage(lines) {
+		const name = this.MessageClass.name.toLowerCase()
+		const bodyInstance = new this.BodyClass()
+		const bodyProps = Object.keys(bodyInstance)
+
+		if (bodyProps.length === 0) {
+			lines.push(`Usage: ${name}`)
+			lines.push("")
+			return
+		}
+
+		const placeholderParts = []
+		const flagParts = []
+
+		bodyProps.forEach(prop => {
+			/** @type {CommandHelpField} */
+			const schema = this.BodyClass[prop] || {}
+			const alias = schema.alias ? `-${schema.alias}, ` : ""
+			const placeholder = schema.placeholder || schema.defaultValue
+			if (placeholder) {
+				placeholderParts.push(`[${alias}--${prop}=${placeholder}]`)
+			} else {
+				flagParts.push(`[${alias}--${prop}]`)
+			}
+		})
+
+		// Build usage string respecting spacing rules:
+		//   * when only flags exist → separate with " , "
+		//   * when placeholders exist:
+		//       – if exactly ONE flag part → prepend with ", "
+		//       – otherwise just space‑separate all parts.
+		let usage = ""
+		if (placeholderParts.length) {
+			usage = placeholderParts.join(" ")
+			if (flagParts.length) {
+				if (flagParts.length === 1) {
+					usage = `${usage}, ${flagParts[0]}`
+				} else {
+					usage = `${usage} ${flagParts.join(" ")}`
+				}
+			}
+		} else {
+			// only flag parts
+			usage = flagParts.join(" , ")
+		}
+		lines.push(`Usage: ${name} ${usage}`)
+		lines.push("")
+	}
+
+	/**
+	 * Renders the Options section.
+	 *
+	 * @param {string[]} lines - Accumulator array.
+	 */
+	#options(lines) {
+		const bodyInstance = new this.BodyClass()
+		const bodyProps = Object.keys(bodyInstance)
+		if (bodyProps.length === 0) return
+
+		lines.push("Options:")
+		bodyProps.forEach(prop => {
+			/** @type {CommandHelpField} */
+			const schema = this.BodyClass[prop] || {}
+			if (typeof schema !== "object") return
+
+			const flags = schema.alias
+				? `--${prop}, -${schema.alias}`
+				: `--${prop}`
+
+			const type = undefined !== schema.type ? String(schema.type)
+				: undefined !== schema.defaultValue ? typeof schema.defaultValue
+				: undefined !== schema.placeholder ? typeof schema.placeholder
+				: "any"
+			const required = schema.required || schema.pattern || schema.defaultValue === undefined ? " *" : "  "
+			const description = schema.help || "No description"
+
+			// Pad flags to align the type column with the expectations.
+			lines.push(`  ${flags.padEnd(30)} ${type.padEnd(9)}${required} ${description}`)
+		})
+		lines.push("")
+	}
+
+	/**
+	 * @param {object} body
+	 * @returns {Map<string, any>} A map of errors, empty map if no errors.
+	 */
+	validate(body) {
+		const Class = /** @type {typeof this.BodyClass} */ (body.constructor)
+		const result = new Map()
+		for (const [name, schema] of Object.entries(Class)) {
+			const fn = schema?.validate
+			if ("function" !== typeof fn) continue
+			const ok = fn.apply(body, [body[name]])
+			if (true === ok) continue
+			result.set(name, ok)
+		}
+		return result
+	}
+
+	/**
+	 * Renders Subcommands, if any.
+	 *
+	 * @param {string[]} lines - Accumulator array.
+	 */
+	#subcommands(lines) {
+		const children = this.MessageClass['Children'] || []
+		if (children.length === 0) return
+
+		lines.push("Subcommands:")
+		children.forEach(ChildClass => {
+			const childName = ChildClass.name.toLowerCase()
+			const childHelp = ChildClass.help || "No description"
+			lines.push(`  ${childName.padEnd(20)}  ${childHelp}`)
+		})
+		lines.push("")
+	}
+}