@nan0web/payload-release 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# @nan0web/payload-release
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Payload CMS 3.x plugin for release tracking, idempotency, execution logs, and Markdown specification preview.
+
+## Features
+
+- **Releases Collection**: Automatic recording of release runs with tabbed navigation:
+  - **General**: Status, version, command (`seed`, `fresh`, `migrate`), execution duration, Git SHA, Git Dirty state, Node.js and pnpm versions.
+  - **Steps (N)**: Execution steps with duration and output.
+  - **Parity (N)**: Data parity check between CSV/source rows and DB records.
+  - **Issues (N)**: Structured audit messages (`info`, `warning`, `error`).
+  - **Files (N)**: Release artifacts with size, SHA-256 hash, and embedded modal preview.
+- **Embedded Markdown Modal**: Built-in preview for `task.md` and `user.md` directly in the Payload Admin panel.
+- **DB-FS Secure Endpoints**: Read release artifacts without blocking Node.js procedural calls in client components.
+
+## Installation
+
+```bash
+pnpm add @nan0web/payload-release
+```
+
+## Usage
+
+```typescript
+import { buildConfig } from 'payload'
+import { payloadRelease } from '@nan0web/payload-release'
+
+export default buildConfig({
+  plugins: [
+    payloadRelease({
+      releasesDir: 'releases',
+      allowPreview: true,
+    }),
+  ],
+})
+```

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@nan0web/payload-release",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Payload CMS plugin for release tracking, idempotency, execution logs, and Markdown specification preview.",
+  "type": "module",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nan0web/payload-cms.git",
+    "directory": "packages/payload-release"
+  },
+  "bugs": {
+    "url": "https://github.com/nan0web/payload-cms/issues"
+  },
+  "homepage": "https://github.com/nan0web/payload-cms/tree/main/packages/payload-release#readme",
+  "main": "src/index.js",
+  "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./admin": {
+      "types": "./types/admin.d.ts",
+      "import": "./src/admin.jsx"
+    }
+  },
+  "files": [
+    "src",
+    "types",
+    "docs",
+    "releases",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@payloadcms/ui": ">=3.0.0",
+    "payload": ">=3.0.0",
+    "react": ">=18.0.0"
+  },
+  "dependencies": {
+    "@nan0web/types": "^3.4.0",
+    "markdown-it": "^14.1.0"
+  },
+  "devDependencies": {
+    "husky": "^9.1.7",
+    "knip": "^5.61.0"
+  },
+  "scripts": {
+    "prebuild": "rm -rf types/",
+    "build": "tsc",
+    "knip": "pnpm dlx knip --production",
+    "test:releases": "node --test --test-timeout=9999 'releases/**/*.spec.js'",
+    "test": "node --test --test-timeout=9999 'tests/**/*.test.js' 'src/**/*.test.js' 'releases/**/*.spec.js'",
+    "test:e2e": "node --test --test-name-pattern=e2e",
+    "test:all": "pnpm test && pnpm build && pnpm knip",
+    "pack:check": "pnpm pack --pack-destination .artifacts",
+    "pack:local": "pnpm pack --pack-destination .artifacts",
+    "release:validate": "dilo validate packages/payload-release"
+  }
 }

package/releases/0/1/v0.1.0/task.md

