@nan0web/release 3.3.0 → 3.5.0

package/README.md

@@ -6,36 +6,29 @@ Project management as code, Git-native, GPG-signed, and test-driven.
 
 Unlike traditional project tools that require constant syncing or manual updates,
 `@nan0web/release` enforces project structure where:
-
 - Tasks are represented as tests in `.test.js` files.
 - Status is tracked via test outcomes.
 - Team roles and approvals are stored in structured files.
 - All changes are signed, versioned, and composable.
 
-
 This ensures:
-
 - Clear, automatable project tracking.
 - Immutable release notes and retro reflections.
 - Zero ambiguity – tasks don't exist unless tested.
 
-
 ## Installation
 
 How to install with pnpm?
-
 ```bash
 pnpm add @nan0web/release
 ```
 
 How to install with npm?
-
 ```bash
 npm install @nan0web/release
 ```
 
 How to install with yarn?
-
 ```bash
 yarn add @nan0web/release
 ```
@@ -45,7 +38,6 @@ yarn add @nan0web/release
 Start by initializing a new release:
 
 How to initialize a new release version?
-
 ```bash
 nan0release init v1.0.0
 ```
@@ -53,7 +45,6 @@ nan0release init v1.0.0
 Show release details:
 
 How to show release information?
-
 ```bash
 release show [--full]
 ```
@@ -66,7 +57,6 @@ console.info(release.version) // v1.0.0
 List all releases in the project:
 
 How to list all releases?
-
 ```bash
 nan0release list [--json]
 ```
@@ -74,7 +64,6 @@ nan0release list [--json]
 Add a chat message to the current release:
 
 How to write a release chat message?
-
 ```bash
 nan0release chat write --user alice "Issue with the build pipeline"
 ```
@@ -82,7 +71,6 @@ nan0release chat write --user alice "Issue with the build pipeline"
 Host a static server for viewing releases:
 
 How to host release UI?
-
 ```bash
 nan0release host [--webui] [--port 3000]
 ```
@@ -90,7 +78,6 @@ nan0release host [--webui] [--port 3000]
 Serve all release files for local inspection:
 
 How to serve release static assets?
-
 ```bash
 nan0release serve [--port 8080]
 ```
@@ -98,7 +85,6 @@ nan0release serve [--port 8080]
 Validate release tasks and integrity:
 
 How to validate release tasks?
-
 ```bash
 nan0release validate [--ignore-fail]
 ```
@@ -106,7 +92,6 @@ nan0release validate [--ignore-fail]
 Seal the release with retro reflection:
 
 How to seal a release?
-
 ```bash
 nan0release seal [--message "All core APIs are stable and tested"]
 ```
@@ -116,16 +101,13 @@ nan0release seal [--message "All core APIs are stable and tested"]
 ### 1. Release as Object
 
 A `Release` is a structured class containing:
-
 - `version`: release identifier (vX.Y.Z).
 - `createdAt`, `startAt`, `planAt`, `completeAt`: datetime milestones.
 - `document`: parsed markdown document with structure-aware parsing.
 
-
 Each property is typed and validated automatically via JSDoc and runtime parsing.
 
 How to instantiate a Release?
