@nuasite/cms 0.18.0 → 0.19.0

package/src/handlers/redirect-ops.ts

@@ -0,0 +1,163 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { getProjectRoot } from '../config'
+import type { AddRedirectRequest, DeleteRedirectRequest, RedirectOperationResponse, RedirectRule, UpdateRedirectRequest } from '../types'
+import { acquireFileLock, isNodeError } from '../utils'
+
+const DEFAULT_STATUS_CODE = 307
+const REDIRECTS_FILE = 'src/_redirects'
+
+function getRedirectsFilePath(): string {
+	return path.join(getProjectRoot(), REDIRECTS_FILE)
+}
+
+export async function handleGetRedirects(): Promise<{ rules: RedirectRule[] }> {
+	const lines = await readRedirectsFile(getRedirectsFilePath())
+	return { rules: parseRedirectLines(lines) }
+}
+
+export async function handleAddRedirect(request: AddRedirectRequest): Promise<RedirectOperationResponse> {
+	const { source, destination, statusCode = DEFAULT_STATUS_CODE } = request
+
+	if (!source || !destination) {
+		return { success: false, error: 'Source and destination are required' }
+	}
+	if (!source.startsWith('/')) {
+		return { success: false, error: 'Source must start with /' }
+	}
+	if (!destination.startsWith('/') && !destination.startsWith('http')) {
+		return { success: false, error: 'Destination must start with / or http' }
+	}
+
+	const filePath = getRedirectsFilePath()
+	const release = await acquireFileLock(filePath)
+
+	try {
+		const lines = await readRedirectsFile(filePath)
+		const existing = parseRedirectLines(lines)
+
+		if (existing.some(r => r.source === source)) {
+			return { success: false, error: `Redirect already exists for ${source}` }
+		}
+
+		lines.push(formatRedirectLine(source, destination, statusCode))
+		await writeRedirectsFile(filePath, lines)
+		return { success: true }
+	} finally {
+		release()
+	}
+}
+
+export async function handleUpdateRedirect(request: UpdateRedirectRequest): Promise<RedirectOperationResponse> {
+	const { lineIndex, source, destination, statusCode = DEFAULT_STATUS_CODE } = request
+
+	if (!source || !destination) {
+		return { success: false, error: 'Source and destination are required' }
+	}
+
+	const filePath = getRedirectsFilePath()
+	const release = await acquireFileLock(filePath)
+
+	try {
+		const lines = await readRedirectsFile(filePath)
+
+		// Guard against stale line index
+		const currentLine = lines[lineIndex]?.trim()
+		if (!currentLine || currentLine.startsWith('#')) {
+			return { success: false, error: 'Line at index is no longer a redirect rule — please refresh and try again' }
+		}
+
+		lines[lineIndex] = formatRedirectLine(source, destination, statusCode)
+		await writeRedirectsFile(filePath, lines)
+		return { success: true }
+	} finally {
+		release()
+	}
+}
+
+export async function handleDeleteRedirect(request: DeleteRedirectRequest): Promise<RedirectOperationResponse> {
+	const { lineIndex } = request
+
+	const filePath = getRedirectsFilePath()
+	const release = await acquireFileLock(filePath)
+
+	try {
+		const lines = await readRedirectsFile(filePath)
+
+		if (lineIndex < 0 || lineIndex >= lines.length) {
+			return { success: false, error: `Invalid line index: ${lineIndex}` }
+		}
+
+		const line = lines[lineIndex]!.trim()
+		if (!line || line.startsWith('#')) {
+			return { success: false, error: 'Line is not a redirect rule' }
+		}
+
+		lines.splice(lineIndex, 1)
+		await writeRedirectsFile(filePath, lines)
+		return { success: true }
+	} finally {
+		release()
+	}
+}
+
+// --- Internal helpers ---
+
+function formatRedirectLine(source: string, destination: string, statusCode: number): string {
+	return statusCode === DEFAULT_STATUS_CODE
+		? `${source} ${destination}`
+		: `${source} ${destination} ${statusCode}`
+}
+
+async function readRedirectsFile(filePath: string): Promise<string[]> {
+	try {
+		const content = await fs.readFile(filePath, 'utf-8')
+		return content.split('\n')
+	} catch (error) {
+		if (isNodeError(error, 'ENOENT')) return []
+		throw error
+	}
+}
+
+async function writeRedirectsFile(filePath: string, lines: string[]): Promise<void> {
+	await fs.mkdir(path.dirname(filePath), { recursive: true })
+
+	const trimmed = lines.slice()
+	while (trimmed.length > 0 && trimmed[trimmed.length - 1]!.trim() === '') {
+		trimmed.pop()
+	}
+
+	if (trimmed.length === 0) {
+		await fs.writeFile(filePath, '', 'utf-8')
+		return
+	}
+
+	await fs.writeFile(filePath, trimmed.join('\n') + '\n', 'utf-8')
+}
+
+function parseRedirectLines(lines: string[]): RedirectRule[] {
+	const rules: RedirectRule[] = []
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i]!.trim()
+		if (!line || line.startsWith('#')) continue
+
+		const parts = line.split(/\s+/)
+		if (parts.length < 2) continue
+
+		const source = parts[0]!
+		if (!source.startsWith('/')) continue
+
+		const destination = parts[1]!
+		const statusCode = parts[2] ? parseInt(parts[2], 10) : DEFAULT_STATUS_CODE
+
+		rules.push({
+			source,
+			destination,
+			statusCode: Number.isNaN(statusCode) ? DEFAULT_STATUS_CODE : statusCode,
+			lineIndex: i,
+		})
+	}
+
+	return rules
+}

