@growth-labs/cms 0.3.0 → 0.4.0

package/src/engine/publisher.ts

@@ -20,6 +20,7 @@
 // duplicate is NOT re-queued to Foundry. Any future `content_items` column
 // addition requires a matching edit here or the duplicate silently drops it.
 import type { ContentType } from '../schema/types.js'
+import { type ContentMetadata, serializeContentMetadata } from './content-metadata.js'
 import type { D1Database } from './d1.js'
 import { evaluateArticleBody, type PublishGuardOutcome } from './publish-guard.js'
 import { slugify } from './slug.js'
@@ -95,6 +96,8 @@ export interface BaseContentInput {
 	tags?: string[]
 	/** The SEO focus keyword for this content item (migration 0004 column). */
 	seoFocusKeyword?: string | null
+	/** Declared site-specific JSON values retained in every immutable revision. */
+	metadata?: ContentMetadata
 }
 
 export interface ArticleInput extends BaseContentInput {
@@ -154,12 +157,23 @@ export interface PageInput extends BaseContentInput {
 	}
 }
 
-export type CreateContentInput =
+export type CreateContentInput = (
 	| ArticleInput
 	| VideoInput
 	| PodcastInput
 	| NewsletterInput
 	| PageInput
+) & {
+	/** Optional namespaced archive key. New copies deliberately do not inherit it. */
+	sourceId?: string | null
+	/** Initial historical values for archive ingestion; normal creates omit this. */
+	initialTimestamps?: {
+		publishedAt?: number | null
+		createdAt?: number | null
+		updatedAt?: number | null
+		publishTz?: string | null
+	}
+}
 
 type BodyBackedContentInput = ArticleInput | NewsletterInput | PageInput
 
@@ -215,10 +229,57 @@ export interface ContentItemRecord {
 	ai_locked_fields: string | null
 	published_revision_id: string | null
 	seo_focus_keyword: string | null
+	metadata_json: string
+	source_id: string | null
 	created_at: number | null
 	updated_at: number | null
 }
 
