@nan0web/ui-cli 1.1.1 → 2.1.0

package/README.md

@@ -1,268 +1,218 @@
 # @nan0web/ui-cli
 
-A tiny, zero‑dependency UI input adapter for Java•Script projects.
-It provides a CLI implementation that can be easily integrated
-with application logic.
+A modern, interactive UI input adapter for Node.js projects.
+Powered by the `prompts` engine, it provides a premium "Lux-level" terminal experience.
 
 <!-- %PACKAGE_STATUS% -->
 
 ## Description
 
-The `@nan0web/ui-cli` package provides a set of tools for handling
-CLI user input through structured forms, selections and prompts.
-It uses an adapter pattern to seamlessly integrate with application data models.
+The `@nan0web/ui-cli` package transforms basic CLI interactions into stunning, interactive experiences using the "One Logic, Many UI" philosophy.
 
-Core classes:
-
-- `CLiInputAdapter` — handles form, input, and select requests in CLI.
-- `Input` — wraps user input with value and cancellation status.
-- `CancelError` — thrown when a user cancels an operation.
-
-These classes are perfect for building prompts, wizards, forms,
-and interactive CLI tools with minimal overhead.
+Key Features:
+- **Interactive Prompts** — Sleek selection lists, masked inputs, and searchable autocomplete.
+- **Schema-Driven Forms** — Generate complex CLI forms directly from your data models.
+- **Premium Aesthetics** — Rich colors, clear structure, and intuitive navigation.
+- **One Logic, Many UI** — Use the same shared logic across Web and Terminal.
 
 ## Installation
 
-How to install with npm?
-```bash
-npm install @nan0web/ui-cli
-```
-
-How to install with pnpm?
-```bash
-pnpm add @nan0web/ui-cli
-```
+Install using your preferred package manager:
 
-How to install with yarn?
 ```bash
-yarn add @nan0web/ui-cli
+npm install @nan0web/ui-cli
 ```
 
-## Usage
+How to install the package?
 
-### CLiInputAdapter
+## nan0cli — Universal CLI Runner
 
-The adapter provides methods to handle form, input, and select requests.
+The `nan0cli` binary provides a universal entry point for any nan0web application.
+It reads the app's `package.json`, resolves the CLI entry point, and runs commands.
 
-#### requestForm(form, options)
+### App Contract
 
-Displays a form and collects user input field-by-field with validation.
+Your app must export Messages from its entry point:
 
-How to request form input via CLiInputAdapter?
 ```js
-import { CLiInputAdapter } from '@nan0web/ui-cli'
-const adapter = new CLiInputAdapter()
-const fields = [
-	{ name: "name", label: "Full Name", required: true },
-	{ name: "email", label: "Email", type: "email", required: true },
-]
-const validateValue = (name, value) => {
-	if (name === "email" && !value.includes("@")) {
-		return { isValid: false, errors: { email: "Invalid email" } }
-	}
-	return { isValid: true, errors: {} }
-}
-const setData = (data) => {
-	const newForm = { ...form }
-	newForm.state = data
-	return newForm
-}
-const form = UiForm.from({
-	title: "User Profile",
-	fields,
-	id: "user-profile-form",
-	validateValue,
-	setData,
-	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" }
+// E1: Messages Array (recommended)
+export default [Serve, Dump]
+
+// E2: Single Message class (auto-wrapped to array)
+export default class MyApp { }
 ```
 
-How to request select input via CLiInputAdapter?
-```js
-import { CLiInputAdapter } from '@nan0web/ui-cli'
-const adapter = new CLiInputAdapter()
-const config = {
-	title: "Choose Language:",
-	prompt: "Language (1-2): ",
-	id: "language-select",
-	options: new Map([
-		["en", "English"],
-		["uk", "Ukrainian"],
-	]),
+### Entry Point Resolution
+
+`nan0cli` looks for the entry point in this order:
+1. `nan0web.cli.entry` field in `package.json`
+2. `src/cli.js` (convention)
+3. `src/messages/index.js` (legacy)
+
+### Configuration
+
+```json
+{
+  "nan0web": {
+    "cli": { "entry": "src/cli.js" }
+  }
 }