@@ -0,0 +1,49 @@
+---
+status: done
+type: minor
+epic: EPIC-PAYLOAD-RELEASE
+sprint: Sprint 43
+tracker: https://github.com/nan0web/payload-cms/issues/{id}
+---
+
+# v0.1.0 — payload-release: Audit, Idempotency & Markdown Preview
+
+## Опис та Мета
+Плагін `@nan0web/payload-release` для Payload CMS 3.x, що забезпечує автоматичну фіксацію запусків релізів, контроль версій (Idempotency), вбудований журнал аудиту (Steps, Parity, Issues, Files) та компактний перегляд специфікацій `task.md` і `user.md` у форматі Markdown безпосередньо в інтерфейсі адмін-панелі.
+
+## Команда
+- **Lead / Architect:** Олександр Снігірьов (@snigirev)
+- **AI Lead Developer:** Agent Antigravity (@agy)
+- **Auditor:** Security Bot (@sec-bot)
+
+## Робочий План та Задачі
+
+### 1. Колекція `Releases` з компактним Tabbed Layout
+- [x] [#REL-1] Нативна розбивка форми релізу на вкладки (Tabs): General, Steps, Parity, Issues, Files.
+- [x] [#REL-2] Відображення бейджів кількості в заголовках вкладок (steps, parity, issues, files).
+- [x] [#REL-3] Забезпечення суворого Read-Only доступу в адмін-панелі (заборона create, update, delete, приховування кнопки Create New).
+
+### 2. Вбудований Markdown Modal Viewer
+- [x] [#VIEW-1] Реалізація кнопки перегляду (`👁️`) біля артефактів `task.md` та `user.md`.
+- [x] [#VIEW-2] Вбудований модальний переглядач Markdown зі стилями та закриттям за клавішею `Esc` або кнопкою `✕`.
+
+### 3. Серверні Ендпоінти та Автономне Читання
+- [x] [#SRV-1] Безпечний Local API / REST ендпоінт для отримання сирого або відрендереного файлу (`GET /api/releases/:id/file?path=...`).
+- [x] [#SRV-2] Захист від path traversal та безпечне читання артефактів релізу.
+
+### 4. Zero-Config Plugin Interface та Auto-Discovery
+- [x] [#PLG-1] Підтримка виклику без обов'язкових параметрів `payloadRelease()`.
+- [x] [#PLG-2] Автоматичне виявлення релізів з файлової системи (проєктні релізи та вбудований реліз плагіна) під час ініціалізації (`onInit`).
+
+## Критерії Прийнятності (DoD)
+- [x] [#DOD-1] Пакет створено в монорепо `payload-cms/packages/payload-release` з чистою структурою `package.json`, `tsconfig.json` та `@nan0web` залежностями.
+- [x] [#DOD-2] Колекція `releases` реєструється автоматично через плагін `payloadRelease()`.
+- [x] [#DOD-3] Усі масиви полів форми релізу мають бейджі кількості в заголовках вкладок.
+- [x] [#DOD-4] Файли `task.md` та `user.md` відображаються у списку `files` та доступні для читання у вбудованій модалці.
+- [x] [#DOD-5] Забезпечено суворий **Read-Only доступ**: заборонено `create`, `update`, `delete`, кнопка `Create New` прихована.
+- [x] [#DOD-6] Підтримується виклик без параметрів: `payloadRelease()`.
+- [x] [#DOD-7] Релізи автоматично завантажуються із файлової системи (включно із вбудованим демонстраційним релізом `v0.1.0`).
+- [x] [#DOD-8] Оновлено контрактні тести `task.spec.js` для верифікації прав доступу та автозавантаження.
+- [x] [#DOD-9] Пройдено інспекцію без викликів `console.warn` / `console.error`.
+
+

package/releases/0/1/v0.1.0/task.spec.js

@@ -0,0 +1,156 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import path from 'node:path'
+import {
+	payloadRelease,
+	ReleaseConfigModel,
+	createReleaseFileEndpoint,
+	discoverReleases,
+	parseMarkdownCheckboxes,
+} from '../../../../src/index.js'
+
+describe('payload-release v0.1.0 contract', () => {
+	it('exports valid plugin function and ReleaseConfigModel', () => {
+		assert.equal(typeof payloadRelease, 'function')
+		assert.ok(ReleaseConfigModel)
+		assert.equal(typeof ReleaseConfigModel.releasesDir, 'object')
+	})
+
+	it('configures Releases collection with tabs, badges and strict read-only access', () => {
+		const plugin = payloadRelease({
+			releasesDir: 'releases',
+			allowPreview: true,
+		})
+
+		const config = plugin({ collections: [] })
+		assert.ok(Array.isArray(config.collections))
+		const releasesCol = config.collections.find((c) => c.slug === 'releases')
+		assert.ok(releasesCol, 'Releases collection must be registered')
+		assert.equal(releasesCol.admin?.useAsTitle, 'version')
+
+		// Verify strict Read-Only access controls
+		assert.ok(releasesCol.access, 'Access configuration must exist')
+		assert.equal(typeof releasesCol.access.create, 'function')
+		assert.equal(releasesCol.access.create(), false, 'create access must be forbidden')
+		assert.equal(typeof releasesCol.access.update, 'function')
+		assert.equal(releasesCol.access.update(), false, 'update access must be forbidden')
+		assert.equal(typeof releasesCol.access.delete, 'function')
+		assert.equal(releasesCol.access.delete(), false, 'delete access must be forbidden')
+		assert.equal(typeof releasesCol.access.read, 'function')
+		assert.equal(releasesCol.access.read(), true, 'read access must be allowed')
+
+		// Check tabs layout
+		const tabsField = releasesCol.fields.find((f) => f.type === 'tabs')
+		assert.ok(tabsField, 'Tabs field must exist')
+		assert.ok(Array.isArray(tabsField.tabs))
+		assert.equal(tabsField.tabs.length, 5)
+
+		const resolvedLabels = tabsField.tabs.map((t) => {
+			if (typeof t.label === 'function') {
+				return t.label({ data: { steps: [{}], parity: [{}], issues: [{}], files: [{}] } })
+			}
+			return t.name || t.label
+		})
+		assert.ok(resolvedLabels.some((n) => typeof n === 'string' && n.includes('General')))
+		assert.ok(resolvedLabels.some((n) => typeof n === 'string' && n.includes('Steps')))
+		assert.ok(resolvedLabels.some((n) => typeof n === 'string' && n.includes('Parity')))
+		assert.ok(resolvedLabels.some((n) => typeof n === 'string' && n.includes('Issues')))
+		assert.ok(resolvedLabels.some((n) => typeof n === 'string' && n.includes('Files')))
+	})
+
+	it('supports zero-config invocation without options', () => {
+		const plugin = payloadRelease()
+		assert.equal(typeof plugin, 'function')
+
+		const config = plugin({ collections: [], endpoints: [] })
+		assert.ok(config.collections.some((c) => c.slug === 'releases'))
+		assert.ok(Array.isArray(config.endpoints))
+		assert.equal(typeof config.onInit, 'function')
+	})
+
+	it('registers release file reading endpoint', () => {
+		const plugin = payloadRelease()
+		const config = plugin({ collections: [], endpoints: [] })
+		assert.ok(Array.isArray(config.endpoints))
+		const fileEndpoint = config.endpoints.find(
+			(e) => e.path === '/api/releases/:id/file' || e.path === '/releases/:id/file'
+		)
+		assert.ok(fileEndpoint, 'Release file endpoint must be registered')
+		assert.equal(fileEndpoint.method, 'get')
+		assert.equal(typeof fileEndpoint.handler, 'function')
+	})
+
+	it('safely serves file content and markdown rendering via endpoint handler', async () => {
+		const handler = createReleaseFileEndpoint({
+			releasesDir: 'releases',
+			readReleaseFile: async (relPath) => {
+				if (relPath.includes('task.md')) {
+					return '# Task Spec\n\n- [x] Done item\n- [ ] Todo item'
+				}
+				return null
+			},
+		})
+
+		const req = {
+			url: 'http://payload.local/api/releases/123/file?path=0/1/v0.1.0/task.md',
+			routeParams: { id: '123' },
+		}
+
+		const res = await handler(req)
+		assert.equal(res.status, 200)
+		const data = await res.json()
+		assert.ok(data.found)
+		assert.match(data.raw, /# Task Spec/)
+		assert.match(data.html, /<h1>Task Spec<\/h1>/)
+		assert.match(data.html, /Done item/)
+	})
+
+	it('rejects path traversal attempts in file endpoint', async () => {
+		const handler = createReleaseFileEndpoint({
+			releasesDir: 'releases',
+			readReleaseFile: async () => 'secret',
+		})
+
+		const req = {
+			url: 'http://payload.local/api/releases/123/file?path=../../etc/passwd',
+			routeParams: { id: '123' },
+		}
+
+		const res = await handler(req)
+		assert.equal(res.status, 400)
+	})
+
+	it('automatically discovers releases and parses task checkboxes from filesystem', async () => {
+		const releases = await discoverReleases()
+		assert.ok(Array.isArray(releases))
+		assert.ok(releases.length >= 1)
+
+		const v010 = releases.find((r) => r.version === 'v0.1.0')
+		assert.ok(v010, 'v0.1.0 release must be discovered')
+		assert.equal(v010.status, 'ok')
+		assert.ok(Array.isArray(v010.files))
+		assert.ok(v010.files.some((f) => f.path.endsWith('task.md')))
+		assert.ok(v010.files.some((f) => f.path.endsWith('user.md')))
+		assert.ok(Array.isArray(v010.steps))
+		assert.ok(v010.steps.length > 0)
+	})
+
+	it('synchronizes discovered releases in onInit hook', async () => {
+		const plugin = payloadRelease()
+		const config = plugin({ collections: [] })
+
+		const created = []
+		const mockPayload = {
+			find: async () => ({ docs: [] }),
+			create: async ({ collection, data }) => {
+				created.push({ collection, data })
+				return data
+			},
+		}
+
+		await config.onInit(mockPayload)
+		assert.ok(created.length >= 1)
+		assert.equal(created[0].collection, 'releases')
+		assert.equal(created[0].data.version, 'v0.1.0')
+	})
+})

package/releases/0/1/v0.1.0/user.md

@@ -0,0 +1,34 @@
+# user metrics — payload-release v0.1.0
+
+## Метрики Виконання
+- **Цільова версія:** v0.1.0
+- **Статус:** done
+- **Витрачений час розробки (Годин):** 2.8
+- **Кількість ітерацій:** 4
+- **Фінальний бал RRS:** 345
+
+## Опис Реалізованих Задач (Task Log)
+- **[#REL-1, #REL-2] Tabbed Layout & Badges:** Форму колекції `Releases` розбито на компактні вкладки із динамічними бейджами кількості елементів (`steps`, `parity`, `issues`, `files`).
+- **[#REL-3, #DOD-5] Суворий Read-Only доступ:** Встановлено заборону створення (`create: false`), редагування (`update: false`) та видалення (`delete: false`). Кнопку `Create New` приховано.
+- **[#VIEW-1, #VIEW-2] Вбудований Markdown Modal Viewer:** Додано інтерактивну кнопку перегляду (`👁️`) біля артефактів `task.md` та `user.md` із відкриттям модального вікна та підтримкою `Esc` / `✕`.
+- **[#SRV-1, #SRV-2] Безпечні REST/Local API Ендпоінти:** Реалізовано обробник `/api/releases/:id/file` з обов'язковою санітизацією шляхів від path traversal.
+- **[#PLG-1, #PLG-2] Zero-Config Plugin & Auto-Discovery:** Плагін підключається через `payloadRelease()` без аргументів і автоматично синхронізує релізи під час старту.
+
+## Журнал Зворотного Зв'язку (Feedback & Notes)
+- **Настанова Архітектора від 14.10.2026:**
+  1. Колекція `releases` у Payload CMS призначена **виключно для перегляду**.
+  2. Плагін повинен запускатися максимально просто: `payloadRelease()` без зайвих конфігурацій.
+  3. Релізи мають надходити автоматично із файлової системи / внутрішнього сховища і одразу бути доступними у списку адмінки.
+  4. Клієнтський інтерфейс адмінки залишається стандартним нативним клієнтом Payload CMS.
+
+## Статус та Послідовність Кроків (Pipeline)
+- [x] **Крок B (Виконано):** Інтеграція та сумісність з опублікованими `@nan0web/release@3.5.0` та `@nan0web/release.app@0.3.0`.
+  - Релізні документи приведені до PMaC-стандарту.
+  - Валідатор `dilo validate packages/payload-release` повертає **PASSED ✅** (100% валідність, 9/9 завдань виконано).
+  - Скрипт `pnpm run release:validate` додано у `package.json`.
+  - `pnpm test:all` (контрактні тести, типи, knip) зелений.
+- [x] **Крок A (Виконано):** Інтеграційне тестування та перевірка в `testing-app` (підключення плагіна `payloadRelease()`, реєстрація колекції `releases`, генерація importMap, ручна візуальна перевірка адмінки).
+- [x] **Крок C (Готово до релізу):** Усі контракти, типи та валідація пакету `dilo validate` пройдені успішно. Пакунок готовий до публікації `@nan0web/payload-release@0.1.0`.
+
+
+