+function normalizeSourceId(value: unknown): string | null {
+	if (value === null || value === undefined) return null
+	if (typeof value !== 'string' || !value || value !== value.trim() || value.length > 256) {
+		throw new TypeError('sourceId must be a trimmed non-empty string of at most 256 characters')
+	}
+	return value
+}
+
+function normalizeInitialTimestamps(value: CreateContentInput['initialTimestamps']): {
+	publishedAt: number | null
+	createdAt: number | null
+	updatedAt: number | null
+	publishTz: string | null
+} {
+	const timestamps = value ?? {}
+	for (const [field, candidate] of [
+		['publishedAt', timestamps.publishedAt],
+		['createdAt', timestamps.createdAt],
+		['updatedAt', timestamps.updatedAt],
+	] as const) {
+		if (candidate !== null && candidate !== undefined) {
+			if (!Number.isSafeInteger(candidate) || candidate < 0) {
+				throw new TypeError(`${field} must be a non-negative epoch second`)
+			}
+		}
+	}
+	const publishTz = timestamps.publishTz
+	if (
+		publishTz !== null &&
+		publishTz !== undefined &&
+		(typeof publishTz !== 'string' ||
+			!publishTz.trim() ||
+			publishTz !== publishTz.trim() ||
+			publishTz.length > 64)
+	) {
+		throw new TypeError('publishTz must be a trimmed non-empty string of at most 64 characters')
+	}
+	return {
+		publishedAt: timestamps.publishedAt ?? null,
+		createdAt: timestamps.createdAt ?? null,
+		updatedAt: timestamps.updatedAt ?? null,
+		publishTz: publishTz ?? null,
+	}
+}
+
 export async function ensureUniqueSlug(
 	db: D1Database,
 	slug: string,
@@ -229,12 +290,28 @@ export async function ensureUniqueSlug(
 	let suffix = 2
 
 	while (true) {
-		const row = await db
+		const draftRow = await db
 			.prepare('SELECT id FROM content_items WHERE slug = ? LIMIT 1')
 			.bind(candidate)
 			.first<{ id: string }>()
+		const publishedRow = await db
+			.prepare(
+				`SELECT ci.id
+				 FROM content_items ci
+				 JOIN content_revisions cr
+				   ON cr.id = ci.published_revision_id AND cr.content_id = ci.id
+				 WHERE ci.status = 'published'
+				   AND ci.deleted_at IS NULL
+				   AND json_extract(cr.payload_json, '$.item.slug') = ?
+				 LIMIT 1`,
+			)
+			.bind(candidate)
+			.first<{ id: string }>()
 
-		if (!row || (excludeId && row.id === excludeId)) {
+		const draftAvailable = !draftRow || (excludeId !== undefined && draftRow.id === excludeId)
+		const publishedAvailable =
+			!publishedRow || (excludeId !== undefined && publishedRow.id === excludeId)
+		if (draftAvailable && publishedAvailable) {
 			return candidate
 		}
 
@@ -343,6 +420,9 @@ export async function createContent(
 	const slug = await ensureUniqueSlug(db, input.slug)
 	const visibility = input.visibility || 'free'
 	const primaryCategory = input.primaryCategory || 'analysis'
+	const metadataJson = serializeContentMetadata(input.metadata)
+	const sourceId = normalizeSourceId(input.sourceId)
+	const initialTimestamps = normalizeInitialTimestamps(input.initialTimestamps)
 
 	await db
 		.prepare(
@@ -350,8 +430,10 @@ export async function createContent(
       INSERT INTO content_items (
         id, type, status, visibility, slug, title, seo_title, description, excerpt,
         byline, channel, primary_topic, featured, author_id, hero_image_id,
-        hero_image_alt, hero_image_caption, social_image_id, canonical_url
-      ) VALUES (?, ?, 'draft', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        hero_image_alt, hero_image_caption, social_image_id, canonical_url,
+        metadata_json, source_id, published_at, created_at, updated_at, publish_tz
+      ) VALUES (?, ?, 'draft', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?,
+                COALESCE(?, unixepoch()), COALESCE(?, unixepoch()), COALESCE(?, 'Europe/Paris'))
       `,
 		)
 		.bind(
@@ -373,6 +455,12 @@ export async function createContent(
 			input.heroImageCaption || null,
 			input.socialImageId || null,
 			input.canonicalUrl || null,
+			metadataJson,
+			sourceId,
+			initialTimestamps.publishedAt,
+			initialTimestamps.createdAt,
+			initialTimestamps.updatedAt,
+			initialTimestamps.publishTz,
 		)
 		.run()
 
@@ -505,6 +593,9 @@ export async function updateContentItem(
 	const seoFocusKeyword = hasOwn(input, 'seoFocusKeyword')
 		? (input.seoFocusKeyword ?? null)
 		: (existing.seo_focus_keyword ?? null)
+	const metadataJson = hasOwn(input, 'metadata')
+		? serializeContentMetadata(input.metadata)
+		: existing.metadata_json
 
 	await db
 		.prepare(
@@ -528,6 +619,7 @@ export async function updateContentItem(
         canonical_url = ?,
         ai_locked_fields = ?,
         seo_focus_keyword = ?,
+		metadata_json = ?,
         updated_at = unixepoch()
       WHERE id = ?
       `,
@@ -551,6 +643,7 @@ export async function updateContentItem(
 			canonicalUrl,
 			aiLockedFields,
 			seoFocusKeyword,
+			metadataJson,
 			id,
 		)
 		.run()
@@ -915,7 +1008,8 @@ export async function duplicateContentItem(
 	// DEFAULT (unixepoch()) timestamps; status forced to 'draft', featured to
 	// 0, publish_at/published_at/published_revision_id to NULL. (inventory §6)
 	//
-	// SEO carries over (seo_title, seo_focus_keyword, seo_score, ai_og_image_id)
+	// SEO and declared metadata carry over (seo_title, seo_focus_keyword,
+	// seo_score, ai_og_image_id, metadata_json)
 	// — a duplicate should keep the SEO work already done on the source. But
 	// board_position is the source item's slot in the editorial board ordering;
 	// a fresh draft copy must NOT inherit it, so it is reset to NULL.
@@ -927,7 +1021,8 @@ export async function duplicateContentItem(
 				hero_image_id, hero_image_alt, hero_image_caption, social_image_id,
 				canonical_url, publish_at, published_at,
 				publish_tz, ai_locked_fields, published_revision_id,
-				seo_focus_keyword, seo_score, ai_og_image_id, board_position
+				seo_focus_keyword, seo_score, ai_og_image_id, board_position,
+				metadata_json
 			)
 			SELECT
 				?, type, 'draft', visibility, ?, title || ' (Copy)', seo_title, description, excerpt,
@@ -935,7 +1030,8 @@ export async function duplicateContentItem(
 				hero_image_id, hero_image_alt, hero_image_caption, social_image_id,
 				canonical_url, NULL, NULL,
 				publish_tz, ai_locked_fields, NULL,
-				seo_focus_keyword, seo_score, ai_og_image_id, NULL
+				seo_focus_keyword, seo_score, ai_og_image_id, NULL,
+				metadata_json
 			FROM content_items
 			WHERE id = ?`,
 		)
@@ -1047,14 +1143,14 @@ export async function getContentSnapshot(
 
 	const tags = await db
 		.prepare(
-			'SELECT t.slug FROM content_tag_links l JOIN content_tags t ON t.id = l.tag_id WHERE l.content_id = ?',
+			'SELECT t.slug FROM content_tag_links l JOIN content_tags t ON t.id = l.tag_id WHERE l.content_id = ? ORDER BY t.slug ASC',
 		)
 		.bind(contentId)
 		.all<{ slug: string }>()
 
 	const related = await db
 		.prepare(
-			'SELECT related_id, rank, reason FROM content_relations WHERE content_id = ? ORDER BY rank ASC',
+			'SELECT related_id, rank, reason FROM content_relations WHERE content_id = ? ORDER BY rank ASC, related_id ASC',
 		)
 		.bind(contentId)
 		.all<{ related_id: string; rank: number; reason: string | null }>()

package/src/engine/revisions.ts

@@ -5,6 +5,7 @@
 // (words_added, words_removed, tag). Snapshot shape is formalized as
 // ContentRevisionPayload, aligned to getContentSnapshot's output.
 
+import { parseContentMetadata } from './content-metadata.js'
 import type { D1Database } from './d1.js'
 import { countWords, getContentItem, getContentSnapshot, updateContentItem } from './publisher.js'
 
@@ -233,6 +234,9 @@ export async function restoreRevision(
 		canonicalUrl: (item.canonical_url as string | null) ?? null,
 		// SEO focus keyword is part of the snapshot — restore it too.
 		seoFocusKeyword: (item.seo_focus_keyword as string | null) ?? null,
+		metadata: parseContentMetadata(
+			typeof item.metadata_json === 'string' ? item.metadata_json : '{}',
+		),
 		tags: target.payload.tags,
 		relations: target.payload.related.map((r) => ({
 			relatedId: r.related_id,

package/src/migration-vendor-files.ts

@@ -0,0 +1,100 @@
+import { link, unlink } from 'node:fs/promises'
+
+export interface StagedMigrationVendorFile {
+	tempPath: string
+	targetPath: string
+}
+
+export interface MigrationVendorFileOperations {
+	link(source: string, target: string): Promise<void>
+	unlink(path: string): Promise<void>
+}
+
+const DEFAULT_OPERATIONS: MigrationVendorFileOperations = { link, unlink }
+
+async function removePaths(
+	paths: string[],
+	operations: MigrationVendorFileOperations,
+): Promise<unknown[]> {
+	const errors: unknown[] = []
+	for (const path of [...paths].reverse()) {
+		try {
+			await operations.unlink(path)
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== 'ENOENT') errors.push(error)
+		}
+	}
+	return errors
+}
+
+export async function rollbackNewFiles(
+	paths: string[],
+	operations: MigrationVendorFileOperations = DEFAULT_OPERATIONS,
+): Promise<void> {
+	const errors = await removePaths(paths, operations)
+	if (errors.length > 0) {
+		throw new AggregateError(errors, 'failed to roll back newly linked CMS migration files')
+	}
+}
+
+/**
+ * Link every pre-staged file without replacing an existing directory entry.
+ * A later failure removes all targets linked by this attempt and every temp.
+ */
+export async function commitNewFilesAtomically(
+	files: StagedMigrationVendorFile[],
+	operations: MigrationVendorFileOperations = DEFAULT_OPERATIONS,
+): Promise<string[]> {
+	const committed: string[] = []
+	let failure: unknown
+
+	try {
+		for (const file of files) {
+			await operations.link(file.tempPath, file.targetPath)
+			committed.push(file.targetPath)
+		}
+	} catch (error) {
+		failure = error
+	}
+
+	const cleanupErrors = await removePaths(
+		files.map((file) => file.tempPath),
+		operations,
+	)
+	if (failure) {
+		const rollbackErrors = await removePaths(committed, operations)
+		const errors = [failure, ...cleanupErrors, ...rollbackErrors].filter(
+			(error): error is NonNullable<unknown> => error !== undefined,
+		)
+		const primary = failure instanceof Error ? `: ${failure.message}` : ''
+		throw new AggregateError(errors, `CMS migration file commit failed${primary}`)
+	}
+	// A hard-linked target remains valid when unlinking only its staged temp
+	// fails. The caller's outer finally retries temp cleanup; rolling targets
+	// back here would turn a harmless leftover temp into data loss.
+
+	return committed
+}
+
+/** Commit staged SQL, then run the receipt/final verification boundary. */
+export async function commitStagedMigrationBatch(
+	files: StagedMigrationVendorFile[],
+	finalize: () => Promise<void>,
+	operations: MigrationVendorFileOperations = DEFAULT_OPERATIONS,
+): Promise<string[]> {
+	const committed = await commitNewFilesAtomically(files, operations)
+	try {
+		await finalize()
+		return committed
+	} catch (error) {
+		try {
+			await rollbackNewFiles(committed, operations)
+		} catch (rollbackError) {
+			throw new AggregateError(
+				[error, rollbackError],
+				'CMS migration batch finalization failed and rollback was incomplete',
+			)
+		}
+		throw error
+	}
+}