@nan0web/ui-cli 1.1.0 → 2.0.0

package/src/Command.js

@@ -4,9 +4,9 @@
  * @module Command
  */
 
-import { Message } from "@nan0web/co"
-import CommandMessage from "./CommandMessage.js"
-import CommandError from "./CommandError.js"
+import { Message } from '@nan0web/co'
+import CommandMessage from './CommandMessage.js'
+import CommandError from './CommandError.js'
 
 /**
  * Represents a command definition.
@@ -15,8 +15,8 @@ import CommandError from "./CommandError.js"
  * @deprecated Use CLI instead
  */
 export default class Command {
-	/** @type {string} */ name = ""
-	/** @type {string} */ help = ""
+	/** @type {string} */ name = ''
+	/** @type {string} */ help = ''
 	/** @type {Object} */ options = {}
 	/** @type {Function} */ run = async function* () {}
 	/** @type {Command[]} */ children = []
@@ -30,10 +30,10 @@ export default class Command {
 	 * @param {Command[]} [config.children] - Sub‑commands.
 	 */
 	constructor(config) {
-		this.name = config.name || ""
-		this.help = config.help || ""
+		this.name = config.name || ''
+		this.help = config.help || ''
 		this.options = config.options || {}
-		this.run = config.run || (async function* () {})
+		this.run = config.run || async function* () {}
 		this.children = config.children || []
 	}
 
@@ -55,7 +55,7 @@ export default class Command {
 	 * @returns {Command|null}
 	 */
 	findSubcommand(name) {
-		return this.children.find(c => c.name === name) || null
+		return this.children.find((c) => c.name === name) || null
 	}
 
 	/**
@@ -66,14 +66,14 @@ export default class Command {
 	 */
 	parse(argv) {
 		const args = Array.isArray(argv) ? argv : [argv]
-		const msg = new CommandMessage({ name: "", argv: [], opts: {} })
+		const msg = new CommandMessage({ name: '', argv: [], opts: {} })
 		let i = 0
 		while (i < args.length) {
 			const cur = args[i]
-			if (cur.startsWith("--")) {
+			if (cur.startsWith('--')) {
 				handleLongOption(msg, args, i)
 				i = updateIndexAfterOption(args, i)
-			} else if (cur.startsWith("-")) {
+			} else if (cur.startsWith('-')) {
 				handleShortOption(msg, args, i)
 				i = updateIndexAfterOption(args, i)
 			} else {
@@ -84,7 +84,7 @@ export default class Command {
 		}
 		if (msg.name === this.name) {
 			msg.argv = [...msg.argv]
-			msg.name = ""
+			msg.name = ''
 		}
 		if (msg.argv.length > 0) {
 			const subName = msg.argv[0]
@@ -108,9 +108,11 @@ export default class Command {
 	generateHelp() {
 		const parts = []
 		if (this.help) parts.push(this.help)
-		const optFlags = Object.keys(this.options).map(k => `--${k}`).join(" ")
+		const optFlags = Object.keys(this.options)
+			.map((k) => `--${k}`)
+			.join(' ')
 		parts.push(optFlags ? `Usage: ${this.name} ${optFlags}` : `Usage: ${this.name}`)
-		return parts.join("\n")
+		return parts.join('\n')
 	}
 
 	/**
@@ -120,13 +122,13 @@ export default class Command {
 	 * @yields {any}
 	 * @throws {CommandError}
 	 */
-	async * execute(message) {
+	async *execute(message) {
 		try {
-			if (typeof this.run === "function") yield* this.run(message)
+			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 })
+			throw new CommandError('Command execution failed', { message: e.message, stack: e.stack })
 		}
 	}
 
@@ -139,7 +141,7 @@ export default class Command {
 	_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 : ""
+				msg.opts[opt] = def !== undefined ? def : type === Boolean ? false : ''
 			}
 		}
 	}
@@ -157,14 +159,14 @@ export default class Command {
  */
 function handleLongOption(msg, argv, index) {
 	const cur = argv[index]
-	const eq = cur.indexOf("=")
+	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("-")) {
+		if (index + 1 < argv.length && !argv[index + 1].startsWith('-')) {
 			msg.opts[k] = argv[index + 1]
 		} else {
 			msg.opts[k] = true
@@ -186,7 +188,7 @@ function handleShortOption(msg, argv, index) {
 		for (const ch of cur) msg.opts[ch] = true
 	} else {
 		const k = cur
-		if (index + 1 < argv.length && !argv[index + 1].startsWith("-")) {
+		if (index + 1 < argv.length && !argv[index + 1].startsWith('-')) {
 			msg.opts[k] = argv[index + 1]
 		} else {
 			msg.opts[k] = true
@@ -204,7 +206,7 @@ function handleShortOption(msg, argv, index) {
  */
 function updateIndexAfterOption(argv, index) {
 	const cur = argv[index]
-	if (cur.includes("=")) return index + 1
-	const hasVal = index + 1 < argv.length && !argv[index + 1].startsWith("-")
+	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

@@ -17,7 +17,7 @@ export default class CommandError extends Error {
 	 */
 	constructor(message, data = null) {
 		super(message)
-		this.name = "CommandError"
+		this.name = 'CommandError'
 		this.data = data
 		Error.captureStackTrace(this, CommandError)
 	}
@@ -28,8 +28,6 @@ export default class CommandError extends Error {
 	 * @returns {string}
 	 */
 	toString() {
-		return this.data
-			? `${this.message}\n${JSON.stringify(this.data, null, 2)}`
-			: this.message
+		return this.data ? `${this.message}\n${JSON.stringify(this.data, null, 2)}` : this.message
 	}
-}
+}

package/src/CommandHelp.js

@@ -1,5 +1,5 @@
-import { Message } from "@nan0web/co"
-import Logger from "@nan0web/log"
+import { Message } from '@nan0web/co'
+import Logger from '@nan0web/log'
 
 /**
  * @typedef {Object} CommandHelpField MessageBodySchema
@@ -55,7 +55,7 @@ export default class CommandHelp {
 		this.#usage(lines)
 		this.#options(lines)
 		this.#subcommands(lines)
-		return lines.join("\n")
+		return lines.join('\n')
 	}
 
 	/**
@@ -72,12 +72,13 @@ export default class CommandHelp {
 	 */
 	#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("")
+		const help = this.MessageClass['help'] || ''
+		lines.push(
+			[`${this.Logger.style(name, { color: this.Logger.MAGENTA })}`, help]
+				.filter(Boolean)
+				.join(' • ')
+		)
+		lines.push('')
 	}
 
 	/**
@@ -92,17 +93,17 @@ export default class CommandHelp {
 
 		if (bodyProps.length === 0) {
 			lines.push(`Usage: ${name}`)
-			lines.push("")
+			lines.push('')
 			return
 		}
 
 		const placeholderParts = []
 		const flagParts = []
 
-		bodyProps.forEach(prop => {
+		bodyProps.forEach((prop) => {
 			/** @type {CommandHelpField} */
 			const schema = this.BodyClass[prop] || {}
-			const alias = schema.alias ? `-${schema.alias}, ` : ""
+			const alias = schema.alias ? `-${schema.alias}, ` : ''
 			const placeholder = schema.placeholder || schema.defaultValue
 			if (placeholder) {
 				placeholderParts.push(`[${alias}--${prop}=${placeholder}]`)
@@ -116,22 +117,22 @@ export default class CommandHelp {
 		//   * when placeholders exist:
 		//       – if exactly ONE flag part → prepend with ", "
 		//       – otherwise just space‑separate all parts.
-		let usage = ""
+		let usage = ''
 		if (placeholderParts.length) {
-			usage = placeholderParts.join(" ")
+			usage = placeholderParts.join(' ')
 			if (flagParts.length) {
 				if (flagParts.length === 1) {
 					usage = `${usage}, ${flagParts[0]}`
 				} else {
-					usage = `${usage} ${flagParts.join(" ")}`
+					usage = `${usage} ${flagParts.join(' ')}`
 				}
 			}
 		} else {
 			// only flag parts
-			usage = flagParts.join(" , ")
+			usage = flagParts.join(' , ')
 		}
 		lines.push(`Usage: ${name} ${usage}`)
-		lines.push("")
+		lines.push('')
 	}
 
 	/**
@@ -144,27 +145,30 @@ export default class CommandHelp {
 		const bodyProps = Object.keys(bodyInstance)
 		if (bodyProps.length === 0) return
 
-		lines.push("Options:")
-		bodyProps.forEach(prop => {
+		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"
+			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("")
+		lines.push('')
 	}
 
 	/**
@@ -185,12 +189,12 @@ export default class CommandHelp {
 		const children = this.MessageClass['Children'] || []
 		if (children.length === 0) return
 
-		lines.push("Subcommands:")
-		children.forEach(ChildClass => {
+		lines.push('Subcommands:')
+		children.forEach((ChildClass) => {
 			const childName = ChildClass.name.toLowerCase()
-			const childHelp = ChildClass.help || "No description"
+			const childHelp = ChildClass.help || 'No description'
 			lines.push(`  ${childName.padEnd(20)}  ${childHelp}`)
 		})
-		lines.push("")
+		lines.push('')
 	}
 }

package/src/CommandMessage.js

@@ -4,9 +4,9 @@
  * @module CommandMessage
  */
 
-import { Message } from "@nan0web/co"
-import { str2argv } from "./utils/parse.js"
-import CommandError from "./CommandError.js"
+import { Message } from '@nan0web/co'
+import { str2argv } from './utils/parse.js'
+import CommandError from './CommandError.js'
 
 /**
  * @class
@@ -14,7 +14,7 @@ import CommandError from "./CommandError.js"
  * @extends Message
  */
 export default class CommandMessage extends Message {
-	#name = ""
+	#name = ''
 	#argv = []
 	#opts = {}
 	#children = []
@@ -30,14 +30,8 @@ export default class CommandMessage extends Message {
 	constructor(input = {}) {
 		super(input)
 		/** @type {any} */
-		const data = typeof input === "object" && !Array.isArray(input) ? input : {}
-		const {
-			name = "",
-			argv = [],
-			opts = {},
-			children = [],
-			body = {},
-		} = data
+		const data = typeof input === 'object' && !Array.isArray(input) ? input : {}
+		const { name = '', argv = [], opts = {}, children = [], body = {} } = data
 
 		const fullBody = { ...body, ...opts }
 		this.body = fullBody
@@ -45,9 +39,9 @@ export default class CommandMessage extends Message {
 		this.#name = String(name)
 		this.#argv = argv.map(String)
 		this.#opts = opts
-		this.#children = children.map(c => CommandMessage.from(c))
+		this.#children = children.map((c) => CommandMessage.from(c))
 
-		if (typeof input === "string" || Array.isArray(input)) {
+		if (typeof input === 'string' || Array.isArray(input)) {
 			const parsed = CommandMessage.parse(input)
 			this.#name = parsed.name
 			this.#argv = parsed.argv
@@ -57,38 +51,60 @@ export default class CommandMessage extends Message {
 	}
 
 	/** @returns {string} */
-	get name() { return this.#name }
+	get name() {
+		return this.#name
+	}
 	/** @param {string} v */
-	set name(v) { this.#name = String(v) }
+	set name(v) {
+		this.#name = String(v)
+	}
 
 	/** @returns {string[]} */
-	get argv() { return this.#argv }
+	get argv() {
+		return this.#argv
+	}
 	/** @param {string[]} v */
-	set argv(v) { this.#argv = v.map(String) }
+	set argv(v) {
+		this.#argv = v.map(String)
+	}
 
 	/** @returns {Object} */
-	get opts() { return this.#opts }
+	get opts() {
+		return this.#opts
+	}
 	/** @param {Object} v */
-	set opts(v) { this.#opts = v }
+	set opts(v) {
+		this.#opts = v
+	}
 
 	/** @returns {Array<CommandMessage>} */
-	get children() { return this.#children }
+	get children() {
+		return this.#children
+	}
 
 	/** @returns {Array<string>} Full command line (name + args). */
-	get args() { return [this.name, ...this.argv].filter(Boolean) }
+	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 || "" }
+	get subCommand() {
+		return this.children[0]?.name || ''
+	}
 
 	/** @returns {CommandMessage|null} First child message, or null. */
-	get subCommandMessage() { return this.children[0] || 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)) }
+	add(msg) {
+		this.#children.push(CommandMessage.from(msg))
+	}
 
 	/**
 	 * Convert the message back to a command‑line string.
@@ -98,9 +114,9 @@ export default class CommandMessage extends Message {
 	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(" ")
+			.join(' ')
+		const argsStr = this.argv.join(' ')
+		return [this.name, argsStr, optsStr].filter(Boolean).join(' ')
 	}
 
 	/**
@@ -112,37 +128,37 @@ export default class CommandMessage extends Message {
 	 * @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: {} }
+		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("-")) {
+		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 (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("-")) {
+					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) {
+			} else if (cur.startsWith('-') && cur.length > 1) {
 				const shorts = cur.slice(1)
 				if (shorts.length > 1) {
-					shorts.split("").forEach(s => (result.opts[s] = true))
+					shorts.split('').forEach((s) => (result.opts[s] = true))
 				} else {
 					const k = shorts
-					if (i + 1 < argv.length && !argv[i + 1].startsWith("-")) {
+					if (i + 1 < argv.length && !argv[i + 1].startsWith('-')) {
 						result.opts[k] = argv[++i]
 					} else {
 						result.opts[k] = true
@@ -160,7 +176,7 @@ export default class CommandMessage extends Message {
 			msg.body = body
 			/** @ts-ignore */
 			const errors = body.getErrors?.() || {}
-			if (Object.keys(errors).length) throw new CommandError("Validation failed", { errors })
+			if (Object.keys(errors).length) throw new CommandError('Validation failed', { errors })
 		}
 		return msg
 	}
@@ -175,7 +191,7 @@ export default class CommandMessage extends Message {
 		if (input instanceof CommandMessage) return input
 		if (input instanceof Message) {
 			/** @ts-ignore */
-			return new CommandMessage({ body: input.body, name: input.name || "" })
+			return new CommandMessage({ body: input.body, name: input.name || '' })
 		}
 		return new CommandMessage(input)
 	}

package/src/CommandParser.js

@@ -4,10 +4,10 @@
  * @module CommandParser
  */
 
-import { Message } from "@nan0web/co"
-import CommandHelp from "./CommandHelp.js"
-import CommandError from "./CommandError.js"
-import { str2argv } from "./utils/parse.js"
+import { Message } from '@nan0web/co'
+import CommandHelp from './CommandHelp.js'
+import CommandError from './CommandError.js'
+import { str2argv } from './utils/parse.js'
 
 /**
  * @class
@@ -31,18 +31,16 @@ export default class CommandParser {
 	 * @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")
+		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("-")) {
+		if (!argv[0].startsWith('-')) {
 			rootName = argv[0]
 			remaining = argv.slice(1)
 
-			let RootClass = this.Messages.find(
-				cls => cls.name.toLowerCase() === rootName.toLowerCase(),
-			)
+			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}`)
@@ -56,7 +54,7 @@ export default class CommandParser {
 			return this.#processMessageTree(rootMessage, remaining)
 		}
 
-		if (this.Messages.length !== 1) throw new Error("Unable to infer root command from options")
+		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
@@ -81,7 +79,7 @@ export default class CommandParser {
 			const subName = remaining[0]
 			// @ts-ignore
 			const SubClass = currentMessage.constructor.Children.find(
-				cls => cls.name.toLowerCase() === subName.toLowerCase(),
+				(cls) => cls.name.toLowerCase() === subName.toLowerCase()
 			)
 			if (!SubClass) break
 
@@ -97,14 +95,14 @@ export default class CommandParser {
 			const parsedBody = this.#parseLeafBody(
 				remaining,
 				// @ts-ignore – `Body` may be undefined on some classes
-				currentMessage.constructor.Body,
+				currentMessage.constructor.Body
 			)
 			currentMessage.body = { ...currentMessage.body, ...parsedBody }
 		}
 
 		if (
 			rootMessage.body.subCommand &&
-			typeof rootMessage.body.subCommand.assertValid === "function"
+			typeof rootMessage.body.subCommand.assertValid === 'function'
 		) {
 			rootMessage.body.subCommand.assertValid()
 		}
@@ -125,23 +123,23 @@ export default class CommandParser {
 		for (let i = 0; i < tokens.length; i++) {
 			const token = tokens[i]
 
-			if (token.startsWith("--")) {
+			if (token.startsWith('--')) {
 				let key = token.slice(2)
 				/** @type {boolean | string} */
 				let value = true
-				const eqIdx = key.indexOf("=")
+				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("-")) {
+				} 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) {
+			} else if (token.startsWith('-') && token.length > 1) {
 				const short = token.slice(1)
 				if (short.length > 1) {
-					short.split("").forEach(ch => {
+					short.split('').forEach((ch) => {
 						const realKey = this.#resolveAlias(ch, BodyClass)
 						if (realKey && props.includes(realKey)) body[realKey] = true
 					})
@@ -150,10 +148,15 @@ export default class CommandParser {
 					if (props.includes(realKey)) {
 						/** @type {boolean | string} */
 						let value = true
-						if (i + 1 < tokens.length && !tokens[i + 1].startsWith("-")) {
+						if (i + 1 < tokens.length && !tokens[i + 1].startsWith('-')) {
 							value = tokens[++i]
 						}
-						body[realKey] = this.#convertType(body[realKey], value)
+						const type = typeof body[realKey]
+						if ('object' === type && Array.isArray(body[realKey])) {
+							body[realKey].push(this.#convertType(body[realKey], value))
+						} else {
+							body[realKey] = this.#convertType(body[realKey], value)
+						}
 					}
 				}
 			} else {
@@ -162,7 +165,7 @@ export default class CommandParser {
 			}
 		}
 
-		props.forEach(prop => {
+		props.forEach((prop) => {
 			const schema = BodyClass[prop]
 			if (schema?.default !== undefined && body[prop] === undefined) {
 				body[prop] = schema.default
@@ -199,9 +202,8 @@ export default class CommandParser {
 	 */
 	#convertType(defaultVal, value) {
 		const type = typeof defaultVal
-		if (type === "boolean")
-			return Boolean(value !== "false" && value !== false && value !== "")
-		if (type === "number") return Number(value) || 0
+		if (type === 'boolean') return Boolean(value !== 'false' && value !== false && value !== '')
+		if (type === 'number') return Number(value) || 0
 		return String(value)
 	}