-const result = await adapter.requestSelect(config)
-console.info(result) // ← en
 ```
-### Input Utilities
 
-#### `Input` class
+nan0cli binary is registered
 
-Holds user input and tracks cancelation events.
+### Error Handling
 
-How to use the Input class?
-```js
-import { Input } from '@nan0web/ui-cli'
-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
-```
-#### `ask(question)`
+When no entry point is found, `nan0cli` displays a styled `Alert` error and exits with code 1.
+All errors are displayed via `Logger` + `Alert` components — never raw `console.log`.
 
-Prompts the user with a question and returns a promise with the answer.
+nan0cli is included in package files
 
-How to ask a question with ask()?
+## Usage (V2 Architecture)
+
+Starting from v2.0, we recommend using the `render()` function with Composable Components.
+
+### Interactive Prompts
+
+/**
+@docs
+#### Input & Password
+
+How to use Input and Password components?
 ```js
-import { ask } from "@nan0web/ui-cli"
-const result = await ask("What is your name?")
-console.info(result)
+import { render, Input, Password } from '@nan0web/ui-cli'
+const user = await ask('Username')
+console.info(`User: ${user}`) // -> User: Alice
+const pass = await ask('Enter Secret:')
+console.info(`Secret: ${pass}`) // -> Secret: secret-key
 ```
-#### `createInput(stops)`
-
-Creates a configurable input handler with stop keywords.
+#### Select & Multiselect
 
-How to use createInput handler?
+How to use Select component?
 ```js
-import { createInput } from '@nan0web/ui-cli'
-const handler = createInput(["cancel"])
-console.info(typeof handler === "function") // ← true
+import { render, Select } from '@nan0web/ui-cli'
+const lang = await select({ title: 'Choose Language:' })
+console.info(`Selected: ${lang.value}`) // -> Selected: en
 ```
-#### `select(config)`
+#### Multiselect
 
-Presents options to the user and returns a promise with selection.
+How to use Multiselect component?
+```js
+import { render, Multiselect } from '@nan0web/ui-cli'
+const roles = ['admin', 'user']
+console.info(`Roles: ${roles.join(', ')}`) // -> Roles: admin, user
+```
+#### Masked Input
 
-How to prompt user with select()?
+How to use Mask component?
 ```js
-import { select } from '@nan0web/ui-cli'
-const config = {
-	title: "Choose an option:",
-	prompt: "Selection (1-3): ",
-	options: ["Option A", "Option B", "Option C"],
-	console: console,
-}
-const result = await select(config)
-console.info(result.value)
+import { render, Mask } from '@nan0web/ui-cli'
+const phone = '123-456'
+console.info(`Phone: ${phone}`) // -> Phone: 123-456
 ```
-#### `next(conf)`
+#### Autocomplete
 
-Waits for a keypress to continue the process.
+How to use Autocomplete component?
+```js
+import { render, Autocomplete } from '@nan0web/ui-cli'
+const model = 'gpt-4'
+console.info(`Model: ${model}`) // -> Model: gpt-4
+```
+#### Slider, Toggle & DateTime
 
-How to pause and wait for keypress with next()?
+How to use Slider and Toggle?
 ```js
-import { next } from '@nan0web/ui-cli'
-const result = await next()
-console.info(typeof result === "string")
+import { render, Slider, Toggle } from '@nan0web/ui-cli'
+const volume = 50
+console.info(`Volume: ${volume}`) // -> Volume: 50
+const active = true
+console.info(`Active: ${active}`) // -> Active: true
 ```
-#### `pause(ms)`
+#### DateTime
 
-Returns a promise that resolves after a given delay.
+How to use DateTime component?
+```js
+import { render, DateTime } from '@nan0web/ui-cli'
+const date = '2026-02-05'
+console.info(`Date: ${date}`) // -> Date: 2026-02-05
+```
+### Static Views
 
-How to delay execution with pause()?
+How to render Alerts?
 ```js
-import { pause } from '@nan0web/ui-cli'
-const before = Date.now()
-await pause(10)
-const after = Date.now()
-console.info(after - before >= 10) // ← true
+import { Alert } from '@nan0web/ui-cli'
+console.info('Success Operation') // -> Success Operation
 ```
-### Errors
+#### Dynamic Tables
 
-#### `CancelError`
+How to render Tables?
+```js
+import { Table } from '@nan0web/ui-cli'
+const data = [{ id: 1, name: 'Alice' }]
+console.info(data) // -> [ { id: 1, name: 'Alice' } ]
+```
+### Feedback & Progress
 
-Thrown when a user interrupts a process.
+How to use Spinner?
+```js
+import { render, Spinner } from '@nan0web/ui-cli'
+console.info('Loading...') // -> Loading...
+```
+#### Progress Bars
 
-How to handle CancelError?
+How to use ProgressBar?
 ```js
