@nuasite/cms 0.1.0

package/src/index.ts

@@ -0,0 +1,284 @@
+import type { AstroIntegration } from 'astro'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import tailwindcss from '@tailwindcss/vite'
+
+import { processBuildOutput } from './build-processor'
+import { scanCollections } from './collection-scanner'
+import { ComponentRegistry } from './component-registry'
+import { resetProjectRoot } from './config'
+import { createDevMiddleware } from './dev-middleware'
+import { getErrorCollector, resetErrorCollector } from './error-collector'
+import { ManifestWriter } from './manifest-writer'
+import { createLocalStorageAdapter } from './media/local'
+import type { MediaStorageAdapter } from './media/types'
+import type { CmsMarkerOptions, ComponentDefinition } from './types'
+import { createVitePlugin } from './vite-plugin'
+
+export interface NuaCmsOptions extends CmsMarkerOptions {
+	/**
+	 * URL to the CMS editor script.
+	 * If not set, the built-in editor bundle is served from the dev server.
+	 */
+	src?: string
+	/**
+	 * CMS configuration passed as window.NuaCmsConfig.
+	 */
+	cmsConfig?: {
+		apiBase?: string
+		highlightColor?: string
+		debug?: boolean
+		theme?: Record<string, string>
+		themePreset?: string
+	}
+	/**
+	 * Proxy /_nua/cms requests to this target URL during dev.
+	 * Example: 'http://localhost:8787'
+	 */
+	proxy?: string
+	/**
+	 * Media storage adapter for file uploads.
+	 * Defaults to local filesystem (public/uploads) when no proxy is configured.
+	 */
+	media?: MediaStorageAdapter
+}
+
+const VIRTUAL_CMS_PATH = '/@nuasite/cms-editor.js'
+
+export default function nuaCms(options: NuaCmsOptions = {}): AstroIntegration {
+	const {
+		// CMS editor options
+		src,
+		cmsConfig,
+		proxy,
+		media,
+		// CMS marker options
+		attributeName = 'data-cms-id',
+		includeTags = null,
+		excludeTags = ['html', 'head', 'body', 'script', 'style'],
+		includeEmptyText = false,
+		generateManifest = true,
+		manifestFile = 'cms-manifest.json',
+		markComponents = true,
+		componentDirs = ['src/components'],
+		contentDir = 'src/content',
+		seo = { trackSeo: true, markTitle: true, parseJsonLd: true },
+	} = options
+
+	// When no proxy, enable local CMS API with default media adapter
+	const enableCmsApi = !proxy
+	const mediaAdapter = media ?? (enableCmsApi ? createLocalStorageAdapter() : undefined)
+
+	// Default apiBase to local dev server when no proxy
+	const resolvedCmsConfig = enableCmsApi && !cmsConfig?.apiBase
+		? { ...cmsConfig, apiBase: '/_nua/cms' }
+		: cmsConfig
+
+	let componentDefinitions: Record<string, ComponentDefinition> = {}
+
+	const idCounter = { value: 0 }
+	const manifestWriter = new ManifestWriter(manifestFile, componentDefinitions)
+
+	const markerConfig = {
+		attributeName,
+		includeTags,
+		excludeTags,
+		includeEmptyText,
+		generateManifest,
+		manifestFile,
+		markComponents,
+		componentDirs,
+		contentDir,
+		seo,
+	}
+
+	return {
+		name: '@nuasite/astro-cms',
+		hooks: {
+			'astro:config:setup': async ({ updateConfig, command, injectScript, logger }) => {
+				// --- CMS Marker setup ---
+				idCounter.value = 0
+				manifestWriter.reset()
+				resetErrorCollector()
+				resetProjectRoot()
+
+				await manifestWriter.loadAvailableColors()
+
+				if (markComponents) {
+					const registry = new ComponentRegistry(componentDirs)
+					await registry.scan()
+					componentDefinitions = registry.getComponents()
+					manifestWriter.setComponentDefinitions(componentDefinitions)
+
+					const componentCount = Object.keys(componentDefinitions).length
+					if (componentCount > 0) {
+						logger.info(`Found ${componentCount} component definitions`)
+					}
+				}
+
+				const collectionDefinitions = await scanCollections(contentDir)
+				manifestWriter.setCollectionDefinitions(collectionDefinitions)
+
+				const collectionCount = Object.keys(collectionDefinitions).length
+				if (collectionCount > 0) {
+					logger.info(`Found ${collectionCount} content collection(s)`)
+				}
+
+				const pluginContext = {
+					manifestWriter,
+					componentDefinitions,
+					config: markerConfig,
+					idCounter,
+					command,
+				}
+
+				const vitePlugins: any[] = [...(createVitePlugin(pluginContext) as any)]
+
+				// --- CMS Editor setup (dev only) ---
+				if (command === 'dev') {
+					const editorSrc = src ?? VIRTUAL_CMS_PATH
+
+					const configScript = resolvedCmsConfig
+						? `window.NuaCmsConfig = ${JSON.stringify(resolvedCmsConfig)};`
+						: ''
+
+					injectScript('page', `
+						${configScript}
+						if (!document.querySelector('script[data-nuasite-cms]')) {
+							const s = document.createElement('script');
+							s.type = 'module';
+							s.src = ${JSON.stringify(editorSrc)};
+							s.dataset.nuasiteCms = '';
+							document.head.appendChild(s);
+						}
+					`)
+
+					// Resolve the virtual CMS editor path to the actual source file.
+					// Vite's dev server transforms the TSX, resolves imports, and serves it.
+					if (!src) {
+						const __dirname = dirname(fileURLToPath(import.meta.url))
+
+						vitePlugins.push({
+							name: 'nuasite-cms-editor',
+							resolveId(id: string) {
+								if (id === VIRTUAL_CMS_PATH) {
+									return join(__dirname, 'editor/index.tsx')
+								}
+							},
+						})
+
+						// Prepend @jsxImportSource pragma for editor .tsx files
+						// so Vite's esbuild uses Preact's h function
+						vitePlugins.push({
+							name: 'nuasite-cms-preact-jsx',
+							transform(code: string, id: string) {
+								if (id.includes('/src/editor/') && id.endsWith('.tsx') && !code.includes('@jsxImportSource')) {
+									return `/** @jsxImportSource preact */\n${code}`
+								}
+							},
+						})
+
+						// Add Tailwind CSS Vite plugin for editor styles
+						vitePlugins.push(tailwindcss())
+					}
+				}
+
+				// Proxy API requests to the backend
+				const proxyConfig: Record<string, any> = {}
+				if (proxy) {
+					proxyConfig['/_nua'] = {
+						target: proxy,
+						changeOrigin: true,
+					}
+				}
+
+				updateConfig({
+					vite: {
+						plugins: vitePlugins,
+						resolve: !src ? {
+							alias: {
+								'react': 'preact/compat',
+								'react-dom': 'preact/compat',
+								'react/jsx-runtime': 'preact/jsx-runtime',
+							},
+						} : undefined,
+						server: {
+							proxy: proxyConfig,
+						},
+					},
+				})
+			},
+
+			'astro:server:setup': ({ server, logger }) => {
+				createDevMiddleware(
+					server,
+					markerConfig,
+					manifestWriter,
+					componentDefinitions,
+					idCounter,
+					{ enableCmsApi, mediaAdapter },
+				)
+				logger.info('CMS dev middleware initialized')
+				if (enableCmsApi) {
+					logger.info('CMS API enabled at /_nua/cms/')
+				}
+			},
+
+			'astro:build:done': async ({ dir, logger }) => {
+				if (generateManifest) {
+					await processBuildOutput(dir, markerConfig, manifestWriter, idCounter, logger)
+				}
+
+				const errorCollector = getErrorCollector()
+				if (errorCollector.hasWarnings()) {
+					const warnings = errorCollector.getWarnings()
+					logger.warn(`${warnings.length} warning(s) during processing:`)
+					for (const { context, message } of warnings) {
+						logger.warn(`  - ${context}: ${message}`)
+					}
+				}
+			},
+		},
+	}
+}
+
+export { createContemberStorageAdapter as contemberMedia } from './media/contember'
+export { createLocalStorageAdapter as localMedia } from './media/local'
+export { createS3StorageAdapter as s3Media } from './media/s3'
+export type { MediaItem, MediaStorageAdapter } from './media/types'
+
+export { scanCollections } from './collection-scanner'
+export { getProjectRoot, resetProjectRoot, setProjectRoot } from './config'
+export type { CollectionInfo, MarkdownContent, SourceLocation, VariableReference } from './source-finder'
+export { findCollectionSource, parseMarkdownContent } from './source-finder'
+export type {
+	Attribute,
+	AvailableColors,
+	AvailableTextStyles,
+	CanonicalUrl,
+	CmsManifest,
+	CmsMarkerOptions,
+	CollectionDefinition,
+	CollectionEntry,
+	ComponentDefinition,
+	ComponentInstance,
+	ComponentProp,
+	ContentConstraints,
+	FieldDefinition,
+	FieldType,
+	ImageMetadata,
+	JsonLdEntry,
+	ManifestEntry,
+	ManifestMetadata,
+	OpenGraphData,
+	PageEntry,
+	PageSeoData,
+	SeoKeywords,
+	SeoMetaTag,
+	SeoOptions,
+	SeoSourceInfo,
+	SeoTitle,
+	TailwindColor,
+	TextStyleValue,
+	TwitterCardData,
+} from './types'

