@nan0web/ui-cli 1.0.0

package/src/ui/select.test.js

@@ -0,0 +1,34 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { select } from './select.js'
+import { CancelError } from '@nan0web/ui/core'
+
+describe('Select utility', () => {
+	it('should throw error for empty options', async () => {
+		await assert.rejects(
+			select({
+				title: 'Test',
+				prompt: 'Choose:',
+				options: [],
+				console: console
+			}),
+			Error
+		)
+	})
+
+	it('should throw CancelError for cancellation', async () => {
+		// Мокаємо ask для скасування
+		const mockAsk = () => Promise.resolve({ cancelled: true })
+
+		await assert.rejects(
+			select({
+				title: 'Test',
+				prompt: 'Choose:',
+				options: ['option1', 'option2'],
+				console: console,
+				ask: mockAsk
+			}),
+			CancelError
+		)
+	})
+})

package/system.md

@@ -0,0 +1,99 @@
+---
+PROJECT_NAME: "ui-cli"
+VERSION: "1.0.0"
+CORE_PRINCIPLE: "Універсальний CLI‑адаптер – простота + надійність."
+VALIDATION_PHRASE: "UI‑CLI відповідає"
+FAILURE_RESPONSE: "Це — не UI‑CLI. Я не можу працювати далі."
+IDENTITY_MODEL: "Я / тИ / мИ / вИ"
+LOGIC_BASE: "Запит → відповідь → валідація → результат"
+---
+
+# ✨ UI‑CLI – системне керівництво
+
+> **Мета** – надати мінімальний, беззалежний інтерфейс вводу/виводу для Node‑CLI‑додатків, що працює без сторонніх бібліотек, лише чистий JavaScript.
+
+## 📦 Основні компоненти
+
+| Компонент | Опис | Експорт |
+|----------|------|---------|
+| `CLIInputAdapter` | Клас‑адаптер, що обгортає процес запиту форм, окремих полів та списків. | `default`, `CLIInputAdapter` |
+| `Input` | Об’єкт, який зберігає рядок вводу та статус скасування. | `Input` |
+| `CancelError` | Помилка, кидається при скасуванні запиту. | `CancelError` |
+| `ask` | Проста функція‑проміс, що виводить питання та повертає відповідь. | `ask` |
+| `createInput` | Фабрика, що створює кастомізований обробник вводу з ключовими словами «stop». | `createInput` |
+| `select` | Генерує список варіантів, приймає номер, повертає обраний `value`. | `select` |
+| `next` | Очікує будь‑яку клавішу (можна вказати схеми). | `next` |
+| `pause` | Пауза на вказану кількість мілісекунд. | `pause` |
+
+## 🚀 Швидкий старт
+
+```bash
+npm i @nan0web/ui-cli
+```
+
+```js
+import {
+	CLIInputAdapter,
+	ask,
+	select,
+	next,
+	pause,
+	CancelError,
+	Input,
+	createInput,
+} from '@nan0web/ui-cli'
+
+const adapter = new CLIInputAdapter()
+
+// Приклад: простий запит
+const name = await adapter.ask('Ваше ім’я?')
+console.log('Вітаємо,', name)
+
+// Приклад: вибір зі списку
+const lang = await adapter.select({
+	title: 'Виберіть мову',
+	prompt: 'Введіть номер: ',
+	options: new Map([['en', 'English'], ['uk', 'Українська']]),
+	console: console,
+})
+console.log('Обрана мова:', lang.value)
+```
+
+## 🛠️ Тестування (TDD)
+
+- **Команда** `npm test` – запускає всі `*.test.js` у `src/`.
+- **Coverage** `npm run test:coverage` – мінімум 90 %.
+- **Документація** `npm run test:docs` – генерує `README.md` з тестових блоків.
+- **Release** `npm run test:release` – перевірка `releases/**/*.test.js`.
+
+Кожна публічна функція/клас має **принаймні один тест** у `.test.js` поряд з файлом коду.
+
+## 🧭 Доступні CLI‑методи
+
+| Метод | Параметри | Повертає | Опис |
+|-------|-----------|----------|------|
+| `ask(question)` | `string` – підказка | `Promise<string>` | Запит користувачу, повертає введений рядок. |
+| `createInput(stops?)` | `string[]` – слова‑сигнали | `Promise<Input>` | Створює інстанс `Input` з автоскасуванням. |
+| `select(config)` | `{title, prompt, options, console, ask?}` | `Promise<{index, value}>` | Виводить нумерований список, повертає вибір. |
+| `next(conf?)` | `string|array` – послідовність клавіш | `Promise<string>` | Чекає на натискання клавіші (або набору). |
+| `pause(ms)` | `number` – мілісекунди | `Promise<void>` | Затримка виконання. |
+| `CLIInputAdapter.requestForm(form, {silent})` | `UIForm` + опції | `Promise<FormMessage>` | Показує форму, проходить по полях, валідує, повертає результат або `escaped:true`. |
+| `CLIInputAdapter.requestSelect(config)` | `config` (аналог `select`) | `Promise<InputMessage>` | Викликає `select`, обгортає результат у `InputMessage`. |
+| `CLIInputAdapter.requestInput(config)` | `{prompt, id, label, name}` | `Promise<InputMessage>` | Простий рядковий запит. |
+
+## 📝 Рекомендації для розробників
+
+1. **JSDoc** – кожна функція/клас має повний опис (`@param`, `@returns`, `@throws`). Це забезпечує автодоповнення у IDE без TypeScript.
+2. **Імпорти** – використовуйте `import { … } from '@nan0web/ui-cli'` лише в точках входу.
+3. **Структура** – залишайте `src/` чистим, `tests/` поруч, `types/` лише декларації (`*.d.ts`), `README.md` генерується з тестів.
+4. **Локальність** – UI‑текст передається через `i18n` (передача функції `t`). В `playground` вже реалізовано приклад.
+5. **Нульові залежності** – не підключайте сторонні пакети у `ui-cli`; лише Node‑вбудовані (`readline`, `process`).
+
+## 🌐 Підтримка та внесок
+
+- **Bug‑репорт** – відкривайте Issue у репозиторії.
+- **Pull‑request** – додайте нові функції з тестами та оновленою документацією.
+- **CI** – автоматично запускає `npm test` та `npm run test:coverage`.
+
+> **UI‑CLI відповідає** – коли команда виконується без помилок, коли тестове покриття достатнє, коли документація генерується без «шуму».
+

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+	"compilerOptions": {
+		"target": "esnext",
+		"module": "nodenext",
+		"lib": ["esnext"],
+		"declaration": true,
+		"declarationMap": false,
+		"emitDeclarationOnly": true,
+		"outDir": "./types",
+		"rootDir": "./src",
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"moduleResolution": "nodenext",
+		"allowSyntheticDefaultImports": true,
+		"noImplicitAny": false,
+		"allowJs": true,
+		"checkJs": true
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "src/**/*.test.js"]
+}

