@nan0web/payload-release 0.0.0-stage → 0.1.0

package/src/collections/Releases.js

@@ -0,0 +1,308 @@
+import { ReleaseConfigModel } from '../domain/ReleaseConfigModel.js'
+
+/**
+ * Creates dynamic tab label with count badge
+ * @param {string} baseLabel
+ * @param {string} arrayFieldName
+ * @returns {import('payload').LabelFunction}
+ */
+function createTabBadgeLabel(baseLabel, arrayFieldName) {
+	return ({ data }) => {
+		const arr = data?.[arrayFieldName]
+		if (Array.isArray(arr) && arr.length > 0) {
+			return baseLabel.replace('{count}', String(arr.length))
+		}
+		// Return clean label without ' (0)' placeholder if no items or data not loaded yet
+		return baseLabel.replace(' ({count})', '').replace('{count}', '')
+	}
+}
+
+/**
+ * Builds the Payload CMS Collection configuration for Releases.
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.allowPreview=true]
+ * @returns {import('payload').CollectionConfig}
+ */
+export function buildReleasesCollection(options = {}) {
+	const allowPreview = options.allowPreview !== false
+	const fileEndpointHandler = options.fileEndpointHandler
+
+	return {
+		slug: 'releases',
+		labels: {
+			singular: ReleaseConfigModel.UI.singular,
+			plural: ReleaseConfigModel.UI.plural,
+		},
+		endpoints: fileEndpointHandler
+			? [
+					{
+						path: '/:id/file',
+						method: 'get',
+						handler: fileEndpointHandler,
+					},
+					{
+						path: '/view/file',
+						method: 'get',
+						handler: fileEndpointHandler,
+					},
+				]
+			: [],
+		access: {
+			read: () => true,
+			create: () => false,
+			update: () => false,
+			delete: () => false,
+		},
+		admin: {
+			useAsTitle: 'version',
+			defaultColumns: ['version', 'command', 'status', 'durationMs', 'createdAt'],
+			group: ReleaseConfigModel.UI.group,
+			hideAPIURL: false,
+			components: {
+				beforeList: [],
+				views: {
+					edit: {
+						default: {
+							Component: '@nan0web/payload-release/admin#ReleaseDocumentView',
+						},
+					},
+				},
+			},
+		},
+		fields: [
+			{
+				type: 'tabs',
+				tabs: [
+					{
+						label: ReleaseConfigModel.UI.tabGeneral,
+						fields: [
+							{
+								type: 'row',
+								fields: [
+									{
+										name: 'version',
+										type: 'text',
+										required: true,
+										unique: true,
+										index: true,
+										admin: { width: '50%' },
+									},
+									{
+										name: 'status',
+										type: 'select',
+										defaultValue: 'ok',
+										options: [
+											{ label: 'OK', value: 'ok' },
+											{ label: 'Failed', value: 'failed' },
+										],
+										admin: { width: '50%' },
+									},
+								],
+							},
+							{
+								type: 'row',
+								fields: [
+									{
+										name: 'command',
+										type: 'select',
+										options: [
+											{ label: 'Seed', value: 'seed' },
+											{ label: 'Fresh', value: 'fresh' },
+											{ label: 'Migrate', value: 'migrate' },
+										],
+										admin: { width: '50%' },
+									},
+									{
+										name: 'durationMs',
+										type: 'number',
+										admin: { width: '50%' },
+									},
+								],
+							},
+							{
+								type: 'row',
+								fields: [
+									{
+										name: 'gitSha',
+										type: 'text',
+										admin: { width: '50%' },
+									},
+									{
+										name: 'gitDirty',
+										type: 'checkbox',
+										admin: { width: '50%' },
+									},
+								],
+							},
+							{
+								type: 'row',
+								fields: [
+									{
+										name: 'nodeVersion',
+										type: 'text',
+										admin: { width: '50%' },
+									},
+									{
+										name: 'pnpmVersion',
+										type: 'text',
+										admin: { width: '50%' },
+									},
+								],
+							},
+						],
+					},
+					{
+						label: createTabBadgeLabel(ReleaseConfigModel.UI.tabSteps, 'steps'),
+						fields: [
+							{
+								name: 'steps',
+								type: 'array',
+								admin: {
+									components: {
+										Field: '@nan0web/payload-release/admin#ReleaseStepsField',
+									},
+								},
+								fields: [
+									{
+										type: 'row',
+										fields: [
+											{ name: 'name', type: 'text', required: true, admin: { width: '40%' } },
+											{
+												name: 'status',
+												type: 'select',
+												defaultValue: 'ok',
+												options: [
+													{ label: 'OK', value: 'ok' },
+													{ label: 'Error', value: 'error' },
+												],
+												admin: { width: '20%' },
+											},
+											{ name: 'startedAt', type: 'date', admin: { width: '20%' } },
+											{ name: 'durationMs', type: 'number', admin: { width: '20%' } },
+										],
+									},
+									{
+										name: 'output',
+										type: 'textarea',
+										admin: { rows: 3 },
+									},
+								],
+							},
+						],
+					},
+					{
+						label: createTabBadgeLabel(ReleaseConfigModel.UI.tabParity, 'parity'),
+						fields: [
+							{
+								name: 'parity',
+								type: 'array',
+								admin: {
+									components: {
+										Field: '@nan0web/payload-release/admin#ReleaseParityField',
+									},
+								},
+								fields: [
+									{
+										type: 'row',
+										fields: [
+											{ name: 'collection', type: 'text', required: true, admin: { width: '30%' } },
+											{ name: 'csvRows', type: 'number', admin: { width: '25%' } },
+											{ name: 'dbRows', type: 'number', admin: { width: '25%' } },
+											{
+												name: 'synced',
+												type: 'checkbox',
+												defaultValue: true,
+												admin: { width: '20%' },
+											},
+										],
+									},
+								],
+							},
+						],
+					},
+					{
+						label: createTabBadgeLabel(ReleaseConfigModel.UI.tabIssues, 'issues'),
+						fields: [
+							{
+								name: 'issues',
+								type: 'array',
+								admin: {
+									components: {
+										Field: '@nan0web/payload-release/admin#ReleaseIssuesField',
+									},
+								},
+								fields: [
+									{
+										type: 'row',
+										fields: [
+											{
+												name: 'level',
+												type: 'select',
+												defaultValue: 'warning',
+												options: [
+													{ label: 'Info', value: 'info' },
+													{ label: 'Warning', value: 'warning' },
+													{ label: 'Error', value: 'error' },
+												],
+												admin: { width: '25%' },
+											},
+											{ name: 'code', type: 'text', admin: { width: '25%' } },
+											{ name: 'source', type: 'text', admin: { width: '25%' } },
+											{ name: 'file', type: 'text', admin: { width: '25%' } },
+										],
+									},
+									{
+										name: 'message',
+										type: 'textarea',
+										required: true,
+									},
+								],
+							},
+						],
+					},
+					{
+						label: createTabBadgeLabel(ReleaseConfigModel.UI.tabFiles, 'files'),
+						fields: [
+							{
+								name: 'files',
+								type: 'array',
+								admin: {
+									components: {
+										Field: '@nan0web/payload-release/admin#ReleaseFilesField',
+									},
+								},
+								fields: [
+									{
+										type: 'row',
+										fields: [
+											{ name: 'path', type: 'text', required: true, admin: { width: '40%' } },
+											{ name: 'size', type: 'number', admin: { width: '20%' } },
+											{ name: 'sha256', type: 'text', admin: { width: '30%' } },
+											...(allowPreview
+												? [
+														{
+															name: 'preview',
+															type: 'ui',
+															admin: {
+																width: '10%',
+																components: {
+																	Field: '@nan0web/payload-release/admin#FilePreviewButton',
+																},
+															},
+														},
+													]
+												: []),
+										],
+									},
+								],
+							},
+						],
+					},
+				],
+			},
+		],
+	}
+}
+
+export const ReleasesCollection = buildReleasesCollection()

