emdash 1.3.0 → 1.4.0

package/src/database/types.ts

@@ -448,7 +448,7 @@ export interface CollectionTable {
 	date_field: string | null; // field slug (datetime) for the admin list Date column (NULL = default)
 	url_pattern: string | null; // URL pattern with {slug} placeholder (e.g. "/blog/{slug}")
 	routable: Generated<number>; // 0 or 1 — published entries require a slug when enabled
-	hidden: Generated<number>; // 0 or 1 — omit the auto-generated sidebar entry and dashboard quick action
+	hidden: Generated<number>; // 0 or 1 — omit the auto-generated sidebar entry, dashboard quick action, and dashboard Content card row
 	sort_order: number | null; // explicit admin sidebar position; NULL = alphabetical fallback
 	nav_group: string | null; // admin sidebar folder label; NULL = inline
 	comments_enabled: Generated<number>; // 0 or 1

package/src/emdash-runtime.ts

@@ -61,6 +61,7 @@ import {
 	MIGRATION_RACE_WAIT_MS,
 	MigrationFailedError,
 	MigrationLockHeldError,
+	MigrationRowLimitError,
 } from "./database/migrations/runner.js";
 import { AuditRepository } from "./database/repositories/audit.js";
 import { CommentRepository } from "./database/repositories/comment.js";
@@ -632,7 +633,7 @@ interface DbHolder {
 	 * through the migration advisory lock (#1744). Entries expire after
 	 * DB_INIT_FAILURE_BACKOFF_MS; a successful init clears them.
 	 */
-	failures: Map<string, { at: number; message: string }>;
+	failures: Map<string, { at: number; message: string; cause?: unknown }>;
 }
 const globalSymbolStore = globalThis as Record<symbol, unknown>;
 function getDbHolder(): DbHolder {
@@ -660,6 +661,24 @@ function getDbHolder(): DbHolder {
  */
 const DB_INIT_FAILURE_BACKOFF_MS = 30_000;
 
+/**
+ * The most content rows auto mode migrates inside a deployed Worker request.
+ * Datetime normalization (079) issues about one statement per row it changes,
+ * a paid Worker invocation stops at 10,000 subrequests and 30 s of CPU by
+ * default, and the migrations around it need some of that budget too.
+ */
+const WORKER_AUTO_MIGRATION_CONTENT_ROW_LIMIT = 5_000;
+
+/** Local development enforces no Worker limits, and Node has none. */
+function autoMigrationContentRowLimit(): number | undefined {
+	if (import.meta.env.DEV) return undefined;
+	const onWorkers =
+		typeof navigator !== "undefined" &&
+		typeof navigator.userAgent === "string" &&
+		navigator.userAgent.includes("Cloudflare-Workers");
+	return onWorkers ? WORKER_AUTO_MIGRATION_CONTENT_ROW_LIMIT : undefined;
+}
+
 /**
  * Auto-seed runs at most once per isolate per database. Its lock + "done" set
  * live on globalThis (same bundler-duplication reasoning as the db cache) so a
@@ -2422,6 +2441,7 @@ export class EmDashRuntime {
 			if (Date.now() - failure.at < DB_INIT_FAILURE_BACKOFF_MS) {
 				throw new Error(
 					`Database initialization is backing off after a recent migration failure: ${failure.message}`,
+					{ cause: failure.cause },
 				);
 			}
 			// Expired — drop it so the map only ever holds active backoffs.
@@ -2442,18 +2462,25 @@ export class EmDashRuntime {
 				const db = new Kysely<Database>({ dialect, log: kyselyLogOption() });
 
 				try {
-					await enforceRuntimeMigrationPolicy(db, deps.migrationMode ?? "auto");
+					await enforceRuntimeMigrationPolicy(db, deps.migrationMode ?? "auto", {
+						contentRowLimit: autoMigrationContentRowLimit(),
+					});
 				} catch (error) {
-					// Only a failed migration run, or a lock its holder left behind,
-					// backs off. Waiting behind a slow concurrent migrator, pending
-					// migrations in check mode, and errors from the applied-migration
-					// check on an up-to-date database (a lost connection, an
-					// unavailable replica) stay retryable, so the next request tries
-					// again.
-					if (error instanceof MigrationFailedError || error instanceof MigrationLockHeldError) {
+					// Only a failed migration run, a lock its holder left behind, or
+					// content migrations too large for a request back off. Waiting
+					// behind a slow concurrent migrator, pending migrations in check
+					// mode, and errors from the applied-migration check on an
+					// up-to-date database (a lost connection, an unavailable replica)
+					// stay retryable, so the next request tries again.
+					if (
+						error instanceof MigrationFailedError ||
+						error instanceof MigrationLockHeldError ||
+						error instanceof MigrationRowLimitError
+					) {
 						holder.failures.set(cacheKey, {
 							at: Date.now(),
-							message: error instanceof Error ? error.message : String(error),
+							message: error.message,
+							cause: error,
 						});
 					}
 					// Every attempt builds a fresh dialect/pool; close it or each
@@ -6011,6 +6038,8 @@ export class EmDashRuntime {
 						: await normalizeMediaValue(value, getProvider);
 				if (normalized) {
 					result[field.slug] = normalized;
+				} else if (isBlankString(value)) {
+					result[field.slug] = null;
 				}
 			} catch {
 				// Don't fail the save if normalization fails for a single field
@@ -6038,6 +6067,8 @@ export class EmDashRuntime {
 							const normalized = await normalizeImageValue(subValue, getProvider);
 							if (normalized) {
 								normalizedItem[slug] = normalized;
+							} else if (isBlankString(subValue)) {
+								normalizedItem[slug] = null;
 							}
 						} catch {
 							// Don't fail the save if normalization fails for a single sub-field
@@ -6066,12 +6097,16 @@ export class EmDashRuntime {
 							const nestedValue = normalizedBlock[nestedField.slug];
 							if (nestedValue == null) continue;
 							try {
-								if (nestedField.type === "image") {
-									const normalized = await normalizeImageValue(nestedValue, getProvider);
-									if (normalized) normalizedBlock[nestedField.slug] = normalized;
-								} else if (nestedField.type === "file") {
-									const normalized = await normalizeMediaValue(nestedValue, getProvider);
-									if (normalized) normalizedBlock[nestedField.slug] = normalized;
+								if (nestedField.type === "image" || nestedField.type === "file") {
+									const normalized =
+										nestedField.type === "image"
+											? await normalizeImageValue(nestedValue, getProvider)
+											: await normalizeMediaValue(nestedValue, getProvider);
+									if (normalized) {
+										normalizedBlock[nestedField.slug] = normalized;
+									} else if (isBlankString(nestedValue)) {
+										normalizedBlock[nestedField.slug] = null;
+									}
 								} else if (nestedField.type === "repeater" && Array.isArray(nestedValue)) {
 									const imageSlugs = (nestedField.validation?.subFields ?? [])
 										.filter((subField) => subField.type === "image")
@@ -6086,7 +6121,11 @@ export class EmDashRuntime {
 														normalizedItem[slug],
 														getProvider,
 													);
-													if (normalized) normalizedItem[slug] = normalized;
+													if (normalized) {
+														normalizedItem[slug] = normalized;
+													} else if (isBlankString(normalizedItem[slug])) {
+														normalizedItem[slug] = null;
+													}
 												} catch {
 													continue;
 												}
@@ -6478,6 +6517,10 @@ export class EmDashRuntime {
 	}
 }
 
+function isBlankString(value: unknown): boolean {
+	return typeof value === "string" && value.trim() === "";
+}
+
 /**
  * Normalize an image field value together with its `darkVariant`. The media
  * normalizer only keeps the media item's own keys, so the variant is normalized

package/src/fields/image.ts

@@ -6,6 +6,7 @@ const mediaSchema = z.object({
 	id: z.string(),
 	src: z.string().optional(),
 	alt: z.string().optional(),
+	caption: z.string().optional(),
 	width: z.number().optional(),
 	height: z.number().optional(),
 	filename: z.string().optional(),

package/src/i18n/config.ts

@@ -8,6 +8,8 @@
 export interface I18nConfig {
 	defaultLocale: string;
 	locales: string[];
+	/** Astro locale codes mapped to their canonical content locale paths. */
+	localeAliases?: Record<string, string>;
 	fallback?: Record<string, string>;
 	prefixDefaultLocale?: boolean;
 }
@@ -36,13 +38,60 @@ export function getI18nConfig(): I18nConfig | null {
 	return configStore()[I18N_CONFIG_KEY] ?? null;
 }
 
-/** Match a locale to the exact casing used by the site configuration. */
-export function resolveConfiguredLocale(locale: string): string {
-	const config = getI18nConfig();
+/** Match a locale path or Astro code to the canonical content locale. */
+export function resolveConfiguredLocale(
+	locale: string,
+	config: I18nConfig | null = getI18nConfig(),
+): string {
+	const configured = config?.locales.find(
+		(candidate) => candidate.toLowerCase() === locale.toLowerCase(),
+	);
+	if (configured) return configured;
+
+	const aliased = Object.entries(config?.localeAliases ?? {}).find(
+		([code]) => code.toLowerCase() === locale.toLowerCase(),
+	)?.[1];
+	if (aliased === undefined) return locale;
+
 	return (
-		config?.locales.find((configured) => configured.toLowerCase() === locale.toLowerCase()) ??
-		locale
+		config?.locales.find((candidate) => candidate.toLowerCase() === aliased.toLowerCase()) ??
+		aliased
+	);
+}
+
+/** Stored locale spellings for one configured locale, in read-preference order. */
+export function getLocaleCandidates(locale: string): string[] {
+	const canonical = resolveConfiguredLocale(locale);
+	const candidates = [canonical];
+	const seen = new Set([canonical.toLowerCase()]);
+	for (const code of Object.keys(getI18nConfig()?.localeAliases ?? {})) {
+		if (resolveConfiguredLocale(code) === canonical && !seen.has(code.toLowerCase())) {
+			candidates.push(code);
+			seen.add(code.toLowerCase());
+		}
+	}
+	return candidates;
+}
+
+/** Rank a stored row's locale for a lookup by path or code. */
+export function getLocaleRank(stored: string, requested: string): number {
+	const candidates = getLocaleCandidates(requested);
+	const rank = candidates.findIndex(
+		(candidate) => candidate.toLowerCase() === stored.toLowerCase(),
 	);
+	return rank === -1 ? candidates.length : rank;
+}
+
+/** Rank stored locale variants before moving to the next fallback locale. */
+export function getLocaleChainRank(stored: string, chain: readonly string[]): number {
+	let offset = 0;
+	for (const locale of chain) {
+		const candidates = getLocaleCandidates(locale);
+		const rank = getLocaleRank(stored, locale);
+		if (rank < candidates.length) return offset + rank;
+		offset += candidates.length;
+	}
+	return offset;
 }
 
 /** Whether a string matches the locale-code subset accepted by EmDash. */
@@ -59,10 +108,8 @@ export function resolveContentCreateLocale(
 		if (typeof locale !== "string") {
 			throw new Error("Invalid locale code: expected a string");
 		}
-		const configured = config?.locales.find(
-			(candidate) => candidate.toLowerCase() === locale.toLowerCase(),
-		);
-		if (configured) return configured;
+		const configured = resolveConfiguredLocale(locale, config);
+		if (config?.locales.includes(configured)) return configured;
 		if (!isValidLocaleCode(locale)) {
 			throw new Error(`Invalid locale code: "${locale}"`);
 		}
@@ -93,13 +140,14 @@ export function getFallbackChain(locale: string): string[] {
 	const config = getI18nConfig();
 	if (!config) return [locale];
 
+	locale = resolveConfiguredLocale(locale, config);
 	const chain: string[] = [locale];
 	let current = locale;
 	const visited = new Set<string>([locale]);
 
 	while (config.fallback?.[current]) {
 		// eslint-disable-next-line typescript/no-unnecessary-type-assertion -- noUncheckedIndexedAccess
-		const next = config.fallback[current]!;
+		const next = resolveConfiguredLocale(config.fallback[current]!, config);
 		if (visited.has(next)) break; // prevent cycles
 		chain.push(next);
 		visited.add(next);

package/src/i18n/normalize.ts

@@ -1,4 +1,4 @@
-import type { I18nConfig } from "./config.js";
+import { resolveConfiguredLocale, type I18nConfig } from "./config.js";
 
 export interface AstroLocaleObject {
 	path: string;
@@ -15,7 +15,11 @@ export interface AstroI18nInput {
 export function normalizeAstroI18n(config: AstroI18nInput | null | undefined): I18nConfig | null {
 	if (!config) return null;
 
-	return {
+	const aliases = config.locales.flatMap((locale) =>
+		typeof locale === "string" ? [] : locale.codes.map((code) => [code, locale.path]),
+	);
+	const normalized: I18nConfig = {
+		...(aliases.length > 0 ? { localeAliases: Object.fromEntries(aliases) } : {}),
 		defaultLocale: config.defaultLocale,
 		locales: config.locales.map((locale) => (typeof locale === "string" ? locale : locale.path)),
 		fallback: config.fallback
@@ -28,4 +32,14 @@ export function normalizeAstroI18n(config: AstroI18nInput | null | undefined): I
 		prefixDefaultLocale:
 			typeof config.routing === "object" ? (config.routing.prefixDefaultLocale ?? false) : false,
 	};
+	normalized.defaultLocale = resolveConfiguredLocale(config.defaultLocale, normalized);
+	if (normalized.fallback) {
+		normalized.fallback = Object.fromEntries(
+			Object.entries(normalized.fallback).map(([from, to]) => [
+				resolveConfiguredLocale(from, normalized),
+				resolveConfiguredLocale(to, normalized),
+			]),
+		);
+	}
+	return normalized;
 }

package/src/i18n/query.ts

@@ -0,0 +1,47 @@
+import { sql, type SqlBool } from "kysely";
+
+import { getI18nConfig, getLocaleCandidates } from "./config.js";
+
+/** Match both canonical paths and code-stamped rows written by older versions. */
+export function localeMatches(column: string, locale: string) {
+	const candidates = getLocaleCandidates(locale);
+	if (candidates.length === 1) return sql<SqlBool>`${sql.ref(column)} = ${candidates[0]}`;
+	return sql<SqlBool>`${sql.ref(column)} IN (${sql.join(candidates)})`;
+}
+
+/** Prefer the configured path, then its Astro codes in configuration order. */
+export function localeOrder(column: string, locale: string) {
+	const candidates = getLocaleCandidates(locale);
+	return sql<number>`CASE lower(${sql.ref(column)}) ${sql.join(
+		candidates.map((candidate, rank) => sql`WHEN ${candidate.toLowerCase()} THEN ${sql.lit(rank)}`),
+		sql` `,
+	)} ELSE ${sql.lit(candidates.length)} END`;
+}
+
+/** Compare locale columns without losing rows stored under an Astro code. */
+export function canonicalLocaleColumn(column: string) {
+	const aliases = (getI18nConfig()?.locales ?? []).flatMap((locale) =>
+		getLocaleCandidates(locale)
+			.slice(1)
+			.map((code) => ({ code, locale })),
+	);
+	if (aliases.length === 0) return sql<string>`${sql.ref(column)}`;
+	return sql<string>`CASE lower(${sql.ref(column)}) ${sql.join(
+		aliases.map(({ code, locale }) => sql`WHEN ${code.toLowerCase()} THEN ${locale.toLowerCase()}`),
+		sql` `,
+	)} ELSE lower(${sql.ref(column)}) END`;
+}
+
+/** Rank a row's code within its own configured locale; paths always rank first. */
+export function storedLocaleOrder(column: string) {
+	const aliases = (getI18nConfig()?.locales ?? []).flatMap((locale) =>
+		getLocaleCandidates(locale)
+			.slice(1)
+			.map((code, index) => ({ code, rank: index + 1 })),
+	);
+	if (aliases.length === 0) return sql<number>`0`;
+	return sql<number>`CASE lower(${sql.ref(column)}) ${sql.join(
+		aliases.map(({ code, rank }) => sql`WHEN ${code.toLowerCase()} THEN ${sql.lit(rank)}`),
+		sql` `,
+	)} ELSE 0 END`;
+}

package/src/i18n/resolve.ts

@@ -8,7 +8,12 @@
  */
 
 import { getRequestContext } from "../request-context.js";
-import { getFallbackChain, getI18nConfig, isI18nEnabled } from "./config.js";
+import {
+	getFallbackChain,
+	getI18nConfig,
+	isI18nEnabled,
+	resolveConfiguredLocale,
+} from "./config.js";
 
 /**
  * Resolve the locale to use for a query given an optional explicit value.
@@ -16,9 +21,9 @@ import { getFallbackChain, getI18nConfig, isI18nEnabled } from "./config.js";
  * treat that as "do not filter by locale".
  */
 export function resolveLocale(explicit?: string): string | undefined {
-	if (explicit !== undefined) return explicit;
+	if (explicit !== undefined) return resolveConfiguredLocale(explicit);
 	const ctxLocale = getRequestContext()?.locale;
-	if (ctxLocale !== undefined) return ctxLocale;
+	if (ctxLocale !== undefined) return resolveConfiguredLocale(ctxLocale);
 	const cfg = getI18nConfig();
 	if (cfg && isI18nEnabled()) return cfg.defaultLocale;
 	return undefined;

package/src/import/utils.ts

@@ -7,7 +7,7 @@
 import type { PortableTextBlock } from "@emdash-cms/gutenberg-to-portable-text";
 import mime from "mime/lite";
 
-import { RESERVED_FIELD_SLUGS } from "../schema/types.js";
+import { RESERVED_COLLECTION_SLUGS, RESERVED_FIELD_SLUGS } from "../schema/types.js";
 import type { ImportFieldDef, CollectionSchemaStatus } from "./types.js";
 
 // =============================================================================
@@ -137,11 +137,24 @@ const POST_TYPE_TO_COLLECTION: Record<string, string> = {
 	faq: "faqs",
 };
 
+const INVALID_COLLECTION_SLUG_CHARS = /[^a-z0-9_]/g;
+
+/** Turn a WordPress post type name into a valid, non-reserved collection slug. */
+export function sanitizeCollectionSlug(slug: string): string {
+	const sanitized = slug
+		.toLowerCase()
+		.replace(INVALID_COLLECTION_SLUG_CHARS, "_")
+		.replace(LEADING_NON_ALPHA_CHARS, "");
+	if (!sanitized) return "imported";
+	if (RESERVED_COLLECTION_SLUGS.includes(sanitized)) return `wp_${sanitized}`;
+	return sanitized;
+}
+
 /**
  * Map WordPress post type to EmDash collection name
  */
 export function mapPostTypeToCollection(postType: string): string {
-	return POST_TYPE_TO_COLLECTION[postType] || postType;
+	return POST_TYPE_TO_COLLECTION[postType] || sanitizeCollectionSlug(postType);
 }
 
 // =============================================================================

package/src/import/wxr-taxonomies.ts

@@ -34,6 +34,7 @@ import {
 } from "../database/repositories/taxonomy-def.js";
 import { TaxonomyRepository } from "../database/repositories/taxonomy.js";
 import type { Database } from "../database/types.js";
+import { localeMatches, localeOrder } from "../i18n/query.js";
 import { invalidateTermCache } from "../taxonomies/index.js";
 
 /**
@@ -292,8 +293,8 @@ async function findExistingTerms(
 			.where((eb) =>
 				eb.or(batch.map((d) => eb.and([eb("name", "=", d.taxonomyName), eb("slug", "=", d.slug)]))),
 			)
-			.$if(locale !== undefined, (qb) => qb.where("locale", "=", locale!))
-			.orderBy("locale", "asc")
+			.$if(locale !== undefined, (qb) => qb.where(localeMatches("locale", locale!)))
+			.orderBy(locale !== undefined ? localeOrder("locale", locale) : "locale", "asc")
 			.execute();
 
 		for (const row of batchRows) {

package/src/index.ts

@@ -256,6 +256,7 @@ export {
 	invalidateTaxonomyObjectCache,
 	invalidateBylineObjectCache,
 	invalidateMenuObjectCache,
+	invalidateWidgetObjectCache,
 	invalidateSchemaObjectCache,
 	invalidateCommentObjectCache,
 	contentNamespace,