package/types/InputAdapter.d.ts

@@ -0,0 +1,106 @@
+/**
+ * CLI specific adapter extending the generic {@link BaseInputAdapter}.
+ * Implements concrete `ask` and `select` helpers that rely on the CLI utilities.
+ */
+export default class CLIInputAdapter extends BaseInputAdapter {
+    /**
+     * Interactively fill a {@link UIForm} field‑by‑field.
+     *
+     * @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`.
+     */
+    requestForm(form: UIForm, options?: {
+        silent?: boolean | undefined;
+    }): Promise<FormMessage>;
+    /**
+     * Request a selection from a list of options.
+     *
+     * @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.
+     */
+    requestSelect(config: {
+        title: string;
+        prompt: string;
+        options: Array<string> | Map<string, string> | Array<{
+            label: string;
+            value: string;
+        }>;
+        id: string;
+    }): Promise<BaseInputMessage>;
+    /**
+     * Simple string input request.
+     *
+     * @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.
+     */
+    requestInput(config: {
+        prompt: string;
+        id: string;
+        label?: string | undefined;
+        name?: string | undefined;
+    }): Promise<BaseInputMessage>;
+    /** @inheritDoc */
+    ask(question: any): Promise<any>;
+    /** @inheritDoc */
+    select(config: any): Promise<{
+        index: number; /** @type {UIForm} Form data associated with the message */
+        value: string | null;
+    }>;
+}
+export type FormMessageValue = Partial<UIForm>;
+export type InputMessageValue = Partial<Message> | null;
+import { InputAdapter as BaseInputAdapter } from '@nan0web/ui';
+import { UIForm } from '@nan0web/ui';
+/** @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.
+ *
+ * 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.
+ */
+declare class FormMessage extends BaseInputMessage {
+    /**
+     * 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: FormMessage | object): FormMessage;
+    /**
+     * 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?: {
+        form?: Partial<UIForm> | undefined;
+        value?: InputMessageValue | undefined;
+        options?: string | string[] | undefined;
+        waiting?: boolean | undefined;
+        escaped?: boolean | undefined;
+    });
+    /** @type {UIForm} Form data associated with the message */
+    form: UIForm;
+}
+import { InputMessage as BaseInputMessage } from '@nan0web/ui';
+import { Message } from '@nan0web/co';
+export {};