package/src/handlers/source-writer.ts

@@ -1,9 +1,11 @@
 import { NodeType, parse as parseHtml } from 'node-html-parser'
 import fs from 'node:fs/promises'
 import path from 'node:path'
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
 import { getProjectRoot } from '../config'
 import type { AttributeChangePayload, ChangePayload, SaveBatchRequest } from '../editor/types'
 import type { ManifestWriter } from '../manifest-writer'
+import { extractAstroImageOriginalUrl } from '../source-finder/snippet-utils'
 import type { CmsManifest, ManifestEntry } from '../types'
 import { acquireFileLock, escapeReplacement, normalizePagePath, resolveAndValidatePath } from '../utils'
 
@@ -59,7 +61,6 @@ export async function handleUpdate(
 					fileChanges,
 					manifest,
 				)
-
 				if (failedChanges.length > 0) {
 					errors.push(...failedChanges)
 				}
@@ -185,6 +186,32 @@ export function applyImageChange(
 		}
 	}
 
+	// Extract original path from Astro Image optimization URLs (/_image?href=...)
+	const decodedHref = extractAstroImageOriginalUrl(originalSrc)
+	if (decodedHref && !srcCandidates.includes(decodedHref)) {
+		srcCandidates.push(decodedHref)
+	}
+
+	// Extract the authored value from YAML/JSON source snippets.
+	// Astro optimizes images from content collections (e.g. ./images/photo.jpg → /assets/hash.webp),
+	// so the rendered URL won't match the value in the data file. Parse the snippet to recover it.
+	if (change.sourceSnippet) {
+		const yamlKeyMatch = change.sourceSnippet.match(/^\s*([\w][\w-]*):\s*/)
+		if (yamlKeyMatch?.[1]) {
+			try {
+				const parsed = parseYaml(change.sourceSnippet)
+				if (parsed && typeof parsed === 'object') {
+					const value = (parsed as Record<string, unknown>)[yamlKeyMatch[1]]
+					if (typeof value === 'string' && !srcCandidates.includes(value)) {
+						srcCandidates.push(value)
+					}
+				}
+			} catch {
+				// Not valid YAML, ignore
+			}
+		}
+	}
+
 	let newContent = content
 	let replacedIndex = -1
 	for (const srcToFind of srcCandidates) {
@@ -209,6 +236,46 @@ export function applyImageChange(
 		}
 	}
 
