@nan0web/release 3.3.0 → 3.4.0

package/src/domain/Registry/RegistryModel.js

@@ -0,0 +1,124 @@
+import { Model } from '@nan0web/types'
+
+/**
+ * @typedef {Object} ProjectEntry
+ * @property {string} path - Project relative or absolute path
+ * @property {string} name - Package name from package.json or folder basename
+ * @property {string} version - Package version from package.json
+ */
+
+/**
+ * RegistryModel - PM-as-Code Project Registry manager.
+ * Reads project paths from releases.txt and discovers package metadata.
+ */
+export class RegistryModel extends Model {
+	static filePath = {
+		help: 'Path to releases.txt registry file',
+		default: 'releases.txt',
+		type: 'string',
+	}
+
+	static projects = {
+		help: 'List of registered projects',
+		default: () => [],
+		type: 'array',
+	}
+
+	static UI = {
+		fileNotFound: 'Registry file {$path} not found',
+		loadingProjects: 'Loading projects from registry {$path}...',
+		projectsLoaded: 'Loaded {$count} projects from registry',
+	}
+
+	/**
+	 * @param {Partial<RegistryModel>} [data]
+	 * @param {import('@nan0web/types').ModelOptions} [options]
+	 */
+	constructor(data = {}, options = {}) {
+		super(data, options)
+		/** @type {string} Path to registry file */ this.filePath
+		/** @type {ProjectEntry[]} List of registered projects */ this.projects
+	}
+
+	/**
+	 * Parse raw content of releases.txt into array of clean paths
+	 * @param {string} content
+	 * @returns {string[]}
+	 */
+	static parsePaths(content = '') {
+		if (typeof content !== 'string') return []
+		return content
+			.split('\n')
+			.map((line) => {
+				// Strip comments starting with #
+				const withoutComment = line.split('#')[0]
+				return withoutComment.trim()
+			})
+			.filter((line) => line.length > 0)
+	}
+
+	/**
+	 * Load project entries from registry file using injected DB instance
+	 * @returns {Promise<ProjectEntry[]>}
+	 */
+	async loadProjects() {
+		const db = this._.db
+		if (!db) {
+			throw new Error('Database instance is required in options ({ db }) to load projects')
+		}
+
+		let content = await db.loadDocument(this.filePath, '')
+		let rootPrefix = ''
+		if (!content && this.filePath === 'releases.txt') {
+			try {
+				const parent2 = await db.loadDocument('../../releases.txt', '')
+				if (parent2) {
+					content = parent2
+					rootPrefix = '../../'
+				} else {
+					const parent1 = await db.loadDocument('../releases.txt', '')
+					if (parent1) {
+						content = parent1
+						rootPrefix = '../'
+					}
+				}
+			} catch {
+				// ignore
+			}
+		}
+
+		const paths = RegistryModel.parsePaths(String(content || ''))
+
+		/** @type {ProjectEntry[]} */
+		const result = []
+
+		for (const projectPath of paths) {
+			const effectivePath = rootPrefix
+				? projectPath === '.'
+					? rootPrefix.slice(0, -1)
+					: `${rootPrefix}${projectPath}`
+				: projectPath
+			const pkgPath = effectivePath === '.' ? 'package.json' : `${effectivePath.replace(/\/+$/, '')}/package.json`
+			let pkg = null
+			try {
+				pkg = await db.loadDocument(pkgPath, null)
+			} catch {
+				pkg = null
+			}
+
+			const name = pkg?.name || projectPath
+			const version = pkg?.version || '0.0.0'
+
+			result.push({
+				path: projectPath,
+				name,
+				version,
+			})
+		}
+
+		this.projects = result
+		return result
+	}
+}
+
+export default RegistryModel

package/src/domain/ServeCommand.js