-
 ```js
 import { Release } from '@nan0web/release'
 const release = new Release({
@@ -138,14 +120,11 @@ console.info(release.createdAt instanceof Date) // ← true
 ### 2. Release Document Parsing
 
 A `ReleaseDocument` extends `@nan0web/markdown` with:
-
 - Structured parsing of markdown release notes
 - Extraction of sections and tasks
 - Team and role parsing from markdown frontmatter or code
 
-
 How to parse release notes markdown into structured data?
-
 ```js
 import { ReleaseDocument } from '@nan0web/release'
 const md = `# v1.0.0 - 2025-08-20
@@ -162,14 +141,11 @@ console.info(doc.document.children instanceof Array) // ← true
 ### 3. Person & Team Structures
 
 A `Person` instance includes:
-
 - `name`: HumanName
 - `gender`: HumanGender
 - `contacts`: array of HumanContact
 
-
 How to create a Person with typed properties?
-
 ```js
 import { Person } from '@nan0web/release'
 const person = new Person({
@@ -190,7 +166,6 @@ Tasks are registered as `taskId` → `testFilePath` in `ProjectManagement`.
 Their status is derived by running `node:test` suites.
 
 How to register and validate tasks as tests?
-
 ```js
 import { ProjectManagement } from '@nan0web/release'
 const pm = new ProjectManagement()
@@ -210,14 +185,11 @@ console.info(results.pending.includes('task-2')) // ← true
 
 The `ReleaseManager` coordinates releases and validates readiness.
 It ensures:
-
 - All registered tests pass
 - Version is correctly incremented
 - Git tag is applied if all validations succeed
 
-
 How to execute a release after validation?
-
 ```js
 import { ReleaseManager, ProjectManagement } from '@nan0web/release'
 const pm = new ProjectManagement()
@@ -231,14 +203,11 @@ console.info(result.published) // ← true
 ### Changelog Integration
 
 Using `ChangelogTaskManager`, you can:
-
 - Extract task definitions from changelog entries
 - Generate corresponding test files
 - Automate task progression in CI
 
-
 How to parse changelog and extract tasks?
-
 ```js
 import { ChangelogTaskManager } from '@nan0web/release'
 const ctm = new ChangelogTaskManager()
@@ -260,7 +229,6 @@ Uses JSDoc and .d.ts files for autocompletion
 Try the package in the terminal:
 
 How to run playground demo?
-
 ```bash
 git clone https://github.com/nan0web/release.git
 cd release
@@ -273,7 +241,6 @@ pnpm run playground
 To verify the project is ready, run:
 
 How to check project status before publishing?
-
 ```bash
 npm test
 npm run test:coverage
@@ -287,5 +254,3 @@ How to contribute? - [check here](./CONTRIBUTING.md)
 ## License
 
 How to license ISC? - [check here](./LICENSE)
-
-

package/bin/nan0release.js

@@ -1,6 +1,37 @@
 #!/usr/bin/env node
-
+import { existsSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
 import { bootstrapApp } from '@nan0web/ui-cli'
+import DBFS from '@nan0web/db-fs'
 import { ReleaseApp } from '../src/domain/App.js'
 
-bootstrapApp(ReleaseApp)
+function findMonorepoRoot(startDir) {
+	let dir = resolve(startDir)
+	const markers = ['pnpm-workspace.yaml', 'releases.txt']
+	for (let i = 0; i < 10; i++) {
+		for (const marker of markers) {
+			if (existsSync(resolve(dir, marker))) {
+				return dir
+			}
+		}
+		const parent = dirname(dir)
+		if (parent === dir) break
+		dir = parent
+	}
+	return startDir
+}
+
+const startCwd = process.env.INIT_CWD || process.cwd()
+process.env.RELEASE_CWD = startCwd
+const root = findMonorepoRoot(startCwd)
+if (process.cwd() !== root && existsSync(resolve(root, 'releases.txt'))) {
+	process.chdir(root)
+}
+
+const db = new DBFS({ root: '.' })
+await db.connect()
+
+bootstrapApp(ReleaseApp, { db, root: '.' }).catch((err) => {
+	console.error(err)
+	process.exit(1)
+})

package/bin/serve.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { bootstrapApp } from '@nan0web/ui-cli'
+import DBFS from '@nan0web/db-fs'
+import { ServeCommand } from '../src/domain/ServeCommand.js'
+
+function findMonorepoRoot(startDir) {
+	let dir = resolve(startDir)
+	const markers = ['pnpm-workspace.yaml', 'releases.txt']
+	for (let i = 0; i < 10; i++) {
+		for (const marker of markers) {
+			if (existsSync(resolve(dir, marker))) {
+				return dir
+			}
+		}
+		const parent = dirname(dir)
+		if (parent === dir) break
+		dir = parent
+	}
+	return startDir
+}
+
+const startCwd = process.env.INIT_CWD || process.cwd()
+process.env.RELEASE_CWD = startCwd
+const root = findMonorepoRoot(startCwd)
+if (process.cwd() !== root && existsSync(resolve(root, 'releases.txt'))) {
+	process.chdir(root)
+}
+
+const db = new DBFS()
+await db.connect()
+
+const res = await bootstrapApp(ServeCommand, { db, noExit: true }).catch((err) => {
+	console.error(err)
+	process.exit(1)
+})
+
+const resultIntent = res?.data || {}
+const data = resultIntent?.data || resultIntent || {}
+if (data.success && data.html) {
+	try {
+		const { createServer } = await import('node:http')
+		const port = data.port || 3131
+		const server = createServer((req, resHttp) => {
+			resHttp.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+			resHttp.end(data.html)
+		})
+
+		server.listen(port, () => {
+			if (data.open) {
+				import('node:child_process')
+					.then(({ exec }) => exec(`open http://localhost:${port}`))
+					.catch(() => {})
+			}
+		})
+
+		const stopServer = () => {
+			server.close(() => {
+				process.exit(0)
+			})
+		}
+
+		process.on('SIGINT', stopServer)
+		process.on('SIGTERM', stopServer)
+	} catch (err) {
+		console.error(`Failed to start HTTP server: ${err.message}`)
+		process.exit(1)
+	}
+} else if (data.success === false) {
+	process.exit(1)
+}
+

