@nan0web/release 1.0.0

package/releases/1/0/v1.0.0/release.md

@@ -0,0 +1,121 @@
+# v1.0.0 - 2025-08-18
+
+## PM as a code
+
+Project management as a code is real if you believe and do this way.
+
+### Team
+
+#### developer
+
+- YaRaSLove (ЯRаСлав) <support@yaro.page>
+
+#### assistant
+
+- Qwen-3-coder-480b <https://api.cerebras.ai/>
+
+## CLI application
+
+### 1. Git-Native & Version-Controlled Workflow [](./task/git-native.test.js)
+
+- Treats project management like code: everything is versioned, auditable, reversible.
+- No external tools or databases needed — just Git.
+- Natural for developers; lowers barrier to entry for dev-centric teams.
+
+#### Acceptance Criteria
+
+- MUST verify that `git status` does not show any `releases/0/0/v0.0.0/*` files;
+- MUST create all required files according to the structure:
+```text
+release.md                      ← Release notes (tasks, sections)
+release.js                      ← Team, roles, config (class Release)
+release.test.js                 ← Main test suite (CI entrypoint)
+test/
+  {username}/                   ← Optional scope
+    tasks.test.js               ← User-specific tests
+chat/                           ← Release-wide chat
+  2025/08/18/
+    162000420.{username}.md     ← Message (timestamp + user)
+task/
+  ux.logo/                      ← Task by slug
+    config.json                 ← { assignee, priority, dependsOn }
+    approved/
+      ceo.json                  ← Approval record (GPG-signed)
+    chat/
+      2025/08/18/
+        162000420.{username}.md ← Task-specific message
+assets/                         ← Designs, docs, deliverables
+retro.md                        ← Final reflection (sealed)
+.cache/                         ← gitignored: read state, session
+```
+- MUST confirm with `git status` which files are ignored and which are tracked.
+
+---
+
+### 2. Test-Driven Project Progress [](./test/YaRaSLove/test-driven.test.js)
+- Tasks become testable units → Pass/fail defines completion.
+- Automates status tracking via CI/CD: "Done" = test passes.
+- Enables **automated QA gates in releases** — powerful for regulated environments.
+
+#### Acceptance Criteria
+- MUST write `release.md` inside the test folder `releases/0/0/v0.0.0/release.md` using proper formatting;
+- MUST initialize the release with `nan0release init v0.0.0`;
+- MUST check the generated tests and compare them against expected templates;
+- MUST prepare tests generated from complete releases notes markdown file with command `nan0release prepare v0.0.0`
+- MUST begin the workflow: all tests start in `todo`, transition states by modifying files and executing tests, validate each state (`todo`, `in progress`, `complete`, `approved`), verify release status and confirm `git tag` commands are executed once all tasks complete.
+- MUST execute `nan0release [status] v0.0.0`
+- MUST execute `nan0release todo v0.0.0`
+- MUST execute `nan0release validate v0.0.0`
+- MUST execute `nan0release seal v0.0.0`
+
+### 3. Transparent & Predictable Progress Tracking [](./test/YaRaSLove/progress-tracking.test.js)
+- Real-time progress %, ETA, and velocity derived from commit history.
+- Immediate visibility through stats (pending/pass/fail).
+- Eliminates manual updates in Jira/Trello → reduces noise and inaccuracies.
+
+#### Acceptance Criteria
+- MUST validate updates occur upon commits (these may be simulated or run within an isolated temporary `.git` environment); ensure CI/CD generates reports which are both testable and consumable by UIs.
+
+---
+
+### 4. Integrated Team Communication [](./test/YaRaSLove/chat.test.js)
+- Structured chat per release and task embedded directly in file system.
+- Chronologically ordered, searchable, and version-controlled conversations.
+- `.cache` supports user-specific read/unread states without requiring a central server.
+
+#### Acceptance Criteria
+
+- MUST test by verifying created files after running the following commands:
+- `nan0release chat write "msg"`
+- `nan0release chat write ux.logo "help needed"`
+- `nan0release chat read`
+- `nan0release chat find "help"`
+- `nan0release chat --sender member@example.com`
+- `nan0release chat unread`
+- MUST test both output and resulting file content.
+
+---
+
+### 5. Self-Documenting Releases [](./test/YaRaSLove/docs.test.js)
+
+- Structured, machine-readable release notes, always current.
+- Markdown enhanced with YAML frontmatter enables metadata (assignees, dates, etc.).
+- Facilitates automatic generation of changelogs, roadmaps, dashboards.
+
+#### Acceptance Criteria
+
+- MUST validate success and failure outcomes of `nan0release validate` when processing valid and invalid release note formats. It must exit with status code 1 on a failure.
+
+---
+
+### 6. Extensible & Composable & Office-First & Decentralized by Design [ci-cd.test.js]
+- Assets such as designs, configurations, and logs stored within the release for full context.
+- Supports custom scripts, hooks, templates (e.g., `pre-release.js`, `post-release.sh`).
+- Seamlessly integrates into CI/CD pipelines.
+- Works offline and independently of external services.
+- No vendor lock-in — all data remains in the repository.
+
+#### Acceptance Criteria
+
+- MUST confirm context preservation by adding test files to assets and validating output of `git status`.
+

