@nan0web/release 1.0.0

package/docs/uk/README.md

@@ -0,0 +1,284 @@
+# @nan0web/release
+
+| Назва пакету | [Статус](https://github.com/nan0web/monorepo/blob/main/system.md#написання-сценаріїв) | Документація | Покриття тестами | Особливості | Версія npm |
+|--------------|----------------------------------------------------------------------------------------|---------------|------------------|-------------|------------|
+| [@nan0web/release](https://github.com/nan0web/release/) |🟢 `97.1%` | 🧪 [Англійською 🏴󠁧󠁢󠁥󠁮󠁧󠁿](https://github.com/nan0web/release/blob/main/README.md)<br />[Українською 🇺🇦](https://github.com/nan0web/release/blob/main/docs/uk/README.md) |🟡 `84.2%` | ✅ d.ts 📜 system.md 🕹️ playground | — |
+
+Керування проєктами як код, орієнтоване на Git, підписане GPG та кероване тестами.
+
+На відміну від традиційних інструментів керування проєктами, які потребують постійної синхронізації чи ручних оновлень,
+`@nan0web/release` забезпечує структуру проєкту, де:
+- Завдання представлені як тести у файлах `.test.js`.
+- Статус відстежується через результати виконання тестів.
+- Ролі в команді та погодження зберігаються у структурованих файлах.
+- Всі зміни підписані, версійовані та компонуємі.
+
+Це гарантує:
+- Чітке, автоматизоване відстеження проєкту.
+- Незмінні нотатки релізів і рефлексії після них.
+- Нульову неоднозначність – завдання не існують, якщо не протестовані.
+
+## Встановлення
+
+Як встановити за допомогою pnpm?
+```bash
+pnpm add @nan0web/release
+```
+
+Як встановити за допомогою npm?
+```bash
+npm install @nan0web/release
+```
+
+Як встановити за допомогою yarn?
+```bash
+yarn add @nan0web/release
+```
+
+## Використання CLI
+
+Почніть із ініціалізації нового релізу:
+
+Як ініціалізувати нову версію релізу?
+```bash
+release init v1.0.0
+```
+
+const cli = new ReleaseCLI()
+Показати деталі релізу:
+
+Як показати інформацію про реліз?
+```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
+Список усіх релізів у проєкті:
+
+Як отримати список усіх релізів?
+```bash
+release list [--json]
+```
+
+const cli = new ReleaseCLI()
+Додати повідомлення до поточного релізу:
+
+Як написати повідомлення до релізу?
+```bash
+release chat write --user alice "Проблема з пайплайном збірки"
+```
+
+const cli = new ReleaseCLI()
+Запустити статичний сервер для перегляду релізів:
+
+Як запустити інтерфейс релізів?
+```bash
+release host [--webui] [--port 3000]
+```
+
+const cli = new ReleaseCLI()
+Обслуговувати всі файли релізу для локального перегляду:
+
+Як обслуговувати статичні ресурси релізу?
+```bash
+release serve [--port 8080]
+```
+
+const cli = new ReleaseCLI()
+Перевірити завдання та цілісність релізу:
+
+Як перевірити завдання релізу?
+```bash
+release validate [--ignore-fail]
+```
+
+const release = new Release({
+version: "v1.0.0",
+createdAt: new Date("2025-08-20")
+})
+Завершити реліз з рефлексією:
+
+Як завершити (запечатати) реліз?
+```bash
+release seal [--message "Усі основні API стабільні і протестовані"]
+```
+
+const cli = new ReleaseCLI()
+## Основні концепції
+
+### 1. Реліз як об’єкт
+
+Об’єкт `Release` включає:
+- `version`: ідентифікатор релізу (vX.Y.Z).
+- `createdAt`, `startAt`, `planAt`, `completeAt`: часові мітки.
+- `document`: розібраний markdown-документ із структурною орієнтацією.
+
+Усі властивості типізовані та автоматично перевіряються через JSDoc та runtime-аналіз.
+
+Як створити об’єкт Release?
+```js
+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
+
+```
+### 2. Розпізнавання документа релізу
+
+`ReleaseDocument` розширює `@nan0web/markdown`:
+- Структурний аналіз markdown-файлу нотаток релізу
+- Видобування розділів і завдань
+- Аналіз команд і ролей із frontmatter чи коду
+
+Як перетворити markdown-нотатки релізу у структуровані дані?
+```js
+import { ReleaseDocument } from '@nan0web/release'
+const md = `# v1.0.0 - 2025-08-20
+
+## Огляд
+Цей реліз включає поліпшення інтерфейсу та стабілізацію API.
+
+### Завдання
+### Done **Реалізувати основний дизайн інтерфейсу** [ui.core-design]
+### InProgress **Виправити проблеми адаптивності на мобільних пристроях** [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
+
+```
+### 3. Структури персони та команди
+
+Об’єкт `Person` включає:
+- `name`: HumanName
+- `gender`: HumanGender
+- `contacts`: масив HumanContact
+
+Як створити об’єкт Person із типізованими властивостями?
+```js
+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
+
+```
+## Архітектура: керування проєктами як код
+
+Ця архітектура розглядає завдання як тести, ролі — як класи, а прогрес — як підтверджені результати.
+
+### Управління завданнями
+
+Завдання фіксуються як `taskId` → `testFilePath` в `ProjectManagement`.
+Статус визначається через запуск наборів тестів `node:test`.
+
+Як зареєструвати та перевірити завдання за допомогою тестів?
+```js
+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
+
+```
+### Обробка релізу
+
+`ReleaseManager` координує релізи і перевіряє готовність.
+Він гарантує:
+- Всі зареєстровані тести проходять
+- Версія правильно збільшується
+- Git-тег встановлюється, якщо всі перевірки успішні
+
+Як виконати реліз після перевірки?
+```js
+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
+
+```
+### Інтеграція з CHANGELOG
+
+Через `ChangelogTaskManager` можна:
+- Видобувати означення завдань з записів змін
+- Генерувати відповідні тести
+- Автоматизувати перевірку завдань у CI
+
+Як розібрати changelog і видобути завдання?
+```js
+import { ChangelogTaskManager } from '@nan0web/release'
+const ctm = new ChangelogTaskManager()
+const changelog = `# Зміни
+
+## [1.0.0] - 2025-08-20
+### Added
+- Створено основну структуру [core.init]
+- Додано підтримку нотаток релізу [docs.release-notes]`
+
+const tasks = ctm.parseChangelog(changelog)
+console.info(Array.isArray(tasks)) // ← true
+console.info(tasks.length >= 0) // ← true
+
+```
+## Особливості Java•Script
+
+Використовує JSDoc і .d.ts для автозаповнення
+
+## Демонстрація CLI
+
+Спробуйте пакет у терміналі:
+
+Як запустити демо playground?
+```bash
+git clone https://github.com/nan0web/release.git
+cd release
+pnpm install
+pnpm run playground
+```
+
+## Статус проєкту
+
+Перевірити готовність проєкту можна так:
+
+Як перевірити статус перед публікацією?
+```bash
+npm test
+npm run test:coverage
+npm run test:status
+```
+
+## Внески
+
+Як зробити внесок? — [перегляньте тут](./CONTRIBUTING.md)
+
+## Ліцензія
+
+Як застосувати ліцензію ISC? — [перегляньте тут](./LICENSE)

package/legacy/PrepareCommand.js

@@ -0,0 +1,154 @@
+import { execSync } from 'node:child_process'
+import DB from '@nan0web/db-fs'
+import Logger from '@nan0web/log'
+import { Changelog } from '@nan0web/changelog'
+import { Command } from '@nan0web/co'
+
+/**
+ * @typedef {Object} PrepareCommandOpts
+ * @property {boolean} laconic
+ * @property {boolean} descriptive
+ * @property {string} template
+ */
+/**
+ * Prepare command class
+ */
+class PrepareCommand extends Command {
+	/** @type {Logger} */
+	logger
+	/** @type {PrepareCommandOpts}  */
+	opts
+	/** @type {string} */
+	cwd
+	/** @type {DB} */
+	db
+
+	constructor(options = {}) {
+		const {
+			logger = new Logger(),
+			cwd = ".",
+		} = options
+		super(options)
+		this.logger = Logger.from(logger)
+		this.cwd = String(cwd)
+		this.options = new Map([
+			["laconic", [false, "Generate laconic changelog"]],
+			["descriptive", [false, "Generate descriptive changelog"]],
+			["template", [String, "Template file or message for a changelog"]],
+		])
+		this.db = new DB({ cwd: this.cwd })
+	}
+
+	/**
+	 * Run the prepare command
+	 * @param {string[]} args - Command arguments
+	 * @returns {Promise<void>}
+	 */
+	async run(args) {
+		let content = await this.db.loadDocument('CHANGELOG.md', '')
+
+		const changelog = new Changelog()
+		changelog.parse(content)
+		changelog.init()
+		const latest = changelog.getLatestVersion()
+		const versions = changelog.getVersions()
+
+		// Get git changes
+		const changes = this.getGitChanges()
+
+		if (changes.length > 0) {
+			const promptContent = await this.generateChangelogPrompt(changes)
+			await this.db.writeDocument("me.md", String(promptContent))
+		}
+
+		// Save updated changelog
+		await this.db.saveDocument('CHANGELOG.md', String(changelog.document))
+	}
+
+	/**
+	 * Get list of new and modified files from git
+	 * @returns {string[]} - Array of file paths
+	 */
+	getGitChanges() {
+		try {
+			// Get uncommitted changes
+			const statusOutput = execSync('git status --porcelain', {
+				cwd: this.cwd,
+				encoding: 'utf8'
+			})
+
+			const changes = statusOutput
+				.split('\n')
+				.filter(line => line.trim() !== '')
+				.map(line => {
+					const parts = line.trim().split(/\s+/)
+					return parts[1]
+				})
+
+			return changes
+		} catch (e) {
+			this.logger.warn('Git repository not found or git command failed')
+			return []
+		}
+	}
+
+	/**
+	 * Generate changelog prompt from file changes
+	 * @param {string[]} changes - Array of changed file paths
+	 * @returns {Promise<string>} - Prompt content
+	 */
+	async generateChangelogPrompt(changes) {
+		const fileStats = []
+		for (const filePath of changes) {
+			try {
+				const stat = await this.db.statDocument(filePath)
+				fileStats.push({ path: filePath, isFile: stat.isFile })
+			} catch {
+				fileStats.push({ path: filePath, isFile: false })
+			}
+		}
+
+		const files = fileStats
+			.filter(item => item.isFile)
+			.map(item => item.path)
+
+		if (files.length === 0) {
+			return ''
+		}
+
+		const promptLines = [
+			"Based on the following changed files, please provide changelog entries:",
+		]
+
+		const diffOutput = execSync('git diff --no-color HEAD', {
+			cwd: this.cwd,
+			encoding: 'utf8'
+		})
+
+		if (diffOutput.trim() !== '') {
+			promptLines.push('\n```diff\n' + diffOutput.trim() + '\n```')
+		}
+
+		const newFiles = execSync('git ls-files --others --exclude-standard', {
+			cwd: this.cwd,
+			encoding: 'utf8'
+		}).split('\n').filter(line => line.trim() !== '')
+
+		for (const file of newFiles) {
+			try {
+				const content = await this.db.loadDocumentAs(".txt", file)
+				promptLines.push(`\n#### \`${file}\``)
+				promptLines.push('```')
+				promptLines.push(content)
+				promptLines.push('```')
+			} catch {
+				// ignore files that can't be read
+				this.logger.warn("Could not read file", file)
+			}
+		}
+
+		return promptLines.join('\n')
+	}
+}
+
+export default PrepareCommand

package/legacy/PrepareCommand.test.js

@@ -0,0 +1,189 @@
+import { describe, it } from 'node:test'
+import { strict as assert } from 'node:assert'
+import { execSync } from 'node:child_process'
+import { mkdirSync, writeFileSync, existsSync, rmSync } from 'node:fs'
+import { resolve } from 'node:path'
+import DB from '@nan0web/db-fs'
+import Logger from '@nan0web/log'
+import PrepareCommand from './PrepareCommand.js'
+
+describe('PrepareCommand', () => {
+	it('should initialize CHANGELOG.md if it is empty', async () => {
+		const testDir = resolve('test_data/empty_changelog')
+
+		// Remove directory if exists
+		if (existsSync(testDir)) {
+			rmSync(testDir, { recursive: true })
+		}
+
+		mkdirSync(testDir, { recursive: true })
+
+		// Initialize git repo
+		try {
+			execSync('git init', { cwd: testDir })
+			execSync('git config user.name "Test User"', { cwd: testDir })
+			execSync('git config user.email "test@example.com"', { cwd: testDir })
+		} catch (e) {
+			assert.fail('Failed to initialize git repository: ' + e.message)
+		}
+
+		// Create empty CHANGELOG.md
+		writeFileSync(resolve(testDir, 'CHANGELOG.md'), '')
+
+		// Add and commit
+		try {
+			execSync('git add CHANGELOG.md', { cwd: testDir })
+			execSync('git commit -m "Initial commit"', { cwd: testDir })
+		} catch (e) {
+			// Ignore if nothing to commit
+		}
+
+		const command = new PrepareCommand({
+			cwd: testDir,
+			logger: new Logger({ silent: true })
+		})
+
+	try {
+			await command.run([])
+		} catch (e) {
+			assert.fail('Command failed: ' + e.message)
+		}
+
+		const db = new DB({ cwd: testDir })
+		const changelogContent = await db.loadDocument('CHANGELOG.md', '')
+		assert.ok(changelogContent.includes('# Changelog'), 'CHANGELOG.md should be initialized with header')
+	})
+
+	it('should generate changelog prompt with new and modified files', async () => {
+		const testDir = resolve('test_data/changes')
+
+		// Remove directory if exists
+		if (existsSync(testDir)) {
+			rmSync(testDir, { recursive: true })
+		}
+
+		mkdirSync(testDir, { recursive: true })
+
+		// Initialize git repo
+		try {
+			execSync('git init', { cwd: testDir })
+			execSync('git config user.name "Test User"', { cwd: testDir })
+			execSync('git config user.email "test@example.com"', { cwd: testDir })
+			// Create initial commit
+			writeFileSync(resolve(testDir, 'initial.txt'), 'initial content')
+			execSync('git add initial.txt', { cwd: testDir })
+			execSync('git commit -m "Initial commit"', { cwd: testDir })
+		} catch (e) {
+			assert.fail('Failed to initialize git repository: ' + e.message)
+		}
+
+		// Create initial files
+		writeFileSync(resolve(testDir, 'CHANGELOG.md'), '# Changelog\n')
+		writeFileSync(resolve(testDir, 'existing-file.txt'), 'existing content\n')
+
+		// Add and commit initial files
+		try {
+			execSync('git add CHANGELOG.md existing-file.txt', { cwd: testDir })
+			execSync('git commit -m "Add initial files"', { cwd: testDir })
+		} catch (e) {
+			// Ignore if nothing to commit
+		}
+
+		// Make changes
+		writeFileSync(resolve(testDir, 'new-file.txt'), 'new content\n')
+		writeFileSync(resolve(testDir, 'existing-file.txt'), 'existing content\nmodified content\n')
+
+		const command = new PrepareCommand({
+			cwd: testDir,
+			logger: new Logger({ silent: true })
+		})
+
+		try {
+			await command.run([])
+		} catch (err) {
+			assert.fail('Command failed: ' + err.message)
+		}
+
+		// Test passes if no exception is thrown
+		assert.ok(true)
+	})
+
+	it('should include recent changelog entries in the prompt', async () => {
+		const testDir = resolve('test_data/recent_entries')
+
+		// Remove directory if exists
+		if (existsSync(testDir)) {
+			rmSync(testDir, { recursive: true })
+		}
+
+		mkdirSync(testDir, { recursive: true })
+
+		// Initialize git repo
+		try {
+			execSync('git init', { cwd: testDir })
+			execSync('git config user.name "Test User"', { cwd: testDir })
+			execSync('git config user.email "test@example.com"', { cwd: testDir })
+			// Create initial commit
+			writeFileSync(resolve(testDir, 'initial.txt'), 'initial content')
+			execSync('git add initial.txt', { cwd: testDir })
+			execSync('git commit -m "Initial commit"', { cwd: testDir })
+		} catch (e) {
+			assert.fail('Failed to initialize git repository: ' + e.message)
+		}
+
+		// Create directories
+		mkdirSync(resolve(testDir, 'src'), { recursive: true })
+
+		// Create CHANGELOG.md with existing releases
+		const changelogContent = `# Changelog
+
+## [1.2.0] - 2024-01-03
+### Added
+- New feature Y
+
+## [1.1.0] - 2024-01-02
+### Changed
+- Improved performance of module X
+
+## [1.0.0] - 2024-01-01
+### Added
+- Initial release
+- Core functionality implemented
+`
+		writeFileSync(resolve(testDir, 'CHANGELOG.md'), changelogContent)
+
+		// Add and commit CHANGELOG.md
+		try {
+			execSync('git add CHANGELOG.md', { cwd: testDir })
+			execSync('git commit -m "Add changelog with entries"', { cwd: testDir })
+		} catch (e) {
+			// Ignore if nothing to commit
+		}
+
+		// Make changes
+		writeFileSync(resolve(testDir, 'src/new-feature.js'), 'console.log("new feature")\n')
+
+		const command = new PrepareCommand({
+			cwd: testDir,
+			logger: new Logger({ silent: true })
+		})
+
+		try {
+			await command.run([])
+		} catch (err) {
+			assert.fail('Command failed: ' + err.message)
+		}
+
+		const db = new DB({ cwd: testDir })
+		const promptContent = await db.loadDocument('me.md', '')
+
+		// Check that recent entries are included in the prompt
+		assert.ok(promptContent.includes('## [1.2.0] - 2024-01-03'), 'Prompt should include most recent entry')
+		assert.ok(promptContent.includes('## [1.1.0] - 2024-01-02'), 'Prompt should include second recent entry')
+		assert.ok(promptContent.includes('## [1.0.0] - 2024-01-01'), 'Prompt should include third recent entry')
+
+		// Check that the prompt contains the instruction about using these entries as examples
+		assert.ok(promptContent.includes('Based on the following changed files, please provide changelog entries:'),
+			'Prompt should contain instructions for generating changelog entries')
+	})
+})