@nan0web/ui-cli 1.0.2 → 1.1.0

package/src/test/PlaygroundTest.js

@@ -0,0 +1,157 @@
+/**
+ * PlaygroundTest – utilities for automated stdin sequence testing.
+ *
+ * Updated to handle errors gracefully and normalize output properly.
+ * Changes:
+ * - Caught EPIPE errors during setTimeout callback to prevent uncaught exceptions.
+ * - Normalize function now properly trims leading whitespace from each line.
+ */
+
+/* eslint-disable no-use-before-define */
+import { spawn } from "node:child_process"
+import event, { EventContext } from "@nan0web/event"
+
+/**
+ * @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 {
+	#bus
+	/**
+	 * @param {NodeJS.ProcessEnv} env Environment variables for the child process.
+	 * @param {{ includeDebugger?: boolean, includeEmptyLines?: boolean }} [config={}] Configuration options.
+	 */
+	constructor(env, config = {}) {
+		this.env = env
+		this.#bus = event()
+		/** @type {boolean} Include debugger lines in output (default: false). */
+		this.includeDebugger = config.includeDebugger ?? false
+		this.incldeEmptyLines = config.includeEmptyLines ?? false
+	}
+
+	/**
+	 * Subscribe to an event.
+	 */
+	on(event, fn) {
+		this.#bus.on(event, fn)
+	}
+	/**
+	 * Unsubscribe from an event.
+	 */
+	off(event, fn) {
+		this.#bus.off(event, fn)
+	}
+	/**
+	 * Emit an event.
+	 */
+	async emit(event, data) {
+		return await this.#bus.emit(event, data)
+	}
+	/**
+	 * Filter debugger related lines.
+	 */
+	filterDebugger(str) {
+		if (this.includeDebugger) return str
+		const words = ["debugger", "https://nodejs.org/en/docs/inspector"]
+		return str
+			.split("\n")
+			.filter(s => !words.some(w => s.toLowerCase().includes(w)))
+			.join("\n")
+	}
+	/**
+	 * Slice lines from stdout or stderr.
+	 */
+	slice(target, start, end) {
+		const txt = (this.recentResult?.[target] ?? "")
+		return txt.split("\n").slice(start, end)
+	}
+	/**
+	 * Write the answer sequence to the child process **asynchronously**,
+	 * waiting a short period after each prompt appears.
+	 *
+	 * @param {any} child – ChildProcess instance.
+	 */
+	async #feedSequence(child) {
+		const raw = this.env.PLAY_DEMO_SEQUENCE
+		if (!raw) return
+
+		const sequence = raw.split(",").map(s => s.trim()).filter(Boolean)
+		if (sequence.length === 0) return
+
+		if (child.stdin) child.stdin.setDefaultEncoding("utf-8")
+
+		const writeNext = (idx) => {
+			if (idx >= sequence.length) {
+				try {
+					child.stdin?.end()
+				} catch (_) { }
+				return
+			}
+			setTimeout(() => {
+				try {
+					if (!child.killed && child.stdin?.writable) {
+						child.stdin.write(`${sequence[idx]}\n`)
+						writeNext(idx + 1)
+					}
+				} catch (_) {
+					// Silently swallow EPIPE and stop feeding.
+				}
+			}, 200)
+		}
+		writeNext(0)
+	}
+	/**
+	 * Executes the playground script.
+	 *
+	 * @param {string[]} [args=["play/main.js"]] Arguments passed to the node process.
+	 */
+	async run(args = ["play/main.js"]) {
+		const child = spawn("node", args, {
+			env: this.env,
+			stdio: ["pipe", "pipe", "pipe"],
+		})
+
+		this.#feedSequence(child)
+
+		let stdout = ""
+		for await (const chunk of child.stdout) {
+			stdout += chunk.toString()
+			this.emit("stdout", { chunk })
+		}
+
+		let stderr = ""
+		for await (const chunk of child.stderr) {
+			const clean = this.filterDebugger(chunk.toString())
+			stderr += clean
+			this.emit("stderr", { chunk, clean })
+		}
+
+		const exitCode = await new Promise(resolve => child.on("close", resolve))
+
+		// Trim leading whitespace from every line – the test suite expects raw
+		// output without logger prefixes or indentation.
+		const normalize = txt => this.incldeEmptyLines ? txt
+			: txt.split("\n").filter(row => row.trim() !== "").join("\n")
+
+		this.recentResult = {
+			stdout: normalize(stdout),
+			stderr: normalize(stderr),
+			exitCode,
+		}
+		return this.recentResult
+	}
+}