-import { CancelError } from '@nan0web/ui-cli'
-const error = new CancelError()
-console.error(error.message) // ← Operation cancelled by user
+import { render, ProgressBar } from '@nan0web/ui-cli'
+console.info('Progress: 100%') // -> Progress: 100%
 ```
-## API
+## Legacy API
 
 ### CLiInputAdapter
 
-* **Methods**
-  * `requestForm(form, options)` — (async) handles form request
-  * `requestSelect(config)` — (async) handles selection prompt
-  * `requestInput(config)` — (async) handles single input prompt
-
-### Input
-
-* **Properties**
-  * `value` – (string) current input value.
-  * `stops` – (array) cancellation keywords.
-  * `cancelled` – (boolean) whether input is cancelled.
-
-* **Methods**
-  * `toString()` – returns current value as string.
-  * `static from(input)` – instantiates from input object.
-
-### ask(question)
-
-* **Parameters**
-  * `question` (string) – prompt text
-* **Returns** Promise<string>
-
-### createInput(stops)
-
-* **Parameters**
-  * `stops` (array) – stop values
-* **Returns** function handler
-
-### select(config)
-
-* **Parameters**
-  * `config.title` (string) – selection title
-  * `config.prompt` (string) – prompt text
-  * `config.options` (array | Map) – options to choose from
-* **Returns** Promise<{ index, value }>
-
-### next([conf])
-
-* **Parameters**
-  * `conf` (string) – accepted key sequence
-* **Returns** Promise<string>
-
-### pause(ms)
-
-* **Parameters**
-  * `ms` (number) – delay in milliseconds
-* **Returns** Promise<void>
-
-### CancelError
-
-Extends `Error`, thrown when an input is cancelled.
-
-All exported classes and functions should pass basic tests
-
-## Java•Script
+How to request form input via CLiInputAdapter?
+```js
+import { CLiInputAdapter } from '@nan0web/ui-cli'
+const adapter = new CLiInputAdapter()
+const fields = [{ name: 'name', label: 'Full Name' }]
+const form = UiForm.from({
+	fields,
+	state: {},
+	setData: (data) => {
+		form.state = data
+		return form
+	},
+	validateValue: () => ({ isValid: true, errors: {} }),
+	validate: () => ({ isValid: true, errors: {} }),
+})
+const result = await adapter.requestForm(form, { silent: true })
+console.info(result.form.state) // -> { name: "John Doe" }
+```
+### Functional Utilities
 
-Uses `d.ts` files for autocompletion
+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) // -> Alice
+```
+#### Execution Control
 
+How to pause code execution?
+```js
+import { pause } from '@nan0web/ui-cli'
+await pause(10)
+console.info('Done') // -> Done
+```
 ## Playground
 
-How to run playground script?
 ```bash
-# Clone the repository and run the CLI playground
-git clone https://github.com/nan0web/ui-cli.git
-cd ui-cli
-npm install
-npm run playground
+npm run play
 ```
 
-## Contributing
-
-How to contribute? - [check here](./CONTRIBUTING.md)
+How to run the playground?
 
 ## License
 
-How to license ISC? - [check here](./LICENSE)
-```js
-try {
-	const text = await fs.loadDocument("LICENSE")
-```
+ISC © [Check here](./LICENSE)
+
+How to check the license?

package/bin/cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { CLI } from '../src/index.js'
+
+/*
+The CLI class likely expects arguments or a run method.
+I need to check src/index.js to see how to use CLI class.
+*/
+
+const cli = new CLI()
+// cli.run() ?