package/package.json

@@ -1,31 +1,59 @@
 {
   "name": "@nan0web/release",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "description": "Project Management as Code, Git-Native, GPG-Signed, Test-Driven",
   "main": "src/index.js",
   "types": "types/index.d.ts",
   "type": "module",
   "bin": {
     "nan0release": "./bin/nan0release.js",
-    "release": "./bin/nan0release.js"
+    "release": "./bin/nan0release.js",
+    "serve": "./bin/serve.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./types/index.d.ts"
+    },
+    "./domain/inspect/ReleaseAuditor": {
+      "import": "./src/domain/inspect/ReleaseAuditor.js",
+      "types": "./types/domain/inspect/ReleaseAuditor.d.ts"
+    },
+    "./domain/CheckCommand": {
+      "import": "./src/domain/CheckCommand.js",
+      "types": "./types/domain/CheckCommand.d.ts"
+    },
+    "./domain/StatusCommand": {
+      "import": "./src/domain/StatusCommand.js",
+      "types": "./types/domain/StatusCommand.d.ts"
+    },
+    "./domain/App": {
+      "import": "./src/domain/App.js",
+      "types": "./types/domain/App.d.ts"
+    },
+    "./domain/*": {
+      "import": "./src/domain/*.js"
+    }
   },
   "dependencies": {
-    "@nan0web/db-fs": "3.3.0",
-    "@nan0web/db": "3.3.0",
-    "@nan0web/types": "3.3.0",
-    "@nan0web/markdown": "3.3.0",
-    "@nan0web/log": "3.3.0",
-    "@nan0web/co": "3.3.0",
-    "@nan0web/changelog": "3.3.0",
-    "@nan0web/logos": "3.3.0",
-    "@nan0web/ui": "3.3.0",
-    "@nan0web/ui-cli": "3.3.0"
+    "@nan0web/changelog": "3.4.0",
+    "@nan0web/csv0": "3.6.0",
+    "@nan0web/co": "3.5.0",
+    "@nan0web/db-fs": "3.6.0",
+    "@nan0web/db": "3.5.0",
+    "@nan0web/inspect": "3.7.0",
+    "@nan0web/log": "3.4.0",
+    "@nan0web/logos": "3.4.0",
+    "@nan0web/markdown": "3.4.0",
+    "@nan0web/ui": "3.5.0",
+    "@nan0web/types": "3.4.0",
+    "@nan0web/ui-cli": "3.5.0"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
     "husky": "^9.1.7",
-    "knip": "^5.86.0",
-    "@nan0web/test": "3.3.0"
+    "knip": "^5.88.1",
+    "@nan0web/test": "3.4.0"
   },
   "files": [
     "bin",
@@ -39,11 +67,12 @@
     "build": "tsc",
     "clean": "rm -rf .cache/ && rm -rf dist/",
     "clean:modules": "rm -rf node_modules",
-    "test": "node --test \"src/**/*.test.js\"",
-    "test1": "node --test \"src/**/*.test.js\" | nan0test parse --fail",
+    "test": "node --test \"src/**/*.{test,story}.js\"",
+    "test:stories": "node --test \"src/**/*.story.js\"",
+    "test1": "node --test \"src/**/*.{test,story}.js\" | nan0test parse --fail",
     "test:docs": "node --test \"src/README.md.js\"",
     "test:release": "node --test \"releases/**/*.test.js\"",
-    "test:coverage": "node --experimental-test-coverage --test-coverage-include=\"src/**/*.js\" --test-coverage-exclude=\"src/**/*.test.js\" --test \"src/**/*.test.js\"",
+    "test:coverage": "node --experimental-test-coverage --test-coverage-include=\"src/**/*.js\" --test-coverage-exclude=\"src/**/*.{test,story}.js\" --test \"src/**/*.{test,story}.js\"",
     "test:coverage:collect": "nan0test coverage",
     "test:status": "nan0test status",
     "test:all": "npm run test && npm run test:docs && npm run build && npm run knip",

package/src/Release/Document.js

@@ -83,6 +83,7 @@ class ReleaseDocument extends Markdown {
 			}
 		}
 