@@ -0,0 +1,165 @@
+import { ModelAsApp, result, show } from '@nan0web/ui'
+import Markdown from '@nan0web/markdown'
+import DEFAULT_TEMPLATE from './templates/release.html.template.js'
+
+/**
+ * ServeCommand - Universal ModelAsApp for data or release catalogs.
+ *
+ * Generates HTML content from README.md and release templates using $db and Markdown.
+ * Pure OLMUI model: does not start HTTP server, does not call node:fs or child_process.
+ *
+ * Usage:
+ *   pnpm exec serve releases/  # Runs via CLI bootstrap
+ */
+export default class ServeCommand extends ModelAsApp {
+	static alias = 'serve'
+
+	static UI = {
+		title: 'serve',
+		help: 'Serve data or releases catalog over HTTP',
+		serving: '🌐 Serving {$dir} on http://localhost:{$port} (Press Ctrl+C to stop)',
+		dirNotFound: 'Directory {$dir} does not exist.',
+	}
+
+	static dir = {
+		help: 'Directory to serve (e.g. releases/ or data/)',
+		positional: true,
+		type: 'string',
+		default: 'releases',
+	}
+
+	static port = {
+		help: 'HTTP server port',
+		default: 3131,
+		type: 'number',
+		alias: 'p',
+	}
+
+	static open = {
+		help: 'Automatically open in browser',
+		default: true,
+		type: 'boolean',
+	}
+
+	/**
+	 * @param {Partial<ServeCommand>} [data]
+	 * @param {import('@nan0web/types').ModelOptions} [options]
+	 */
+	constructor(data = {}, options = {}) {
+		super(data, options)
+		/** @type {string} */
+		this.dir = String(data.dir || (options && 'dir' in options ? /** @type {any} */ (options).dir : 'releases'))
+		/** @type {number} */
+		this.port = Number(data.port ?? (options && 'port' in options ? /** @type {any} */ (options).port : 3131))
+		/** @type {boolean} */
+		this.open = Boolean(data.open ?? (options && 'open' in options ? /** @type {any} */ (options).open : true))
+	}
+
+	/**
+	 * Convert markdown string to HTML using @nan0web/markdown
+	 * @param {string} mdRaw
+	 * @returns {string}
+	 */
+	renderMarkdownToHtml(mdRaw) {
+		if (!mdRaw || typeof mdRaw !== 'string') return ''
+		const md = new Markdown(mdRaw)
+		return md.stringify()
+	}
+
+	/**
+	 * Render HTML content for the target directory
+	 * @returns {Promise<string>}
+	 */
+	async renderHtml() {
+		const db = this.$db
+		let readmeContent = ''
+		const readmePath = db.resolveSync ? db.resolveSync(this.dir, 'README.md') : `${this.dir}/README.md`
+
+		try {
+			const mdRaw = await db.loadDocument(readmePath, null)
+			if (mdRaw) {
+				readmeContent = this.renderMarkdownToHtml(typeof mdRaw === 'string' ? mdRaw : mdRaw.content || String(mdRaw))
+			}
+		} catch {}
+
+		if (!readmeContent) {
+			// If no README.md in directory, scan directory entries and list them nicely
+			let listItems = []
+			try {
+				if (typeof db.listDir === 'function') {
+					const entries = await db.listDir(this.dir)
+					if (entries && Array.isArray(entries)) {
+						listItems = entries
+							.map((e) => e?.name || e?.path || String(e))
+							.filter((name) => !name.startsWith('.'))
+					}
+				}
+			} catch {}
+
+			const title = this.dir === 'releases' ? 'Releases Catalog' : `Index of ${this.dir}`
+			let md = `# ${title}\n\n`
+			if (listItems.length > 0) {
+				md += `Found **${listItems.length}** item(s) in \`${this.dir}\`:\n\n`
+				for (const item of listItems) {
+					md += `- **\`${item}\`**\n`
+				}
+			} else {
+				md += `Directory \`${this.dir}\` is currently empty or contains no catalog entries.\n`
+			}
+			readmeContent = this.renderMarkdownToHtml(md)
+		}
+
+		// Load template via DB or fallback to bundled template
+		let templateRaw = null
+		try {
+			templateRaw = await db.loadDocument('packages/release/src/domain/templates/release.html', null)
+		} catch {}
+
+		if (!templateRaw) {
+			templateRaw = DEFAULT_TEMPLATE
+		}
+
+		return String(templateRaw).replace('{{CONTENT}}', readmeContent)
+	}
+
+	async *run() {
+		const db = this.$db
+
+		// Check if directory exists via db.listDir or db.stat
+		let dirExists = false
+		try {
+			if (typeof db.listDir === 'function') {
+				const entries = await db.listDir(this.dir)
+				dirExists = entries && entries.length > 0
+			}
+			if (!dirExists && typeof db.stat === 'function') {
+				const stat = await db.stat(this.dir)
+				dirExists = Boolean(stat && (stat.exists || stat.isDirectory || stat.isFile))
+			}
+		} catch {
+			dirExists = false
+		}
+
+		if (!dirExists) {
+			yield show(ServeCommand.UI.dirNotFound.replace('{$dir}', this.dir), 'error')
+			return result({ success: false })
+		}
+
+		const html = await this.renderHtml()
+
+		yield show(
+			ServeCommand.UI.serving.replace('{$dir}', this.dir).replace('{$port}', String(this.port)),
+			'success'
+		)
+
+		return result({
+			success: true,
+			dir: this.dir,
+			port: this.port,
+			open: this.open,
+			html,
+		})
+	}
+}
+
+export { ServeCommand }