+	// Fallback: try YAML key-value replacement for collection frontmatter fields
+	// Try all srcCandidates since the rendered URL may differ from the authored YAML value
+	if (replacedIndex < 0 && change.sourceSnippet) {
+		for (const srcToFind of srcCandidates) {
+			const yamlResult = tryYamlValueReplacement(change.sourceSnippet, srcToFind, newSrc)
+			if (yamlResult !== null) {
+				// Search near the source line to avoid matching a duplicate snippet elsewhere
+				let searchStart = 0
+				if (change.sourceLine > 1) {
+					let linesFound = 0
+					for (let j = 0; j < newContent.length; j++) {
+						if (newContent[j] === '\n' && ++linesFound >= change.sourceLine - 1) {
+							searchStart = j + 1
+							break
+						}
+					}
+				}
+				const snippetIdx = newContent.indexOf(change.sourceSnippet, searchStart)
+				if (snippetIdx >= 0) {
+					replacedIndex = snippetIdx
+					newContent = newContent.slice(0, snippetIdx) + yamlResult + newContent.slice(snippetIdx + change.sourceSnippet.length)
+					break
+				}
+			}
+		}
+	}
+
+	// Fallback: direct quoted-value replacement for data files (JSON, YAML, MD frontmatter)
+	// The source file may be a collection data file where the image is a plain string value
+	if (replacedIndex < 0 && change.sourceSnippet) {
+		for (const srcToFind of srcCandidates) {
+			const result = tryDataFileValueReplacement(newContent, change.sourceSnippet, srcToFind, newSrc, change.sourceLine)
+			if (result) {
+				replacedIndex = result.index
+				newContent = result.content
+				break
+			}
+		}
+	}
+
 	// Fallback: if literal src not found, try to find an expression-based src attribute
 	// near the source line (handles src={variable}, src={obj.prop}, etc.)
 	if (replacedIndex < 0 && change.sourceLine > 0) {
@@ -543,6 +610,13 @@ export function applyTextChange(
 	const updatedSnippet = sourceSnippet.replace(resolvedOriginal, resolvedNewText)
 
 	if (updatedSnippet === sourceSnippet) {
+		// Try YAML key-value replacement for multi-line frontmatter values
+		// (e.g., "title: long text\n  that wraps")
+		const yamlResult = tryYamlValueReplacement(sourceSnippet, resolvedOriginal, resolvedNewText)
+		if (yamlResult !== null) {
+			return { success: true, content: content.replace(sourceSnippet, yamlResult) }
+		}
+
 		// Try AST-based <br> normalization (browser normalizes <br class="..." /> to <br>
 		// and collapses surrounding whitespace/indentation)
 		const brResult = tryBrNormalizedChange(sourceSnippet, resolvedOriginal, resolvedNewText)
@@ -774,6 +848,88 @@ function getVisibleText(html: string): string {
 	return text.trim()
 }
 
+/**
+ * Try to replace a YAML value in a frontmatter snippet.
+ * Uses the YAML parser to resolve the value (handles all scalar styles:
+ * plain wrapping, single/double quoted, block literal `|`, folded `>`).
+ * Returns the updated snippet, or null if this approach doesn't apply.
+ */
+function tryYamlValueReplacement(
+	sourceSnippet: string,
+	resolvedOriginal: string,
+	resolvedNewText: string,
+): string | null {
+	// Must look like a YAML key: value pair
+	const keyMatch = sourceSnippet.match(/^(\s*([\w][\w-]*):\s*)/)
+	if (!keyMatch) return null
+
+	// Use the YAML parser to resolve the value — handles all scalar styles
+	try {
+		const parsed = parseYaml(sourceSnippet)
+		if (parsed == null || typeof parsed !== 'object') return null
+		const value = (parsed as Record<string, unknown>)[keyMatch[2]!]
+		if (typeof value !== 'string' && typeof value !== 'number') return null
+		if (String(value) !== resolvedOriginal) return null
+	} catch {
+		return null
+	}
+
+	// Use the YAML library to safely serialize the new value,
+	// handling characters that would break plain scalars (: # [ ] { } , etc.)
+	const serialized = stringifyYaml(resolvedNewText, { lineWidth: 0 }).trimEnd()
+	return `${keyMatch[1]}${serialized}`
+}
+
+/**
+ * Replace an image value in a data file (JSON, YAML, MD frontmatter).
+ * Matches the original value as a quoted string within the source snippet context.
+ */
+function tryDataFileValueReplacement(
+	content: string,
+	sourceSnippet: string,
+	originalValue: string,
+	newValue: string,
+	sourceLine: number,
+): { content: string; index: number } | null {
+	// Check if snippet contains the original value as a quoted string (JSON or YAML)
+	const doubleQuoted = `"${originalValue}"`
+	const singleQuoted = `'${originalValue}'`
+
+	let quotedOriginal: string
+	let quotedNew: string
+	if (sourceSnippet.includes(doubleQuoted)) {
+		quotedOriginal = doubleQuoted
+		quotedNew = `"${newValue}"`
+	} else if (sourceSnippet.includes(singleQuoted)) {
+		quotedOriginal = singleQuoted
+		quotedNew = `'${newValue}'`
+	} else {
+		return null
+	}
+
+	const updatedSnippet = sourceSnippet.replace(quotedOriginal, quotedNew)
+	if (updatedSnippet === sourceSnippet) return null
+
+	// Find the snippet in content near the source line
+	let searchStart = 0
+	if (sourceLine > 1) {
+		let linesFound = 0
+		for (let j = 0; j < content.length; j++) {
+			if (content[j] === '\n' && ++linesFound >= sourceLine - 1) {
+				searchStart = j + 1
+				break
+			}
+		}
+	}
+	const snippetIdx = content.indexOf(sourceSnippet, searchStart)
+	if (snippetIdx < 0) return null
+
+	return {
+		content: content.slice(0, snippetIdx) + updatedSnippet + content.slice(snippetIdx + sourceSnippet.length),
+		index: snippetIdx,
+	}
+}
+
 /**
  * Try to apply a text change when the mismatch is due to <br> normalization.
  * The browser normalizes <br class="..." /> to plain <br> and collapses surrounding whitespace.

package/src/html-processor.ts

@@ -2,7 +2,16 @@ import { type HTMLElement as ParsedHTMLElement, parse } from 'node-html-parser'
 import { processSeoFromHtml } from './seo-processor'
 import { enhanceManifestWithSourceSnippets } from './source-finder'
 import { extractBackgroundImageClasses, extractColorClasses, extractTextStyleClasses } from './tailwind-colors'
-import type { Attribute, BackgroundImageMetadata, ComponentInstance, ImageMetadata, ManifestEntry, PageSeoData, SeoOptions } from './types'
+import type {
+	Attribute,
+	BackgroundImageMetadata,
+	CollectionDefinition,
+	ComponentInstance,
+	ImageMetadata,
+	ManifestEntry,
+	PageSeoData,
+	SeoOptions,
+} from './types'
 import { generateStableId } from './utils'
 
 /** Type for parsed HTML element nodes from node-html-parser */
@@ -69,6 +78,8 @@ export interface ProcessHtmlOptions {
 	}
 	/** SEO tracking options */
 	seo?: SeoOptions
+	/** Collection definitions for resolving frontmatter text on listing pages */
+	collectionDefinitions?: Record<string, CollectionDefinition>
 }
 
 export interface ProcessHtmlResult {
@@ -223,6 +234,7 @@ export async function processHtml(
 		skipInlineStyleTags = true,
 		collectionInfo,
 		seo: seoOptions,
+		collectionDefinitions,
 	} = options
 
 	const root = parse(html, {
@@ -1013,7 +1025,7 @@ export async function processHtml(
 
 	// Enhance manifest entries with actual source snippets from source files
 	// This allows the CMS to match and replace dynamic content in source files
-	const enhancedEntries = await enhanceManifestWithSourceSnippets(entries)
+	const enhancedEntries = await enhanceManifestWithSourceSnippets(entries, collectionDefinitions)
 
 	// Get the current HTML for SEO processing
 	let finalHtml = root.toString()

package/src/index.ts

@@ -1,5 +1,6 @@
 import type { AstroIntegration } from 'astro'
 import { existsSync, readFileSync } from 'node:fs'
+import fs from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -12,7 +13,7 @@ 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 type { CmsFeatures, CmsMarkerOptions, ComponentDefinition } from './types'
 import { createVitePlugin } from './vite-plugin'
 
 export interface NuaCmsOptions extends CmsMarkerOptions {
@@ -30,6 +31,7 @@ export interface NuaCmsOptions extends CmsMarkerOptions {
 		debug?: boolean
 		theme?: Record<string, string>
 		themePreset?: string
+		features?: CmsFeatures
 	}
 	/**
 	 * Proxy /_nua/cms requests to this target URL during dev.
@@ -41,6 +43,19 @@ export interface NuaCmsOptions extends CmsMarkerOptions {
 	 * Defaults to local filesystem (public/uploads) when no proxy is configured.
 	 */
 	media?: MediaStorageAdapter
+	/**
+	 * Directories containing components available in the MDX component picker.
+	 * Only components within these directories (relative to project root) will appear.
+	 * Example: ['src/components/mdx'] or ['src/components/mdx', 'src/components/blocks']
+	 */
+	mdxComponentDirs?: string[]
+	/**
+	 * Per-collection field overrides for position and grouping.
+	 * Highest priority — overrides scanner defaults and frontmatter comment directives.
+	 */
+	collections?: Record<string, {
+		fields?: Record<string, { position?: 'sidebar' | 'header'; group?: string }>
+	}>
 }
 
 const VIRTUAL_CMS_PATH = '/@nuasite/cms-editor.js'
@@ -62,6 +77,7 @@ export default function nuaCms(options: NuaCmsOptions = {}): AstroIntegration {
 		markComponents = true,
 		componentDirs = ['src/components'],
 		contentDir = 'src/content',
+		mdxComponentDirs,
 		seo = { trackSeo: true, markTitle: true, parseJsonLd: true },
 	} = options
 
@@ -110,6 +126,14 @@ export default function nuaCms(options: NuaCmsOptions = {}): AstroIntegration {
 					componentDefinitions = registry.getComponents()
 					manifestWriter.setComponentDefinitions(componentDefinitions)
 
+					if (mdxComponentDirs) {
+						const normalizedDirs = mdxComponentDirs.map(dir => dir.endsWith('/') ? dir : dir + '/')
+						const mdxNames = Object.values(componentDefinitions)
+							.filter(def => normalizedDirs.some(dir => def.file.startsWith(dir)))
+							.map(def => def.name)
+						manifestWriter.setMdxComponents(mdxNames)
+					}
+
 					const componentCount = Object.keys(componentDefinitions).length
 					if (componentCount > 0) {
 						logger.info(`Found ${componentCount} component definitions`)
@@ -117,6 +141,21 @@ export default function nuaCms(options: NuaCmsOptions = {}): AstroIntegration {
 				}
 
 				const collectionDefinitions = await scanCollections(contentDir)
+
+				// Apply per-collection field overrides from astro config (highest priority)
+				if (options.collections) {
+					for (const [collectionName, overrides] of Object.entries(options.collections)) {
+						const def = collectionDefinitions[collectionName]
+						if (!def || !overrides.fields) continue
+						for (const field of def.fields) {
+							const fieldOverride = overrides.fields[field.name]
+							if (!fieldOverride) continue
+							if (fieldOverride.position) field.position = fieldOverride.position
+							if (fieldOverride.group) field.group = fieldOverride.group
+						}
+					}
+				}
+
 				manifestWriter.setCollectionDefinitions(collectionDefinitions)
 
 				const collectionCount = Object.keys(collectionDefinitions).length
@@ -260,6 +299,9 @@ export default function nuaCms(options: NuaCmsOptions = {}): AstroIntegration {
 					await processBuildOutput(dir, markerConfig, manifestWriter, idCounter, logger)
 				}
 
+				// Merge CMS-managed redirects (src/_redirects) into dist/_redirects
+				await mergeRedirects(dir, logger)
+
 				const errorCollector = getErrorCollector()
 				if (errorCollector.hasWarnings()) {
 					const warnings = errorCollector.getWarnings()
@@ -273,10 +315,42 @@ export default function nuaCms(options: NuaCmsOptions = {}): AstroIntegration {
 	}
 }
 
+/**
+ * Merge CMS-managed redirects from src/_redirects into the build output's dist/_redirects.
+ * This ensures both Astro config redirects (written by adapters) and CMS-managed redirects coexist.
+ */
+async function mergeRedirects(dir: URL, logger: { info: (msg: string) => void }): Promise<void> {
+	const srcRedirectsPath = join(process.cwd(), 'src', '_redirects')
+
+	let cmsRedirects: string
+	try {
+		cmsRedirects = (await fs.readFile(srcRedirectsPath, 'utf-8')).trim()
+	} catch {
+		return
+	}
+	if (!cmsRedirects) return
+
+	const distDir = fileURLToPath(dir)
+	const distRedirectsPath = join(distDir, '_redirects')
+
+	let existing = ''
+	try {
+		existing = await fs.readFile(distRedirectsPath, 'utf-8')
+	} catch {
+		// File doesn't exist yet — will be created
+	}
+
+	const separator = existing ? '\n\n# CMS-managed redirects\n' : '# CMS-managed redirects\n'
+	await fs.writeFile(distRedirectsPath, existing + separator + cmsRedirects + '\n', 'utf-8')
+
+	const lineCount = cmsRedirects.split('\n').filter((l) => l.trim() && !l.trim().startsWith('#')).length
+	logger.info(`Merged ${lineCount} CMS redirect(s) into _redirects`)
+}
+
 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 type { MediaFolderItem, MediaItem, MediaListOptions, MediaListResult, MediaStorageAdapter, MediaTypeFilter } from './media/types'
 
 export { scanCollections } from './collection-scanner'
 export { getProjectRoot, resetProjectRoot, setProjectRoot } from './config'

package/src/manifest-writer.ts

@@ -38,6 +38,7 @@ export class ManifestWriter {
 	private collectionDefinitions: Record<string, CollectionDefinition> = {}
 	private availableColors: AvailableColors | undefined
 	private availableTextStyles: AvailableTextStyles | undefined
+	private mdxComponents: string[] | undefined
 	private writeQueue: Promise<void> = Promise.resolve()
 
 	constructor(manifestFile: string, componentDefinitions: Record<string, ComponentDefinition> = {}) {
@@ -67,6 +68,14 @@ export class ManifestWriter {
 		this.globalManifest.componentDefinitions = definitions
 	}
 
+	/**
+	 * Set the list of component names allowed in the MDX component picker
+	 */
+	setMdxComponents(names: string[]): void {
+		this.mdxComponents = names
+		this.globalManifest.mdxComponents = names
+	}
+
 	/**
 	 * Load available Tailwind colors and text styles from the project's CSS config
 	 */
@@ -98,7 +107,15 @@ export class ManifestWriter {
 	 */
 	setCollectionDefinitions(definitions: Record<string, CollectionDefinition>): void {
 		this.collectionDefinitions = definitions
-		this.globalManifest.collectionDefinitions = definitions
+		// Strip entry.data before publishing to the manifest — it's only needed
+		// server-side (for reference detection) and would bloat the browser payload.
+		const stripped: Record<string, CollectionDefinition> = {}
+		for (const [name, def] of Object.entries(definitions)) {
+			stripped[name] = def.entries
+				? { ...def, entries: def.entries.map(({ data, ...rest }) => rest) }
+				: def
+		}
+		this.globalManifest.collectionDefinitions = stripped
 	}
 
 	/**
@@ -325,6 +342,7 @@ export class ManifestWriter {
 			collectionDefinitions: this.collectionDefinitions,
 			availableColors: this.availableColors,
 			availableTextStyles: this.availableTextStyles,
+			mdxComponents: this.mdxComponents,
 		}
 		this.writeQueue = Promise.resolve()
 	}

package/src/media/contember.ts

@@ -42,7 +42,8 @@ export function createContemberStorageAdapter(options: ContemberStorageOptions):
 				throw new Error(`Failed to list media (${res.status}): ${await res.text()}`)
 			}
 
-			return (await res.json()) as MediaListResult
+			const data = await res.json()
+			return { folders: [], ...data } as MediaListResult
 		},
 
 		async upload(file, filename, contentType) {