@nan0web/ui 1.12.0 → 1.12.2

package/README.md

@@ -250,6 +250,16 @@ const res = await ScenarioTest.run(ValidatedApp, [
 	{ field: 'code', value: '' } // Simulating empty response
 ])
 ```
+### Story Testing (.nan0 spec files)
+
+The `SpecRunner.executeFile` helper allows running `.nan0` spec stories automatically without boilerplate DBFS setup.
+All manual assertions are omitted because `SpecAdapter` handles strict expectation matching internally.
+
+How to execute .nan0 spec files automatically?
+```js
+import { SpecRunner } from '@nan0web/ui/testing'
+const { SpecRunner } = await import('./testing/index.js')
+```
 All components, adapters, and models are designed to be testable
 with minimal setup.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nan0web/ui",
-  "version": "1.12.0",
+  "version": "1.12.2",
   "description": "NaN•Web UI. One application logic (algorithm) and many UI.",
   "main": "src/index.js",
   "types": "types/index.d.ts",
@@ -74,23 +74,23 @@
     "lit": "^3.3.2",
     "vite": "^6.4.1",
     "vitest": "^3.2.4",
-    "@nan0web/db-fs": "1.2.1",
+    "@nan0web/db-fs": "1.2.2",
     "@nan0web/event": "1.0.1",
-    "@nan0web/icons": "1.1.0",
     "@nan0web/i18n": "1.5.0",
-    "@nan0web/ui-cli": "2.13.0",
     "@nan0web/inspect": "1.0.0",
     "@nan0web/test": "1.1.4",
-    "@nan0web/nan0web.app": "0.1.0",
+    "@nan0web/ui-cli": "2.13.1",
     "@nan0web/release": "1.0.3",
-    "@nan0web/ui-lit": "1.1.0"
+    "@nan0web/icons": "1.1.0",
+    "@nan0web/ui-lit": "1.1.0",
+    "@nan0web/nan0web.app": "0.1.0"
   },
   "dependencies": {
     "string-width": "^7.2.0",
     "@nan0web/co": "2.0.1",
     "@nan0web/core": "1.1.3",
-    "@nan0web/log": "1.1.1",
-    "@nan0web/types": "1.7.2"
+    "@nan0web/types": "1.7.3",
+    "@nan0web/log": "1.1.1"
   },
   "scripts": {
     "prebuild": "rm -rf types/",

package/src/App/Core/CoreApp.js

@@ -15,7 +15,7 @@ export default class CoreApp {
 	/** @type {Map<string, CommandFn>} Registered command handlers */
 	commands
 
-	/** @type {object} App state */
+	/** @type {Record<string, any>} App state */
 	state
 
 	/** @type {Message} Starting command parsed from argv */

package/src/View/View.js

@@ -28,7 +28,7 @@ export default class View {
 	frame
 	/** @type {Locale} */
 	locale
-	/** @type {Map} */
+	/** @type {Map<string, string>} */
 	vocab
 	/** @type {number[]} */
 	windowSize
@@ -43,7 +43,7 @@ export default class View {
 	 * @param {number} [input.startedAt]
 	 * @param {Frame} [input.frame]
 	 * @param {Locale} [input.locale]
-	 * @param {Map} [input.vocab]
+	 * @param {Map<string, string>} [input.vocab]
 	 * @param {number[]} [input.windowSize]
 	 * @param {Map<string, ComponentFn>} [input.components]
 	 * @param {string} [input.renderMethod]
@@ -66,7 +66,7 @@ export default class View {
 		this.frame = frame
 		this.locale = locale
 		this.vocab = vocab
-		this.windowSize = null === windowSize ? this.stdout.getWindowSize() : windowSize
+		this.windowSize = /** @type {number[]} */ (null === windowSize ? this.stdout.getWindowSize() : windowSize)
 		this.components = components
 		this.renderMethod = renderMethod
 		if (!empty(frame)) {
@@ -85,6 +85,10 @@ export default class View {
 	getWindowSize() {
 		return equal(this.windowSize, [0, 0]) ? this.stdout.getWindowSize() : this.windowSize
 	}
+	/**
+	 * @param {number} width
+	 * @param {number} height
+	 */
 	setWindowSize(width, height) {
 		this.windowSize = [width, height]
 	}
@@ -181,6 +185,7 @@ export default class View {
 		}
 	}
 
+	/** @param {any} value */
 	t(value) {
 		if (typeOf(Array)(value)) {
 			value = value.map((row) => {
@@ -196,16 +201,22 @@ export default class View {
 		return this.vocab.has(value) ? this.vocab.get(value) : value
 	}
 
+	/** @param {any[]} args */
 	debug(...args) {
+		// @ts-ignore
 		return this.render(1)([StdOut.STYLES.dim, 'Debug: ', args.join(' '), Frame.EOL, StdOut.RESET])
 	}
 
+	/** @param {any[]} args */
 	info(...args) {
+		// @ts-ignore
 		return this.render(1)([StdOut.COLORS.green, 'Info : ', args.join(' '), Frame.EOL, StdOut.RESET])
 	}
 
+	/** @param {any[]} args */
 	warn(...args) {
 		return this.render(1)([
+			// @ts-ignore
 			StdOut.COLORS.yellow,
 			'Warn : ',
 			args.join(' '),
@@ -214,8 +225,10 @@ export default class View {
 		])
 	}
 
+	/** @param {any[]} args */
 	error(...args) {
 		return this.render(1)([
+			// @ts-ignore
 			StdOut.COLORS.red,
 			StdOut.STYLES.bold,
 			'Error: ',

package/src/core/GeneratorRunner.js

@@ -276,6 +276,14 @@ export async function runGenerator(generator, handlers, options = {}) {
 				break
 			}
 
+			case 'result': {
+				if (handlers.result) {
+					await handlers.result(intent)
+				}
+				nextVal = undefined
+				break
+			}
+
 			default:
 				throw IntentErrorModel.error('unhandled_intent', { type: /** @type {any} */ (intent).type })
 		}

package/src/core/Intent.js

@@ -72,6 +72,7 @@ import { IntentErrorModel } from './IntentErrorModel.js'
  * @typedef {Object} ResultIntent
  * @property {'result'} type
  * @property {*} data - The raw result data (JSON-serializable).
+ * @property {boolean} [raw] - If true, Adapter MUST output data raw (no UI decorations).
  */
 
 /**
@@ -312,10 +313,11 @@ export function render(component, props = {}) {
 /**
  * Create a result intent.
  * @param {*} data - The raw result data.
+ * @param {boolean} [raw=false] - If true, result is printed raw.
  * @returns {ResultIntent}
  */
-export function result(data) {
-	return { type: 'result', data }
+export function result(data, raw = false) {
+	return { type: 'result', data, raw }
 }
 
 /**

package/src/domain/ModelAsApp.js

@@ -16,7 +16,7 @@ export class ModelAsApp extends Model {
 	}
 	/**
 	 * @param {Partial<ModelAsApp> | Record<string, any>} [data={}]
-	 * @param {ModelAsAppOptions} [options={}]
+	 * @param {Partial<ModelAsAppOptions>} [options={}]
 	 */
 	constructor(data = {}, options = {}) {
 		super(data, options)

package/src/domain/app/ConfigApp.js

@@ -0,0 +1,61 @@
+import { ModelAsApp } from '../ModelAsApp.js'
+import { show, result, render } from '../../core/Intent.js'
+
+export default class ConfigApp extends ModelAsApp {
+	static name = 'config'
+	static alias = 'cfg'
+
+	static resource = {
+		type: 'string',
+		help: 'Resource to configure (e.g. agents)',
+		positional: true,
+		default: 'agents',
+	}
+
+	static action = {
+		type: 'string',
+		help: 'Action to perform (e.g. list)',
+		positional: true,
+		default: 'list',
+	}
+
+	constructor(data = {}, options = {}) {
+		super(data, options)
+		this.resource = data.resource || 'agents'
+		this.action = data.action || 'list'
+	}
+
+	async *run() {
+		if (this.resource === 'agents') {
+			if (this.action === 'list') {
+				const DBFS = (await import('@nan0web/db-fs')).default
+				const db = new DBFS({ root: process.cwd() })
+				const config = await db.loadDocument('nan0web.nan0', {}).catch(() => ({}))
+
+				if (!config || !config.agents || !Array.isArray(config.agents)) {
+					yield show('No agents configured in nan0web.nan0')
+					return result({ success: true })
+				}
+
+				const tableData = config.agents.map((a) => ({
+					ID: a.id,
+					Description: a.description,
+					Workflows: a.workflows ? a.workflows.length : 0,
+					Inspectors: a.inspectors ? a.inspectors.length : 0,
+				}))
+
+				yield render('Table', { 
+					data: tableData, 
+					columns: ['ID', 'Description', 'Workflows', 'Inspectors'],
+					interactive: false 
+				})
+				return result({ success: true })
+			}
+			yield show(`Unknown action for agents: ${this.action}`, 'error')
+			return result({ success: false })
+		}
+
+		yield show(`Unknown config resource: ${this.resource}`, 'error')
+		return result({ success: false })
+	}
+}

package/src/domain/app/UIApp.js

@@ -2,13 +2,14 @@ import { ModelAsApp } from '../ModelAsApp.js'
 import { resolvePositionalArgs } from '@nan0web/ui-cli'
 import SnapshotAuditor from './SnapshotAuditor.js'
 import GalleryCommand from './GalleryCommand.js'
+import ConfigApp from './ConfigApp.js'
 import { show, result } from '../../core/Intent.js'
 
 export class UIApp extends ModelAsApp {
 	static command = {
 		type: 'string',
 		help: 'Command to run (e.g. gallery)',
-		options: [GalleryCommand, SnapshotAuditor],
+		options: [GalleryCommand, SnapshotAuditor, ConfigApp],
 		default: GalleryCommand.alias || GalleryCommand.name,
 		positional: true,
 	}

package/src/testing/SpecRunner.js

@@ -35,6 +35,43 @@ export class SpecRunner extends ModelAsApp {
 		this.registry
 	}
 
+	/**
+	 * Convenience method to load a .nan0 file and run a specific scenario.
+	 * 
+	 * 💡 Note on Expectations:
+	 * You do NOT need to write manual assertions when using this method. 
+	 * The `for await (const _ of runner.run()) {}` loop drives the generator,
+	 * but ALL assertions are handled automatically inside `SpecAdapter.js`.
+	 * 
+	 * Whenever the App yields an intent (`ask`, `show`, `result`), `SpecAdapter`
+	 * intercepts it and compares it strictly against the next step in the `.nan0` file.
+	 * - If it matches, the test continues (and `$value` is injected back into the App).
+	 * - If it mismatches, it throws an `assert.fail()` which fails the Node.js test immediately.
+	 * - If the App finishes early, it throws an `unhandledSteps` error.
+	 * 
+	 * @param {string} fileDir The directory containing the file (e.g., import.meta.dirname)
+	 * @param {string} fileName The name of the .nan0 file
+	 * @param {string} scenarioName The name of the scenario to run
+	 * @param {Record<string, any>} registry The Model Class registry
+	 * @param {Partial<import('../index.js').ModelAsAppOptions>} [options={}] Additional runner context options
+	 * @throws {Error} If the scenario is missing or if expectations fail during execution
+	 */
+	static async executeFile(fileDir, fileName, scenarioName, registry, options = {}) {
+		const DB = (await import('@nan0web/db-fs')).DBFS
+		const db = new DB({ root: fileDir })
+		const doc = await db.loadDocument(fileName)
+		const scenarios = Array.isArray(doc) ? doc : [doc]
+		const scenario = scenarios.find((s) => s.name === scenarioName) || scenarios[0]
+
+		if (!scenario) throw new Error(`Scenario ${scenarioName} not found in ${fileName}`)
+		if (!scenario.story) throw new Error(`Scenario ${scenarioName} has no story array`)
+
+		const runner = new this({ stream: scenario.story, registry }, options)
+		for await (const _ of runner.run()) {
+			// Iterate completely
+		}
+	}
+
 	/**
 	 * @throws {Error}
 	 * @returns {AsyncGenerator<import('../core/Intent.js').Intent, import('../core/Intent.js').ResultIntent, any>}

package/types/App/Core/CoreApp.d.ts

@@ -20,8 +20,8 @@ export default class CoreApp {
     name: string;
     /** @type {Map<string, CommandFn>} Registered command handlers */
     commands: Map<string, CommandFn>;
-    /** @type {object} App state */
-    state: object;
+    /** @type {Record<string, any>} App state */
+    state: Record<string, any>;
     /** @type {Message} Starting command parsed from argv */
     startCommand: Message;
     /**

package/types/View/View.d.ts

@@ -22,7 +22,7 @@ export default class View {
      * @param {number} [input.startedAt]
      * @param {Frame} [input.frame]
      * @param {Locale} [input.locale]
-     * @param {Map} [input.vocab]
+     * @param {Map<string, string>} [input.vocab]
      * @param {number[]} [input.windowSize]
      * @param {Map<string, ComponentFn>} [input.components]
      * @param {string} [input.renderMethod]
@@ -33,7 +33,7 @@ export default class View {
         startedAt?: number | undefined;
         frame?: Frame | undefined;
         locale?: Locale | undefined;
-        vocab?: Map<any, any> | undefined;
+        vocab?: Map<string, string> | undefined;
         windowSize?: number[] | undefined;
         components?: Map<string, ComponentFn> | undefined;
         renderMethod?: string | undefined;
@@ -48,8 +48,8 @@ export default class View {
     frame: Frame;
     /** @type {Locale} */
     locale: Locale;
-    /** @type {Map} */
-    vocab: Map<any, any>;
+    /** @type {Map<string, string>} */
+    vocab: Map<string, string>;
     /** @type {number[]} */
     windowSize: number[];
     /** @type {Map<string, ComponentFn>} */
@@ -60,7 +60,11 @@ export default class View {
     get RenderMethod(): typeof FrameRenderMethod;
     get RenderOptions(): typeof RenderOptions;
     getWindowSize(): number[];
-    setWindowSize(width: any, height: any): void;
+    /**
+     * @param {number} width
+     * @param {number} height
+     */
+    setWindowSize(width: number, height: number): void;
     startTimer(): void;
     spent(checkpoint?: number): number;
     /**
@@ -71,10 +75,15 @@ export default class View {
     render(shouldRender?: boolean | number | Function | ComponentFn, options?: RenderOptions): (value: Frame | string | string[], ...args: any) => Frame;
     clear(shouldRender?: number): Frame;
     progress(shouldRender?: boolean): (value: any) => Frame;
+    /** @param {any} value */
     t(value: any): any;
+    /** @param {any[]} args */
     debug(...args: any[]): Frame;
+    /** @param {any[]} args */
     info(...args: any[]): Frame;
+    /** @param {any[]} args */
     warn(...args: any[]): Frame;
+    /** @param {any[]} args */
     error(...args: any[]): Frame;
     /**
      * @param {string} name

package/types/core/Intent.d.ts

@@ -59,9 +59,10 @@ export function render(component: string, props?: object): RenderIntent;
 /**
  * Create a result intent.
  * @param {*} data - The raw result data.
+ * @param {boolean} [raw=false] - If true, result is printed raw.
  * @returns {ResultIntent}
  */
-export function result(data: any): ResultIntent;
+export function result(data: any, raw?: boolean): ResultIntent;
 /**
  * @typedef {Object} ShowData
  * @property {any} [component]
@@ -135,6 +136,7 @@ export function agent(task: string, context?: AgentContext): AgentIntent;
  * @typedef {Object} ResultIntent
  * @property {'result'} type
  * @property {*} data - The raw result data (JSON-serializable).
+ * @property {boolean} [raw] - If true, Adapter MUST output data raw (no UI decorations).
  */
 /**
  * Model requests rendering of a pure UI component (Header, Footer, Static Map).
@@ -364,6 +366,10 @@ export type ResultIntent = {
      * - The raw result data (JSON-serializable).
      */
     data: any;
+    /**
+     * - If true, Adapter MUST output data raw (no UI decorations).
+     */
+    raw?: boolean | undefined;
 };
 /**
  * Model requests rendering of a pure UI component (Header, Footer, Static Map).

package/types/domain/ModelAsApp.d.ts

@@ -5,9 +5,9 @@
 export class ModelAsApp extends Model {
     /**
      * @param {Partial<ModelAsApp> | Record<string, any>} [data={}]
-     * @param {ModelAsAppOptions} [options={}]
+     * @param {Partial<ModelAsAppOptions>} [options={}]
      */
-    constructor(data?: Partial<ModelAsApp> | Record<string, any>, options?: ModelAsAppOptions);
+    constructor(data?: Partial<ModelAsApp> | Record<string, any>, options?: Partial<ModelAsAppOptions>);
     /** @returns {ModelAsAppOptions} */
     get _(): ModelAsAppOptions;
     /**

package/types/domain/app/ConfigApp.d.ts

@@ -0,0 +1,21 @@
+export default class ConfigApp extends ModelAsApp {
+    static name: string;
+    static alias: string;
+    static resource: {
+        type: string;
+        help: string;
+        positional: boolean;
+        default: string;
+    };
+    static action: {
+        type: string;
+        help: string;
+        positional: boolean;
+        default: string;
+    };
+    constructor(data?: {}, options?: {});
+    resource: any;
+    action: any;
+    run(): AsyncGenerator<import("../../core/Intent.js").ShowIntent | import("../../core/Intent.js").RenderIntent, import("../../core/Intent.js").ResultIntent, unknown>;
+}
+import { ModelAsApp } from '../ModelAsApp.js';

package/types/domain/app/UIApp.d.ts

@@ -2,7 +2,7 @@ export class UIApp extends ModelAsApp {
     static command: {
         type: string;
         help: string;
-        options: (typeof SnapshotAuditor | typeof GalleryCommand)[];
+        options: (typeof SnapshotAuditor | typeof GalleryCommand | typeof ConfigApp)[];
         default: string;
         positional: boolean;
     };
@@ -22,7 +22,7 @@ export class UIApp extends ModelAsApp {
     /** @type {string[]} */ _positionals: string[];
     /** @type {string} Type of command to run */ command: string;
     /** @type {boolean} Show help message */ help: boolean;
-    run(): AsyncGenerator<import("../../core/Intent.js").ShowIntent | (import("../../core/Intent.js").AskIntent & {
+    run(): AsyncGenerator<import("../../core/Intent.js").ShowIntent | import("../../core/Intent.js").RenderIntent | (import("../../core/Intent.js").AskIntent & {
         $value?: any;
         $success?: boolean;
         $files?: Record<string, string>;
@@ -37,11 +37,6 @@ export class UIApp extends ModelAsApp {
         $success?: boolean;
         $files?: Record<string, string>;
         $message?: string;
-    }) | (import("../../core/Intent.js").RenderIntent & {
-        $value?: any;
-        $success?: boolean;
-        $files?: Record<string, string>;
-        $message?: string;
     }) | (import("../../core/Intent.js").AgentIntent & {
         $value?: any;
         $success?: boolean;
@@ -58,3 +53,4 @@ export default UIApp;
 import { ModelAsApp } from '../ModelAsApp.js';
 import SnapshotAuditor from './SnapshotAuditor.js';
 import GalleryCommand from './GalleryCommand.js';
+import ConfigApp from './ConfigApp.js';

package/types/testing/SpecRunner.d.ts

@@ -16,6 +16,28 @@ export class SpecRunner extends ModelAsApp {
         running: string;
         unhandledSteps: string;
     };
+    /**
+     * Convenience method to load a .nan0 file and run a specific scenario.
+     *
+     * 💡 Note on Expectations:
+     * You do NOT need to write manual assertions when using this method.
+     * The `for await (const _ of runner.run()) {}` loop drives the generator,
+     * but ALL assertions are handled automatically inside `SpecAdapter.js`.
+     *
+     * Whenever the App yields an intent (`ask`, `show`, `result`), `SpecAdapter`
+     * intercepts it and compares it strictly against the next step in the `.nan0` file.
+     * - If it matches, the test continues (and `$value` is injected back into the App).
+     * - If it mismatches, it throws an `assert.fail()` which fails the Node.js test immediately.
+     * - If the App finishes early, it throws an `unhandledSteps` error.
+     *
+     * @param {string} fileDir The directory containing the file (e.g., import.meta.dirname)
+     * @param {string} fileName The name of the .nan0 file
+     * @param {string} scenarioName The name of the scenario to run
+     * @param {Record<string, any>} registry The Model Class registry
+     * @param {Partial<import('../index.js').ModelAsAppOptions>} [options={}] Additional runner context options
+     * @throws {Error} If the scenario is missing or if expectations fail during execution
+     */
+    static executeFile(fileDir: string, fileName: string, scenarioName: string, registry: Record<string, any>, options?: Partial<import("../index.js").ModelAsAppOptions>): Promise<void>;
     /**
      * Run a Nan0Spec sequence programmatically (for unit tests).
      *