package/src/domain/ServeCommand.story.js

@@ -0,0 +1,88 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import DB from '@nan0web/db'
+import ServeCommand from './ServeCommand.js'
+
+describe('ServeCommand OLMUI Scenario & Model Test', () => {
+	it('generates HTML from releases/README.md when directory exists', async () => {
+		const readmeMd = `# Releases
+
+This is the main catalog of releases.
+
+## Active Projects
+- @nan0web/ui
+- @nan0web/db
+`
+		const templateHtml = `<!DOCTYPE html><html><body><main>{{CONTENT}}</main></body></html>`
+
+		const db = new DB({
+			predefined: [
+				['releases/README.md', readmeMd],
+				['packages/release/src/domain/templates/release.html', templateHtml],
+			],
+		})
+		await db.connect()
+
+		const cmd = new ServeCommand({ dir: 'releases', port: 3131 }, { db })
+		const gen = cmd.run()
+
+		let step = await gen.next()
+		const outputs = []
+		while (!step.done) {
+			outputs.push(step.value)
+			step = await gen.next()
+		}
+
+		const res = step.value?.data || step.value
+		assert.ok(res.success !== false, 'Execution should succeed')
+		assert.equal(res.dir, 'releases')
+		assert.equal(res.port, 3131)
+		assert.ok(typeof res.html === 'string', 'Should return html string')
+		assert.ok(res.html.includes('Releases'), 'HTML should contain rendered markdown title')
+		assert.ok(res.html.includes('main'), 'HTML should use the template')
+	})
+
+	it('yields error when target directory does not exist', async () => {
+		const db = new DB({
+			predefined: [],
+		})
+		await db.connect()
+
+		const cmd = new ServeCommand({ dir: 'nonexistent-dir' }, { db })
+		const gen = cmd.run()
+
+		let step = await gen.next()
+		const outputs = []
+		while (!step.done) {
+			outputs.push(step.value)
+			step = await gen.next()
+		}
+
+		const res = step.value?.data || step.value
+		assert.equal(res.success, false)
+		assert.ok(outputs.some((o) => o?.type === 'show' || o?.tag === 'show' || String(o).includes('Directory') || o?.content?.includes('nonexistent-dir')))
+	})
+
+	it('handles missing README.md with fallback content', async () => {
+		const templateHtml = `<!DOCTYPE html><html><body>{{CONTENT}}</body></html>`
+		const db = new DB({
+			predefined: [
+				['releases/.gitkeep', ''],
+				['packages/release/src/domain/templates/release.html', templateHtml],
+			],
+		})
+		await db.connect()
+
+		const cmd = new ServeCommand({ dir: 'releases' }, { db })
+		const gen = cmd.run()
+
+		let step = await gen.next()
+		while (!step.done) {
+			step = await gen.next()
+		}
+
+		const res = step.value?.data || step.value
+		assert.ok(res.success !== false)
+		assert.ok(res.html.includes('Releases'))
+	})
+})

package/src/domain/SpecCommand.js

