@growth-labs/cms 0.3.0 → 0.4.0

package/src/migration-vendor.ts

@@ -0,0 +1,450 @@
+import {
+	link,
+	lstat,
+	readdir,
+	readFile,
+	realpath,
+	rename,
+	unlink,
+	writeFile,
+} from 'node:fs/promises'
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+	commitStagedMigrationBatch,
+	type StagedMigrationVendorFile,
+} from './migration-vendor-files.js'
+
+const PACKAGE_NAME = '@growth-labs/cms'
+const MANIFEST_NAME = '.growth-labs-cms-migrations.json'
+const MANIFEST_SCHEMA_VERSION = 1
+const MIGRATION_FILE = /^\d{4}_[a-z0-9][a-z0-9_-]*\.sql$/
+
+interface PackageJson {
+	name?: string
+	version?: string
+}
+
+interface PlannedMigration {
+	source: string
+	target: string
+	sequence: number
+	sha256: string
+	bytes: Uint8Array
+}
+
+interface CmsMigrationManifestEntry {
+	source: string
+	target: string
+	sha256: string
+}
+
+interface CmsMigrationManifest {
+	schemaVersion: 1
+	packageName: typeof PACKAGE_NAME
+	packageVersion: string
+	startSequence: number
+	files: CmsMigrationManifestEntry[]
+}
+
+export interface SyncCmsMigrationsOptions {
+	/** Existing consumer-owned Wrangler migrations directory. */
+	migrationsDir: string
+	/** First unused sequence number reserved for the package migrations. */
+	startSequence: number
+	/** Override only when a consumer keeps the receipt outside migrationsDir. */
+	manifestPath?: string
+}
+
+export interface VerifyCmsMigrationsOptions {
+	migrationsDir: string
+	manifestPath?: string
+}
+
+export interface CmsMigrationVendorResult {
+	packageName: typeof PACKAGE_NAME
+	packageVersion: string
+	startSequence: number
+	managedFiles: string[]
+	written: number
+	verified: number
+	manifestPath: string
+}
+
+interface PackageContract {
+	packageVersion: string
+	sourceDir: string
+}
+
+async function packageContract(): Promise<PackageContract> {
+	const packageRoot = fileURLToPath(new URL('..', import.meta.url))
+	const packageJsonPath = join(packageRoot, 'package.json')
+	const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf8')) as PackageJson
+	if (packageJson.name !== PACKAGE_NAME || !packageJson.version) {
+		throw new Error('installed CMS package metadata is invalid')
+	}
+	return {
+		packageVersion: packageJson.version,
+		sourceDir: join(packageRoot, 'migrations'),
+	}
+}
+
+async function sha256(bytes: Uint8Array): Promise<string> {
+	const input = new Uint8Array(bytes.byteLength)
+	input.set(bytes)
+	const digest = await crypto.subtle.digest('SHA-256', input.buffer)
+	return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+
+async function requireExistingDirectory(path: string, label = 'migrationsDir'): Promise<string> {
+	let stat: Awaited<ReturnType<typeof lstat>>
+	try {
+		stat = await lstat(path)
+	} catch {
+		throw new Error(`${label} must be an existing directory: ${path}`)
+	}
+	if (!stat.isDirectory() || stat.isSymbolicLink()) {
+		throw new Error(`${label} must be an existing non-symlink directory: ${path}`)
+	}
+	return realpath(path)
+}
+
+function assertStartSequence(value: number): void {
+	if (!Number.isSafeInteger(value) || value < 1) {
+		throw new Error('startSequence must be a positive integer')
+	}
+}
+
+function sequencePrefix(sequence: number): string {
+	return String(sequence).padStart(4, '0')
+}
+
+async function planMigrations(
+	sourceDir: string,
+	startSequence: number,
+): Promise<PlannedMigration[]> {
+	assertStartSequence(startSequence)
+	const sourceNames = (await readdir(sourceDir)).filter((name) => MIGRATION_FILE.test(name)).sort()
+	if (sourceNames.length === 0) throw new Error('installed CMS package has no migration SQL')
+	if (startSequence + sourceNames.length - 1 > 9999) {
+		throw new Error('reserved CMS migration sequence exceeds 9999')
+	}
+
+	return Promise.all(
+		sourceNames.map(async (source, index) => {
+			const sequence = startSequence + index
+			const suffix = source.replace(/^\d{4}_/, '')
+			const target = `${sequencePrefix(sequence)}_growth_labs_cms_${suffix}`
+			const bytes = new Uint8Array(await readFile(join(sourceDir, source)))
+			return { source, target, sequence, sha256: await sha256(bytes), bytes }
+		}),
+	)
+}
+
+function manifestFor(
+	packageVersion: string,
+	startSequence: number,
+	plan: PlannedMigration[],
+): CmsMigrationManifest {
+	return {
+		schemaVersion: MANIFEST_SCHEMA_VERSION,
+		packageName: PACKAGE_NAME,
+		packageVersion,
+		startSequence,
+		files: plan.map(({ source, target, sha256: hash }) => ({ source, target, sha256: hash })),
+	}
+}
+
+async function readManifest(path: string): Promise<CmsMigrationManifest | null> {
+	try {
+		const stat = await lstat(path)
+		if (!stat.isFile() || stat.isSymbolicLink()) {
+			throw new Error(`CMS migration manifest must be a regular file: ${path}`)
+		}
+		const parsed = JSON.parse(await readFile(path, 'utf8')) as Partial<CmsMigrationManifest>
+		if (
+			parsed.schemaVersion !== MANIFEST_SCHEMA_VERSION ||
+			parsed.packageName !== PACKAGE_NAME ||
+			!parsed.packageVersion ||
+			!Number.isSafeInteger(parsed.startSequence) ||
+			(parsed.startSequence as number) < 1 ||
+			!Array.isArray(parsed.files)
+		) {
+			throw new Error(`CMS migration manifest is invalid: ${path}`)
+		}
+		for (const entry of parsed.files) {
+			if (
+				!entry ||
+				typeof entry.source !== 'string' ||
+				typeof entry.target !== 'string' ||
+				!MIGRATION_FILE.test(entry.source) ||
+				!MIGRATION_FILE.test(entry.target) ||
+				!/^([a-f0-9]{64})$/.test(entry.sha256)
+			) {
+				throw new Error(`CMS migration manifest contains an invalid file entry: ${path}`)
+			}
+		}
+		return parsed as CmsMigrationManifest
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
+		throw error
+	}
+}
+
+function entriesEqual(left: CmsMigrationManifestEntry, right: CmsMigrationManifestEntry): boolean {
+	return (
+		left.source === right.source && left.target === right.target && left.sha256 === right.sha256
+	)
+}
+
+function assertManifestCanAdvance(
+	current: CmsMigrationManifest | null,
+	next: CmsMigrationManifest,
+): void {
+	if (!current) return
+	if (current.startSequence !== next.startSequence) {
+		throw new Error(
+			`CMS migration manifest reserves startSequence ${current.startSequence}; received ${next.startSequence}`,
+		)
+	}
+	if (current.files.length > next.files.length) {
+		throw new Error('installed CMS package removed migrations recorded by the consumer manifest')
+	}
+	for (const [index, entry] of current.files.entries()) {
+		const nextEntry = next.files[index]
+		if (!nextEntry || !entriesEqual(entry, nextEntry)) {
+			throw new Error(`installed CMS migration changed after vendoring: ${entry.source}`)
+		}
+	}
+}
+
+async function assertNoSequenceCollisions(
+	migrationsDir: string,
+	plan: PlannedMigration[],
+): Promise<void> {
+	const existing = await readdir(migrationsDir)
+	for (const migration of plan) {
+		const prefix = `${sequencePrefix(migration.sequence)}_`
+		const collisions = existing.filter(
+			(name) => name.endsWith('.sql') && name.startsWith(prefix) && name !== migration.target,
+		)
+		if (collisions.length > 0) {
+			throw new Error(
+				`reserved sequence ${sequencePrefix(migration.sequence)} collides with ${collisions.join(', ')}`,
+			)
+		}
+	}
+}
+
+async function verifyTargets(
+	migrationsDir: string,
+	plan: PlannedMigration[],
+	allowMissing: boolean,
+): Promise<{ verified: number; missing: PlannedMigration[] }> {
+	let verified = 0
+	const missing: PlannedMigration[] = []
+	for (const migration of plan) {
+		const targetPath = join(migrationsDir, migration.target)
+		try {
+			const stat = await lstat(targetPath)
+			if (!stat.isFile() || stat.isSymbolicLink()) {
+				throw new Error(`managed CMS migration must be a regular file: ${migration.target}`)
+			}
+			const targetHash = await sha256(new Uint8Array(await readFile(targetPath)))
+			if (targetHash !== migration.sha256) {
+				throw new Error(`CMS migration hash mismatch: ${migration.target}`)
+			}
+			verified += 1
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === 'ENOENT' && allowMissing) {
+				missing.push(migration)
+				continue
+			}
+			throw error
+		}
+	}
+	return { verified, missing }
+}
+
+async function stageNewFile(path: string, bytes: Uint8Array): Promise<string> {
+	const temp = `${path}.tmp-${crypto.randomUUID()}`
+	await writeFile(temp, bytes, { flag: 'wx' })
+	return temp
+}
+
+async function stageManifest(path: string, manifest: CmsMigrationManifest): Promise<string> {
+	const temp = `${path}.tmp-${crypto.randomUUID()}`
+	await writeFile(temp, `${JSON.stringify(manifest, null, 2)}\n`, { flag: 'wx' })
+	return temp
+}
+
+async function commitManifest(
+	tempPath: string,
+	manifestPath: string,
+	currentManifest: CmsMigrationManifest | null,
+): Promise<void> {
+	if (currentManifest) {
+		const latest = await readManifest(manifestPath)
+		if (!latest || JSON.stringify(latest) !== JSON.stringify(currentManifest)) {
+			throw new Error('CMS migration manifest changed during sync')
+		}
+		await rename(tempPath, manifestPath)
+		return
+	}
+	await link(tempPath, manifestPath)
+}
+
+function isInsideDirectory(directory: string, path: string): boolean {
+	const fromDirectory = relative(directory, path)
+	return (
+		fromDirectory === '' ||
+		(!fromDirectory.startsWith(`..${sep}`) && fromDirectory !== '..' && !isAbsolute(fromDirectory))
+	)
+}
+
+async function resolveManifestPath(migrationsDir: string, override?: string): Promise<string> {
+	if (!override) return join(migrationsDir, MANIFEST_NAME)
+	const requested = resolve(override)
+	if (extname(requested).toLowerCase() !== '.json') {
+		throw new Error('CMS migration manifest override must be a .json file')
+	}
+	if (isInsideDirectory(migrationsDir, requested)) {
+		throw new Error('CMS migration manifest override must be outside migrationsDir')
+	}
+	const parent = await requireExistingDirectory(dirname(requested), 'manifest parent')
+	const resolvedPath = join(parent, basename(requested))
+	if (isInsideDirectory(migrationsDir, resolvedPath)) {
+		throw new Error('CMS migration manifest override must be outside migrationsDir')
+	}
+	return resolvedPath
+}
+
+async function withManifestLock<T>(manifestPath: string, action: () => Promise<T>): Promise<T> {
+	const lockPath = `${manifestPath}.lock`
+	try {
+		await writeFile(lockPath, `${JSON.stringify({ pid: process.pid, startedAt: Date.now() })}\n`, {
+			flag: 'wx',
+			mode: 0o600,
+		})
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+			throw new Error(`another CMS migration operation is already active: ${lockPath}`)
+		}
+		throw error
+	}
+
+	let result: T | undefined
+	let operationError: unknown
+	try {
+		result = await action()
+	} catch (error) {
+		operationError = error
+	}
+	let releaseError: unknown
+	try {
+		await unlink(lockPath)
+	} catch (error) {
+		releaseError = error
+	}
+	if (operationError && releaseError) {
+		throw new AggregateError(
+			[operationError, releaseError],
+			'CMS migration operation failed and its receipt lock could not be released',
+		)
+	}
+	if (operationError) throw operationError
+	if (releaseError) throw releaseError
+	return result as T
+}
+
+export async function syncCmsMigrations(
+	options: SyncCmsMigrationsOptions,
+): Promise<CmsMigrationVendorResult> {
+	assertStartSequence(options.startSequence)
+	const migrationsDir = await requireExistingDirectory(resolve(options.migrationsDir))
+	const manifestPath = await resolveManifestPath(migrationsDir, options.manifestPath)
+	return withManifestLock(manifestPath, async () => {
+		const contract = await packageContract()
+		const plan = await planMigrations(contract.sourceDir, options.startSequence)
+		const nextManifest = manifestFor(contract.packageVersion, options.startSequence, plan)
+		const currentManifest = await readManifest(manifestPath)
+		assertManifestCanAdvance(currentManifest, nextManifest)
+		await assertNoSequenceCollisions(migrationsDir, plan)
+		const preflight = await verifyTargets(migrationsDir, plan, true)
+		const staged: StagedMigrationVendorFile[] = []
+		let manifestTemp: string | null = null
+		let verified = 0
+
+		try {
+			for (const migration of preflight.missing) {
+				const targetPath = join(migrationsDir, migration.target)
+				staged.push({
+					targetPath,
+					tempPath: await stageNewFile(targetPath, migration.bytes),
+				})
+			}
+			const stagedManifest = await stageManifest(manifestPath, nextManifest)
+			manifestTemp = stagedManifest
+			await commitStagedMigrationBatch(staged, async () => {
+				await assertNoSequenceCollisions(migrationsDir, plan)
+				const final = await verifyTargets(migrationsDir, plan, false)
+				verified = final.verified
+				await commitManifest(stagedManifest, manifestPath, currentManifest)
+			})
+
+			return {
+				packageName: PACKAGE_NAME,
+				packageVersion: contract.packageVersion,
+				startSequence: options.startSequence,
+				managedFiles: plan.map(({ target }) => target),
+				written: preflight.missing.length,
+				verified,
+				manifestPath,
+			}
+		} finally {
+			await Promise.all([
+				...staged.map(({ tempPath }) => unlink(tempPath).catch(() => {})),
+				...(manifestTemp ? [unlink(manifestTemp).catch(() => {})] : []),
+			])
+		}
+	})
+}
+
+export async function verifyCmsMigrations(
+	options: VerifyCmsMigrationsOptions,
+): Promise<CmsMigrationVendorResult> {
+	const migrationsDir = await requireExistingDirectory(resolve(options.migrationsDir))
+	const manifestPath = await resolveManifestPath(migrationsDir, options.manifestPath)
+	return withManifestLock(manifestPath, async () => {
+		const manifest = await readManifest(manifestPath)
+		if (!manifest) throw new Error(`CMS migration manifest is missing: ${manifestPath}`)
+		const contract = await packageContract()
+		if (manifest.packageVersion !== contract.packageVersion) {
+			throw new Error(
+				`CMS migration manifest version ${manifest.packageVersion} does not match installed ${contract.packageVersion}`,
+			)
+		}
+		const plan = await planMigrations(contract.sourceDir, manifest.startSequence)
+		const expected = manifestFor(contract.packageVersion, manifest.startSequence, plan)
+		if (
+			expected.files.length !== manifest.files.length ||
+			expected.files.some(
+				(entry, index) => !entriesEqual(entry, manifest.files[index] as CmsMigrationManifestEntry),
+			)
+		) {
+			throw new Error('CMS migration manifest does not match the installed package contract')
+		}
+		await assertNoSequenceCollisions(migrationsDir, plan)
+		const result = await verifyTargets(migrationsDir, plan, false)
+
+		return {
+			packageName: PACKAGE_NAME,
+			packageVersion: contract.packageVersion,
+			startSequence: manifest.startSequence,
+			managedFiles: plan.map(({ target }) => target),
+			written: 0,
+			verified: result.verified,
+			manifestPath,
+		}
+	})
+}

