@nan0web/ui 1.12.1 → 1.12.3

package/src/domain/ModelAsApp.js

@@ -1,46 +1,336 @@
-import { Model } from '@nan0web/types'
-import { result } from '../core/Intent.js'
+import { Model, getMetadata } from '@nan0web/types'
+import { result, ask, show } from '../core/Intent.js'
 import { InputAdapter } from '../core/InputAdapter.js'
+import { resolvePositionalArgs } from '../core/resolvePositionalArgs.js'
 
-/** @typedef {import('@nan0web/types').ModelOptions & { adapter: InputAdapter }} ModelAsAppOptions */
+/**
+ * @typedef {Object} AppOptions
+ * @property {InputAdapter} adapter
+ * @property {string} parentPath
+ * @property {boolean} _isExplicit
+ */
+/** @typedef {import('@nan0web/types').ModelOptions & AppOptions} ModelAsAppOptions */
 
 /**
  * The model with a run generator.
+ * @property {boolean} help Show help
  */
 export class ModelAsApp extends Model {
-	/** @type {ModelAsAppOptions} */
-	#appOptions = {
-		t: (key) => key,
-		plugins: {},
-		adapter: null,
+	static help = {
+		help: 'Show help',
+		default: false,
 	}
+
 	/**
 	 * @param {Partial<ModelAsApp> | Record<string, any>} [data={}]
 	 * @param {Partial<ModelAsAppOptions>} [options={}]
 	 */
 	constructor(data = {}, options = {}) {
 		super(data, options)
-		this.#appOptions = {
-			...options,
-			t:
-				options.t ||
-				((key, props = {}) =>
-					String(key)
-						.replace(/{(\w+)}/g, (_, x) => props[x] ?? `{${x}}`)
-						.replace(/_/g, ' ')),
-			plugins: options.plugins || {},
+		/** @type {boolean} Show help */ this.help
+		this._ =  {
+			...this._,
 			adapter: options.adapter || new InputAdapter(),
+			parentPath: String(options.parentPath || ''),
+			_isExplicit: Boolean(options._isExplicit),
+		}
+
+		// ── Automated Sub-Command Instantiation ──
+		const metadata = getMetadata(this.constructor)
+		for (const [key, meta] of Object.entries(metadata)) {
+			if (meta && typeof meta === 'object' && Array.isArray(meta.options)) {
+				const val = /** @type {any} */ (this)[key]
+				if (val) {
+					/** @type {any} */ this[key] = this._instantiateSubCommand(key, val, data)
+				}
+			}
+		}
+	}
+
+	/**
+	 * Instantiates a subcommand if the value matches one of the options.
+	 * @param {string} key - Field name.
+	 * @param {any} val - Current value (string, class, or instance).
+	 * @param {any} [data={}] - Data to pass to the new instance.
+	 * @returns {any} Instantiated subcommand or original value.
+	 */
+	_instantiateSubCommand(key, val, data = {}) {
+		if (val && typeof val === 'object' && typeof val.run === 'function') return val
+
+		const Class = /** @type {typeof ModelAsApp} */ (this.constructor)
+		const meta = /** @type {any} */ (Class)[key]
+		if (!meta || !Array.isArray(meta.options)) return val
+
+		let SubClass = null
+		let isExplicit = false
+		if (typeof val === 'function' && val.prototype && typeof val.prototype.run === 'function') {
+			SubClass = val
+		} else if (typeof val === 'string') {
+			SubClass = meta.options.find((C) => {
+				if (typeof C !== 'function') return false
+				const className = typeof C.name === 'string' ? C.name : ''
+				const alias =
+					(typeof C.alias === 'string' ? C.alias : null) ||
+					className.replace(/Command|App/g, '').toLowerCase()
+				return alias === val
+			})
+			isExplicit = !!SubClass
+		}
+
+		if (SubClass) {
+			const className = typeof Class.name === 'string' ? Class.name : ''
+			const myAlias =
+				(typeof /** @type {any} */ (Class).alias === 'string' ? /** @type {any} */ (Class).alias : null) ||
+				className.replace(/Command|App/g, '').toLowerCase()
+			const fullPath = this._.parentPath ? `${this._.parentPath} ${myAlias}` : myAlias
+
+			const finalData = resolvePositionalArgs(SubClass, data._positionals || [], data)
+			return new SubClass(finalData, { ...this._, parentPath: fullPath, _isExplicit: isExplicit })
+		}
+
+		return val
+	}
+
+	/**
+	 * Generate help text for the model
+	 * @param {string} [parentPath]
+	 * @returns {string}
+	 */
+	generateHelp(parentPath = this._.parentPath) {
+		const Class = /** @type {typeof ModelAsApp} */ (this.constructor)
+
+		// Delegate help to sub-command ONLY if it was explicitly requested via arguments.
+		// This prevents "store --help" from showing "store list --help" documentation.
+		for (const key in this) {
+			const val = /** @type {any} */ (this)[key]
+			if (val instanceof ModelAsApp && val['help'] && val._._isExplicit) {
+				const className = typeof Class.name === 'string' ? Class.name : ''
+				const myAlias =
+					(typeof /** @type {any} */ (Class).alias === 'string' ? /** @type {any} */ (Class).alias : null) ||
+					className.replace(/Command|App/g, '').toLowerCase()
+				const fullPath = parentPath ? `${parentPath} ${myAlias}` : myAlias
+				return val.generateHelp(fullPath)
+			}
+		}
+
+		const className = typeof Class.name === 'string' ? Class.name : ''
+		const myAlias =
+			(typeof /** @type {any} */ (Class).alias === 'string' ? /** @type {any} */ (Class).alias : null) ||
+			className.replace(/Command|App/g, '').toLowerCase()
+		const fullPath = parentPath ? `${parentPath} ${myAlias}` : myAlias
+
+		const t = this._.t
+		const lines = []
+
+		/** @type {any} */
+		const UI =
+			typeof (/** @type {any} */ (Class).UI) === 'object' && /** @type {any} */ (Class).UI
+				? /** @type {any} */ (Class).UI
+				: {}
+
+		if (UI.title) {
+			lines.push(`# ${UI.icon ? UI.icon + ' ' : ''}${t(UI.title)}`.trim())
+			if (UI.description) lines.push(`${t(UI.description)}`)
+			lines.push('')
+		}
+
+		const posMeta = []
+		const posNames = []
+		for (const key in Class) {
+			const meta = /** @type {any} */ (Class)[key]
+			if (meta && typeof meta === 'object' && meta.help && meta.positional) {
+				posNames.push(meta.required ? `<${key}>` : `[${key}]`)
+				posMeta.push({ key, meta })
+			}
 		}
+
+		const usageTitle = UI.usageTitle ? t(UI.usageTitle) : 'Usage:'
+		lines.push(`## ${usageTitle}`)
+		lines.push('```bash')
+		const posStr = posNames.length > 0 ? ` ${posNames.join(' ')}` : ''
+		lines.push(`${fullPath}${posStr} [options]`.trimEnd())
+
+		let usageExamples = UI.usageExamples
+		if (!usageExamples) {
+			for (const key in Class) {
+				const meta = /** @type {any} */ (Class)[key]
+				if (
+					meta &&
+					typeof meta === 'object' &&
+					meta.positional &&
+					(Array.isArray(meta.type) || Array.isArray(meta.options))
+				) {
+					usageExamples = []
+					const subcommands = Array.isArray(meta.type) ? meta.type : meta.options
+					for (const SubCmd of subcommands) {
+						if (SubCmd && SubCmd.prototype && SubCmd.prototype.generateHelp) {
+							const subClassName = typeof SubCmd.name === 'string' ? SubCmd.name : ''
+							const cmdName = SubCmd.alias || subClassName.replace(/Command|App/g, '').toLowerCase()
+							const desc = SubCmd.UI?.title ? t(SubCmd.UI.title) : ''
+							usageExamples.push(`${fullPath} ${cmdName} ${desc ? `— ${desc}` : ''}`.trim())
+						}
+					}
+					if (usageExamples.length === 0) usageExamples = undefined
+					break
+				}
+			}
+		}
+
+		if (Array.isArray(usageExamples)) {
+			let maxLeft = 0
+			/** @type {any[]} */
+			const parsedExamples = []
+			for (const ex of usageExamples) {
+				const renderedStr = t(ex, { cmd: fullPath })
+				const match = renderedStr.match(/^(.*?)\s+(—|-)\s+(.*)$/)
+				if (match) {
+					const left = match[1].trim()
+					const sep = match[2]
+					const right = match[3].trim()
+					maxLeft = Math.max(maxLeft, left.length)
+					parsedExamples.push({ left, sep, right })
+				} else {
+					parsedExamples.push({ left: renderedStr.trim(), sep: '', right: '' })
+				}
+			}
+			for (const p of parsedExamples) {
+				if (p.right) {
+					lines.push(`${p.left.padEnd(maxLeft + 3)}${p.sep} ${p.right}`)
+				} else {
+					lines.push(p.left)
+				}
+			}
+		}
+		lines.push('```')
+		lines.push('')
+
+		if (posMeta.length > 0) {
+			lines.push(`## Arguments:`)
+			lines.push('```bash')
+			let maxPosLen = 0
+			for (const p of posMeta) maxPosLen = Math.max(maxPosLen, p.key.length)
+			for (const p of posMeta) {
+				const desc = t(p.meta.help)
+				let defValue = p.meta.default
+				if (typeof defValue === 'function' && defValue.prototype) {
+					const defClassName = typeof defValue.name === 'string' ? defValue.name : ''
+					defValue = defValue.alias || defClassName.replace(/Command|App/g, '').toLowerCase()
+				}
+				const def = defValue !== undefined ? ` [${defValue}]` : ''
+				lines.push(`  ${p.key.padEnd(maxPosLen + 2)} - ${desc}${def}`)
+			}
+			lines.push('```')
+			lines.push('')
+		}
+
+		const optionsTitle = t(UI.optionsTitle || 'Options:')
+		lines.push(`## ${optionsTitle}`)
+		lines.push('```bash')
+
+		let maxOptLen = 0
+		let hasAlias = false
+		/** @type {Array<{key: string, meta: any, left: string}>} */
+		const parsedOptions = []
+
+		for (const key in Class) {
+			const meta = /** @type {any} */ (Class)[key]
+			if (!meta || typeof meta !== 'object' || !meta.help || key === 'UI' || meta.positional)
+				continue
+			if (meta.alias) hasAlias = true
+		}
+
+		const entries = []
+		for (const key in Class) {
+			entries.push([key, /** @type {any} */ (Class)[key]])
+		}
+		const sortedEntries = entries.sort(([a], [b]) => a.localeCompare(b))
+
+		for (const [key, meta] of sortedEntries) {
+			if (!meta || typeof meta !== 'object' || !meta.help || key === 'UI' || meta.positional)
+				continue
+
+			let left
+			if (hasAlias) {
+				left = meta.alias ? `  -${meta.alias}, --${key}` : `      --${key}`
+			} else {
+				left = `  --${key}`
+			}
+
+			maxOptLen = Math.max(maxOptLen, left.length)
+			parsedOptions.push({ key, meta, left })
+		}
+
+		for (const opt of parsedOptions) {
+			let right = t(opt.meta.help)
+			if (
+				opt.key !== 'help' &&
+				opt.meta.default !== undefined &&
+				opt.meta.default !== null &&
+				typeof opt.meta.default !== 'function' &&
+				!Array.isArray(opt.meta.default)
+			) {
+				if (['boolean', 'string', 'number'].includes(typeof opt.meta.default)) {
+					right += ` [${opt.meta.default}]`
+				}
+			}
+			lines.push(`${opt.left.padEnd(maxOptLen + 2)} - ${right}`)
+		}
+
+		lines.push('```')
+		lines.push('')
+		return lines.join('\n')
 	}
 
-	/** @returns {ModelAsAppOptions} */
-	get _() {
-		return this.#appOptions
+	/**
+	 * Execute the model programmatically without a UI adapter.
+	 * @param {any} [data]
+	 * @param {Partial<ModelAsAppOptions>} [options]
+	 * @returns {Promise<any>}
+	 */
+	static async execute(data = {}, options = {}) {
+		const app = new this(data, options)
+		if (typeof app.run !== 'function') return null
+
+		let finalData = null
+		const gen = app.run()
+		let res = await gen.next()
+		while (!res.done) {
+			const intent = res.value
+			if (intent && intent.type === 'result') finalData = intent.data
+			res = await gen.next()
+		}
+		if (res.value && res.value.type === 'result') finalData = res.value.data
+		return finalData
 	}
+
 	/**
+	 * Default execution generator.
+	 * Automatically delegates to the first instantiated subcommand field.
+	 *
 	 * @returns {AsyncGenerator<import('@nan0web/ui').Intent, import('@nan0web/ui').ResultIntent, any>}
 	 */
 	async *run() {
+		// 1. Automatic Help Handling (Premium OLMUI style)
+		if (/** @type {any} */ (this).help) {
+			const content = this.generateHelp()
+			const UI = /** @type {any} */ (this.constructor).UI || {}
+			const title = UI.title || this.constructor.name
+
+			if (/** @type {any} */ (this).raw) {
+				yield show(content, 'info', /** @type {any} */ ({ format: 'markdown', raw: true }))
+			} else {
+				yield ask('help', { content, title: `${title} Help`, hint: 'content-viewer' })
+			}
+			return result({})
+		}
+
+		// 2. Automatic Subcommand Delegation
+		for (const key in this) {
+			const val = /** @type {any} */ (this)[key]
+			if (val instanceof ModelAsApp && val !== this) {
+				return yield* val.run()
+			}
+		}
 		return result({})
 	}
 }

package/src/domain/ModelAsApp.story.js

@@ -0,0 +1,117 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { ModelAsApp } from './ModelAsApp.js'
+import { runGenerator, show, result } from '../index.js'
+import DB from '@nan0web/db'
+
+// ─── 1. Mock Models for Testing ───
+
+class SubCommand extends ModelAsApp {
+	static UI = { title: 'Sub Logic' }
+	static alias = 'sub'
+	static timeout = {
+		help: 'Timeout to cancel',
+		default: 333,
+	}
+	constructor(data = {}, options = {}) {
+		super(data, options)
+		/** @type {number} Timeout to cancel */ this.timeout
+	}
+	async *run() {
+		yield show('Sub running')
+		return result({ ok: true, timeout: this.timeout })
+	}
+}
+
+/**
+ * @property {SubCommand} command
+ * @property {boolean} help
+ */
+class RootApp extends ModelAsApp {
+	static alias = 'root'
+	static UI = { title: 'Root App' }
+	static command = {
+		help: 'Target command',
+		options: [SubCommand],
+		positional: true,
+	}
+	static debug = {
+		help: 'Debug mode',
+		type: 'boolean',
+		default: false,
+	}
+}
+
+// ─── 2. User Stories ───
+
+describe('ModelAsApp User Stories', () => {
+	it('Story: Universal Help - renders sorted and inherited options', async () => {
+		const app = new RootApp()
+		const help = app.generateHelp()
+		assert.deepStrictEqual(help.split('\n'), [
+			'# Root App',
+			'',
+			'## Usage:',
+			'```bash',
+			'root [command] [options]',
+			'root sub   — Sub Logic',
+			'```',
+			'',
+			'## Arguments:',
+			'```bash',
+			'  command   - Target command',
+			'```',
+			'',
+			'## Options:',
+			'```bash',
+			'  --debug   - Debug mode [false]',
+			'  --help    - Show help',
+			'```',
+			'',
+		])
+	})
+
+	it('Story: Subcommand Auto-Routing - instantiates subcommand from string', async () => {
+		const app = new RootApp({ command: 'sub' })
+		const cmd = /** @type {any} */ (app).command
+		assert.ok(cmd instanceof SubCommand, 'Should auto-instantiate SubCommand')
+		assert.equal(cmd._.parentPath, 'root', 'Should inject parentPath')
+	})
+
+	it('Story: Subcommand Help - delegates help to subcommand if requested', async () => {
+		// Simulating "root sub --help"
+		const app = new RootApp({ command: 'sub', help: true })
+		const cmd = /** @type {any} */ (app).command
+		// In this case, root.command is instantiated and has help: true
+		assert.ok(cmd.help, 'Subcommand should have help: true')
+
+		const helpText = app.generateHelp()
+		assert.ok(helpText.includes('# Sub Logic'), 'Should show subcommand help')
+		assert.ok(helpText.includes('Usage:'), 'Should have usage')
+		assert.ok(helpText.includes('root sub'), 'Should have correct command path')
+	})
+
+	it('Story: Positional Mapping - resolves positionals into model fields', async () => {
+		const db = new DB()
+		await db.connect()
+
+		// We use execute to run without real UI
+		const res = await RootApp.execute({ command: 'sub', timeout: '3' }, { db })
+		assert.deepEqual(res, { ok: true, timeout: 3 }, 'Should execute subcommand and return result')
+		assert.equal(res.timeout, 3)
+	})
+
+	it('Story: OLMUI Lifecycle - flows through runGenerator handlers', async () => {
+		const app = new RootApp({ command: 'sub' })
+		const events = []
+
+		const data = await runGenerator(app.run(), {
+			ask: async () => ({ value: {}, cancelled: false }),
+			show: (i) => { events.push(`show:${i.message || i}`) },
+			result: (i) => i.data,
+		})
+
+		assert.equal(events[0], 'show:Sub running', 'Should capture show intent from subcommand')
+		assert.deepEqual(data, { ok: true, timeout: 333 }, 'Should capture final result')
+	})
+})

package/src/domain/app/GalleryCommand.js

@@ -1,7 +1,7 @@
 import { ModelAsApp } from '../ModelAsApp.js'
 import { resolvePositionalArgs } from '@nan0web/ui-cli'
 import SnapshotAuditor from './SnapshotAuditor.js'
-import GalleryRenderIntent from './GalleryRenderIntent.js'
+import GalleryRenderCommand from './GalleryRenderCommand.js'
 import { show, result } from '../../core/Intent.js'
 
 export class GalleryCommand extends ModelAsApp {
@@ -14,25 +14,26 @@ export class GalleryCommand extends ModelAsApp {
 	static action = {
 		type: 'string',
 		help: 'Command to run',
-		options: [SnapshotAuditor, GalleryRenderIntent],
-		default: SnapshotAuditor.alias || SnapshotAuditor.name,
+		options: [SnapshotAuditor, GalleryRenderCommand],
+		default: SnapshotAuditor,
 		positional: true,
 	}
 
 	/**
 	 * @param {Partial<GalleryCommand> | Record<string, any>} [data={}]
-	 * @param {import('@nan0web/types').ModelOptions} [options={}]
+	 * @param {Partial<import('@nan0web/types').ModelOptions>} [options={}]
 	 */
 	constructor(data = {}, options = {}) {
 		super(data, options)
-		/** @type {string} */ this.action
+		/** @type {typeof SnapshotAuditor | typeof GalleryRenderCommand} */ this.action
 		/** @type {string[]} */ this._positionals = []
 	}
 
+	/**
+	 * @returns {AsyncGenerator<import('@nan0web/ui').Intent, import('@nan0web/ui').ResultIntent, any>}
+	 */
 	async *run() {
-		const TargetAction = GalleryCommand.action.options.find(
-			(opt) => opt.alias === this.action || opt.name === this.action
-		)
+		const TargetAction = this.action
 
 		if (!TargetAction) {
 			yield show(this._.t(GalleryCommand.UI.unknownAction, { command: this.action }), 'error')

package/src/domain/app/{GalleryRenderIntent.js → GalleryRenderCommand.js}

@@ -1,9 +1,9 @@
-import { Model } from '@nan0web/types'
 import SnapshotRunner from './SnapshotRunner.js'
 
 import { show, result } from '../../core/Intent.js'
+import { ModelAsApp } from '../index.js'
 
-export class GalleryRenderIntent extends Model {
+export class GalleryRenderCommand extends ModelAsApp {
 	static alias = 'render'
 
 	static UI = {
@@ -11,36 +11,35 @@ export class GalleryRenderIntent extends Model {
 		success: '✅ Gallery render complete',
 		failed: '🚨 Gallery render failed: {error}',
 	}
-	
-	static dataDir = { 
-		type: 'string', 
+
+	static dataDir = {
+		type: 'string',
 		default: 'docs/data',
 		help: 'Path to source models directory'
 	}
-	
-	static dir = { 
-		type: 'string', 
+
+	static dir = {
+		type: 'string',
 		default: 'snapshots/core',
 		help: 'Path to output snapshots directory'
 	}
 
 	/**
-
-	 * @param {Partial<GalleryRenderIntent> | Record<string, any>} [data={}]
-
-	 * @param {import('@nan0web/types').ModelOptions} [options={}]
-
+	 * @param {Partial<GalleryRenderCommand> | Record<string, any>} [data={}]
+	 * @param {Partial<import('@nan0web/types').ModelOptions>} [options={}]
 	 */
-
 	constructor(data = {}, options = {}) {
 		super(data, options)
 		/** @type {string} */ this.dataDir
 		/** @type {string} */ this.dir
 	}
 
+	/**
+	 * @returns {AsyncGenerator<import('../../core/Intent.js').Intent, import('../../core/Intent.js').ResultIntent, any>}
+	 */
 	async *run() {
-		yield show(this._.t(GalleryRenderIntent.UI.rendering, { dataDir: this.dataDir, dir: this.dir }))
-		
+		yield show(this._.t(GalleryRenderCommand.UI.rendering, { dataDir: this.dataDir, dir: this.dir }))
+
 		const snapshotRunner = new SnapshotRunner({
 			dataDir: this.dataDir,
 			snapshotsDir: this.dir,
@@ -62,16 +61,17 @@ export class GalleryRenderIntent extends Model {
 		try {
 			const res = yield* snapshotRunner.run()
 			if (res.data && res.data.success) {
-				yield show(this._.t(GalleryRenderIntent.UI.success, {}))
+				yield show(this._.t(GalleryRenderCommand.UI.success, {}))
 			} else {
-				yield show(this._.t(GalleryRenderIntent.UI.failed, { error: 'Audit failed' }), 'error')
+				yield show(this._.t(GalleryRenderCommand.UI.failed, { error: 'Audit failed' }), 'error')
 				return result({ status: 'error' })
 			}
 		} catch (error) {
-			yield show(this._.t(GalleryRenderIntent.UI.failed, { error: /** @type {Error} */ (error).message }), 'error')
+			yield show(this._.t(GalleryRenderCommand.UI.failed, { error: /** @type {Error} */ (error).message }), 'error')
 			return result({ status: 'error' })
 		}
+		return result({})
 	}
 }
 
-export default GalleryRenderIntent
+export default GalleryRenderCommand