@@ -3,6 +3,9 @@ import { runSpawn } from '@nan0web/test'
 import Scanner from '../Release/Scanner.js'
 
 export default class SpecCommand extends ModelAsApp {
+	/** @type {string} Release version filter */
+	version = ''
+
 	static version = {
 		help: 'Release version filter',
 		default: '',
@@ -18,7 +21,6 @@ export default class SpecCommand extends ModelAsApp {
 	 */
 	constructor(data = {}, options = {}) {
 		super(data, options)
-		/** @type {string} Release version filter */ this.version
 	}
 
 	/**

package/src/domain/StatusCommand.js

@@ -1,16 +1,262 @@
 import { ModelAsApp, result, show } from '@nan0web/ui'
+import { DashboardModel } from './Dashboard/DashboardModel.js'
 import Scanner from '../Release/Scanner.js'
 
+/**
+ * StatusCommand - ModelAsApp Subcommand to display PM-as-Code dashboard and project inspector.
+ */
 export default class StatusCommand extends ModelAsApp {
+	static alias = 'status'
+
 	static UI = {
 		title: 'status',
-		help: 'Show release status',
+		help: 'Show release status dashboard or project inspector',
+		header: '📊 Global PM-as-Code Release Dashboard ({$file})',
+		summaryHeader: '📈 Summary:',
+		summaryRow1: '  Total Projects: {$total} | Active (WIP): {$wip} | Closed: {$closed}',
+		summaryRow2: '  Total Hours: {$hours}h | Total Iterations: {$iterations}',
+		noProjects: 'No projects registered in {$file}',
+	}
+
+	static registryFile = {
+		help: 'Path to releases.txt registry file',
+		default: 'releases.txt',
+		type: 'string',
+		alias: 'f',
+	}
+
+	static target = {
+		help: 'Target project # or name for detailed inspection',
+		default: '',
+		positional: true,
+		type: 'string',
+	}
+
+	static sort = {
+		help: 'Sort projects by column (hours, rrs, iters, state, name)',
+		default: '',
+		type: 'string',
+		alias: 's',
 	}
 
 	/**
-	 * @returns {AsyncGenerator<import('@nan0web/ui').Intent, import('@nan0web/ui').ResultIntent, any>}
+	 * @param {Partial<StatusCommand>} [data]
+	 * @param {import('@nan0web/types').ModelOptions} [options]
+	 */
+	constructor(data = {}, options = {}) {
+		super(data, options)
+		/** @type {string} */ this.registryFile
+		/** @type {string} */ this.target
+		/** @type {string} */ this.sort
+	}
+
+	/**
+	 * @returns {AsyncGenerator<import('@nan0web/ui').Intent, any, any>}
 	 */
 	async *run() {
+		const db = this._.db
+		if (!db) {
+			throw new Error('Database instance is required in options ({ db })')
+		}
+
+		let hasRegistry = false
+		try {
+			const regDoc = await db.loadDocument(this.registryFile || 'releases.txt', null)
+			hasRegistry = regDoc !== null
+		} catch {}
+
+		if (hasRegistry || this.target || this.sort) {
+			let gitTelemetry = null
+			try {
+				gitTelemetry = await import('../utils/nodejs/GitTelemetry.js')
+			} catch {}
+			const dashboard = new DashboardModel(
+				{ registryFile: this.registryFile || 'releases.txt' },
+				{ db, gitTelemetry }
+			)
+			let { summary, projects } = await dashboard.aggregate()
+
+			// 1. Sorting if requested
+			if (this.sort) {
+				const s = String(this.sort).toLowerCase()
+				if (s === 'hours') {
+					projects = [...projects].sort((a, b) => (b.hours || 0) - (a.hours || 0))
+				} else if (s === 'rrs') {
+					projects = [...projects].sort((a, b) => (b.rrs || 0) - (a.rrs || 0))
+				} else if (s === 'iters' || s === 'iterations') {
+					projects = [...projects].sort((a, b) => (b.iterations || 0) - (a.iterations || 0))
+				} else if (s === 'name') {
+					projects = [...projects].sort((a, b) => (a.name || '').localeCompare(b.name || ''))
+				} else if (s === 'state' || s === 'status') {
+					const priority = { wip: 1, closed: 2, unknown: 3 }
+					projects = [...projects].sort((a, b) => (priority[a.status] || 99) - (priority[b.status] || 99))
+				}
+			}
+
+			// 2. Inspector mode if target is specified
+			if (this.target) {
+				const targetStr = String(this.target).trim()
+				let matchedIndex = -1
+				let matchedProj = null
+
+				const targetNum = parseInt(targetStr, 10)
+				if (!isNaN(targetNum) && targetNum >= 1 && targetNum <= projects.length) {
+					matchedIndex = targetNum - 1
+					matchedProj = projects[matchedIndex]
+				} else {
+					matchedIndex = projects.findIndex(
+						(p) =>
+							p.name.toLowerCase() === targetStr.toLowerCase() ||
+							p.path.toLowerCase() === targetStr.toLowerCase() ||
+							p.name.toLowerCase().includes(targetStr.toLowerCase()) ||
+							p.path.toLowerCase().includes(targetStr.toLowerCase()),
+					)
+					if (matchedIndex !== -1) {
+						matchedProj = projects[matchedIndex]
+					}
+				}
+
+				if (matchedProj) {
+					yield show(`🔍 Project Inspector: #${matchedIndex + 1} ${matchedProj.name}@${matchedProj.version}`, 'info')
+					yield show(
+						`  • Path: ${matchedProj.path} | Branch: ${matchedProj.branch || 'main'} (${matchedProj.gitStatus || 'clean'})`,
+						'info',
+					)
+					yield show(
+						`  • State: [${(matchedProj.status || 'unknown').toUpperCase()}] | Hours: ${matchedProj.hours}h | Iterations: ${matchedProj.iterations} | RRS: ${matchedProj.rrs}`,
+						'info',
+					)
+
+					yield show(`📋 Tasks & Checklist:`, 'info')
+					let renderedTasksCount = 0
+					if (matchedProj.releaseContent) {
+						const lines = matchedProj.releaseContent.split('\n')
+						for (const rawLine of lines) {
+							const l = rawLine.trim()
+							if (l.startsWith('- [x]') || l.startsWith('- [ ]') || l.startsWith('* [x]') || l.startsWith('* [ ]')) {
+								yield show(`  ${l}`, 'info')
+								renderedTasksCount++
+							} else if (
+								l.startsWith('### Done') ||
+								l.startsWith('### InProgress') ||
+								l.startsWith('### Todo') ||
+								l.startsWith('### Draft')
+							) {
+								const icon = l.startsWith('### Done') ? '[x]' : '[ ]'
+								const desc = l.replace(/^###\s+(?:Done|InProgress|Todo|Draft)\s+/, '')
+								yield show(`  - ${icon} ${desc}`, 'info')
+								renderedTasksCount++
+							}
+						}
+					}
+
+					if (renderedTasksCount === 0 && Array.isArray(matchedProj.tasks) && matchedProj.tasks.length > 0) {
+						for (const t of matchedProj.tasks) {
+							const icon = t.status === 'Done' ? '[x]' : '[ ]'
+							yield show(`  - ${icon} ${t.content || t.slug}`, 'info')
+						}
+					}
+
+					if (matchedProj.userContent) {
+						yield show(`📝 User Metrics & Feedback (user.md):`, 'info')
+						const userLines = matchedProj.userContent
+							.split('\n')
+							.map((l) => l.trim())
+							.filter(
+								(l) =>
+									l.length > 0 &&
+									!l.startsWith('---') &&
+									!l.startsWith('name:') &&
+									!l.startsWith('version:') &&
+									!l.startsWith('locale:'),
+							)
+						for (const ul of userLines) {
+							yield show(`  ${ul}`, 'info')
+						}
+					}
+				} else {
+					yield show(`❌ Project matching target "${this.target}" not found`, 'warn')
+				}
+
+				return result({
+					status: 'ok',
+					summary,
+					projects,
+				})
+			}
+
+			// 3. Normal Table mode
+			yield show(StatusCommand.UI.header.replace('{$file}', this.registryFile || 'releases.txt'), 'info')
+
+			if (projects.length === 0) {
+				yield show(StatusCommand.UI.noProjects.replace('{$file}', this.registryFile || 'releases.txt'), 'warn')
+			} else {
+				const colNum = '#'.padEnd(3)
+				const colProj = 'Project'.padEnd(25)
+				const colVer = 'Version'.padEnd(9)
+				const colBranch = 'Branch'.padEnd(12)
+				const colGit = 'Git'.padEnd(7)
+				const colState = 'State'.padEnd(10)
+				const colHours = 'Hours'.padEnd(7)
+				const colIters = 'Iters'.padEnd(7)
+				const colRRS = 'RRS'.padEnd(5)
+				const colTasks = 'Tasks'
+
+				const tableHeader = `┌─────┬───────────────────────────┬───────────┬──────────────┬─────────┬────────────┬─────────┬─────────┬───────┬───────┐`
+				const headerRow = `│ ${colNum} │ ${colProj} │ ${colVer} │ ${colBranch} │ ${colGit} │ ${colState} │ ${colHours} │ ${colIters} │ ${colRRS} │ ${colTasks.padEnd(5)} │`
+				const separator = `├─────┼───────────────────────────┼───────────┼──────────────┼─────────┼────────────┼─────────┼─────────┼───────┼───────┤`
+				const tableFooter = `└─────┴───────────────────────────┴───────────┴──────────────┴─────────┴────────────┴─────────┴─────────┴───────┴───────┘`
+
+				yield show(tableHeader, 'info')
+				yield show(headerRow, 'info')
+				yield show(separator, 'info')
+
+				for (let i = 0; i < projects.length; i++) {
+					const proj = projects[i]
+					const statusTag = proj.status === 'wip' ? '[WIP]' : proj.status === 'closed' ? '[CLOSED]' : '[UNKNOWN]'
+					const rowNum = String(i + 1).padEnd(3)
+					const rowName = (proj.name || '').padEnd(25).slice(0, 25)
+					const rowVer = (proj.version || '').padEnd(9).slice(0, 9)
+					const rowBranch = (proj.branch || 'main').padEnd(12).slice(0, 12)
+					const rowGit = (proj.gitStatus || 'clean').padEnd(7).slice(0, 7)
+					const rowState = statusTag.padEnd(10)
+					const rowHours = `${proj.hours}h`.padEnd(7)
+					const rowIters = String(proj.iterations).padEnd(7)
+					const rowRRS = String(proj.rrs).padEnd(5)
+					const doneTasks = Array.isArray(proj.tasks) ? proj.tasks.filter((t) => t.status === 'Done').length : 0
+					const totalTasks = Array.isArray(proj.tasks) ? proj.tasks.length : 0
+					const rowTasks = `${doneTasks}/${totalTasks}`.padEnd(5)
+
+					const rowStr = `│ ${rowNum} │ ${rowName} │ ${rowVer} │ ${rowBranch} │ ${rowGit} │ ${rowState} │ ${rowHours} │ ${rowIters} │ ${rowRRS} │ ${rowTasks} │`
+					yield show(rowStr, proj.status === 'wip' ? 'warn' : 'info')
+				}
+
+				yield show(tableFooter, 'info')
+
+				yield show(StatusCommand.UI.summaryHeader, 'info')
+				yield show(
+					StatusCommand.UI.summaryRow1
+						.replace('{$total}', String(summary.totalProjects))
+						.replace('{$wip}', String(summary.wipCount))
+						.replace('{$closed}', String(summary.closedCount)),
+					'info',
+				)
+				yield show(
+					StatusCommand.UI.summaryRow2
+						.replace('{$hours}', String(summary.totalHours))
+						.replace('{$iterations}', String(summary.totalIterations)),
+					'info',
+				)
+			}
+
+			return result({
+				status: 'ok',
+				summary,
+				projects,
+			})
+		}
+
+		// Local package fallback
 		const scanner = new Scanner(process.cwd())
 		const statuses = scanner.status()
 
@@ -20,6 +266,6 @@ export default class StatusCommand extends ModelAsApp {
 				`${st.version.padEnd(10)} | ${st.state.padEnd(6)} | Specs: ${st.specs.length}, Tests: ${st.tests.length}`,
 			)
 		}
-		return result({})
+		return result({ statuses })
 	}
 }