@nan0web/ui 1.9.0 → 1.11.0

package/src/testing/LogicInspector.js

@@ -0,0 +1,55 @@
+import { runGenerator } from '../core/GeneratorRunner.js'
+
+/**
+ * LogicInspector
+ * 
+ * Базовий клас для захоплення "Логічних зліпків" (Intent Stream) будь-яких моделей OLMUI.
+ * Дозволяє виконувати чисто-логічне тестування без прив'язки до рендерингу.
+ */
+export class LogicInspector {
+    /**
+     * Виконує генератор моделі та записує послідовність усіх інтенцій.
+     * @param {AsyncGenerator<import('../core/Intent.js').Intent, import('../core/Intent.js').ResultIntent, import('../core/Intent.js').IntentResponse>} modelStream - результат виклику model.run()
+     * @param {object} options 
+     * @param {Array<any> | ((locale: string) => Array<any>)} [options.inputs] - черга вхідних значень для askIntent
+     * @param {string} [options.locale] - локаль для тестів
+     * @param {function} [options.t] - функція перекладу
+     * @returns {Promise<Array<any>>} Intent Stream Log
+     */
+    static async capture(modelStream, { inputs = [], locale = 'uk', t = (k) => k } = {}) {
+        const intents = []
+        let inputIdx = 0
+        const resolvedInputs = typeof inputs === 'function' ? inputs(locale) : inputs
+
+        const recordingAdapter = {
+            /** @param {import('../core/Intent.js').AskIntent} i */
+            ask: async (i) => {
+                const value = resolvedInputs[inputIdx++]
+                const entry = { type: 'ask', field: i.field, schema: i.schema, input: value }
+                intents.push(entry)
+                return { value }
+            },
+            /** @param {import('../core/Intent.js').ShowIntent} i */
+            show: async (i) => {
+                intents.push({ type: 'show', level: i.level || 'info', message: i.message })
+            },
+            /** @param {import('../core/Intent.js').ProgressIntent} i */
+            progress: async (i) => {
+                intents.push({ type: 'progress', message: i.message })
+            },
+            /** @param {import('../core/Intent.js').RenderIntent} i */
+            render: async (i) => {
+                intents.push({ type: 'render', component: i.component, props: i.props })
+            },
+            /** @param {import('../core/Intent.js').ResultIntent} i */
+            result: async (i) => {
+                intents.push({ type: 'result', data: i.data })
+            },
+            t
+        }
+
+        // Викликаємо базовий раннер з нашим записуючим адаптером
+        await runGenerator(modelStream, recordingAdapter)
+        return intents
+    }
+}

package/src/testing/SnapshotRunner.js

@@ -0,0 +1,22 @@
+import { SnapshotRunner as Runner } from '../domain/app/SnapshotRunner.js'
+import DBFS from '@nan0web/db-fs'
+
+/**
+ * Legacy bridge for SnapshotRunner.
+ * @deprecated Use SnapshotRunner model from domain/app
+ */
+export class SnapshotRunner {
+	static async generateAndAudit(options) {
+		const db = options.db || new DBFS({ root: options.dataDir })
+		const runner = new Runner(options, { db })
+		if (options.getCategory) runner.getCategory = options.getCategory
+		if (options.createModelStream) runner.createModelStream = options.createModelStream
+		
+		const gen = runner.run()
+		let res = await gen.next()
+		while (!res.done) {
+			res = await gen.next()
+		}
+		return res.value
+	}
+}

package/src/testing/SpecAdapter.js

