@nan0web/release 1.0.2 → 3.1.0

package/README.md

@@ -6,29 +6,36 @@ 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
 ```
@@ -38,14 +45,15 @@ yarn add @nan0web/release
 Start by initializing a new release:
 
 How to initialize a new release version?
+
 ```bash
-release init v1.0.0
+nan0release init v1.0.0
 ```
 
-const cli = ReleaseCLi()
 Show release details:
 
 How to show release information?
+
 ```bash
 release show [--full]
 ```
@@ -58,66 +66,66 @@ console.info(release.version) // v1.0.0
 List all releases in the project:
 
 How to list all releases?
+
 ```bash
-release list [--json]
+nan0release list [--json]
 ```
 
-const cli = ReleaseCLi()
 Add a chat message to the current release:
 
 How to write a release chat message?
+
 ```bash
-release chat write --user alice "Issue with the build pipeline"
+nan0release chat write --user alice "Issue with the build pipeline"
 ```
 
-const cli = ReleaseCLi()
 Host a static server for viewing releases:
 
 How to host release UI?
+
 ```bash
-release host [--webui] [--port 3000]
+nan0release host [--webui] [--port 3000]
 ```
 
-const cli = ReleaseCLi()
 Serve all release files for local inspection:
 
 How to serve release static assets?
+
 ```bash
-release serve [--port 8080]
+nan0release serve [--port 8080]
 ```
 
-const cli = ReleaseCLi()
 Validate release tasks and integrity:
 
 How to validate release tasks?
+
 ```bash
-release validate [--ignore-fail]
+nan0release validate [--ignore-fail]
 ```
 
-const release = new Release({
-version: 'v1.0.0',
-createdAt: new Date('2025-08-20'),
-})
 Seal the release with retro reflection:
 
 How to seal a release?
+
 ```bash
-release seal [--message "All core APIs are stable and tested"]
+nan0release seal [--message "All core APIs are stable and tested"]
 ```
 
-const cli = ReleaseCLi()
 ## Core Concepts
 
 ### 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({
@@ -130,11 +138,14 @@ 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
@@ -151,11 +162,14 @@ 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({
@@ -176,6 +190,7 @@ 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()
@@ -195,11 +210,14 @@ 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()
@@ -213,11 +231,14 @@ 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()
@@ -239,6 +260,7 @@ 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
@@ -251,6 +273,7 @@ pnpm run playground
 To verify the project is ready, run:
 
 How to check project status before publishing?
+
 ```bash
 npm test
 npm run test:coverage
@@ -264,3 +287,5 @@ How to contribute? - [check here](./CONTRIBUTING.md)
 ## License
 
 How to license ISC? - [check here](./LICENSE)
+
+

package/bin/nan0release.js

@@ -1,42 +1,6 @@
 #!/usr/bin/env node
 
-import process from 'node:process'
+import { bootstrapApp } from '@nan0web/ui-cli'
+import { App } from '../src/domain/App.js'
 
-import { OutputMessage } from '@nan0web/co'
-import Logger from '@nan0web/log'
-
-import createReleaseCLI from '../src/ui/cli/ReleaseCLi.js'
-
-class OutputLogger extends Logger {
-	log(first, ...args) {
-		if (first && first instanceof OutputMessage) {
-			if (OutputMessage.TYPES.ERROR === first.type) {
-				return this.error(first.content, ...args)
-			} else if (OutputMessage.TYPES.WARNING === first.type) {
-				return this.warn(first.content, ...args)
-			} else if (OutputMessage.TYPES.SUCCESS === first.type) {
-				return this.success(first.content, ...args)
-			}
-			return this.info(first.content, ...args)
-		}
-		return super.log(first, ...args)
-	}
-}
-
-const logger = new OutputLogger(Logger.detectLevel(process.argv))
-
-async function main(argv = []) {
-	const cli = createReleaseCLI(argv, logger)
-	logger.info(Logger.style(Logger.LOGO, { color: Logger.MAGENTA }))
-
-	const stream = cli.run()
-	for await (const entry of stream) {
-		logger.info(entry)
-	}
-}
-
-main(process.argv.slice(2)).catch((err) => {
-	logger.error('❌ Unhandled error:', err.message || err)
-	if (err.stack) logger.debug(err.stack)
-	process.exit(1)
-})
+bootstrapApp(App)