package/src/manifest-writer.ts

@@ -0,0 +1,371 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { getProjectRoot } from './config'
+import { parseTailwindConfig, parseTextStyles } from './tailwind-colors'
+import type {
+	AvailableColors,
+	AvailableTextStyles,
+	CmsManifest,
+	CollectionDefinition,
+	CollectionEntry,
+	ComponentDefinition,
+	ComponentInstance,
+	ManifestEntry,
+	ManifestMetadata,
+	PageEntry,
+	PageSeoData,
+} from './types'
+import { generateManifestContentHash, generateSourceFileHashes } from './utils'
+
+/** Current manifest schema version */
+const MANIFEST_VERSION = '1.0'
+
+/**
+ * Manages streaming manifest writes during build.
+ * Accumulates entries and writes per-page manifests as pages are processed.
+ */
+export class ManifestWriter {
+	private globalManifest: CmsManifest
+	private pageManifests: Map<string, {
+		entries: Record<string, ManifestEntry>
+		components: Record<string, ComponentInstance>
+		collection?: CollectionEntry
+		seo?: PageSeoData
+	}> = new Map()
+	private outDir: string = ''
+	private manifestFile: string
+	private componentDefinitions: Record<string, ComponentDefinition>
+	private collectionDefinitions: Record<string, CollectionDefinition> = {}
+	private availableColors: AvailableColors | undefined
+	private availableTextStyles: AvailableTextStyles | undefined
+	private writeQueue: Promise<void> = Promise.resolve()
+
+	constructor(manifestFile: string, componentDefinitions: Record<string, ComponentDefinition> = {}) {
+		this.manifestFile = manifestFile
+		this.componentDefinitions = componentDefinitions
+		this.globalManifest = {
+			entries: {},
+			components: {},
+			componentDefinitions,
+			collections: {},
+			collectionDefinitions: {},
+		}
+	}
+
+	/**
+	 * Set the output directory for manifest files
+	 */
+	setOutDir(dir: string): void {
+		this.outDir = dir
+	}
+
+	/**
+	 * Update component definitions (called after initial scan)
+	 */
+	setComponentDefinitions(definitions: Record<string, ComponentDefinition>): void {
+		this.componentDefinitions = definitions
+		this.globalManifest.componentDefinitions = definitions
+	}
+
+	/**
+	 * Load available Tailwind colors and text styles from the project's CSS config
+	 */
+	async loadAvailableColors(projectRoot: string = getProjectRoot()): Promise<void> {
+		this.availableColors = await parseTailwindConfig(projectRoot)
+		this.availableTextStyles = await parseTextStyles(projectRoot)
+		this.globalManifest.availableColors = this.availableColors
+		this.globalManifest.availableTextStyles = this.availableTextStyles
+	}
+
+	/**
+	 * Set available colors directly (for testing or custom colors)
+	 */
+	setAvailableColors(colors: AvailableColors): void {
+		this.availableColors = colors
+		this.globalManifest.availableColors = colors
+	}
+
+	/**
+	 * Set available text styles directly (for testing or custom styles)
+	 */
+	setAvailableTextStyles(textStyles: AvailableTextStyles): void {
+		this.availableTextStyles = textStyles
+		this.globalManifest.availableTextStyles = textStyles
+	}
+
+	/**
+	 * Set collection definitions (inferred schemas for content collections)
+	 */
+	setCollectionDefinitions(definitions: Record<string, CollectionDefinition>): void {
+		this.collectionDefinitions = definitions
+		this.globalManifest.collectionDefinitions = definitions
+	}
+
+	/**
+	 * Get collection definitions
+	 */
+	getCollectionDefinitions(): Record<string, CollectionDefinition> {
+		return this.collectionDefinitions
+	}
+
+	/**
+	 * Get the manifest path for a given page
+	 * Places manifest next to the page: /about -> /about.json, / -> /index.json
+	 */
+	private getPageManifestPath(pagePath: string): string {
+		if (pagePath === '/' || pagePath === '') {
+			return path.join(this.outDir, 'index.json')
+		}
+		const cleanPath = pagePath.replace(/^\//, '')
+		return path.join(this.outDir, `${cleanPath}.json`)
+	}
+
+	/**
+	 * Add a page's entries to the manifest (called after each page is processed)
+	 * This is non-blocking - writes are queued
+	 */
+	addPage(
+		pagePath: string,
+		entries: Record<string, ManifestEntry>,
+		components: Record<string, ComponentInstance>,
+		collection?: CollectionEntry,
+		seo?: PageSeoData,
+	): void {
+		// Store in memory
+		this.pageManifests.set(pagePath, { entries, components, collection, seo })
+
+		// Update global manifest
+		Object.assign(this.globalManifest.entries, entries)
+		Object.assign(this.globalManifest.components, components)
+
+		// Add collection entry to global manifest
+		if (collection) {
+			const collectionKey = `${collection.collectionName}/${collection.collectionSlug}`
+			this.globalManifest.collections = this.globalManifest.collections || {}
+			this.globalManifest.collections[collectionKey] = collection
+
+			// Update pathname on collection definition entry (needed for dev mode
+			// where finalize() doesn't run to populate pathnames)
+			const def = this.collectionDefinitions[collection.collectionName]
+			if (def?.entries) {
+				const entry = def.entries.find(e => e.slug === collection.collectionSlug)
+				if (entry) {
+					entry.pathname = pagePath
+				}
+			}
+		}
+
+		// Queue the write operation (non-blocking, isolated errors)
+		if (this.outDir) {
+			this.writeQueue = this.writeQueue.then(() =>
+				this.writePageManifest(pagePath, entries, components, collection, seo)
+					.catch((err) => {
+						console.error(`[astro-cms] Failed to write manifest for ${pagePath}:`, err)
+					}),
+			)
+		}
+	}
+
+	/**
+	 * Write a single page manifest to disk
+	 */
+	private async writePageManifest(
+		pagePath: string,
+		entries: Record<string, ManifestEntry>,
+		components: Record<string, ComponentInstance>,
+		collection?: CollectionEntry,
+		seo?: PageSeoData,
+	): Promise<void> {
+		const manifestPath = this.getPageManifestPath(pagePath)
+		const manifestDir = path.dirname(manifestPath)
+
+		await fs.mkdir(manifestDir, { recursive: true })
+
+		// Generate metadata for this page manifest
+		const metadata: ManifestMetadata = {
+			version: MANIFEST_VERSION,
+			generatedAt: new Date().toISOString(),
+			generatedBy: 'cms',
+			contentHash: generateManifestContentHash(entries),
+			sourceFileHashes: generateSourceFileHashes(entries),
+		}
+
+		const pageManifest: {
+			metadata: ManifestMetadata
+			page: string
+			entries: Record<string, ManifestEntry>
+			components: Record<string, ComponentInstance>
+			componentDefinitions: Record<string, ComponentDefinition>
+			collection?: CollectionEntry
+			seo?: PageSeoData
+		} = {
+			metadata,
+			page: pagePath,
+			entries,
+			components,
+			componentDefinitions: this.componentDefinitions,
+		}
+
+		if (collection) {
+			pageManifest.collection = collection
+		}
+
+		if (seo) {
+			pageManifest.seo = seo
+		}
+
+		await fs.writeFile(manifestPath, JSON.stringify(pageManifest, null, 2), 'utf-8')
+	}
+
+	/**
+	 * Finalize manifest writes
+	 * Call this in astro:build:done to ensure all writes complete
+	 */
+	async finalize(): Promise<{ totalEntries: number; totalPages: number; totalComponents: number }> {
+		// Wait for all queued writes to complete
+		await this.writeQueue
+
+		// Build pages array with pathname and title, sorted by pathname
+		const pages: PageEntry[] = Array.from(this.pageManifests.entries())
+			.map(([pathname, data]) => {
+				const entry: PageEntry = { pathname }
+				if (data.seo?.title?.content) {
+					entry.title = data.seo.title.content
+				}
+				return entry
+			})
+			.sort((a, b) => a.pathname.localeCompare(b.pathname))
+
+		// Build a map from "collectionName/slug" → pagePath using page collections
+		const collectionPathMap = new Map<string, string>()
+		for (const [pagePath, data] of this.pageManifests) {
+			if (data.collection) {
+				const key = `${data.collection.collectionName}/${data.collection.collectionSlug}`
+				collectionPathMap.set(key, pagePath)
+			}
+		}
+
+		// Populate pathname on collection definition entries
+		for (const def of Object.values(this.collectionDefinitions)) {
+			if (def.entries) {
+				for (const entry of def.entries) {
+					const pathname = collectionPathMap.get(`${def.name}/${entry.slug}`)
+					if (pathname) {
+						entry.pathname = pathname
+					}
+				}
+			}
+		}
+
+		// Write global manifest with settings (component definitions, colors, text styles, collection definitions, and pages)
+		if (this.outDir) {
+			const globalManifestPath = path.join(this.outDir, this.manifestFile)
+			const globalSettings: {
+				componentDefinitions: Record<string, ComponentDefinition>
+				collectionDefinitions?: Record<string, CollectionDefinition>
+				availableColors?: AvailableColors
+				availableTextStyles?: AvailableTextStyles
+				pages: PageEntry[]
+			} = {
+				componentDefinitions: this.componentDefinitions,
+				pages,
+			}
+			if (Object.keys(this.collectionDefinitions).length > 0) {
+				globalSettings.collectionDefinitions = this.collectionDefinitions
+			}
+			if (this.availableColors) {
+				globalSettings.availableColors = this.availableColors
+			}
+			if (this.availableTextStyles) {
+				globalSettings.availableTextStyles = this.availableTextStyles
+			}
+			await fs.writeFile(
+				globalManifestPath,
+				JSON.stringify(globalSettings, null, 2),
+				'utf-8',
+			)
+		}
+
+		return {
+			totalEntries: Object.keys(this.globalManifest.entries).length,
+			totalPages: this.pageManifests.size,
+			totalComponents: Object.keys(this.globalManifest.components).length,
+		}
+	}
+
+	/**
+	 * Get the global manifest (for virtual module support)
+	 */
+	getGlobalManifest(): CmsManifest {
+		return this.globalManifest
+	}
+
+	/**
+	 * Get a page's manifest data (for dev mode)
+	 */
+	getPageManifest(pagePath: string): {
+		entries: Record<string, ManifestEntry>
+		components: Record<string, ComponentInstance>
+		collection?: CollectionEntry
+		seo?: PageSeoData
+	} | undefined {
+		return this.pageManifests.get(pagePath)
+	}
+
+	/**
+	 * Reset state (for dev mode reloads)
+	 */
+	reset(): void {
+		this.pageManifests.clear()
+		this.globalManifest = {
+			entries: {},
+			components: {},
+			componentDefinitions: this.componentDefinitions,
+			collections: {},
+			collectionDefinitions: this.collectionDefinitions,
+			availableColors: this.availableColors,
+			availableTextStyles: this.availableTextStyles,
+		}
+		this.writeQueue = Promise.resolve()
+	}
+
+	/**
+	 * Get page data for preview generation (pages and their components)
+	 */
+	getPageDataForPreviews(): Map<string, {
+		entries: Record<string, ManifestEntry>
+		components: Record<string, ComponentInstance>
+		collection?: CollectionEntry
+		seo?: PageSeoData
+	}> {
+		return this.pageManifests
+	}
+
+	/**
+	 * Get component definitions
+	 */
+	getComponentDefinitions(): Record<string, ComponentDefinition> {
+		return this.componentDefinitions
+	}
+
+	/**
+	 * Get the output directory
+	 */
+	getOutDir(): string {
+		return this.outDir
+	}
+
+	/**
+	 * Get available colors (for use in dev middleware)
+	 */
+	getAvailableColors(): AvailableColors | undefined {
+		return this.availableColors
+	}
+
+	/**
+	 * Get available text styles (for use in dev middleware)
+	 */
+	getAvailableTextStyles(): AvailableTextStyles | undefined {
+		return this.availableTextStyles
+	}
+}