@@ -0,0 +1,115 @@
+import assert from 'node:assert/strict'
+
+/**
+ * @typedef {Object} SpecAdapterOptions
+ * @property {typeof import('node:assert/strict')} [assert] Custom assertion library (falls back to node:assert in Node runtime)
+ */
+
+export class SpecAdapter {
+	/** @type {Array<object>} */
+	stream
+	/** @type {typeof import('node:assert/strict')} */
+	assert
+
+	/**
+	 * @param {Array<object>} stream The remaining nan0 array without the first element.
+	 * @param {SpecAdapterOptions} [options={}]
+	 */
+	constructor(stream, options = {}) {
+		this.stream = stream
+		this.assert = options.assert || assert
+	}
+
+	/**
+	 * Helper to get the next step and assert type match.
+	 * @param {string} intentType
+	 */
+	#popExpected(intentType) {
+		const step = this.stream.shift()
+		if (!step) {
+			this.assert.fail(`Model yielded '${intentType}' intent, but Nan0Spec stream is exhausted (no more steps expected).`)
+		}
+		if (!(intentType in step)) {
+			// Find what step type it actually is
+			const actualType = Object.keys(step).find(k => !k.startsWith('$'))
+			this.assert.fail(`Strict mismatch: Model yielded '${intentType}', but Nan0Spec stream expected '${actualType}'. Trace: ${JSON.stringify(step)}`)
+		}
+		return step
+	}
+
+	/**
+	 * @param {import('../core/Intent.js').AskIntent} intent
+	 */
+	async ask(intent) {
+		const step = this.#popExpected('ask')
+		this.assert.equal(step.ask, intent.field, `Field mismatch on ask. Expected '${step.ask}', got '${intent.field}'`)
+		
+		return { value: step.$value }
+	}
+
+	/**
+	 * @param {import('../core/Intent.js').ShowIntent} intent
+	 */
+	async show(intent) {
+		const step = this.#popExpected('show')
+		if (step.show && typeof step.show === 'string') {
+			const activeMessage = intent.message
+			if (activeMessage && step.show !== '*' && step.show !== '') {
+				this.assert.equal(activeMessage, step.show, `Show message mismatch`)
+			}
+		}
+	}
+
+	/**
+	 * @param {import('../core/Intent.js').LogIntent} intent
+	 */
+	async log(intent) {
+		const step = this.#popExpected('log')
+		if (step.log && typeof step.log === 'string') {
+			const activeMessage = intent.message
+			if (activeMessage && step.log !== '*' && step.log !== '') {
+				this.assert.equal(activeMessage, step.log, `Log message mismatch`)
+			}
+		}
+	}
+
+	/**
+	 * @param {import('../core/Intent.js').ProgressIntent} intent
+	 */
+	async progress(intent) {
+		this.#popExpected('progress')
+	}
+
+	/**
+	 * @param {import('../core/Intent.js').RenderIntent} intent
+	 */
+	async render(intent) {
+		const step = this.#popExpected('render')
+		const activeComponent = intent.component
+		this.assert.equal(activeComponent, step.render, `Render component mismatch. Expected '${step.render}'.`)
+	}
+
+	/**
+	 * @param {import('../core/Intent.js').AgentIntent} intent
+	 */
+	async agent(intent) {
+		const step = this.#popExpected('agent')
+		this.assert.equal(step.agent, intent.task, `Agent task mismatch. Expected '${step.agent}'.`)
+		
+		return { success: step.$success !== false, files: step.$files, message: step.$message }
+	}
+
+	/**
+	 * @param {import('../core/Intent.js').ResultIntent} intent
+	 */
+	async result(intent) {
+		// Only pop result if there's a result recorded in the spec stream
+		if (this.stream.length > 0 && typeof this.stream[0] === 'object' && 'result' in this.stream[0]) {
+			const step = this.#popExpected('result')
+			if (step.result !== undefined && step.result !== '*') {
+				const actualData = intent?.data ?? intent
+				this.assert.deepEqual(actualData, step.result, `Result object deep mismatch`)
+			}
+		}
+	}
+}

package/src/testing/SpecRunner.js