package/src/schema/migrations.ts

@@ -778,6 +778,30 @@ CREATE INDEX idx_cms_reader_state_export
   ON cms_reader_state(identity_user_id, site_id, created_at DESC, content_type, content_id);
 CREATE INDEX idx_cms_reader_state_saved
   ON cms_reader_state(identity_user_id, site_id, saved, updated_at DESC);
+`,
+	},
+	{
+		id: '0020_content_metadata_read_model',
+		sql: `
+ALTER TABLE content_items
+  ADD COLUMN metadata_json TEXT NOT NULL DEFAULT '{}';
+ALTER TABLE content_items
+  ADD COLUMN source_id TEXT;
+CREATE UNIQUE INDEX idx_content_items_source_id_unique
+  ON content_items(source_id)
+  WHERE source_id IS NOT NULL;
+ALTER TABLE content_publication_attempts
+  ADD COLUMN target_published_at INTEGER;
+UPDATE content_publication_attempts
+SET target_published_at = created_at
+WHERE operation = 'publish' AND target_published_at IS NULL;
+`,
+	},
+	{
+		id: '0021_published_revision_slug_index',
+		sql: `
+CREATE INDEX IF NOT EXISTS idx_content_revisions_published_slug
+  ON content_revisions(json_extract(payload_json, '$.item.slug'));
 `,
 	},
 ]

package/src/schema/types.ts

@@ -70,6 +70,10 @@ export interface ContentItemRow {
 	seo_focus_keyword: string | null
 	/** AI-generated OG image asset id (migration 0004). */
 	ai_og_image_id: string | null
+	/** Bounded JSON object for declared site-specific presentation metadata (migration 0020). */
+	metadata_json: string
+	/** Optional namespaced source key used for idempotent archive imports (migration 0020). */
+	source_id: string | null
 }
 
 /** Standalone topic taxonomy row. Counts are derived from content_items.primary_topic. */
@@ -555,6 +559,8 @@ export interface ContentPublicationAttemptRow {
 	content_id: string
 	revision_id: string
 	previous_revision_id: string | null
+	/** Explicit historical publication timestamp for crash-safe publish retries. */
+	target_published_at: number | null
 	state: ContentPublicationAttemptState
 	surface_names_json: string
 	pending_surface_names_json: string