gulp-mu-gulp-api 0.2.0

package/README.md

@@ -0,0 +1,245 @@
+# gulp-mu-gulp-api
+
+Public task API of the **µGulp™** orchestrator — progress reporting and interactive dashboard inputs from within gulp tasks.
+
+Part of the [µGulp™ project on GitHub](https://github.com/mamekudz/microGulp) (subdirectory [`gulp-mu-gulp-api/`](https://github.com/mamekudz/microGulp/tree/main/gulp-mu-gulp-api)).
+
+[English](#english) · [Deutsch](#deutsch)
+
+---
+
+# English
+
+**gulp-mu-gulp-api** gives gulp tasks (and any npm package inside the task stream) access to the extended µGulp™ dashboard features: progress bars, validated text inputs, color and font pickers, single and multi selections, sliders and complete forms.
+
+The module is deliberately **dependency-free** and knows nothing about µGulp™ internals: when the task runs under µGulp™, it talks directly to the engine over the worker process IPC channel. When the gulpfile runs through the classic gulp CLI, every function degrades gracefully — progress renders on the terminal, inputs are asked via readline (TTY) or answered with the declared defaults (CI/non-TTY). Tasks stay fully runnable without µGulp™.
+
+## Installation
+
+```bash
+npm install gulp-mu-gulp-api
+```
+
+## Usage
+
+```javascript
+import { ReportProgress, CreateProgress, PlaySignal, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsUGulp } from 'gulp-mu-gulp-api';
+
+export async function BUILD_THEME() {
+    // single inputs
+    let accent = await RequestColorInput({ label: 'Accent color', default: '#00e5ff' });
+    let font = await RequestFontInput({ label: 'Headline font', options: ['Segoe UI', 'Cascadia Mono'] });
+    let title = await RequestTextInput({
+        label: 'Product title',
+        validate: { required: true, minLength: 3, pattern: '^[A-Za-z0-9 ]+$' },
+    });
+    let servers = await RequestMultiSelectInput({
+        label: 'Rollout servers',
+        options: [{ value: 'SMPMD', checked: true }, 'iMedOne', 'ACM'],
+    });
+
+    // progress (determinate neon bar in the µGulp dashboard)
+    let progress = CreateProgress('compiling theme');
+    for (let step = 1; step <= 10; step++) {
+        // ... work ...
+        progress.Update(step / 10);
+    }
+    progress.Done();
+
+    // sound + speech (rendered by the dashboard, configured in its settings)
+    PlaySignal('success');
+    Speak('Theme build finished.');
+}
+```
+
+Complete forms in one go:
+
+```javascript
+let values = await RequestForm({
+    title: 'Build parameters',
+    fields: [
+        { id: 'mode',    type: 'radio',    label: 'Build mode', default: 'release', options: ['debug', 'release'] },
+        { id: 'threads', type: 'range',    label: 'Worker threads', min: 1, max: 16, step: 1, default: 4 },
+        { id: 'notes',   type: 'textarea', label: 'Release notes', rows: 4, placeholder: 'What changed?' },
+        { id: 'apikey',  type: 'password', label: 'API key', validate: { required: true } },
+        { id: 'targets', type: 'checkbox', label: 'Targets', options: ['Alpha', 'Beta', 'Gamma'], validate: { minSelected: 1 } },
+    ],
+});
+// values => { mode: 'release', threads: '8', notes: '…', apikey: '…', targets: ['Alpha', 'Gamma'] }
+```
+
+## API reference
+
+| Function | Purpose |
+| :--- | :--- |
+| `IsUGulp()` | `true` when the task runs under µGulp™ with an attached dashboard |
+| `ReportProgress(value, label?)` | Report progress `0..1` to the task progress bar |
+| `CreateProgress(label?)` | Reporter object with `Update(value, stepLabel?)` and `Done()` |
+| `PlaySignal(signal?)` | Acoustic signal in the dashboard: `'success'` \| `'error'` \| `'attention'` (default) |
+| `Speak(text, options?)` | Speech output in the dashboard; `options`: `{ rate?, pitch?, volume? }` per-call overrides |
+| `RequestForm(form)` | Request a complete form; resolves with `{ fieldId: value, … }` |
+| `RequestTextInput(options)` | Single text field (with `validate` rules) |
+| `RequestColorInput(options)` | Color picker, returns `#rrggbb` |
+| `RequestFontInput(options)` | Font selection (`options`: font list) |
+| `RequestSelectInput(options)` | Single selection from a fixed option list |
+| `RequestMultiSelectInput(options)` | Multi selection (checkbox group), always resolves to a `string[]` |
+
+### Field types (for `RequestForm`)
+
+A field descriptor is `{ id, type, label, default?, options?, validate?, min?, max?, step?, rows?, placeholder? }`.
+
+| `type` | Dashboard control | Notes |
+| :--- | :--- | :--- |
+| `text` | text field | default type |
+| `password` | masked text field | |
+| `number` | number field | honors `min`, `max`, `step` |
+| `textarea` | multi-line text field | `rows`, `placeholder` |
+| `color` | native color picker | value as `#rrggbb` |
+| `font` | font selection | `options`: font family names |
+| `select` | dropdown | single choice |
+| `radio` | radio group | single exclusive choice, vertical option column |
+| `checkbox` | checkbox group | **multi-select** — resolves to a `string[]` |
+| `range` | slider + synced number box | `min`, `max`, `step`, `default` |
+| `date` / `time` / `datetime` | native date/time pickers | |
+| `file` | file selection | |
+
+**Options** (`select`, `radio`, `checkbox`) accept plain strings or objects `{ value, label?, checked?, disabled? }` — `checked` preselects checkbox options, `disabled` greys an option out.
+
+**Validation rules:** `{ required?, minLength?, pattern?, minSelected? }` (`minSelected` applies to `checkbox`). Checks run asynchronously in the dashboard; invalid forms cannot be submitted.
+
+## Fallback behavior without µGulp™
+
+| Function | TTY (interactive shell) | non-TTY (CI, pipe) |
+| :--- | :--- | :--- |
+| `ReportProgress` | updating progress line | log line every 10% step |
+| `PlaySignal` | terminal bell (`attention`/`error`) | silent |
+| `Speak` | `[speech]` log line | `[speech]` log line |
+| text/password/number/range input | readline prompt (Enter = default) | default value |
+| font/select/radio input | numbered list + readline | default value |
+| checkbox input | numbered list, comma-separated picks | values of the `checked` options |
+
+Sound and speech playback (mute, volume, speech rate/pitch) is configured centrally in the µGulp™ dashboard settings (gear icon in the header) — tasks never need to care about the user's audio preferences.
+
+## License
+
+MIT — © 2026 Meinolf Amekudzi
+
+---
+
+# Deutsch
+
+**gulp-mu-gulp-api** ist die öffentliche Task-API des **µGulp™**-Orchestrators. Gulp-Tasks (und beliebige npm-Pakete innerhalb des Task-Streams) erhalten damit Zugriff auf die erweiterten µGulp™-Dashboard-Funktionen: Fortschrittsanzeige, Texteingaben mit Validierung, Farb- und Schriftart-Auswahl, Einzel- und Mehrfachauswahl, Slider und komplette Formulare.
+
+Teil des [µGulp™-Projekts auf GitHub](https://github.com/mamekudz/microGulp) (Unterverzeichnis [`gulp-mu-gulp-api/`](https://github.com/mamekudz/microGulp/tree/main/gulp-mu-gulp-api)).
+
+Das Modul ist bewusst **abhängigkeitsfrei** und kennt keine µGulp™-Interna: Läuft der Task unter µGulp™, spricht es direkt über den IPC-Kanal des Worker-Prozesses mit der Engine. Läuft das Gulpfile klassisch über die gulp-CLI, degradieren alle Funktionen sauber — Fortschritt landet auf dem Terminal, Eingaben werden per readline abgefragt (TTY) oder mit den deklarierten Default-Werten beantwortet (CI/non-TTY). Tasks bleiben ohne µGulp™ voll lauffähig.
+
+## Installation
+
+```bash
+npm install gulp-mu-gulp-api
+```
+
+## Verwendung
+
+```javascript
+import { ReportProgress, CreateProgress, PlaySignal, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsUGulp } from 'gulp-mu-gulp-api';
+
+export async function BUILD_THEME() {
+    // Einzeleingaben
+    let accent = await RequestColorInput({ label: 'Accent color', default: '#00e5ff' });
+    let font = await RequestFontInput({ label: 'Headline font', options: ['Segoe UI', 'Cascadia Mono'] });
+    let title = await RequestTextInput({
+        label: 'Product title',
+        validate: { required: true, minLength: 3, pattern: '^[A-Za-z0-9 ]+$' },
+    });
+    let servers = await RequestMultiSelectInput({
+        label: 'Rollout servers',
+        options: [{ value: 'SMPMD', checked: true }, 'iMedOne', 'ACM'],
+    });
+
+    // Fortschritt (determinierte Neon-Progressbar im µGulp-Dashboard)
+    let progress = CreateProgress('compiling theme');
+    for (let step = 1; step <= 10; step++) {
+        // ... Arbeit ...
+        progress.Update(step / 10);
+    }
+    progress.Done();
+
+    // sound + speech (rendered by the dashboard, configured in its settings)
+    PlaySignal('success');
+    Speak('Theme build finished.');
+}
+```
+
+Komplette Formulare in einem Rutsch:
+
+```javascript
+let values = await RequestForm({
+    title: 'Build parameters',
+    fields: [
+        { id: 'mode',    type: 'radio',    label: 'Build mode', default: 'release', options: ['debug', 'release'] },
+        { id: 'threads', type: 'range',    label: 'Worker threads', min: 1, max: 16, step: 1, default: 4 },
+        { id: 'notes',   type: 'textarea', label: 'Release notes', rows: 4, placeholder: 'What changed?' },
+        { id: 'apikey',  type: 'password', label: 'API key', validate: { required: true } },
+        { id: 'targets', type: 'checkbox', label: 'Targets', options: ['Alpha', 'Beta', 'Gamma'], validate: { minSelected: 1 } },
+    ],
+});
+// values => { mode: 'release', threads: '8', notes: '…', apikey: '…', targets: ['Alpha', 'Gamma'] }
+```
+
+## API-Referenz
+
+| Funktion | Zweck |
+| :--- | :--- |
+| `IsUGulp()` | `true`, wenn der Task unter µGulp™ mit angebundenem Dashboard läuft |
+| `ReportProgress(value, label?)` | Fortschritt `0..1` an die Task-Progressbar melden |
+| `CreateProgress(label?)` | Reporter-Objekt mit `Update(value, stepLabel?)` und `Done()` |
+| `PlaySignal(signal?)` | Akustisches Signal im Dashboard: `'success'` \| `'error'` \| `'attention'` (Default) |
+| `Speak(text, options?)` | Sprachausgabe im Dashboard; `options`: `{ rate?, pitch?, volume? }` je Aufruf |
+| `RequestForm(form)` | Komplettes Formular anfordern; löst mit `{ fieldId: value, … }` auf |
+| `RequestTextInput(options)` | Einzelnes Textfeld (mit `validate`-Regeln) |
+| `RequestColorInput(options)` | Farbwähler, Rückgabe `#rrggbb` |
+| `RequestFontInput(options)` | Schriftart-Auswahl (`options`: Font-Liste) |
+| `RequestSelectInput(options)` | Einzelauswahl aus fester Optionsliste |
+| `RequestMultiSelectInput(options)` | Mehrfachauswahl (Checkbox-Gruppe), löst immer mit `string[]` auf |
+
+### Feldtypen (für `RequestForm`)
+
+Ein Feld-Deskriptor ist `{ id, type, label, default?, options?, validate?, min?, max?, step?, rows?, placeholder? }`.
+
+| `type` | Dashboard-Steuerelement | Hinweise |
+| :--- | :--- | :--- |
+| `text` | Textfeld | Standardtyp |
+| `password` | maskiertes Textfeld | |
+| `number` | Zahlenfeld | berücksichtigt `min`, `max`, `step` |
+| `textarea` | mehrzeiliges Textfeld | `rows`, `placeholder` |
+| `color` | nativer Farbwähler | Wert als `#rrggbb` |
+| `font` | Schriftart-Auswahl | `options`: Font-Familiennamen |
+| `select` | Dropdown | Einzelauswahl |
+| `radio` | Radiogruppe | exklusive Einzelauswahl, vertikale Optionsspalte |
+| `checkbox` | Checkbox-Gruppe | **Mehrfachauswahl** — löst mit `string[]` auf |
+| `range` | Slider + synchronisiertes Zahlenfeld | `min`, `max`, `step`, `default` |
+| `date` / `time` / `datetime` | native Datums-/Zeitwähler | |
+| `file` | Dateiauswahl | |
+
+**Options** (`select`, `radio`, `checkbox`) akzeptieren einfache Strings oder Objekte `{ value, label?, checked?, disabled? }` — `checked` selektiert Checkbox-Optionen vor, `disabled` graut eine Option aus.
+
+**Validierungsregeln:** `{ required?, minLength?, pattern?, minSelected? }` (`minSelected` gilt für `checkbox`). Die Prüfung läuft asynchron im Dashboard; ungültige Formulare können nicht abgeschickt werden.
+
+## Fallback-Verhalten ohne µGulp™
+
+| Funktion | TTY (interaktive Shell) | non-TTY (CI, Pipe) |
+| :--- | :--- | :--- |
+| `ReportProgress` | aktualisierende Fortschrittszeile | Log-Zeile je 10-%-Schritt |
+| `PlaySignal` | Terminal-Glocke (`attention`/`error`) | stumm |
+| `Speak` | `[speech]`-Log-Zeile | `[speech]`-Log-Zeile |
+| Text-/Passwort-/Zahlen-/Range-Eingabe | readline-Prompt (Enter = Default) | Default-Wert |
+| Font-/Select-/Radio-Eingabe | nummerierte Liste + readline | Default-Wert |
+| Checkbox-Eingabe | nummerierte Liste, Kommaeingabe | Werte der `checked`-Optionen |
+
+Die Sound- und Sprachwiedergabe (Mute, Lautstärke, Sprechgeschwindigkeit/-höhe) wird zentral in den µGulp™-Dashboard-Settings konfiguriert (Zahnrad im Kopfbereich) — Tasks müssen sich um die Audio-Einstellungen der Anwender nicht kümmern.
+
+## Lizenz
+
+MIT — © 2026 Meinolf Amekudzi

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "gulp-mu-gulp-api",
+	"version": "0.2.0",
+	"description": "Public task API for the µGulp orchestrator: progress reporting, sound signals, speech output and interactive UI inputs (text, password, number, textarea, color, font, select, radio, multi-select checkbox, range slider, date/time, file) from within gulp tasks — with graceful CLI fallbacks when running without µGulp.",
+	"type": "module",
+	"main": "src/index.mjs",
+	"exports": {
+		".": "./src/index.mjs"
+	},
+	"files": [
+		"src",
+		"README.md"
+	],
+	"scripts": {
+		"test": "node --test \"tests/**/*.test.mjs\""
+	},
+	"keywords": [
+		"gulp",
+		"ugulp",
+		"microgulp",
+		"progress",
+		"interactive",
+		"sound",
+		"speech",
+		"prompt",
+		"multiselect",
+		"form",
+		"task-api"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/mamekudz/microGulp.git",
+		"directory": "gulp-mu-gulp-api"
+	},
+	"homepage": "https://github.com/mamekudz/microGulp/tree/main/gulp-mu-gulp-api#readme",
+	"bugs": {
+		"url": "https://github.com/mamekudz/microGulp/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"engines": {
+		"node": ">=18"
+	}
+}

package/src/index.mjs

@@ -0,0 +1,322 @@
+// ===========================================
+// gulp-mu-gulp-api — µGulp task API
+// © 2026 Meinolf Amekudzi
+// (published under MIT license)
+// ===========================================
+
+/**
+ * Public API for gulp tasks running under the µGulp orchestrator.
+ *
+ * Under µGulp every task runs inside a forked worker process with an IPC
+ * channel to the engine; this module talks to that channel directly, so it
+ * has zero coupling to µGulp internals and works from any npm package in
+ * the pipeline. Without µGulp (plain "gulp" CLI run) every function
+ * degrades gracefully: progress renders on the terminal, inputs fall back
+ * to readline prompts on a TTY or to the declared defaults otherwise.
+ *
+ * @example
+ * import { ReportProgress, RequestTextInput, RequestColorInput } from 'gulp-mu-gulp-api';
+ *
+ * export async function BUILD_THEME() {
+ *     let accent = await RequestColorInput({ label: 'Accent color', default: '#00e5ff' });
+ *     for (let step = 0; step < 10; step++) {
+ *         // ... work ...
+ *         ReportProgress((step + 1) / 10, 'compiling theme');
+ *     }
+ * }
+ *
+ * @module gulp-mu-gulp-api
+ */
+
+let uiRequestCounter = 0;
+let ipcListenerAttached = false;
+let lastLoggedPercent = -1;
+const pendingUiRequests = new Map();
+
+/**
+ * @returns {boolean} true when the task runs inside a µGulp worker with an
+ * attached dashboard (progress and inputs are rendered in the webview)
+ */
+export function IsUGulp() {
+	return typeof process.send === 'function' && process.env.UGULP === '1';
+}
+
+// -------------------------------------------------
+// progress
+// -------------------------------------------------
+
+/**
+ * Reports task progress to the µGulp dashboard (determinate neon progress
+ * bar in the task's sector). CLI fallback: an updating line on a TTY,
+ * 10%-step log lines otherwise.
+ *
+ * @param {number} _value progress in the range 0..1
+ * @param {string} [_label] short status label shown next to the bar
+ */
+export function ReportProgress(_value, _label) {
+	let value = Math.max(0, Math.min(1, Number(_value) || 0));
+	if (IsUGulp()) {
+		process.send({ type: 'progress', value, label: _label });
+		return;
+	}
+	let percent = Math.round(value * 100);
+	if (process.stdout.isTTY) {
+		process.stdout.write('\r' + (_label ?? 'progress') + ' ' + percent + '%' + (value >= 1 ? '\n' : ''));
+	} else if (percent >= 100 || percent - lastLoggedPercent >= 10) {
+		lastLoggedPercent = percent >= 100 ? -1 : percent;
+		console.log((_label ?? 'progress') + ' ' + percent + '%');
+	}
+}
+
+/**
+ * Convenience wrapper that carries a fixed label.
+ *
+ * @param {string} [_label]
+ * @returns {{Update: function(number, string=): void, Done: function(): void}}
+ */
+export function CreateProgress(_label) {
+	return {
+		Update(_value, _stepLabel) {
+			ReportProgress(_value, _stepLabel ?? _label);
+		},
+		Done() {
+			ReportProgress(1, _label);
+		},
+	};
+}
+
+// -------------------------------------------------
+// sound & speech
+// -------------------------------------------------
+
+/**
+ * Plays an acoustic signal in the µGulp dashboard (WebAudio, respects the
+ * dashboard audio settings: mute/volume). CLI fallback: terminal bell for
+ * 'attention' and 'error' on a TTY, silent otherwise.
+ *
+ * @param {'success'|'error'|'attention'} [_signal]
+ */
+export function PlaySignal(_signal = 'attention') {
+	if (IsUGulp()) {
+		process.send({ type: 'sound', signal: _signal });
+		return;
+	}
+	if (process.stdout.isTTY && (_signal === 'attention' || _signal === 'error')) {
+		process.stdout.write('\u0007');
+	}
+}
+
+/**
+ * Speaks a text through the µGulp dashboard speech output (Web Speech API,
+ * respects the dashboard speech settings: enabled/volume/rate/pitch).
+ * CLI fallback: the text is printed as a log line.
+ *
+ * @param {string} _text
+ * @param {object} [_options] { rate?, pitch?, volume? } — per-call overrides (0..2 / 0..2 / 0..1)
+ */
+export function Speak(_text, _options) {
+	let text = String(_text ?? '').trim();
+	if (!text) return;
+	if (IsUGulp()) {
+		process.send({ type: 'speech', text, options: _options ?? null });
+		return;
+	}
+	console.log('[speech] ' + text);
+}
+
+// -------------------------------------------------
+// interactive inputs
+// -------------------------------------------------
+
+/**
+ * Requests a complete form from the µGulp dashboard.
+ *
+ * Field descriptor: { id, type, label, default?, options?, validate?,
+ * min?, max?, step?, rows?, placeholder? }
+ *
+ * Supported types: 'text' | 'password' | 'number' | 'textarea' | 'color' |
+ * 'font' | 'select' | 'radio' | 'checkbox' (multi-select, resolves to a
+ * string array) | 'range' (slider with synced number box) | 'date' |
+ * 'time' | 'datetime' | 'file'.
+ *
+ * Options (select/radio/checkbox) accept plain strings or objects
+ * { value, label?, checked?, disabled? }.
+ *
+ * Validation rules: { required?, minLength?, pattern?, minSelected? } —
+ * checks run asynchronously in the webview before submission.
+ *
+ * @param {object} _form { title, fields: [...] }
+ * @returns {Promise<object>} map fieldId -> value
+ */
+export async function RequestForm(_form) {
+	if (IsUGulp()) {
+		_EnsureIpcListener();
+		let requestId = 'api-req-' + process.pid + '-' + (++uiRequestCounter);
+		return new Promise((_resolve) => {
+			pendingUiRequests.set(requestId, _resolve);
+			process.send({ type: 'ui-request', requestId, form: _form });
+		});
+	}
+	return _FallbackForm(_form);
+}
+
+/**
+ * Requests a single validated text value.
+ * @param {object} _options { label, title?, default?, validate? }
+ * @returns {Promise<string|null>}
+ */
+export async function RequestTextInput(_options) {
+	return _SingleField({ ..._options, type: 'text' });
+}
+
+/**
+ * Requests a color (native color picker in the dashboard).
+ * @param {object} _options { label, title?, default? } — default as #rrggbb
+ * @returns {Promise<string|null>}
+ */
+export async function RequestColorInput(_options) {
+	return _SingleField({ ..._options, type: 'color' });
+}
+
+/**
+ * Requests a font selection.
+ * @param {object} _options { label, title?, default?, options? } — options: font family names
+ * @returns {Promise<string|null>}
+ */
+export async function RequestFontInput(_options) {
+	return _SingleField({ ..._options, type: 'font' });
+}
+
+/**
+ * Requests a selection from a fixed option list.
+ * @param {object} _options { label, title?, default?, options: string[] }
+ * @returns {Promise<string|null>}
+ */
+export async function RequestSelectInput(_options) {
+	return _SingleField({ ..._options, type: 'select' });
+}
+
+/**
+ * Requests a multi-selection (checkbox group in the dashboard).
+ * @param {object} _options { label, title?, options: Array<string|{value, label?, checked?, disabled?}>, validate? }
+ * @returns {Promise<string[]>} selected values (empty array when nothing was picked)
+ */
+export async function RequestMultiSelectInput(_options) {
+	let value = await _SingleField({ ..._options, type: 'checkbox' });
+	return Array.isArray(value) ? value : (value != null ? [value] : []);
+}
+
+// -------------------------------------------------
+// internal
+// -------------------------------------------------
+
+function _EnsureIpcListener() {
+	if (ipcListenerAttached) return;
+	ipcListenerAttached = true;
+	process.on('message', (_message) => {
+		if (_message && _message.type === 'ui-response' && pendingUiRequests.has(_message.requestId)) {
+			let resolver = pendingUiRequests.get(_message.requestId);
+			pendingUiRequests.delete(_message.requestId);
+			resolver(_message.payload);
+		}
+	});
+}
+
+async function _SingleField(_options) {
+	let values = await RequestForm({
+		title: _options.title ?? _options.label,
+		fields: [{
+			id: 'value',
+			type: _options.type,
+			label: _options.label,
+			default: _options.default,
+			options: _options.options,
+			validate: _options.validate,
+		}],
+	});
+	return values.value ?? null;
+}
+
+async function _FallbackForm(_form) {
+	let values = {};
+	for (let field of _form.fields ?? []) {
+		values[field.id] = await _FallbackField(field);
+	}
+	return values;
+}
+
+function _NormalizeOptions(_options) {
+	let result = [];
+	for (let option of _options ?? []) {
+		if (option == null) continue;
+		if (typeof option === 'object') {
+			if (option.separator) continue;
+			let value = option.value ?? option.label ?? option.name ?? '';
+			result.push({
+				value: String(value),
+				label: String(option.label ?? option.name ?? value),
+				checked: !!option.checked,
+			});
+		} else {
+			result.push({ value: String(option), label: String(option), checked: false });
+		}
+	}
+	return result;
+}
+
+function _FallbackDefault(_field) {
+	if (_field.type === 'checkbox') {
+		return _NormalizeOptions(_field.options).filter((_option) => _option.checked).map((_option) => _option.value);
+	}
+	return _field.default ?? null;
+}
+
+async function _FallbackField(_field) {
+	if (!process.stdin.isTTY || !process.stdout.isTTY) {
+		return _FallbackDefault(_field);
+	}
+	const readline = await import('node:readline/promises');
+	let prompt = readline.createInterface({ input: process.stdin, output: process.stdout });
+	try {
+		let label = _field.label ?? _field.id;
+		let options = _NormalizeOptions(_field.options);
+		let hasOptions = options.length > 0;
+		if (_field.type === 'checkbox' && hasOptions) {
+			options.forEach((_option, _index) => console.log('  [' + (_index + 1) + '] ' + _option.label + (_option.checked ? ' *' : '')));
+			let answer = await prompt.question(label + ' (comma-separated numbers, Enter = defaults marked *): ');
+			let picked = answer.split(',')
+				.map((_part) => parseInt(_part.trim(), 10))
+				.filter((_index) => _index >= 1 && _index <= options.length)
+				.map((_index) => options[_index - 1].value);
+			return picked.length > 0 ? picked : _FallbackDefault(_field);
+		}
+		if ((_field.type === 'select' || _field.type === 'font' || _field.type === 'radio') && hasOptions) {
+			options.forEach((_option, _index) => console.log('  [' + (_index + 1) + '] ' + _option.label));
+			let answer = await prompt.question(label + ' (1-' + options.length + (_field.default ? ', default "' + _field.default + '"' : '') + '): ');
+			let index = parseInt(answer, 10);
+			if (index >= 1 && index <= options.length) return options[index - 1].value;
+			return _field.default ?? null;
+		}
+		let hint = _field.type === 'range' || _field.type === 'number'
+			? ' (' + (_field.min ?? 0) + '-' + (_field.max ?? 100) + (_field.default != null ? ', default ' + _field.default : '') + ')'
+			: (_field.default ? ' [' + _field.default + ']' : '');
+		let answer = await prompt.question(label + hint + ': ');
+		return answer || (_field.default ?? null);
+	} finally {
+		prompt.close();
+	}
+}
+
+export default {
+	IsUGulp,
+	ReportProgress,
+	CreateProgress,
+	PlaySignal,
+	Speak,
+	RequestForm,
+	RequestTextInput,
+	RequestColorInput,
+	RequestFontInput,
+	RequestSelectInput,
+	RequestMultiSelectInput,
+};