@nan0web/release 1.0.2 → 1.0.3

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": "1.0.3",
+  "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/changelog": "^1.0.0",
+    "@nan0web/co": "^2.0.0",
+    "@nan0web/db": "^1.3.3",
+    "@nan0web/db-fs": "^1.1.4",
+    "@nan0web/log": "^1.1.1",
+    "@nan0web/markdown": "^1.0.2",
+    "@nan0web/types": "^1.4.0",
+    "@nan0web/ui": "^1.8.0",
+    "@nan0web/ui-cli": "^2.9.0",
+    "@nan0web/verse": "^1.0.0",
+    "supports-color": "^10.2.2"
+  },
+  "devDependencies": {
+    "@nan0web/test": "^1.1.3",
+    "husky": "^9.1.7",
+    "knip": "^5.86.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

package/src/README.md.js

@@ -0,0 +1,465 @@
+import { describe, it, before, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFile } from 'node:fs/promises'
+import FS from '@nan0web/db-fs'
+import { NoConsole } from '@nan0web/log'
+import { DatasetParser, DocsParser, runSpawn } from '@nan0web/test'
+import ReleaseCLi from './ui/cli/ReleaseCLi.js'
+import Release from './Release.js'
+import ReleaseDocument from './Release/Document.js'
+import Person from './Release/Person.js'
+import {
+	ProjectManagement,
+	ReleaseManager,
+	TaskTestSuite,
+	ChangelogTaskManager,
+} from './architecture/ProjectManagementAsCode.js'
+
+const fs = new FS()
+let pkg
+
+// Load package.json once before tests
+before(async () => {
+	const doc = await fs.loadDocument('package.json', {})
+	pkg = doc || {}
+})
+
+let console = new NoConsole()
+
+beforeEach(() => {
+	console = new NoConsole()
+})
+
+/**
+ * Core test suite that also serves as the source for README generation.
+ *
+ * The block comments inside each `it` block are extracted to build
+ * the final `README.md`. Keeping the comments here ensures the
+ * documentation stays close to the code.
+ */
+function testRender() {
+	/**
+	 * @docs
+	 * # @nan0web/release
+	 *
+	 * <!-- %PACKAGE_STATUS% -->
+	 *
+	 * 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
+	 */
+	it('How to install with pnpm?', () => {
+		/**
+		 * ```bash
+		 * pnpm add @nan0web/release
+		 * ```
+		 */
+		assert.equal(pkg.name, '@nan0web/release')
+	})
+	/**
+	 * @docs
+	 */
+	it('How to install with npm?', () => {
+		/**
+		 * ```bash
+		 * npm install @nan0web/release
+		 * ```
+		 */
+		assert.equal(pkg.name, '@nan0web/release')
+	})
+	/**
+	 * @docs
+	 */
+	it('How to install with yarn?', () => {
+		/**
+		 * ```bash
+		 * yarn add @nan0web/release
+		 * ```
+		 */
+		assert.equal(pkg.name, '@nan0web/release')
+	})
+
+	/**
+	 * @docs
+	 * ## CLI Usage
+	 *
+	 * Start by initializing a new release:
+	 */
+	it('How to initialize a new release version?', () => {
+		/**
+		 * ```bash
+		 * release init v1.0.0
+		 * ```
+		 */
+		const cli = ReleaseCLi()
+		assert.ok(cli.logger)
+	})
+
+	/**
+	 * @docs
+	 * Show release details:
+	 */
+	it('How to show release information?', () => {
+		/**
+		 * ```bash
+		 * release show [--full]
+		 * ```
+		 */
+		const release = new Release({
+			version: 'v1.0.0',
+			createdAt: new Date('2025-08-20'),
+		})
+		console.info(release.version) // v1.0.0
+		assert.strictEqual(console.output()[0][1], 'v1.0.0')
+	})
+
+	/**
+	 * @docs
+	 * List all releases in the project:
+	 */
+	it('How to list all releases?', () => {
+		/**
+		 * ```bash
+		 * release list [--json]
+		 * ```
+		 */
+		const cli = ReleaseCLi()
+		assert.ok(cli.logger)
+	})
+
+	/**
+	 * @docs
+	 * Add a chat message to the current release:
+	 */
+	it('How to write a release chat message?', () => {
+		/**
+		 * ```bash
+		 * release chat write --user alice "Issue with the build pipeline"
+		 * ```
+		 */
+		const cli = ReleaseCLi()
+		assert.ok(cli.logger)
+	})
+
+	/**
+	 * @docs
+	 * Host a static server for viewing releases:
+	 */
+	it('How to host release UI?', () => {
+		/**
+		 * ```bash
+		 * release host [--webui] [--port 3000]
+		 * ```
+		 */
+		const cli = ReleaseCLi()
+		assert.ok(cli.logger)
+	})
+
+	/**
+	 * @docs
+	 * Serve all release files for local inspection:
+	 */
+	it('How to serve release static assets?', () => {
+		/**
+		 * ```bash
+		 * release serve [--port 8080]
+		 * ```
+		 */
+		const cli = ReleaseCLi()
+		assert.ok(cli.logger)
+	})
+
+	/**
+	 * @docs
+	 * Validate release tasks and integrity:
+	 */
+	it('How to validate release tasks?', () => {
+		/**
+		 * ```bash
+		 * release validate [--ignore-fail]
+		 * ```
+		 */
+		const release = new Release({
+			version: 'v1.0.0',
+			createdAt: new Date('2025-08-20'),
+		})
+		assert.ok(release instanceof Release)
+	})
+
+	/**
+	 * @docs
+	 * Seal the release with retro reflection:
+	 */
+	it('How to seal a release?', () => {
+		/**
+		 * ```bash
+		 * release seal [--message "All core APIs are stable and tested"]
+		 * ```
+		 */
+		const cli = ReleaseCLi()
+		assert.ok(cli.logger)
+	})
+
+	/**
+	 * @docs
+	 * ## 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.
+	 */
+	it('How to instantiate a Release?', () => {
+		//import { Release } from '@nan0web/release'
+		const release = new Release({
+			version: 'v1.0.0',
+			createdAt: '2025-08-20T10:00:00Z',
+		})
+		console.info(release.version) // ← v1.0.0
+		console.info(release.createdAt instanceof Date) // ← true
+
+		assert.strictEqual(console.output()[0][1], 'v1.0.0')
+		assert.strictEqual(console.output()[1][1], true)
+	})
+
+	/**
+	 * @docs
+	 * ### 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
+	 */
+	it('How to parse release notes markdown into structured data?', () => {
+		//import { ReleaseDocument } from '@nan0web/release'
+		const md = `# v1.0.0 - 2025-08-20
+
+## Overview
+Release milestone includes UI polish and core API stabilization.
+
+### Tasks
+### Done **Implement core UI design** [ui.core-design]
+### InProgress **Fix responsive issues in mobile layout** [ui.mobile-fixes]`
+
+		const doc = ReleaseDocument.from(md)
+		console.info(doc.version) // ← v1.0.0
+		console.info(doc.date instanceof Date) // ← true
+		console.info(doc.document.children instanceof Array) // ← true
+
+		assert.strictEqual(console.output()[0][1], 'v1.0.0')
+		assert.strictEqual(console.output()[1][1], true)
+		assert.strictEqual(console.output()[2][1], true)
+	})
+
+	/**
+	 * @docs
+	 * ### 3. Person & Team Structures
+	 *
+	 * A `Person` instance includes:
+	 * - `name`: HumanName
+	 * - `gender`: HumanGender
+	 * - `contacts`: array of HumanContact
+	 */
+	it('How to create a Person with typed properties?', () => {
+		//import { Person } from '@nan0web/release'
+		const person = new Person({
+			name: ['Alice', 'Developer'],
+			gender: 'female',
+			contacts: ['mailto:alice@example.com'],
+		})
+		console.info(person.name.firstName) // ← Alice
+		console.info(person.contacts.length >= 0) // ← true
+
+		assert.strictEqual(console.output()[0][1], 'Alice')
+		assert.strictEqual(console.output()[1][1], true)
+	})
+
+	/**
+	 * @docs
+	 * ## Architecture: Project Management as Code
+	 *
+	 * This architecture treats tasks as tests, roles as classes, and progress as validated outcomes.
+	 *
+	 * ### Task Management
+	 *
+	 * Tasks are registered as `taskId` → `testFilePath` in `ProjectManagement`.
+	 * Their status is derived by running `node:test` suites.
+	 */
+	it('How to register and validate tasks as tests?', async () => {
+		//import { ProjectManagement } from '@nan0web/release'
+		const pm = new ProjectManagement()
+		pm.registerTask('task-1', './tests/task1.test.js')
+		pm.registerTask('task-2', './tests/task2.test.js')
+
+		const mockResults = {
+			passed: ['task-1'],
+			failed: [],
+			pending: ['task-2'],
+		}
+
+		pm.validateProjectState = async () => mockResults
+		const results = await pm.validateProjectState()
+
+		console.info(results.passed.includes('task-1')) // ← true
+		console.info(results.pending.includes('task-2')) // ← true
+
+		assert.strictEqual(console.output()[0][1], true)
+		assert.strictEqual(console.output()[1][1], true)
+	})
+
+	/**
+	 * @docs
+	 * ### Release Processing
+	 *
+	 * 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
+	 */
+	it('How to execute a release after validation?', async () => {
+		//import { ReleaseManager, ProjectManagement } from '@nan0web/release'
+		const pm = new ProjectManagement()
+		const rm = new ReleaseManager(pm)
+
+		rm.calculateVersion = () => 'v1.0.1'
+		rm.publish = async () => true
+
+		const result = await rm.executeRelease('patch')
+		console.info(result.version) // ← v1.0.1
+		console.info(result.published) // ← true
+
+		assert.strictEqual(console.output()[0][1], 'v1.0.1')
+		assert.strictEqual(console.output()[1][1], true)
+	})
+
+	/**
+	 * @docs
+	 * ### Changelog Integration
+	 *
+	 * Using `ChangelogTaskManager`, you can:
+	 * - Extract task definitions from changelog entries
+	 * - Generate corresponding test files
+	 * - Automate task progression in CI
+	 */
+	it('How to parse changelog and extract tasks?', () => {
+		//import { ChangelogTaskManager } from '@nan0web/release'
+		const ctm = new ChangelogTaskManager()
+		const changelog = `# Changelog
+
+## [1.0.0] - 2025-08-20
+### Added
+- Initial structure [core.init]
+- Release notes support [docs.release-notes]`
+
+		const tasks = ctm.parseChangelog(changelog)
+		console.info(Array.isArray(tasks)) // ← true
+		console.info(tasks.length >= 0) // ← true
+
+		assert.strictEqual(console.output()[0][1], true)
+		assert.strictEqual(console.output()[1][1], true)
+	})
+
+	/**
+	 * @docs
+	 * ## Java•Script Features
+	 */
+	it('Uses JSDoc and .d.ts files for autocompletion', () => {
+		assert.ok(pkg.types)
+		assert.ok(pkg.types.includes('.d.ts'))
+	})
+
+	/**
+	 * @docs
+	 * ## CLI Playground
+	 *
+	 * Try the package in the terminal:
+	 */
+	it('How to run playground demo?', async () => {
+		/**
+		 * ```bash
+		 * git clone https://github.com/nan0web/release.git
+		 * cd release
+		 * pnpm install
+		 * pnpm run playground
+		 * ```
+		 */
+		assert.ok(pkg.scripts?.playground)
+		const response = await runSpawn('git', ['remote', 'get-url', 'origin'])
+		assert.ok(response.code === 0)
+		assert.ok(response.text.trim().endsWith(':nan0web/release.git'))
+	})
+
+	/**
+	 * @docs
+	 * ## Project Status
+	 *
+	 * To verify the project is ready, run:
+	 */
+	it('How to check project status before publishing?', async () => {
+		/**
+		 * ```bash
+		 * npm test
+		 * npm run test:coverage
+		 * npm run test:status
+		 * ```
+		 */
+		assert.ok(pkg.scripts?.test)
+		assert.ok(pkg.scripts?.['test:coverage'])
+		assert.ok(pkg.scripts?.['test:status'])
+	})
+
+	/**
+	 * @docs
+	 * ## Contributing
+	 */
+	it('How to contribute? - [check here](./CONTRIBUTING.md)', async () => {
+		assert.equal(pkg.scripts?.precommit, 'npm test')
+		assert.equal(pkg.scripts?.prepush, 'npm test')
+		assert.equal(pkg.scripts?.prepare, 'husky')
+	})
+
+	/**
+	 * @docs
+	 * ## License
+	 */
+	it('How to license ISC? - [check here](./LICENSE)', async () => {
+		/** @docs */
+		const text = await fs.loadDocument('LICENSE')
+		assert.ok(String(text).includes('ISC'))
+	})
+}
+
+describe('README.md testing', testRender)
+
+describe('Rendering README.md', async () => {
+	let text = ''
+	const format = new Intl.NumberFormat('en-US').format
+	const parser = new DocsParser()
+	text = String(parser.decode(testRender))
+	await fs.saveDocument('README.md', text)
+	const dataset = DatasetParser.parse(text, pkg.name)
+	await fs.saveDocument('.datasets/README.dataset.jsonl', dataset)
+
+	it(`document is rendered [${format(Buffer.byteLength(text))}b]`, async () => {
+		const text = await readFile('README.md', 'utf8')
+		assert.ok(text.includes('## License'))
+	})
+})