@nan0web/ui-cli 1.0.0 → 1.0.2

package/src/CommandMessage.js

@@ -0,0 +1,181 @@
+/**
+ * CommandMessage – generalized CLI message representation.
+ *
+ * @module CommandMessage
+ */
+
+import { Message } from "@nan0web/co"
+import { str2argv } from "./utils/parse.js"
+import CommandError from "./CommandError.js"
+
+/**
+ * @class
+ * @extends Message
+ */
+export default class CommandMessage extends Message {
+	#name = ""
+	#argv = []
+	#opts = {}
+	#children = []
+
+	/**
+	 * @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 = {}) {
+		super(input)
+		/** @type {any} */
+		const data = typeof input === "object" && !Array.isArray(input) ? input : {}
+		const {
+			name = "",
+			argv = [],
+			opts = {},
+			children = [],
+			body = {},
+		} = data
+
+		const fullBody = { ...body, ...opts }
+		this.body = fullBody
+
+		this.#name = String(name)
+		this.#argv = argv.map(String)
+		this.#opts = opts
+		this.#children = children.map(c => CommandMessage.from(c))
+
+		if (typeof input === "string" || Array.isArray(input)) {
+			const parsed = CommandMessage.parse(input)
+			this.#name = parsed.name
+			this.#argv = parsed.argv
+			this.#opts = parsed.opts
+			this.body = { ...this.body, ...parsed.opts }
+		}
+	}
+
+	/** @returns {string} */
+	get name() { return this.#name }
+	/** @param {string} v */
+	set name(v) { this.#name = String(v) }
+
+	/** @returns {string[]} */
+	get argv() { return this.#argv }
+	/** @param {string[]} v */
+	set argv(v) { this.#argv = v.map(String) }
+
+	/** @returns {Object} */
+	get opts() { return this.#opts }
+	/** @param {Object} v */
+	set opts(v) { this.#opts = v }
+
+	/** @returns {Array<CommandMessage>} */
+	get children() { return this.#children }
+
+	/** @returns {Array<string>} Full command line (name + args). */
+	get args() { return [this.name, ...this.argv].filter(Boolean) }
+
+	/** @returns {string} Sub‑command name of the first child, or empty string. */
+	get subCommand() { return this.children[0]?.name || "" }
+
+	/** @returns {CommandMessage|null} First child message, or null. */
+	get subCommandMessage() { return this.children[0] || null }
+
+	/**
+	 * Append a child {@link CommandMessage}.
+	 *
+	 * @param {CommandMessage|Object} msg
+	 */
+	add(msg) { this.#children.push(CommandMessage.from(msg)) }
+
+	/**
+	 * Convert the message back to a command‑line string.
+	 *
+	 * @returns {string}
+	 */
+	toString() {
+		const optsStr = Object.entries(this.opts)
+			.map(([k, v]) => (v === true ? `--${k}` : `--${k} ${String(v)}`))
+			.join(" ")
+		const argsStr = this.argv.join(" ")
+		return [this.name, argsStr, optsStr].filter(Boolean).join(" ")
+	}
+
+	/**
+	 * 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, BodyClass) {
+		if (typeof argv === "string") argv = str2argv(argv)
+		if (argv.length === 0) throw new CommandError("No input provided")
+		const result = { name: "", argv: [], opts: {} }
+		let i = 0
+		if (!argv[0].startsWith("-")) {
+			result.name = argv[0]
+			i = 1
+		}
+		while (i < argv.length) {
+			const cur = argv[i]
+			if (cur.startsWith("--")) {
+				const eq = cur.indexOf("=")
+				if (eq > -1) {
+					const k = cur.slice(2, eq)
+					const v = cur.slice(eq + 1)
+					result.opts[k] = v
+				} else {
+					const k = cur.slice(2)
+					if (i + 1 < argv.length && !argv[i + 1].startsWith("-")) {
+						result.opts[k] = argv[++i]
+					} else {
+						result.opts[k] = true
+					}
+				}
+			} else if (cur.startsWith("-") && cur.length > 1) {
+				const shorts = cur.slice(1)
+				if (shorts.length > 1) {
+					shorts.split("").forEach(s => (result.opts[s] = true))
+				} else {
+					const k = shorts
+					if (i + 1 < argv.length && !argv[i + 1].startsWith("-")) {
+						result.opts[k] = argv[++i]
+					} else {
+						result.opts[k] = true
+					}
+				}
+			} else {
+				/** @ts-ignore */
+				result.argv.push(cur)
+			}
+			i++
+		}
+		const msg = new CommandMessage(result)
+		if (BodyClass) {
+			const body = new BodyClass(result.opts)
+			msg.body = body
+			/** @ts-ignore */
+			const errors = body.getErrors?.() || {}
+			if (Object.keys(errors).length) throw new CommandError("Validation failed", { errors })
+		}
+		return msg
+	}
+
+	/**
+	 * Convert a raw input into a {@link CommandMessage} instance.
+	 *
+	 * @param {CommandMessage|Message|Object|string|Array<string>} input
+	 * @returns {CommandMessage}
+	 */
+	static from(input) {
+		if (input instanceof CommandMessage) return input
+		if (input instanceof Message) {
+			/** @ts-ignore */
+			return new CommandMessage({ body: input.body, name: input.name || "" })
+		}
+		return new CommandMessage(input)
+	}
+}

package/src/CommandParser.js

@@ -0,0 +1,217 @@
+/**
+ * CommandParser – parses argv into a hierarchical message tree supporting sub‑commands.
+ *
+ * @module CommandParser
+ */
+
+import { Message } from "@nan0web/co"
+import CommandHelp from "./CommandHelp.js"
+import CommandError from "./CommandError.js"
+import { str2argv } from "./utils/parse.js"
+
+/**
+ * @class
+ */
+export default class CommandParser {
+	/** @type {Array<Function>} */
+	Messages
+
+	/**
+	 * @param {Array<Function>} [Messages=[]] - Root message classes.
+	 */
+	constructor(Messages = []) {
+		this.Messages = Array.isArray(Messages) ? Messages : [Messages]
+	}
+
+	/**
+	 * 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 = process.argv.slice(2)) {
+		const argv = typeof input === "string" ? str2argv(input) : input
+		if (argv.length === 0) throw new Error("No command provided")
+		let rootName = null
+		let remaining = argv
+
+		if (!argv[0].startsWith("-")) {
+			rootName = argv[0]
+			remaining = argv.slice(1)
+
+			let RootClass = this.Messages.find(
+				cls => cls.name.toLowerCase() === rootName.toLowerCase(),
+			)
+			if (!RootClass) {
+				if (this.Messages.length === 1) RootClass = this.Messages[0]
+				else throw new Error(`Unknown root command: ${rootName}`)
+			}
+			// @ts-ignore – `RootClass` may not be a concrete `Message` subclass from TS view
+			const rootMessage = new RootClass({})
+			if (rootName) {
+				if (!rootMessage.head) rootMessage.head = {}
+				rootMessage.head.name = rootName
+			}
+			return this.#processMessageTree(rootMessage, remaining)
+		}
+
+		if (this.Messages.length !== 1) throw new Error("Unable to infer root command from options")
+		// @ts-ignore – see comment above
+		const RootClass = this.Messages[0]
+		// @ts-ignore
+		const rootMessage = new RootClass({})
+		if (!rootMessage.head) rootMessage.head = {}
+		return this.#processMessageTree(rootMessage, remaining)
+	}
+
+	/**
+	 * Walk the message tree and attach sub‑commands and leaf arguments.
+	 *
+	 * @param {Message} rootMessage - Root message instance.
+	 * @param {string[]} remainingTokens - Tokens yet to be processed.
+	 * @returns {Message}
+	 */
+	#processMessageTree(rootMessage, remainingTokens) {
+		let currentMessage = rootMessage
+		let remaining = remainingTokens
+
+		// @ts-ignore – `Children` is a static property on concrete message classes
+		while (currentMessage.constructor.Children && remaining.length) {
+			const subName = remaining[0]
+			// @ts-ignore
+			const SubClass = currentMessage.constructor.Children.find(
+				cls => cls.name.toLowerCase() === subName.toLowerCase(),
+			)
+			if (!SubClass) break
+
+			// @ts-ignore
+			const subMessage = new SubClass({})
+			subMessage.name = subName
+			currentMessage.body.subCommand = subMessage
+			currentMessage = subMessage
+			remaining = remaining.slice(1)
+		}
+
+		if (remaining.length) {
+			const parsedBody = this.#parseLeafBody(
+				remaining,
+				// @ts-ignore – `Body` may be undefined on some classes
+				currentMessage.constructor.Body,
+			)
+			currentMessage.body = { ...currentMessage.body, ...parsedBody }
+		}
+
+		if (
+			rootMessage.body.subCommand &&
+			typeof rootMessage.body.subCommand.assertValid === "function"
+		) {
+			rootMessage.body.subCommand.assertValid()
+		}
+		return rootMessage
+	}
+
+	/**
+	 * Parse leaf‑level arguments into the provided body class.
+	 *
+	 * @param {string[]} tokens - Remaining CLI tokens.
+	 * @param {typeof Message} BodyClass - Class defining fields and validation.
+	 * @returns {Object} Instance of BodyClass populated with parsed values.
+	 */
+	#parseLeafBody(tokens, BodyClass) {
+		const body = new BodyClass()
+		const props = Object.keys(body)
+
+		for (let i = 0; i < tokens.length; i++) {
+			const token = tokens[i]
+
+			if (token.startsWith("--")) {
+				let key = token.slice(2)
+				/** @type {boolean | string} */
+				let value = true
+				const eqIdx = key.indexOf("=")
+				if (eqIdx > -1) {
+					value = key.slice(eqIdx + 1)
+					key = key.slice(0, eqIdx)
+				} else if (i + 1 < tokens.length && !tokens[i + 1].startsWith("-")) {
+					value = tokens[++i]
+				}
+				const realKey = this.#resolveAlias(key, BodyClass) || key
+				if (props.includes(realKey)) body[realKey] = this.#convertType(body[realKey], value)
+			} else if (token.startsWith("-") && token.length > 1) {
+				const short = token.slice(1)
+				if (short.length > 1) {
+					short.split("").forEach(ch => {
+						const realKey = this.#resolveAlias(ch, BodyClass)
+						if (realKey && props.includes(realKey)) body[realKey] = true
+					})
+				} else {
+					const realKey = this.#resolveAlias(short, BodyClass) || short
+					if (props.includes(realKey)) {
+						/** @type {boolean | string} */
+						let value = true
+						if (i + 1 < tokens.length && !tokens[i + 1].startsWith("-")) {
+							value = tokens[++i]
+						}
+						body[realKey] = this.#convertType(body[realKey], value)
+					}
+				}
+			} else {
+				const first = props[0]
+				if (first) body[first] = token
+			}
+		}
+
+		props.forEach(prop => {
+			const schema = BodyClass[prop]
+			if (schema?.default !== undefined && body[prop] === undefined) {
+				body[prop] = schema.default
+			}
+			const err = schema?.validate?.(body[prop], body)
+			if (err !== undefined && err !== null && err !== true) {
+				throw new CommandError(`Invalid ${prop}: ${err}`, { [prop]: err })
+			}
+		})
+
+		return body
+	}
+
+	/**
+	 * Resolve an alias to its full property name.
+	 *
+	 * @param {string} alias
+	 * @param {Function} BodyClass
+	 * @returns {string|null}
+	 */
+	#resolveAlias(alias, BodyClass) {
+		for (const [prop, schema] of Object.entries(BodyClass)) {
+			if (schema?.alias === alias) return prop
+		}
+		return null
+	}
+
+	/**
+	 * Convert a raw CLI string to the appropriate JavaScript type.
+	 *
+	 * @param {*} defaultVal - The default value used for type inference.
+	 * @param {*} value - Raw parsed value.
+	 * @returns {*}
+	 */
+	#convertType(defaultVal, value) {
+		const type = typeof defaultVal
+		if (type === "boolean")
+			return Boolean(value !== "false" && value !== false && value !== "")
+		if (type === "number") return Number(value) || 0
+		return String(value)
+	}
+
+	/**
+	 * Generate help text for a given message class.
+	 *
+	 * @param {typeof Message} MessageClass
+	 * @returns {string}
+	 */
+	generateHelp(MessageClass) {
+		return new CommandHelp(MessageClass).generate()
+	}
+}

