@nuasite/cms 0.32.0 → 0.34.0

package/src/handlers/astro-image-upload.ts

@@ -0,0 +1,60 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { pickAstroImageTarget } from '../astro-image-paths'
+import type { ManifestWriter } from '../manifest-writer'
+import type { MediaUploadContext } from '../types'
+import { resolveSourcePath } from '../utils'
+
+export interface AstroImageUploadResult {
+	success: true
+	url: string
+	filename: string
+}
+
+export interface AstroImageUploadError {
+	success: false
+	error: string
+}
+
+/**
+ * Attempt to route an upload to an Astro `image()` field's entry-relative location.
+ * Returns null when the context doesn't match an `astroImage` field — caller should
+ * fall back to the regular media-adapter upload flow.
+ */
+export async function tryAstroImageUpload(args: {
+	context: Partial<MediaUploadContext>
+	manifestWriter: ManifestWriter
+	fileBuffer: Buffer
+	originalFilename: string
+}): Promise<AstroImageUploadResult | AstroImageUploadError | null> {
+	const { collection, entry, field } = args.context
+	if (!collection || !entry || !field) return null
+
+	const definitions = args.manifestWriter.getCollectionDefinitions()
+	const def = definitions[collection]
+	if (!def) return null
+
+	const fieldDef = def.fields.find(f => f.name === field)
+	if (!fieldDef?.astroImage) return null
+
+	const entryInfo = def.entries?.find(e => e.slug === entry)
+	if (!entryInfo) {
+		return { success: false, error: `Entry not found: ${collection}/${entry}` }
+	}
+
+	const target = await pickAstroImageTarget({
+		entryAbsPath: resolveSourcePath(entryInfo.sourcePath),
+		slug: entryInfo.slug,
+		originalFilename: args.originalFilename,
+		compareBuffer: args.fileBuffer,
+	})
+
+	await fs.mkdir(path.dirname(target.absPath), { recursive: true })
+	await fs.writeFile(target.absPath, args.fileBuffer)
+
+	return {
+		success: true,
+		url: target.relPath,
+		filename: path.basename(target.absPath),
+	}
+}

package/src/index.ts