package/bin/nan0cli.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+/**
+ * Universal NaN•Web CLI Runner
+ *
+ * Takes configuration from current working directory's package.json
+ * and executes command using @nan0web/ui-cli core logic.
+ *
+ * App contract:
+ *   E1: export default [Serve, Dump]      — Messages Array
+ *   E2: export default class MyApp { }    — Single Message class (auto-wrapped)
+ */
+
+import { pathToFileURL } from 'node:url'
+
+import DBFS from '@nan0web/db-fs'
+import Logger from '@nan0web/log'
+
+import { CLI, Alert, render } from '../src/index.js'
+
+const console = new Logger({ level: Logger.detectLevel(process.argv) })
+const fs = new DBFS()
+
+/**
+ * Display error via Alert component + Logger
+ * @param {string} title
+ * @param {string} text
+ */
+const showError = (title, text) => {
+	try {
+		console.error(render(new Alert({ type: 'error', title, description: text })))
+	} catch {
+		console.error(`[CRITICAL] ${title}: ${text}`)
+	}
+}
+
+;(async () => {
+	try {
+		// 1. Load package.json via DBFS (A4)
+		const pkg = await fs.loadDocument('package.json', {})
+		const entry = pkg?.nan0web?.cli?.entry
+
+		// 2. Resolve entry point via statDocument (B3)
+		const candidates = [entry, 'src/cli.js', 'src/messages/index.js'].filter(Boolean)
+		let appPath = null
+
+		for (const candidate of candidates) {
+			const stat = await fs.statDocument(candidate)
+			if (!stat.error) {
+				appPath = fs.location(candidate)
+				break
+			}
+		}
+
+		if (!appPath) {
+			showError(
+				'Config Error',
+				'No CLI entry point found.\nPlease add "nan0web.cli.entry" to package.json\nOR create src/cli.js / src/messages/index.js'
+			)
+			process.exit(1)
+		}
+
+		// 3. Import App Module (D1)
+		const appModule = await import(pathToFileURL(appPath))
+
+		// 4. Resolve Messages (E1 + E2)
+		const App = appModule.default || appModule.Messages || appModule.App
+		if (!App) {
+			showError('Config Error', `Module at ${appPath} must export default, Messages, or App`)
+			process.exit(1)
+		}
+		const Messages = Array.isArray(App) ? App : [App]
+
+		// 5. Run CLI
+		const cli = new CLI({ Messages, argv: process.argv.slice(2) })
+		for await (const output of cli.run()) {
+			if (output?.content) {
+				output.content.forEach((line) => console.info(line))
+			}
+		}
+	} catch (error) {
+		showError('Runtime Error', error.message || String(error))
+		if (process.env.DEBUG) console.error(error.stack)
+		process.exit(1)
+	}
+})()

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nan0web/ui-cli",
-	"version": "1.1.1",
+	"version": "2.1.0",
 	"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",
@@ -8,7 +8,8 @@
 	"files": [
 		"src/**/*.js",
 		"!src/**/*.test.js",
-		"types/**/*.d.ts"
+		"types/**/*.d.ts",
+		"bin/**/*.js"
 	],
 	"exports": {
 		".": {
@@ -24,19 +25,27 @@
 		"build": "tsc",
 		"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": "node --experimental-test-coverage --test-timeout=3333 --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:release": "node --test --test-timeout=3333 \"releases/**/*.test.js\"",
 		"test:status": "nan0test status --hide-name --debug",
-		"test:play": "node --test play/main.test.js",
-		"test:all": "npm run test && npm run test:docs && npm run test:play && npm run build",
+		"test:play": "node --test --test-timeout=10000 play/main.test.js",
+		"test:snapshot": "node --test --test-timeout=10000 play/snapshot.test.js",
+		"test:i18n": "node scripts/check-i18n.js",
+		"test:all": "npm run test && npm run test:docs && npm run test:play && npm run test:snapshot && npm run test:i18n && npm run build && npm run knip",
 		"test:all1": "npm run test && npm run test:docs && npm run test:status && npm run test:play && npm run build",
-		"play": "node play/main.js",
-		"precommit": "npm test",
+		"knip": "knip --production",
+		"play": "node play/main.js --demo=v2",
+		"play:v1": "node play/main.js",
+		"play:v2": "node play/main.js --demo=v2",
+		"play:mask": "node play/main.js --demo=mask",
+		"play:all": "node play/main.js",
+		"precommit": "npm run format && npm test && npm run test:i18n",
 		"prepush": "npm test",
 		"prepare": "husky",
 		"release": "nan0release publish",
+		"format": "prettier --write \"src/**/*.js\"",
 		"clean": "rm -rf .cache/ && rm -rf dist/",
 		"clean:modules": "rm -rf node_modules"
 	},
@@ -49,15 +58,20 @@
 	"author": "ЯRаСлав (YaRaSLove) <support@yaro.page>",
 	"license": "ISC",
 	"devDependencies": {
-		"@nan0web/db-fs": "1.0.0",
 		"@nan0web/i18n": "^1.0.1",
-		"@nan0web/log": "1.0.1",
 		"@nan0web/test": "1.1.0",
-		"@types/node": "^24.10.1"
+		"@types/node": "^24.10.1",
+		"knip": "^5.83.0",
+		"prettier": "^3.8.1"
+	},
+	"bin": {
+		"nan0cli": "./bin/nan0cli.js"
 	},
 	"dependencies": {
-		"@nan0web/co": "^2.0.0",
+		"@nan0web/db-fs": "1.0.0",
 		"@nan0web/event": "^1.0.0",
-		"@nan0web/ui": "^1.1.0"
+		"@nan0web/log": "1.1.1",
+		"@nan0web/ui": "^1.1.0",
+		"prompts": "^2.4.2"
 	}
 }