package/src/InputAdapter.js

@@ -1,219 +1,148 @@
-import { Message } from '@nan0web/co'
-import { UIForm, InputAdapter as BaseInputAdapter, InputMessage as BaseInputMessage } from '@nan0web/ui'
-import { ask } from './ui/input.js'
-import { select } from './ui/select.js'
-
-/** @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.
+ * CLIInputAdapter – bridges UI‑CLI utilities with generic UI core.
  *
- * 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.
+ * @module InputAdapter
  */
-class FormMessage extends BaseInputMessage {
-	/** @type {UIForm} Form data associated with the message */
-	form
 
-	/**
-	 * 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 = {}) {
-		const {
-			form = {},
-			...rest
-		} = props
-		// Initialise the parent with the remaining properties.
-		// Cast to `any` to avoid type‑mismatch between duplicated InputMessage
-		// definitions across packages.
-		super(/** @type {any} */ (rest))
-
-		// Store the UIForm; accept an object, UIForm or a plain payload.
-		this.form = UIForm.from(form)
-	}
-
-	/**
-	 * 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) {
-		if (input instanceof FormMessage) return input
-		const {
-			form = {},
-			...rest
-		} = input ?? {}
-		return new FormMessage({ form, ...rest })
-	}
-}
+import { Message } from "@nan0web/co"
+import {
+	UIForm,
+	InputAdapter as BaseInputAdapter,
+} from "@nan0web/ui"
+import { ask } from "./ui/input.js"
+import { select } from "./ui/select.js"
+import { CancelError } from "@nan0web/ui/core"
 
 /**
- * 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.
 	 */
 	async requestForm(form, options = {}) {
 		const { silent = true } = options
-
-		if (!silent) {
-			console.log(`\n${form.title}\n`)
-		}
+		if (!silent) console.log(`\n${form.title}\n`)
 
 		let formData = { ...form.state }
-		let currentFieldIndex = 0
-
-		while (currentFieldIndex < form.fields.length) {
-			const field = form.fields[currentFieldIndex]
-			const prompt = field.label || field.name
-
-			const input = await this.ask(`${prompt}${field.required ? ' *' : ''}: `)
-
-			// Cancel (Esc or empty string)
-			if ([FormMessage.ESCAPE, ''].includes(input)) {
-				return FormMessage.from({
+		let idx = 0
+
+		while (idx < form.fields.length) {
+			const field = form.fields[idx]
+			const prompt = `${field.label || field.name}${field.required ? " *" : ""}: `
+			const answer = await this.ask(prompt)
+
+			if (["", "esc"].includes(answer)) {
+				// @ts-ignore – `UIForm` may not expose `id` in its TS definition
+				// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+				return {
+					// @ts-ignore
+					body: { action: "form-cancel", escaped: true, form: {}, id: form.id },
 					form: {},
 					escaped: true,
-					action: 'form-cancel',
+					action: "form-cancel",
+					// @ts-ignore
 					id: form.id,
-				})
+				}
 			}
 
-			// Navigation shortcuts
-			const trimmed = input.trim()
-			if (trimmed === '::prev' || trimmed === '::back') {
-				currentFieldIndex = Math.max(0, currentFieldIndex - 1)
+			const trimmed = answer.trim()
+			if (trimmed === "::prev" || trimmed === "::back") {
+				idx = Math.max(0, idx - 1)
 				continue
 			}
-			if (trimmed === '::next' || trimmed === '::skip') {
-				currentFieldIndex++
+			if (trimmed === "::next" || trimmed === "::skip") {
+				idx++
 				continue
 			}
-
-			// Skip optional fields when empty
-			if (trimmed === '' && !field.required) {
-				currentFieldIndex++
+			if (trimmed === "" && !field.required) {
+				idx++
+				continue
+			}
+			if (field.required && trimmed === "") {
+				console.log("\nField is required.")
 				continue
 			}
-
-			// Validate using the form's schema / field definition
 			const schema = field.constructor
 			const { isValid, errors } = form.validateValue(field.name, trimmed, schema)
 			if (!isValid) {
-				const errorMessages = Object.values(errors)
-				console.log(`\x1b[31mError: ${errorMessages.join(', ')}\x1b[0m`)
-				continue // stay on current field
+				console.log("\n" + Object.values(errors).join("\n"))
+				continue
 			}
-
-			// Store validated value
 			formData[field.name] = trimmed
-			currentFieldIndex++
+			idx++
 		}
 
-		// Final form validation
 		const finalForm = form.setData(formData)
 		const { isValid, errors } = finalForm.validate()
 		if (!isValid) {
-			console.log('\n' + Object.values(errors).join('\n'))
-			return await this.requestForm(form, options) // retry recursively
+			console.log("\n" + Object.values(errors).join("\n"))
+			return await this.requestForm(form, options)
 		}
 
-		return FormMessage.from({
+		// @ts-ignore – `UIForm` may not expose `id`
+		// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+		return {
+			// @ts-ignore
+			body: { action: "form-submit", escaped: false, form: finalForm, id: form.id },
 			form: finalForm,
 			escaped: false,
-			action: 'form-submit',
+			action: "form-submit",
+			// @ts-ignore
 			id: form.id,
-		})
+		}
 	}
 
 	/**
-	 * 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.
 	 */
 	async requestSelect(config) {
 		try {
 			const result = await this.select({
-				title: config.title ?? 'Select an option:',
-				prompt: config.prompt ?? 'Choose (1‑N): ',
+				title: config.title ?? "Select an option:",
+				prompt: config.prompt ?? "Choose (1‑N): ",
 				options: config.options,
 				console: console,
 			})
-			return BaseInputMessage.from({
-				value: result.value,
-				data: result,
-				id: config.id,
-			})
-		} catch (error) {
-			if (error instanceof this.CancelError) {
-				return BaseInputMessage.from({
-					value: '',
-					id: config.id,
-				})
-			}
-			throw error
+			return result.value
+		} catch (e) {
+			if (e instanceof CancelError) return ""
+			throw e
 		}
 	}
 
 	/**
-	 * 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.
 	 */
 	async requestInput(config) {
 		const prompt = config.prompt ?? `${config.label ?? config.name}: `
 		const input = await this.ask(prompt)
-
-		if (input === '') {
-			return BaseInputMessage.from({
-				value: '',
-				id: config.id,
-			})
-		}
-
-		return BaseInputMessage.from({
-			value: input,
-			id: config.id,
-		})
+		return input
 	}
 
 	/** @inheritDoc */
 	async ask(question) {
 		return ask(question)
 	}
-
 	/** @inheritDoc */
-	async select(config) {
-		return select(config)
+	async select(cfg) {
+		return select(cfg)
 	}
 }