package/types/README.md.d.ts

@@ -0,0 +1 @@
+export {};

package/types/index.d.ts

@@ -0,0 +1,11 @@
+export const renderers: Map<string, (data: any) => string>;
+export default CLIInputAdapter;
+import CLIInputAdapter from './InputAdapter.js';
+import { CancelError } from '@nan0web/ui/core';
+import { createInput } from './ui/index.js';
+import { ask } from './ui/index.js';
+import { Input } from './ui/index.js';
+import { select } from './ui/index.js';
+import { next } from './ui/index.js';
+import { pause } from './ui/index.js';
+export { CLIInputAdapter, CancelError, createInput, ask, Input, select, next, pause };

package/types/test/ReadLine.d.ts

@@ -0,0 +1 @@
+export {};

package/types/ui/errors.d.ts

@@ -0,0 +1,3 @@
+export class CancelError extends Error {
+    constructor(message?: string);
+}

package/types/ui/index.d.ts

@@ -0,0 +1,4 @@
+export { CancelError } from "@nan0web/ui/core";
+export { select } from "./select.js";
+export { Input, ask, createInput } from "./input.js";
+export { next, pause } from "./next.js";

package/types/ui/input.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Helper to ask a question
+ * @param {string} question
+ */
+export function ask(question: string): Promise<any>;
+export function createInput(stops?: any[]): (question: string, loop?: boolean | Function | undefined, nextQuestion?: false | Function | undefined) => Promise<Input>;
+export class Input {
+    constructor(input?: {});
+    value: string;
+    stops: any[];
+    get cancelled(): boolean;
+    toString(): string;
+    #private;
+}
+export default createInput;

package/types/ui/next.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Waits for the confirmation message (input) from user
+ * @param {string | string[] | undefined} conf - Confirmation message or one of messages if array or any if undefined.
+ * @returns {Promise<string>}
+ */
+export function next(conf?: string | string[] | undefined): Promise<string>;
+/**
+ * Make a pause.
+ * @param {number} ms - Amount in miliseconds
+ * @returns {Promise<void>}
+ */
+export function pause(ms: number): Promise<void>;

package/types/ui/select.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Generic selection prompt for CLI.
+ * Automatically creates its own input handler.
+ *
+ * @param {Object} config
+ * @param {string} config.title - Title shown before the list (e.g. "Select currency:")
+ * @param {string} config.prompt - Main prompt text (e.g. "Choose (1-3): ")
+ * @param {string} [config.invalidPrompt] - Retry message when input is invalid
+ * @param {Array<string> | Map<string, string> | Array<{ label: string, value: string }>} config.options - List of displayable options
+ * @param {Object} config.console - Logger (console.info, console.error, etc.)
+ * @param {Function} [config.ask] - Input handler
+ *
+ * @returns {Promise<{ index: number, value: string | null }>} Selected option
+ * @throws {CancelError} if the user cancels
+ */
+export function select({ title, prompt, invalidPrompt, options, console, ask, }: {
+    title: string;
+    prompt: string;
+    invalidPrompt?: string | undefined;
+    options: Array<string> | Map<string, string> | Array<{
+        label: string;
+        value: string;
+    }>;
+    console: any;
+    ask?: Function | undefined;
+}): Promise<{
+    index: number;
+    value: string | null;
+}>;
+export default select;