package/src/test/index.js

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

package/src/ui/Adapter.js

@@ -0,0 +1,3 @@
+// export default class CLiUiAdapter extends UiAdapter {
+
+// }

package/src/ui/form.js

@@ -0,0 +1,254 @@
+/**
+ * Form module – generates and processes CLI forms from model schemas.
+ *
+ * @module ui/form
+ */
+
+import { CancelError } from "@nan0web/ui/core"
+import { createInput, Input } from "./input.js"
+import { select } from "./select.js"
+import { UiForm, FormInput } from "@nan0web/ui"
+
+/**
+ * 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, options = {}) {
+	const { initialState = {}, t } = options
+	const fields = []
+
+	for (const [name, schema] of Object.entries(BodyClass)) {
+		if (typeof schema !== "object" || schema === null) continue
+
+		const translate = (value) => (typeof t === "function" ? t(value) : value)
+
+		fields.push(
+			new FormInput({
+				name,
+				label: translate(schema.help || name),
+				type: schema.type || "text",
+				required: Boolean(schema.required),
+				placeholder: translate(schema.placeholder || schema.defaultValue || ""),
+				options: schema.options
+					? schema.options.map((opt) =>
+						typeof opt === "string"
+							? opt
+							: opt.label
+								? { label: opt.label, value: opt.value }
+								: opt,
+					)
+					: [],
+				validation: schema.validate
+					? (value) => {
+						const res = schema.validate(value)
+						return res === true ? true : typeof res === "string" ? res : `Invalid ${name}`
+					}
+					: () => true,
+			}),
+		)
+	}
+
+	return new UiForm({
+		title: t ? t(BodyClass.name) : BodyClass.name,
+		fields,
+		state: { ...initialState },
+	})
+}
+
+/**
+ * CLI-specific form handler that introspects a model class for static field schemas.
+ *
+ * @class
+ */
+export default class Form {
+	/** @type {Object} Model instance to update. */
+	#model
+	/** @type {Array} Configured fields derived from model schema. */
+	#fields = []
+	/** @type {Function} Input handler with cancellation support. */
+	handler
+
+	/**
+	 * @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, options = {}) {
+		if (!model || typeof model !== "object" || !model.constructor) {
+			throw new TypeError("Form requires a model instance with a constructor")
+		}
+		this.#model = model
+		const { stops = ["quit", "cancel", "exit"], inputFn } = options
+		this.handler = inputFn || createInput(stops)
+		this.#fields = this.#generateFields()
+	}
+
+	/**
+	 * Generates field configurations from the model's static schema.
+	 *
+	 * @returns {Array<{name:string,label:string,type:string,required:boolean,placeholder:string,options:Array,validation:Function}>}
+	 */
+	#generateFields() {
+		const Class = this.#model.constructor
+		const fields = []
+		for (const [name, schema] of Object.entries(Class)) {
+			if (typeof schema !== "object" || schema === null) continue
+			const isRequired = schema.required === true || schema.defaultValue === undefined
+			const placeholder = schema.placeholder || schema.defaultValue || ""
+			const options = schema.options || []
+			const validation = schema.validate
+				? (value) => {
+					const res = schema.validate(value)
+					if (res === true) return true
+					if (typeof res === "string") return res
+					return `Invalid ${name}`
+				}
+				: () => true
+			fields.push({
+				name,
+				label: schema.help || name,
+				type: schema.type || "text",
+				required: isRequired,
+				placeholder,
+				options,
+				validation,
+			})
+		}
+		return fields
+	}
+
+	/**
+	 * 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, initialModel = {}, options = {}) {
+		const model = new BodyClass(initialModel)
+		return new Form(model, options)
+	}
+
+	/**
+	 * Prompts for selection using the provided configuration.
+	 *
+	 * @param {Object} config - Selection configuration.
+	 * @returns {Promise<{index:number, value:any}>} Selected option.
+	 */
+	async select(config) {
+		return select(config)
+	}
+
+	/**
+	 * Prompts for input using the internal handler.
+	 *
+	 * @param {string} prompt - Input prompt.
+	 * @returns {Promise<Input>} Input result.
+	 */
+	async input(prompt) {
+		return this.handler(prompt)
+	}
+
+	/**
+	 * 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.
+	 */
+	async requireInput() {
+		let idx = 0
+		while (idx < this.#fields.length) {
+			const field = this.#fields[idx]
+			const currentValue = this.#model[field.name] ?? field.placeholder
+			const prompt = `${field.label}${field.required ? " *" : ""} [${currentValue}]: `
+			try {
+				if (field.options.length > 0) {
+					const selConfig = {
+						title: field.label,
+						prompt: "Choose (number): ",
+						options: field.options.map((opt) =>
+							typeof opt === "string" ? opt : opt.label ? { label: opt.label, value: opt.value } : opt,
+						),
+						console: { info: console.info.bind(console) },
+						ask: this.handler,
+					}
+					const selResult = await this.select(selConfig)
+					const val = selResult.value
+					const validRes = field.validation(val)
+					if (validRes !== true) {
+						console.error(`\n${validRes}`)
+						continue
+					}
+					this.#model[field.name] = this.convertValue(field, val)
+					idx++
+				} else {
+					const inputObj = await this.input(prompt)
+					if (inputObj.cancelled) {
+						return { cancelled: true }
+					}
+					let answer = inputObj.value.trim()
+					if (answer === "" && !field.required) {
+						this.#model[field.name] = ""
+						idx++
+						continue
+					}
+					const validRes = field.validation(answer)
+					if (validRes !== true) {
+						console.error(`\n${validRes}`)
+						continue
+					}
+					this.#model[field.name] = this.convertValue(field, answer)
+					idx++
+				}
+			} catch (e) {
+				if (e instanceof CancelError) {
+					return { cancelled: true }
+				}
+				throw e
+			}
+		}
+		return { cancelled: false }
+	}
+
+	/**
+	 * 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, value) {
+		const schema = this.#model.constructor[field.name]
+		const type = schema?.type || typeof (schema?.defaultValue ?? "string")
+		switch (type) {
+			case "number":
+				return Number(value) || 0
+			case "boolean":
+				return value.toLowerCase() === "true"
+			default:
+				return String(value)
+		}
+	}
+
+	/** @returns {Object} The updated model instance. */
+	get body() {
+		return this.#model
+	}
+}

