@nan0web/ui-cli 2.0.0 → 2.1.0

package/README.md

@@ -25,6 +25,49 @@ npm install @nan0web/ui-cli
 
 How to install the package?
 
+## nan0cli — Universal CLI Runner
+
+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.
+
+### App Contract
+
+Your app must export Messages from its entry point:
+
+```js
+// E1: Messages Array (recommended)
+export default [Serve, Dump]
+
+// E2: Single Message class (auto-wrapped to array)
+export default class MyApp { }
+```
+
+### 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" }
+  }
+}
+```
+
+nan0cli binary is registered
+
+### Error Handling
+
+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`.
+
+nan0cli is included in package files
+
 ## Usage (V2 Architecture)
 
 Starting from v2.0, we recommend using the `render()` function with Composable Components.

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": "2.0.0",
+	"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": {
 		".": {
@@ -57,17 +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.1.1",
 		"@nan0web/test": "1.1.0",
 		"@types/node": "^24.10.1",
 		"knip": "^5.83.0",
 		"prettier": "^3.8.1"
 	},
+	"bin": {
+		"nan0cli": "./bin/nan0cli.js"
+	},
 	"dependencies": {
+		"@nan0web/db-fs": "1.0.0",
 		"@nan0web/event": "^1.0.0",
-		"@nan0web/ui": "workspace:*",
+		"@nan0web/log": "1.1.1",
+		"@nan0web/ui": "^1.1.0",
 		"prompts": "^2.4.2"
 	}
-}
+}

package/src/README.md.js

@@ -110,6 +110,59 @@ function testRender() {
 		assert.equal(pkg.name, '@nan0web/ui-cli')
 	})
 
+	/**
+	 * @docs
+	 * ## nan0cli — Universal CLI Runner
+	 *
+	 * 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.
+	 *
+	 * ### App Contract
+	 *
+	 * Your app must export Messages from its entry point:
+	 *
+	 * ```js
+	 * // E1: Messages Array (recommended)
+	 * export default [Serve, Dump]
+	 *
+	 * // E2: Single Message class (auto-wrapped to array)
+	 * export default class MyApp { }
+	 * ```
+	 *
+	 * ### 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" }
+	 *   }
+	 * }
+	 * ```
+	 */
+	it('nan0cli binary is registered', () => {
+		assert.ok(pkg.bin?.nan0cli, 'bin.nan0cli must be defined')
+		assert.equal(pkg.bin.nan0cli, './bin/nan0cli.js')
+	})
+
+	/**
+	 * @docs
+	 *
+	 * ### Error Handling
+	 *
+	 * 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`.
+	 */
+	it('nan0cli is included in package files', () => {
+		assert.ok(pkg.files?.includes('bin/**/*.js'), 'bin/**/*.js must be in files array')
+	})
+
 	/**
 	 * @docs
 	 * ## Usage (V2 Architecture)
@@ -324,7 +377,9 @@ describe('README.md testing', testRender)
 
 describe('Rendering README.md', async () => {
 	const parser = new DocsParser()
-	const text = String(parser.decode(testRender))
+	// Read source as string — Bun strips comments from Function.toString()
+	const source = await fs.loadDocument('src/README.md.js', '')
+	const text = String(parser.decode(source))
 	await fs.saveDocument('README.md', text)
 
 	it('document is rendered', async () => {

package/src/index.js

@@ -3,6 +3,7 @@ import OutputAdapter from './OutputAdapter.js'
 import { CancelError } from '@nan0web/ui/core'
 import CLI from './CLI.js'
 import CommandParser from './CommandParser.js'
+import Form, { generateForm } from './ui/form.js'
 
 // V2 Component Exports
 import { render } from './core/render.js'
@@ -87,6 +88,11 @@ export {
 	CLI,
 	CommandParser,
 	OutputAdapter,
+	Form,
+	generateForm,
 }
 
+export { default as Command } from './Command.js'
+export { str2argv } from './utils/parse.js'
+
 export default CLiInputAdapter