package/releases/1/0/v1.0.0/release.test.js

@@ -0,0 +1,36 @@
+import { describe, it } from "node:test"
+import { strict as assert } from "node:assert"
+
+import Release from "./release.js"
+
+/**
+ * @todo
+ * It must validate the structure of every release.
+ * It must be in src/Release.validate().
+ * It must validate loaded markdown into document with the file structure
+ */
+
+describe("Release v1.0.0", () => {
+	it("has a valid static version", () => {
+		assert.equal(Release.version, "v1.0.0")
+	})
+
+	it("has a valid static date", () => {
+		assert.equal(Release.createdAt, "2025-08-18")
+	})
+
+	it("references a valid Company with name", () => {
+		assert.ok(Release.company)
+		assert.equal(Release.company.name, "NaN•Web")
+	})
+
+	it("has a DevTeam defined in teams", () => {
+		assert.ok(Release.teams.DevTeam)
+		assert.equal(Release.teams.DevTeam.name, "Software development team")
+	})
+
+	it("includes all core models: Person, Contact, Message", () => {
+		assert.ok(typeof Person !== 'undefined' || typeof Release.members.YaRaSLove !== 'undefined')
+		// Note: these would be imported if external deps existed
+	})
+})

package/releases/1/0/v1.0.0/test/YaRaSLove/git-native.test.js

@@ -0,0 +1,14 @@
+import { describe, it } from "node:test"
+import assert from "node:assert/strict"
+
+describe("Git-Native & Version-Controlled Workflow", () => {
+	it("Treats project management like code: everything is versioned, auditable, reversible.", () => {
+
+	})
+	it("No external tools or databases needed — just Git.", () => {
+
+	})
+	it("Natural for developers; lowers barrier to entry for dev-centric teams.", () => {
+
+	})
+})

package/releases/current.js

@@ -0,0 +1,3 @@
+import v1_0_0 from "./1/0/v1.0.0/release.js"
+
+export default v1_0_0

package/releases/index.js

@@ -0,0 +1,11 @@
+import v1_0_0 from "./1/0/v1.0.0/release.js"
+import Release from "../src/Release.js"
+
+/**
+ * @type {Record<string, Release>}
+ */
+const releases = {
+	v1_0_0
+}
+
+export default releases

package/src/README.md.js

@@ -0,0 +1,468 @@
+import { describe, it, before, beforeEach } from "node:test"
+import assert from "node:assert/strict"
+import FS from "@nan0web/db-fs"
+import { NoConsole } from "@nan0web/log"
+import {
+	DatasetParser,
+	DocsParser,
+	runSpawn,
+} from "@nan0web/test"
+import ReleaseCLI from "./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 = new ReleaseCLI()
+		assert.ok(cli instanceof ReleaseCLI)
+	})
+
+	/**
+	 * @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 = new ReleaseCLI()
+		assert.ok(cli.releases)
+	})
+
+	/**
+	 * @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 = new ReleaseCLI()
+		assert.ok(cli instanceof ReleaseCLI)
+	})
+
+	/**
+	 * @docs
+	 * Host a static server for viewing releases:
+	 */
+	it("How to host release UI?", () => {
+		/**
+		 * ```bash
+		 * release host [--webui] [--port 3000]
+		 * ```
+		 */
+		const cli = new ReleaseCLI()
+		assert.ok(cli instanceof ReleaseCLI)
+	})
+
+	/**
+	 * @docs
+	 * Serve all release files for local inspection:
+	 */
+	it("How to serve release static assets?", () => {
+		/**
+		 * ```bash
+		 * release serve [--port 8080]
+		 * ```
+		 */
+		const cli = new ReleaseCLI()
+		assert.ok(cli instanceof ReleaseCLI)
+	})
+
+	/**
+	 * @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 = new ReleaseCLI()
+		assert.ok(cli instanceof ReleaseCLI)
+	})
+
+	/**
+	 * @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 fs.loadDocument("README.md")
+		assert.ok(text.includes("## License"))
+	})
+})