package/src/ui/input.js

@@ -6,14 +6,31 @@
 
 import { createInterface } from "node:readline"
 import { stdin, stdout } from "node:process"
+import { CancelError } from "@nan0web/ui"
+
+/** @typedef {import("./select.js").ConsoleLike} ConsoleLike */
+/** @typedef {(input: Input) => Promise<boolean>} LoopFn */
+/** @typedef {(input: Input) => string} NextQuestionFn */
 
 /**
- * @typedef {Function} InputFn
+ * Input function.
+ * ---
+ * Must be used only as a type — typedef does not work with full arguments description for functions.
+ * ---
  * @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.
+ * @param {boolean | LoopFn} [loop=false] - Loop‑control flag, validator or boolean that forces a single answer.
+ * @param {string | NextQuestionFn} [nextQuestion] - When `false` the prompt ends after one answer.
+ *                                            When a `function` is supplied it receives the current {@link Input}
+ *                                            and must return a new question string for the next iteration.
+ *
+ * @returns {Promise<Input>} Resolves with an {@link Input} instance that contains the final answer,
+ *                           the raw value and cancellation state.
+ *
+ * @throws {Error} May propagate errors from the underlying readline interface.
  */
+export async function InputFn(question, loop = false, nextQuestion = undefined) {
+	return new Input()
+}
 
 /**
  * Represents a line of user input.
@@ -69,14 +86,37 @@ export class Input {
 }
 
 /**
- * Prompt a question and return the trimmed answer.
+ * Low‑level prompt that returns a trimmed string.
  *
- * @param {string} question - Text displayed as a prompt.
- * @returns {Promise<string>} User answer without surrounding whitespace.
+ * @param {Object} input
+ * @param {string} input.question - Text displayed as a prompt.
+ * @param {string} [input.predef] - Optional predefined answer (useful for testing).
+ * @param {ConsoleLike} [input.console] - Optional console to show predefined value
+ * @param {import("node:readline").Interface} [input.rl] - Readline interface instnace
+ * @returns {Promise<string>} The answer without surrounding whitespace.
+ *
+ * When `predef` is supplied the function mimics the usual readline output
+ * (`question + answer + newline`) and returns the trimmed value.
  */