package/src/domain/ReleaseConfigModel.js

@@ -0,0 +1,56 @@
+import { Model } from '@nan0web/types'
+
+/**
+ * Configuration schema for @nan0web/payload-release plugin.
+ * Implements Model-as-Schema pattern.
+ */
+export class ReleaseConfigModel extends Model {
+	/**
+	 * Path to releases directory relative to project root.
+	 */
+	static releasesDir = {
+		type: 'string',
+		default: 'releases',
+		help: 'Path to releases directory relative to project root',
+		validate: (v) =>
+			(typeof v === 'string' && v.trim().length > 0) ||
+			'releasesDir must be a non-empty string',
+	}
+
+	/**
+	 * Whether Markdown file preview is enabled in Admin UI.
+	 */
+	static allowPreview = {
+		type: 'boolean',
+		default: true,
+		help: 'Allow modal preview of release Markdown documents',
+	}
+
+	/**
+	 * UI labels and translation tokens.
+	 */
+	static UI = {
+		singular: 'Release',
+		plural: 'Releases',
+		group: 'System',
+		tabGeneral: '📋 General',
+		tabSteps: '⚡ Steps ({count})',
+		tabParity: '⚖️ Parity ({count})',
+		tabIssues: '⚠️ Issues ({count})',
+		tabFiles: '📦 Files ({count})',
+		previewButton: 'Preview',
+		modalClose: 'Close',
+		loading: 'Loading content...',
+		errorNotFound: 'Document not found or inaccessible',
+	}
+
+	/**
+	 * @param {Partial<ReleaseConfigModel>} [data]
+	 * @param {import('@nan0web/types').ModelOptions} [options]
+	 */
+	constructor(data = {}, options = {}) {
+		super(data, options)
+		/** @type {string} */ this.releasesDir
+		/** @type {boolean} */ this.allowPreview
+	}
+}