+		this.sections = sections
 		return result
 	}
 

package/src/Release/Scanner.js

@@ -27,10 +27,11 @@ export default class Scanner {
 	root
 
 	/**
-	 * @param {string} root - Root directory of the project
+	 * @param {string} [root] - Root directory of the project
 	 */
 	constructor(root) {
-		this.root = resolve(root)
+		const targetRoot = root || process.env.INIT_CWD || process.cwd()
+		this.root = resolve(targetRoot)
 	}
 
 	/**

package/src/Release.js

@@ -18,21 +18,21 @@ import Logger from '@nan0web/log'
  */
 export default class Release {
 	/** @type {string} */
-	version
+	version = '0.0.0'
 	/** @type {Date} */
-	createdAt
+	createdAt = new Date()
 	/** @type {Date?} */
-	startAt
+	startAt = null
 	/** @type {Date?} */
-	planAt
+	planAt = null
 	/** @type {Date?} */
-	completeAt
+	completeAt = null
 	/** @type {Map<string, Function>} */
-	tasks
+	tasks = new Map()
 	/** @type {ReleaseDocument} */
 	document
 	/** @type {Logger} */
-	logger
+	logger = new Logger()
 
 	/**
 	 * Creates a Release instance

package/src/domain/App.js

@@ -7,22 +7,40 @@ import PublishCommand from './PublishCommand.js'
 import SpecCommand from './SpecCommand.js'
 import StatusCommand from './StatusCommand.js'
 import BumpCommand from './BumpCommand.js'
+import WebCommand from './WebCommand.js'
+import PreviewCommand from './PreviewCommand.js'
+import ViewCommand from './ViewCommand.js'
+import ListCommand from './ListCommand.js'
+import ServeCommand from './ServeCommand.js'
+import ValidateCommand from './ValidateCommand.js'
 
 export class ReleaseApp extends ModelAsApp {
+	static alias = 'release'
+
+	static UI = {
+		title: 'PM-as-Code Release Protocol (nan0release)',
+	}
+
 	static command = {
 		help: 'Subcommand to run',
 		options: [
 			InitCommand,
 			CheckCommand,
+			ValidateCommand,
 			CloseCommand,
 			DepsCommand,
 			PublishCommand,
 			SpecCommand,
 			StatusCommand,
 			BumpCommand,
+			WebCommand,
+			PreviewCommand,
+			ViewCommand,
+			ListCommand,
+			ServeCommand,
 		],
 		positional: true,
-		default: null,
+		default: ViewCommand,
 	}
 
 	/**
@@ -31,6 +49,19 @@ export class ReleaseApp extends ModelAsApp {
 	 */
 	constructor(data = {}, options = {}) {
 		super(data, options)
-		/** @type {ModelAsApp} Subcommand to run */ this.command
+	}
+
+	/**
+	 * Run the main controller logic.
+	 * @returns {AsyncGenerator<import('@nan0web/ui').Intent, any, any>}
+	 */
+	async *run() {
+		if (this.help || !this.command || typeof this.command.run !== 'function') {
+			return yield* super.run()
+		}
+		return yield* this.command.run()
 	}
 }
+
+export default ReleaseApp
+

package/src/domain/BumpCommand.js

@@ -3,8 +3,18 @@ import { runSpawn } from '@nan0web/test'
 
 /**
  * Command to bump the version of changed packages in the monorepo.
+ * @property {string} version Target version to set
+ * @property {string} since Git reference to diff against
+ * @property {boolean} dryRun Run the command without making any changes
  */
 export default class BumpCommand extends ModelAsApp {
+	/** @type {string} Target version */
+	version = '3.1.1'
+	/** @type {string} Git reference to diff against */
+	since = 'v3.1.0'
+	/** @type {boolean} Run without making changes */
+	dryRun = false
+
 	static version = {
 		help: 'Target version to set',
 		default: '3.1.1',
@@ -38,9 +48,6 @@ export default class BumpCommand extends ModelAsApp {
 	 */
 	constructor(data = {}, options = {}) {
 		super(data, options)
-		/** @type {string} Target version */ this.version
-		/** @type {string} Since reference */ this.since
-		/** @type {boolean} Dry run */ this.dryRun
 	}
 
 	/**