-export async function ask(question) {
+export async function _askRaw(input) {
+	const {
+		question,
+		predef = undefined,
+		console,
+		rl: initialRL,
+	} = input
+	// Fast‑path for predefined answers – mimic readline output.
+	if (typeof predef === "string") {
+		if (console) {
+			console.info(`${question}${predef}\n`)
+		} else {
+			process.stdout.write(`${question}${predef}\n`)
+		}
+		return predef.trim()
+	}
+
 	return new Promise(resolve => {
-		const rl = createInterface({ input: stdin, output: stdout, terminal: true })
+		const rl = initialRL ?? createInterface({ input: stdin, output: stdout, terminal: true })
 		rl.question(question, answer => {
 			rl.close()
 			resolve(answer.trim())
@@ -88,33 +128,95 @@ export async function ask(question) {
  * Factory that creates a reusable async input handler.
  *
  * @param {string[]} [stops=[]] Words that trigger cancellation.
+ * @param {string|undefined} [predef] Optional predefined answer for testing.
+ * @param {ConsoleLike} [console] Optional console instance.
  * @returns {InputFn} Async function that resolves to an {@link Input}.
  */
-export function createInput(stops = []) {
+export function createInput(stops = [], predef = undefined, console = undefined) {
 	const input = new Input({ stops })
 
 	/**
 	 * 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.
+	 * @param {boolean | LoopFn} [loop=false] - Loop‑control flag or validator.
+	 * @param {string | NextQuestionFn} [nextQuestion=false] - Next prompt generator or its value.
 	 * @returns {Promise<Input>}
 	 */
-	async function fn(question, loop = false, nextQuestion = false) {
+	async function fn(question, loop = false, nextQuestion = undefined) {
+		let currentQuestion = question
 		while (true) {
-			input.value = await ask(question)
+			input.value = await _askRaw({ question: currentQuestion, predef, console })
 
 			if (false === loop || input.cancelled) return input
 			if (true === loop && input.value) return input
 			if (typeof loop === "function") {
-				if (!loop(input)) return input
+				const cont = await loop(input)
+				if (!cont) return input
 			}
-			if (typeof nextQuestion === "string") question = nextQuestion
-			if (typeof nextQuestion === "function") question = nextQuestion(input)
+			if (typeof nextQuestion === "string") currentQuestion = nextQuestion
+			if (typeof nextQuestion === "function") currentQuestion = nextQuestion(input)
 		}
 	}
 	return fn
 }
 
+/**
+ * High‑level input helper `ask`.
+ *
+ * This constant inherits the full {@link InputFn} signature **and** the
+ * detailed JSDoc description for each argument, as defined in {@link InputFn}.
+ *
+ * @type {InputFn}
+ */
+export const ask = createInput()
+
+/**
+ * @param {string[]} predefined
+ * @param {ConsoleLike} console
+ * @param {string[]} [stops=[]]
+ * @returns {import("./select.js").InputFn}
+ * @throws {CancelError}
+ */
+export function createPredefinedInput(predefined, console, stops = []) {
+	const strPredefined = predefined.map(String)
+	const input = new Input({ stops })
+	let index = 0
+	return async function predefinedHandler(question, loop = false, nextQuestion = undefined) {
+		let currentQuestion = question
+		while (true) {
+			if (index >= strPredefined.length) {
+				throw new CancelError("No more predefined answers")
+			}
+			const predef = strPredefined[index++]
+			if (console) {
+				console.info(`${currentQuestion}${predef}\n`)
+			} else {
+				process.stdout.write(`${currentQuestion}${predef}\n`)
+			}
+			input.value = predef.trim()
+			if (input.cancelled) {
+				return input
+			}
+			if (false === loop) {
+				return input
+			}
+			if (true === loop && input.value) {
+				return input
+			}
+			if (typeof loop === "function") {
+				const cont = await loop(input)
+				if (!cont) {
+					return input
+				}
+			}
+			if (typeof nextQuestion === "string") {
+				currentQuestion = nextQuestion
+			} else if (typeof nextQuestion === "function") {
+				currentQuestion = nextQuestion(input)
+			}
+		}
+	}
+}
+
 export default createInput