package/src/index.js

@@ -0,0 +1,166 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { ReleaseConfigModel } from './domain/ReleaseConfigModel.js'
+import { buildReleasesCollection, ReleasesCollection } from './collections/Releases.js'
+import { createReleaseFileEndpoint } from './server/endpoint.js'
+import { renderMarkdown, stripFrontmatter } from './server/markdown.js'
+import {
+	discoverReleases,
+	parseMarkdownCheckboxes,
+	getGitInfo,
+	getRuntimeInfo,
+	getPackageRootDir,
+} from './server/discovery.js'
+
+export {
+	ReleaseConfigModel,
+	ReleasesCollection,
+	buildReleasesCollection,
+	createReleaseFileEndpoint,
+	renderMarkdown,
+	stripFrontmatter,
+	discoverReleases,
+	parseMarkdownCheckboxes,
+	getGitInfo,
+	getRuntimeInfo,
+	getPackageRootDir,
+}
+
+/**
+ * Configure payload-release plugin for Payload CMS.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.releasesDir='releases']
+ * @param {boolean} [options.allowPreview=true]
+ * @param {boolean} [options.autoDiscover=true]
+ * @returns {(config: any) => any}
+ */
+export function payloadRelease(options = {}) {
+	const model = new ReleaseConfigModel(options)
+	const { releasesDir, allowPreview } = model
+	const autoDiscover = options.autoDiscover !== false
+
+	return (config) => {
+		const packageRoot = getPackageRootDir()
+
+		// Safe DB-FS or filesystem file reader
+		const readReleaseFile = async (relPath) => {
+			const projectRoot = process.cwd()
+			const cleanPath = String(relPath || '')
+				.replace(/^@releases\/?/, '')
+				.replace(/^\.\//, '')
+
+			const candidatePaths = [
+				path.resolve(projectRoot, cleanPath),
+				path.resolve(projectRoot, releasesDir, cleanPath),
+				path.resolve(packageRoot, cleanPath),
+				path.resolve(packageRoot, 'releases', cleanPath),
+				path.resolve(packageRoot, cleanPath.replace(/^releases\/?/, 'releases/')),
+			]
+
+			const allowedBases = [
+				path.resolve(projectRoot),
+				path.resolve(packageRoot),
+				path.resolve(packageRoot, 'releases'),
+			]
+
+			for (const fullPath of candidatePaths) {
+				const isUnderAllowedBase = allowedBases.some(
+					(base) => fullPath === base || fullPath.startsWith(`${base}${path.sep}`)
+				)
+				if (!isUnderAllowedBase) continue
+
+				try {
+					return await fs.readFile(fullPath, 'utf8')
+				} catch {}
+			}
+
+			return null
+		}
+
+		const fileEndpointHandler = createReleaseFileEndpoint({
+			releasesDir,
+			readReleaseFile,
+		})
+
+		const collection = buildReleasesCollection({ allowPreview, fileEndpointHandler })
+
+
+		const endpoints = [
+			...(Array.isArray(config.endpoints) ? config.endpoints : []),
+			{
+				path: '/releases/:id/file',
+				method: 'get',
+				handler: fileEndpointHandler,
+			},
+			{
+				path: '/releases/view/file',
+				method: 'get',
+				handler: fileEndpointHandler,
+			},
+		]
+
+		const existingOnInit = config.onInit
+		const wrappedOnInit = async (payload) => {
+			if (existingOnInit) {
+				await existingOnInit(payload)
+			}
+
+			if (autoDiscover && payload?.find && payload?.create) {
+				try {
+					const discovered = await discoverReleases({
+						projectRoot: process.cwd(),
+						releasesDir,
+					})
+
+					for (const release of discovered) {
+						const existing = await payload.find({
+							collection: 'releases',
+							where: {
+								version: { equals: release.version },
+							},
+							limit: 1,
+							depth: 0,
+						})
+
+						if (!existing?.docs?.length) {
+							await payload.create({
+								collection: 'releases',
+								data: release,
+							})
+						} else {
+							const doc = existing.docs[0]
+							// If DB record lacks parity data or has fewer steps, sync it
+							if (!Array.isArray(doc.parity) || doc.parity.length === 0) {
+								await payload.update({
+									collection: 'releases',
+									id: doc.id,
+									data: {
+										parity: release.parity,
+										steps: release.steps,
+									},
+								})
+							}
+						}
+					}
+				} catch (err) {
+					payload?.logger?.warn?.(
+						`[payload-release] Auto-discovery note: ${/** @type {Error} */ (err).message}`
+					)
+				}
+			}
+		}
+
+		return {
+			...config,
+			collections: [
+				...(Array.isArray(config.collections) ? config.collections : []),
+				collection,
+			],
+			endpoints,
+			onInit: wrappedOnInit,
+		}
+	}
+}
+
+export default payloadRelease