package/knip.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://unpkg.com/knip@5/schema.json",
+  "entry": [
+    "src/index.js",
+    "bin/nan0release.js",
+    "src/README.md.js"
+  ],
+  "project": ["src/**/*.js", "bin/*.js"],
+  "ignoreDependencies": [
+    "@nan0web/log",
+    "@nan0web/ui",
+    "@nan0web/ui-cli",
+    "@nan0web/logos",
+    "@nan0web/markdown",
+    "@nan0web/db",
+    "@nan0web/db-fs",
+    "@nan0web/types",
+    "@nan0web/co",
+    "@nan0web/changelog"
+  ]
+}

package/nan0web.nan0

@@ -0,0 +1,16 @@
+name: "@nan0web/release"
+agents:
+  - id: 'release-manager'
+    description: 'Release & NPM Publication Manager'
+    workflows:
+      - 'src/agents/workflows/release.md'
+      - 'src/agents/workflows/npm-release.md'
+    inspectors:
+      - 'src/agents/inspectors/package-hygiene.md'
+  - id: 'git-reviewer'
+    description: 'Architectural Git Commit Validator'
+    workflows:
+      - 'src/agents/workflows/commit.md'
+      - 'src/agents/workflows/zero-tolerance-git.md'
+    inspectors:
+      - 'src/agents/inspectors/git-reviewer.md'

package/package.json

@@ -1,50 +1,49 @@
 {
-	"name": "@nan0web/release",
-	"version": "1.0.2",
-	"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"
-	},
-	"scripts": {
-		"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: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:collect": "nan0test coverage",
-		"test:status": "nan0test status",
-		"test:all": "npm run test && npm run test:docs && npm run build && npm run knip",
-		"test:all1": "npm run test && npm run test:docs && npm run test:status && npm run build",
-		"knip": "knip --production",
-		"release": "node ./bin/nan0release.js publish",
-		"precommit": "npm test",
-		"prepush": "npm test",
-		"prepare": "husky",
-		"playground": "node playground/main.js"
-	},
-	"dependencies": {
-		"@nan0web/changelog": "*",
-		"@nan0web/co": "*",
-		"@nan0web/db": "*",
-		"@nan0web/db-fs": "*",
-		"@nan0web/log": "*",
-		"@nan0web/markdown": "*",
-		"@nan0web/types": "*",
-		"@nan0web/ui": "*",
-		"@nan0web/ui-cli": "*",
-		"@nan0web/verse": "*",
-		"supports-color": "^10.2.2"
-	},
-	"devDependencies": {
-		"@nan0web/test": "*",
-		"husky": "^9.1.7",
-		"knip": "^5.85.0"
-	}
-}
+  "name": "@nan0web/release",
+  "version": "3.1.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"
+  },
+  "dependencies": {
+    "@nan0web/log": "3.1.0",
+    "@nan0web/co": "3.1.0",
+    "@nan0web/markdown": "3.1.0",
+    "@nan0web/db-fs": "3.1.0",
+    "@nan0web/types": "3.1.0",
+    "@nan0web/changelog": "3.1.0",
+    "@nan0web/db": "3.1.0",
+    "@nan0web/ui": "3.1.0",
+    "@nan0web/logos": "3.1.0",
+    "@nan0web/ui-cli": "3.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "husky": "^9.1.7",
+    "knip": "^5.86.0",
+    "@nan0web/test": "3.1.0"
+  },
+  "scripts": {
+    "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: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:collect": "nan0test coverage",
+    "test:status": "nan0test status",
+    "test:all": "npm run test && npm run test:docs && npm run build && npm run knip",
+    "test:all1": "npm run test && npm run test:docs && npm run test:status && npm run build",
+    "knip": "knip --production",
+    "release": "node ./bin/nan0release.js publish",
+    "precommit": "npm test",
+    "prepush": "npm test",
+    "playground": "node playground/main.js"
+  }
+}

package/project.yaml