@@ -371,6 +371,7 @@ export type { Color, Date, DateTime, Email, Image, Reference, Textarea, Time, Ur
 
 export { scanCollections } from './collection-scanner'
 export { getProjectRoot, resetProjectRoot, setProjectRoot } from './config'
+export { type FieldMigration, migrateAstroImages, type MigrationOptions, type MigrationResult } from './migrate-astro-image'
 export { rehypeCmsMarker } from './rehype-cms-marker'
 export type { CollectionInfo, MarkdownContent, SourceLocation, VariableReference } from './source-finder'
 export { findCollectionSource, parseMarkdownContent } from './source-finder'

package/src/migrate-astro-image.ts

@@ -0,0 +1,116 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { parseDocument } from 'yaml'
+import { pickAstroImageTarget } from './astro-image-paths'
+import { scanCollections } from './collection-scanner'
+import { getProjectRoot } from './config'
+
+export interface MigrationOptions {
+	/** When true, report what would change without writing anything. */
+	dryRun?: boolean
+	/** Override the project root (mostly for tests). Defaults to getProjectRoot(). */
+	projectRoot?: string
+}
+
+export interface FieldMigration {
+	entrySourcePath: string
+	fieldName: string
+	originalValue: string
+	newValue: string
+	copiedFrom: string
+	copiedTo: string
+}
+
+export interface MigrationResult {
+	migrations: FieldMigration[]
+	skipped: Array<{ entrySourcePath: string; fieldName: string; reason: string }>
+}
+
+const FRONTMATTER_RE = /^(---\r?\n)([\s\S]*?)(\r?\n---\r?\n?)/
+
+/** Idempotent — values that are already relative or that don't resolve to a public file are skipped. */
+export async function migrateAstroImages(options: MigrationOptions = {}): Promise<MigrationResult> {
+	const projectRoot = options.projectRoot ?? getProjectRoot()
+	const dryRun = options.dryRun ?? false
+
+	const collections = await scanCollections()
+	const migrations: FieldMigration[] = []
+	const skipped: MigrationResult['skipped'] = []
+
+	for (const def of Object.values(collections)) {
+		const astroFields = def.fields.filter(f => f.astroImage)
+		if (astroFields.length === 0 || !def.entries) continue
+
+		for (const entry of def.entries) {
+			const entryAbs = path.isAbsolute(entry.sourcePath)
+				? entry.sourcePath
+				: path.join(projectRoot, entry.sourcePath)
+
+			let raw: string
+			try {
+				raw = await fs.readFile(entryAbs, 'utf-8')
+			} catch {
+				skipped.push({ entrySourcePath: entry.sourcePath, fieldName: '*', reason: 'read failed' })
+				continue
+			}
+
+			const fmMatch = raw.match(FRONTMATTER_RE)
+			if (!fmMatch) {
+				skipped.push({ entrySourcePath: entry.sourcePath, fieldName: '*', reason: 'no frontmatter' })
+				continue
+			}
+			const [fullFm, fmStart, yamlBody, fmEnd] = fmMatch as unknown as [string, string, string, string]
+			const doc = parseDocument(yamlBody)
+
+			let mutated = false
+			for (const field of astroFields) {
+				const current = doc.get(field.name)
+				if (typeof current !== 'string') {
+					if (current != null) skipped.push({ entrySourcePath: entry.sourcePath, fieldName: field.name, reason: 'non-string value' })
+					continue
+				}
+				if (!current.startsWith('/') || current.startsWith('//')) continue
+
+				const sourceAbs = path.join(projectRoot, 'public', current.replace(/^\/+/, ''))
+				let sourceBuf: Buffer
+				try {
+					sourceBuf = await fs.readFile(sourceAbs)
+				} catch {
+					skipped.push({ entrySourcePath: entry.sourcePath, fieldName: field.name, reason: `source missing: ${sourceAbs}` })
+					continue
+				}
+
+				const target = await pickAstroImageTarget({
+					entryAbsPath: entryAbs,
+					slug: entry.slug,
+					originalFilename: path.basename(current),
+					compareBuffer: sourceBuf,
+				})
+
+				if (!dryRun) {
+					await fs.mkdir(path.dirname(target.absPath), { recursive: true })
+					await fs.writeFile(target.absPath, sourceBuf)
+				}
+
+				doc.set(field.name, target.relPath)
+				mutated = true
+				migrations.push({
+					entrySourcePath: entry.sourcePath,
+					fieldName: field.name,
+					originalValue: current,
+					newValue: target.relPath,
+					copiedFrom: sourceAbs,
+					copiedTo: target.absPath,
+				})
+			}
+
+			if (mutated && !dryRun) {
+				const newYaml = doc.toString().replace(/\n$/, '')
+				const newRaw = raw.replace(fullFm, `${fmStart}${newYaml}${fmEnd}`)
+				await fs.writeFile(entryAbs, newRaw, 'utf-8')
+			}
+		}
+	}
+
+	return { migrations, skipped }
+}

package/src/source-finder/snippet-utils.ts

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises'
 import path from 'node:path'
 import { parse as parseYaml } from 'yaml'
 
+import { isHugoStyleEntry } from '../astro-image-paths'
 import { getProjectRoot } from '../config'
 import type { Attribute, CollectionDefinition, ManifestEntry } from '../types'
 import { escapeRegex, generateSourceHash, resolveSourcePath } from '../utils'
@@ -702,10 +703,34 @@ export async function enhanceManifestWithSourceSnippets(
 		return result
 	}
 
+	// Built lazily on first need — most entry sets don't have any astroImage <Image> tags
+	// rendered outside `<Content />`, in which case we never iterate the collections.
+	let astroImageIndex: AstroImageCollectionIndex | undefined
+	const getAstroImageIndex = () => {
+		if (!astroImageIndex && collectionDefinitions) {
+			astroImageIndex = buildAstroImageCollectionIndex(collectionDefinitions)
+		}
+		return astroImageIndex
+	}
+
 	// Process entries in parallel for better performance
 	const entryPromises = Object.entries(entries).map(async ([id, entry]) => {
 		// Handle image entries specially - find the line with src attribute
 		if (entry.imageMetadata?.src) {
+			// Astro `image()` URLs (`/_image?href=/@fs/.../src/content/<collection>/<...>`)
+			// embed the source path. If we can match that path to a collection entry's
+			// directory, treat this image as belonging to that entry — even when no
+			// ancestor was tagged as the collection wrapper (e.g. a `<Image>` rendered
+			// outside `<Content />`).
+			if (!entry.collectionName) {
+				const index = getAstroImageIndex()
+				const inferred = index && inferCollectionFromAstroImageUrl(entry.imageMetadata.src, index)
+				if (inferred) {
+					entry.collectionName = inferred.collectionName
+					entry.collectionSlug = inferred.collectionSlug
+				}
+			}
+
 			// ── Collection images: resolve directly from the data file ──
 			// When an image belongs to a known collection entry, bypass the search index
 			// entirely. Astro hashes image filenames (e.g. ./photo.jpg → /assets/a1b2c3.webp),
@@ -1148,14 +1173,15 @@ async function resolveCollectionImageField(
 
 	// Single image field — unambiguous
 	if (imageFields.length === 1) {
+		const fieldName = imageFields[0]!.name
 		const fieldResult = await findFieldInCollectionEntry(
-			imageFields[0]!.name,
+			fieldName,
 			entry.collectionName!,
 			entry.collectionSlug!,
 			collectionDefinitions,
 		)
 		if (fieldResult) {
-			return applyCollectionSource(entry, fieldResult, referenceIndex)
+			return applyCollectionSource(entry, fieldResult, referenceIndex, { collectionFieldName: fieldName })
 		}
 		return undefined
 	}
@@ -1169,12 +1195,12 @@ async function resolveCollectionImageField(
 		collectionDefinitions,
 	)
 
-	let firstFieldResult: SourceLocation | undefined
+	let firstField: { name: string; result: SourceLocation } | undefined
 	for (const field of imageFields) {
 		const fieldResult = allResults.get(field.name)
 		if (!fieldResult?.snippet) continue
 
-		firstFieldResult ??= fieldResult
+		firstField ??= { name: field.name, result: fieldResult }
 
 		try {
 			const cleaned = fieldResult.snippet.replace(/,\s*$/, '')
@@ -1182,7 +1208,7 @@ async function resolveCollectionImageField(
 			if (parsed && typeof parsed === 'object') {
 				const value = (parsed as Record<string, unknown>)[field.name]
 				if (typeof value === 'string' && (value === imgSrc || imgSrc.includes(value) || value.includes(imgSrc))) {
-					return applyCollectionSource(entry, fieldResult, referenceIndex)
+					return applyCollectionSource(entry, fieldResult, referenceIndex, { collectionFieldName: field.name })
 				}
 			}
 		} catch {
@@ -1191,8 +1217,8 @@ async function resolveCollectionImageField(
 	}
 
 	// No value match — fall back to first resolved image field
-	if (firstFieldResult) {
-		return applyCollectionSource(entry, firstFieldResult, referenceIndex)
+	if (firstField) {
+		return applyCollectionSource(entry, firstField.result, referenceIndex, { collectionFieldName: firstField.name })
 	}
 
 	return undefined
@@ -1400,6 +1426,78 @@ async function resolveImageExpression(
 	return undefined
 }
 
+/**
+ * Per-call index over collection entries with at least one `astroImage` field.
+ * Built once per `enhanceEntries` invocation so each manifest entry's lookup is O(1)
+ * for flat entries and O(hugoEntries) for hugo-style.
+ */
+export interface AstroImageCollectionIndex {
+	/** Flat-md entries grouped by their parent directory (lookup by `path.dirname(href)`). */
+	flatByDir: Map<string, Array<{ slug: string; coll: string }>>
+	/** Hugo-style entries — image lives under entry directory, identified by prefix match. */
+	hugoEntries: Array<{ dir: string; slug: string; coll: string }>
+}
+
+export function buildAstroImageCollectionIndex(
+	collectionDefinitions: Record<string, CollectionDefinition>,
+): AstroImageCollectionIndex {
+	const flatByDir = new Map<string, Array<{ slug: string; coll: string }>>()
+	const hugoEntries: Array<{ dir: string; slug: string; coll: string }> = []
+	for (const def of Object.values(collectionDefinitions)) {
+		if (!def.entries || !def.fields.some(f => f.astroImage)) continue
+		for (const entry of def.entries) {
+			const entryAbs = resolveSourcePath(entry.sourcePath)
+			const entryDir = path.dirname(entryAbs)
+			if (isHugoStyleEntry(entryAbs)) {
+				hugoEntries.push({ dir: entryDir, slug: entry.slug, coll: def.name })
+			} else {
+				let list = flatByDir.get(entryDir)
+				if (!list) {
+					list = []
+					flatByDir.set(entryDir, list)
+				}
+				list.push({ slug: entry.slug, coll: def.name })
+			}
+		}
+	}
+	return { flatByDir, hugoEntries }
+}
+
+/**
+ * Match an Astro dev image URL (`/_image?href=/@fs/...`) to a collection entry by
+ * locating the `href` source path under that entry's directory. Used when an
+ * `<Image>` is rendered outside `<Content />` and so doesn't inherit collection
+ * info from the markdown wrapper.
+ */
+export function inferCollectionFromAstroImageUrl(
+	src: string,
+	index: AstroImageCollectionIndex,
+): { collectionName: string; collectionSlug: string } | undefined {
+	const href = extractAstroImageOriginalUrl(src)
+	if (!href) return undefined
+
+	// `/@fs/<absolute-path>` → strip the prefix to get the real filesystem path.
+	let absHref = href
+	if (absHref.startsWith('/@fs/')) absHref = absHref.slice('/@fs'.length)
+	try {
+		absHref = decodeURIComponent(absHref)
+	} catch {
+		// Already decoded
+	}
+
+	const flatList = index.flatByDir.get(path.dirname(absHref))
+	if (flatList) {
+		const hrefBase = path.basename(absHref)
+		for (const { slug, coll } of flatList) {
+			if (hrefBase.startsWith(`${slug}-`)) return { collectionName: coll, collectionSlug: slug }
+		}
+	}
+	for (const { dir, slug, coll } of index.hugoEntries) {
+		if (absHref.startsWith(dir + path.sep)) return { collectionName: coll, collectionSlug: slug }
+	}
+	return undefined
+}
+
 /**
  * Extract the original image path from an Astro Image optimization URL.
  * Astro's `<Image>` component rewrites src to `/_image?href=%2Fpath.jpg&w=...` in dev.

package/src/types.ts

@@ -72,6 +72,13 @@ export interface ImageMetadata {
 	sizes?: string
 }
 
+/** Identifies the (collection, entry, field) destination for an editor upload. */
+export interface MediaUploadContext {
+	collection: string
+	entry: string
+	field: string
+}
+
 /** Content constraints for validation */
 export interface ContentConstraints {
 	/** Maximum content length */
@@ -158,6 +165,8 @@ export interface ManifestEntry {
 	collectionName?: string
 	/** Entry slug for collection entries (e.g., '3d-tisk') */
 	collectionSlug?: string
+	/** Schema field name when this entry was resolved to a specific collection field (e.g., 'image', 'cover'). */
+	collectionFieldName?: string
 	/** Path to the markdown content file (e.g., 'src/content/blog/my-post.md') */
 	contentPath?: string
 
@@ -285,6 +294,8 @@ export interface FieldDefinition {
 	derivedFrom?: string
 	/** Editor hints for enhanced field rendering */
 	hints?: FieldHints
+	/** True when the field uses Astro's `image()` schema (entry-relative paths through astro:assets). */
+	astroImage?: boolean
 }
 
 /** Per-entry metadata for collection browsing */