@@ -0,0 +1,121 @@
+import assert from 'node:assert/strict'
+import { runGenerator } from '../core/GeneratorRunner.js'
+import { ModelAsApp } from '../domain/ModelAsApp.js'
+import { result, progress } from '../core/Intent.js'
+import { SpecAdapter } from './SpecAdapter.js'
+
+export class SpecRunner extends ModelAsApp {
+	static stream = { help: 'The .nan0 intent stream array', default: [] }
+	static registry = { help: 'A registry of Model Classes that can be mounted', default: {} }
+	static UI = {
+		invalidStream: 'Invalid Nan0Spec: stream must be a non-empty array',
+		invalidFirstStep: 'Invalid Nan0Spec: first step missing or invalid',
+		missingAppName:
+			'Invalid Nan0Spec: first step must define the AppName key (e.g. ShoppingCartApp)',
+		appNotFound:
+			"SpecRunner: AppName '{app}' not found in provided registry. Did you forget to import it?",
+		invalidGenerator: "SpecRunner: Model '{app}' does not have a valid run() async generator",
+		running: 'Running {app}...',
+		unhandledSteps: 'Model finished execution, but stream still has {count} unhandled steps',
+	}
+
+	/** @type {typeof import('node:assert/strict')} */
+	#assert
+
+	/**
+	 * @param {Partial<SpecRunner>} [data={}]
+	 * @param {Partial<import('../index.js').ModelAsAppOptions> & { assert?: typeof import('node:assert/strict') }} [options={}]
+	 */
+	constructor(data = {}, options = {}) {
+		super(data, /** @type {import('../index.js').ModelAsAppOptions} */ (options))
+		this.#assert = options.assert || assert
+		/** @type {Array<object>} The Nan0Spec stream */
+		this.stream
+		/** @type {Record<string, any>} The registry of Model Classes */
+		this.registry
+	}
+
+	/**
+	 * @throws {Error}
+	 * @returns {AsyncGenerator<import('../core/Intent.js').Intent, import('../core/Intent.js').ResultIntent, any>}
+	 */
+	async *run() {
+		const { t } = this._
+		const stream = this.stream
+		const registry = this.registry
+
+		if (!Array.isArray(stream) || stream.length === 0) {
+			throw new Error(t(SpecRunner.UI.invalidStream))
+		}
+
+		// Clone the stream so we can shift without destroying the original reference
+		const localStream = [...stream]
+
+		const firstStep = localStream.shift()
+		if (!firstStep || typeof firstStep !== 'object') {
+			throw new Error(t(SpecRunner.UI.invalidFirstStep))
+		}
+
+		const appName = Object.keys(firstStep).find((k) => !k.startsWith('$'))
+		if (!appName) {
+			throw new Error(t(SpecRunner.UI.missingAppName))
+		}
+
+		const ModelClass = /** @type {any} */ (registry[appName])
+		if (!ModelClass) {
+			throw new Error(t(SpecRunner.UI.appNotFound, { app: appName }))
+		}
+
+		const appData = firstStep[appName] || {}
+		const adapter = new SpecAdapter(localStream, { assert: this.#assert })
+
+		// Create the model, passing our own context so it inherits translations etc
+		const model = new ModelClass(appData, this._)
+		const generator = typeof model.run === 'function' ? model.run() : null
+
+		if (!generator || typeof generator.next !== 'function') {
+			throw new Error(t(SpecRunner.UI.invalidGenerator, { app: appName }))
+		}
+
+		try {
+			yield progress(t(SpecRunner.UI.running, { app: appName }))
+			await runGenerator(generator, {
+				ask: adapter.ask.bind(adapter),
+				show: adapter.show.bind(adapter),
+				log: adapter.log.bind(adapter),
+				progress: adapter.progress.bind(adapter),
+				render: adapter.render.bind(adapter),
+				agent: adapter.agent.bind(adapter),
+				result: adapter.result.bind(adapter),
+			})
+		} catch (err) {
+			// Bubbling assertion errors correctly
+			throw err
+		}
+
+		// The stream must be fully consumed
+		if (localStream.length > 0) {
+			assert.fail(t(SpecRunner.UI.unhandledSteps, { count: localStream.length }))
+		}
+
+		return result({ success: true, appName })
+	}
+
+	/**
+	 * Run a Nan0Spec sequence programmatically (for unit tests).
+	 *
+	 * @param {Array<object>} stream The .nan0 intent stream array
+	 * @param {Record<string, any>} registry A registry of Model Classes that can be mounted
+	 * @param {typeof import('node:assert/strict')} [asserter] Custom assertion library
+	 */
+	static async execute(stream, registry, asserter = assert) {
+		const runner = new SpecRunner({ stream, registry }, { assert: asserter })
+		const it = runner.run()
+		while (true) {
+			const { value, done } = await it.next()
+			if (done) return value?.data
+		}
+	}
+}
+
+export default SpecRunner

package/src/testing/VisualAdapter.js

@@ -0,0 +1,46 @@
+/**
+ * VisualAdapter (Base)
+ * 
+ * Базовий клас для візуальної трансформації інтенцій OLMUI.
+ */
+import { NaN0 } from '@nan0web/types'
+
+export class VisualAdapter {
+    /**
+     * Конвертує одну інтенцію у просте текстове представлення.
+     * @param {object} intent - Intent entry from LogicInspector
+     * @param {function} [t] - i18n translate function
+     * @returns {string} Raw description
+     */
+    static render(intent, t = (k) => k) {
+        let node;
+        switch (intent.type) {
+            case 'ask':
+                node = { ask: { field: intent.field, input: intent.input !== undefined ? intent.input : '...' } }
+                break
+            case 'progress':
+                node = { progress: { message: intent.message || '' } }
+                break
+            case 'log':
+                node = { log: { level: intent.level?.toUpperCase() || 'INFO', message: intent.message } }
+                break
+            case 'render':
+                node = { render: { [intent.component]: intent.props || {} } }
+                break
+            case 'result': {
+                const data = intent.data || {}
+                node = { result: (typeof data === 'object' && data !== null && Object.keys(data).length === 0) ? {} : data }
+                break
+            }
+            default:
+                node = { [intent.type || 'unknown']: intent }
+                break
+        }
+        
+        try {
+            return NaN0.stringify([node]).trim()
+        } catch (e) {
+            return `- error: ${JSON.stringify(node)}`
+        }
+    }
+}

package/src/testing/index.js

@@ -0,0 +1,7 @@
+export * from './LogicInspector.js'
+export * from './VisualAdapter.js'
+export * from '../domain/app/SnapshotAuditor.js'
+export * from './verifySnapshot.js'
+export { SpecRunner } from './SpecRunner.js'
+export { SpecAdapter } from './SpecAdapter.js'
+export * from './CrashReporter.js'

package/src/testing/verifySnapshot.js

@@ -0,0 +1,17 @@
+/**
+ * Saves a logical JSONL snapshot sequence
+ * @param {Object} options
+ * @param {string} options.name Snapshot file name (e.g. 'uk/ExploreCatalog.jsonl')
+ * @param {Array<Object>} options.data Array of intents to serialize
+ * @param {typeof import('node:fs/promises')} [options.fs] Injected filesystem
+ * @param {typeof import('node:path')} [options.path] Injected path module
+ */
+export async function verifySnapshot({ name, data, fs, path }) {
+	if (!fs) fs = await import('node:fs/promises')
+	if (!path) path = await import('node:path')
+
+	const outPath = path.resolve(process.cwd(), 'snapshots/jsonl', name)
+	await fs.mkdir(path.dirname(outPath), { recursive: true })
+	const content = data.map((i) => JSON.stringify(i)).join('\n')
+	await fs.writeFile(outPath, content + '\n')
+}

package/types/App/Command/DepsCommand.d.ts

@@ -1,8 +1,6 @@
 export class DepsCommand extends UiMessage {
     static Body: typeof DepsCommandBody;
     constructor(input?: {});
-    /** @type {DepsCommandBody} */
-    body: DepsCommandBody;
 }
 export default DepsCommand;
 import UiMessage from '../../core/Message/Message.js';

package/types/Model/index.d.ts

@@ -1,6 +1,58 @@
-export { User };
-declare namespace _default {
+export default Model;
+import User from './User/User.js';
+import { HeaderModel } from '../domain/HeaderModel.js';
+import { FooterModel } from '../domain/FooterModel.js';
+import { HeroModel } from '../domain/HeroModel.js';
+import { ButtonModel } from '../domain/components/index.js';
+import { ConfirmModel } from '../domain/components/index.js';
+import { InputModel } from '../domain/components/index.js';
+import { SpinnerModel } from '../domain/components/index.js';
+import { TableModel } from '../domain/components/index.js';
+import { ToastModel } from '../domain/components/index.js';
+import { SelectModel } from '../domain/components/index.js';
+import { AutocompleteModel } from '../domain/components/index.js';
+import { TreeModel } from '../domain/components/index.js';
+import { TabsModel } from '../domain/components/index.js';
+import { AccordionModel } from '../domain/components/index.js';
+import { GalleryModel } from '../domain/components/index.js';
+import { PriceModel } from '../domain/components/index.js';
+import { PricingModel } from '../domain/components/index.js';
+import { CommentModel } from '../domain/components/index.js';
+import { TestimonialModel } from '../domain/components/index.js';
+import { StatsItemModel } from '../domain/components/index.js';
+import { StatsModel } from '../domain/components/index.js';
+import { TimelineItemModel } from '../domain/components/index.js';
+import { TimelineModel } from '../domain/components/index.js';
+import { EmptyStateModel } from '../domain/components/index.js';
+import { BannerModel } from '../domain/components/index.js';
+import { ProfileDropdownModel } from '../domain/components/index.js';
+declare namespace Model {
     export { User };
+    export { HeaderModel };
+    export { FooterModel };
+    export { HeroModel };
+    export { ButtonModel };
+    export { ConfirmModel };
+    export { InputModel };
+    export { SpinnerModel };
+    export { TableModel };
+    export { ToastModel };
+    export { SelectModel };
+    export { AutocompleteModel };
+    export { TreeModel };
+    export { TabsModel };
+    export { AccordionModel };
+    export { GalleryModel };
+    export { PriceModel };
+    export { PricingModel };
+    export { CommentModel };
+    export { TestimonialModel };
+    export { StatsItemModel };
+    export { StatsModel };
+    export { TimelineItemModel };
+    export { TimelineModel };
+    export { EmptyStateModel };
+    export { BannerModel };
+    export { ProfileDropdownModel };
 }
-export default _default;
-import User from './User/User.js';
+export { User, HeaderModel, FooterModel, HeroModel, ButtonModel, ConfirmModel, InputModel, SpinnerModel, TableModel, ToastModel, SelectModel, AutocompleteModel, TreeModel, TabsModel, AccordionModel, GalleryModel, PriceModel, PricingModel, CommentModel, TestimonialModel, StatsItemModel, StatsModel, TimelineItemModel, TimelineModel, EmptyStateModel, BannerModel, ProfileDropdownModel };

package/types/StdIn.d.ts

@@ -22,10 +22,10 @@ export default class StdIn extends EventProcessor {
         processor?: Processor | undefined;
         stream?: UiMessage[] | undefined;
     });
-    /** @type {UiMessage[]} Input message buffer */
-    stream: UiMessage[];
     /** @type {Processor} Input processor */
     processor: Processor;
+    /** @type {UiMessage[]} Input message buffer */
+    stream: UiMessage[];
     /**
      * Checks if there are messages waiting in the input stream.
      * @returns {boolean} True if waiting messages, false otherwise
@@ -56,7 +56,7 @@ export default class StdIn extends EventProcessor {
     decode(message: UiMessage | string[] | any): UiMessage;
 }
 import EventProcessor from '@nan0web/event/oop';
-import { UiMessage } from './core/index.js';
 declare class Processor extends EventProcessor {
 }
+import { UiMessage } from './core/index.js';
 export {};

package/types/cli.d.ts

@@ -0,0 +1 @@
+export { UIApp as default } from "./domain/app/UIApp.js";

package/types/core/Form/Form.d.ts

@@ -89,9 +89,9 @@ export default class UIForm extends FormMessage {
     /**
      * Validates the entire form.
      *
-     * @returns {Map<string, string>} Map of validation errors, empty if valid.
+     * @returns {any}
      */
-    validate(): Map<string, string>;
+    validate(): any;
     /**
      * Validates a single field.
      *

package/types/core/GeneratorRunner.d.ts

@@ -29,9 +29,21 @@ export type AdapterHandlers = {
      */
     progress?: ((intent: import("./Intent.js").ProgressIntent) => void | Promise<void>) | undefined;
     /**
-     * Handler for 'log' intents. Optional (defaults to no-op).
+     * Handler for 'show' intents. Optional (defaults to no-op).
+     */
+    show?: ((intent: import("./Intent.js").ShowIntent) => void | Promise<void>) | undefined;
+    /**
+     * Handler for 'log' intents. Optional.
      */
     log?: ((intent: import("./Intent.js").LogIntent) => void | Promise<void>) | undefined;
+    /**
+     * Handler for 'agent' intents (AI Subagents). Optional (fallback to show if not implemented).
+     */
+    agent?: ((intent: import("./Intent.js").AgentIntent) => Promise<import("./Intent.js").AgentResponse>) | undefined;
+    /**
+     * Handler for 'render' intents (visual component injection). Optional.
+     */
+    render?: ((intent: import("./Intent.js").RenderIntent) => void | Promise<void>) | undefined;
     /**
      * Handler for the final 'result'. Optional (defaults to no-op).
      */
@@ -48,4 +60,9 @@ export type RunnerOptions = {
      * External AbortSignal for cancellation from outside.
      */
     signal?: AbortSignal | undefined;
+    /**
+     * Array where all executed intents will be sequentially recorded.
+     * Useful for generating 'crash reports' or Nan0Spec files on failure.
+     */
+    trace?: import("./Intent.js").Intent[] | undefined;
 };

package/types/core/InputAdapter.d.ts

@@ -4,7 +4,7 @@
  * @class InputAdapter
  * @extends Event
  */
-export default class InputAdapter extends Event {
+export class InputAdapter extends Event {
     static CancelError: typeof CancelError;
     /** @returns {typeof CancelError} */
     get CancelError(): typeof CancelError;
@@ -42,5 +42,6 @@ export default class InputAdapter extends Event {
         value: string | null;
     }>;
 }
+export default InputAdapter;
 import Event from '@nan0web/event/oop';
 import CancelError from './Error/CancelError.js';