@@ -0,0 +1,79 @@
+---
+metadata:
+  description: ""
+  tags: []
+  status: planned
+  locale: uk
+sections:
+  - title: "🧭 Фаза 1: Філософія та Абстракція (The Seed)"
+    content:
+      - "**Місія:** Управління проєктами як код (Project Management as Code). Ми відмовляємось від зовнішніх трекерів задач (Jira, Trello). Проєкт — це набір технічних **контрактів**, які проходять шлях від наміру до імплементації, забезпечуючи реальний статус прогресу автоматично."
+      - "**Базова Абстракція:** Пакет відповідає за логіку та CLI, яка читає Markdown, генерує контракти (`.spec.js`), а потім закриває їх як тести (`.test.js`) з подальшою вічною регресією (тести копіюються в кодову базу)."
+      - "**Глосарій:**"
+      - "- **Release Document**: `release.md` з ТЗ та відомостями про команду."
+      - "- **WIP Контракт**: `*.spec.js`, який падає/у стані `todo`, доки задачу не взяли і не зробили. Оновлює прогрес автоматично при виконанні."
+      - "- **Закритий Контракт**: `*.test.js` (результат команди `close`). Він стає законом і гарантує регресію через `pnpm test`."
+      - "---"
+    tasks: []
+  - title: "📐 Фаза 2: Доменне Моделювання (Data-Driven Models)"
+    content:
+      - "Сутності і моделі, які керують процесом релізу, не мають жорсткої прив'язки до вебу, але описуються як чисті об'єкти:"
+      - "- `Release`: Координує стан (версія, час початку, час завершення)."
+      - "- `ReleaseDocument`: Структурує Markdown у модель (дістає задачі)."
+      - "- `Person`: Типізована перевірка того, хто схвалив дії (через GPG або JSON підпис)."
+      - "- `Scanner`: Абстракція доступу до файлової системи (`releases/`)."
+      - "Статуси відстежуються динамічно через статус тестів: `it.todo` -> `it.skip` -> `it()`."
+      - "---"
+    tasks: []
+  - title: "🛠 Фаза 3: Верифікація Логіки (CLI-First)"
+    content:
+      - "Уся бізнес-логіка @nan0web/release 100% покривається Unit-тестами та CLI командами. Жодного веб-коду. Використовуємо Message-based архітектуру `@nan0web/ui-cli`."
+      - "1. **Команди CLI (`bin/nan0release.js`):**"
+      - "- `deps`, `publish` (реалізовані)."
+      - "- Заплановані (`init`, `spec`, `close`, `status`) інкапсулюють керування `Scanner` та `Release` моделями."
+      - "2. **Contract Lifecycle (Автоматизація прогресу):**"
+      - "- На старті `.spec.js` мають `it.todo()` → задача в беклозі."
+      - "- Коли розробник бере задачу → генерує логіку, змінює на `it()`. При коміті реальний прогрес проекту видно \"зеленим\"."
+      - "- `nan0release close` перейменовує `spec → test` і переносить його в `src/releases/` для 100% автоматичної регресії."
+      - "---"
+    tasks: []
+  - title: "🪐 Фаза 4: Sovereign Workbench (The Master IDE)"
+    content:
+      - "_(Для цього пакету застосовується опціонально, оскільки тут CLI-First)_"
+      - "Пакет `release` є постачальником даних для інших Sandbox-середовищ, де може виводитись:"
+      - "- Dashboard релізу (таблиці статусів `wip/closed/mixed`)."
+      - "- Для цього ми генеруємо `.datasets/README.dataset.jsonl` за допомогою `test:docs`, щоб створювати машиночитабельні знання для LLM-агентів для донавчання або можна користуватись README.md як індексу у реальному часі."
+      - "---"
+    tasks: []
+  - title: "🎨 Фаза 5: Тематизація та Інтерфейс (Theming)"
+    content:
+      - "_(Може застосовуватися при запуску HTML звітів про реліз або Dashboard)_"
+      - "Логіка `release UI` (якщо така з'явиться у додатку `@nan0web/release.app`), буде імпортувати компоненти з `@nan0web/ui-lit` зі строгим слідуванням CSS-змінним (напр. `--co` для кольорів бренду) без створення кастомних стилів."
+      - "---"
+    tasks: []
+  - title: "🏁 Чек-лист готовності пакету (Definition of Done)"
+    content: []
+    tasks:
+      - title: "General"
+        content: []
+        items:
+          - text: "Визначена місія та філософія у `system.md` та `project.md`."
+            completed: true
+          - text: "Робота з Markdown-нотатками та базова доменна логіка (`Scanner`, `Release`)."
+            completed: true
+          - text: "Атомарна операція закриття контрактів (`Scanner.close()`)."
+            completed: true
+          - text: "Всі існуючі специфікації проходять через CLI та `node:test` (22/24 pass, 2 skip)."
+            completed: true
+          - text: "Прогрес автоматизується зміною статусу `spec.js` (todo/skip/pass)."
+            completed: true
+          - text: "Усі CLI сценарії для AGRP (spec, close, init, status) завершені."
+            completed: false
+          - text: "Створені API-ендпоінти для відображення релізного прогресу у React-Dashboard."
+            completed: false
+        total: 7
+        completed: 5
+stats:
+  totalTasks: 7
+  completedTasks: 5
+  progress: 71