emdash 0.9.0 → 0.10.0

package/src/database/repositories/taxonomy.ts

@@ -1,4 +1,4 @@
-import type { Kysely } from "kysely";
+import type { Kysely, Selectable } from "kysely";
 import { ulid } from "ulidx";
 
 import type { Database, TaxonomyTable, ContentTaxonomyTable } from "../types.js";
@@ -10,6 +10,8 @@ export interface Taxonomy {
 	label: string;
 	parentId: string | null;
 	data: Record<string, unknown> | null;
+	locale: string;
+	translationGroup: string | null;
 }
 
 export interface CreateTaxonomyInput {
@@ -18,6 +20,11 @@ export interface CreateTaxonomyInput {
 	label: string;
 	parentId?: string;
 	data?: Record<string, unknown>;
+	/** Omit to let the DB default (current value: 'en') apply. Higher layers
+	 * resolve the locale from the request context / i18n config. */
+	locale?: string;
+	/** When set, links the new term into the source term's translation_group. */
+	translationOf?: string;
 }
 
 export interface UpdateTaxonomyInput {
@@ -27,16 +34,29 @@ export interface UpdateTaxonomyInput {
 	data?: Record<string, unknown>;
 }
 
+export interface FindOptions {
+	parentId?: string | null;
+	locale?: string;
+}
+
 /**
- * Taxonomy repository for categories, tags, and other classification
+ * Taxonomy repository for categories, tags, and other classification.
  *
- * Taxonomies are hierarchical (via parentId) and can be attached to content entries.
+ * Terms are per-locale. Translations of the same term share a `translation_group`
+ * ULID. `content_taxonomies.taxonomy_id` stores the translation_group so a single
+ * association spans every locale of a post.
+ *
+ * The repository does not resolve locale fallbacks on its own — callers supply
+ * the locale they want. Runtime helpers and handlers use `getFallbackChain()`
+ * from `i18n/config` when they need fallback behaviour.
  */
 export class TaxonomyRepository {
 	constructor(private db: Kysely<Database>) {}
 
 	/**
-	 * Create a new taxonomy term
+	 * Create a new taxonomy term. When `translationOf` is set the new row joins
+	 * the source term's translation_group; otherwise a fresh group is minted
+	 * (matching the migration backfill pattern `translation_group = id`).
 	 */
 	async create(input: CreateTaxonomyInput): Promise<Taxonomy> {
 		const id = ulid();
@@ -44,58 +64,68 @@ export class TaxonomyRepository {
 		// Empty-string parentId is coerced to null defensively. Higher layers
 		// also normalize this — see handleTermCreate / handleTermUpdate.
 		const parentId = input.parentId === undefined || input.parentId === "" ? null : input.parentId;
-		const row: TaxonomyTable = {
-			id,
-			name: input.name,
-			slug: input.slug,
-			label: input.label,
-			parent_id: parentId,
-			data: input.data ? JSON.stringify(input.data) : null,
-		};
 
-		await this.db.insertInto("taxonomies").values(row).execute();
+		let translationGroup = id;
+		if (input.translationOf) {
+			const source = await this.findById(input.translationOf);
+			if (source?.translationGroup) translationGroup = source.translationGroup;
+		}
+
+		await this.db
+			.insertInto("taxonomies")
+			.values({
+				id,
+				name: input.name,
+				slug: input.slug,
+				label: input.label,
+				parent_id: parentId,
+				data: input.data ? JSON.stringify(input.data) : null,
+				// When omitted, the DB DEFAULT 'en' is used — keeps behaviour
+				// consistent with ContentRepository and lets higher layers
+				// supply an explicit locale from request context.
+				...(input.locale !== undefined ? { locale: input.locale } : {}),
+				translation_group: translationGroup,
+			})
+			.execute();
 
 		const taxonomy = await this.findById(id);
-		if (!taxonomy) {
-			throw new Error("Failed to create taxonomy");
-		}
+		if (!taxonomy) throw new Error("Failed to create taxonomy");
 		return taxonomy;
 	}
 
-	/**
-	 * Find taxonomy by ID
-	 */
 	async findById(id: string): Promise<Taxonomy | null> {
 		const row = await this.db
 			.selectFrom("taxonomies")
 			.selectAll()
 			.where("id", "=", id)
 			.executeTakeFirst();
-
 		return row ? this.rowToTaxonomy(row) : null;
 	}
 
 	/**
-	 * Find taxonomy by name and slug (unique constraint)
+	 * Find a term by (name, slug). When `locale` is provided, filter by it.
+	 * When omitted, returns the lowest-locale-code match (deterministic across
+	 * calls). Mirrors `ContentRepository.findBySlug`.
 	 */
-	async findBySlug(name: string, slug: string): Promise<Taxonomy | null> {
-		const row = await this.db
+	async findBySlug(name: string, slug: string, locale?: string): Promise<Taxonomy | null> {
+		let query = this.db
 			.selectFrom("taxonomies")
 			.selectAll()
 			.where("name", "=", name)
-			.where("slug", "=", slug)
-			.executeTakeFirst();
-
+			.where("slug", "=", slug);
+		if (locale !== undefined) query = query.where("locale", "=", locale);
+		const row = await query.orderBy("locale", "asc").executeTakeFirst();
 		return row ? this.rowToTaxonomy(row) : null;
 	}
 
 	/**
-	 * Get all terms for a taxonomy (e.g., all categories)
+	 * Get all terms for a taxonomy (e.g., all categories).
+	 *
+	 * `id asc` is a stable tiebreaker for terms that share a label. Without it
+	 * the SQL ordering is implementation-defined when labels match, which
+	 * breaks keyset pagination over `(label, id)`.
 	 */
-	async findByName(name: string, options: { parentId?: string | null } = {}): Promise<Taxonomy[]> {
-		// `id asc` is a stable tiebreaker for terms that share a label.
-		// Without it the SQL ordering is implementation-defined when labels
-		// match, which breaks keyset pagination over `(label, id)`.
+	async findByName(name: string, options: FindOptions = {}): Promise<Taxonomy[]> {
 		let query = this.db
 			.selectFrom("taxonomies")
 			.selectAll()
@@ -103,6 +133,8 @@ export class TaxonomyRepository {
 			.orderBy("label", "asc")
 			.orderBy("id", "asc");
 
+		if (options.locale !== undefined) query = query.where("locale", "=", options.locale);
+
 		if (options.parentId !== undefined) {
 			if (options.parentId === null) {
 				query = query.where("parent_id", "is", null);
@@ -115,9 +147,6 @@ export class TaxonomyRepository {
 		return rows.map((row) => this.rowToTaxonomy(row));
 	}
 
-	/**
-	 * Get children of a taxonomy term
-	 */
 	async findChildren(parentId: string): Promise<Taxonomy[]> {
 		const rows = await this.db
 			.selectFrom("taxonomies")
@@ -126,18 +155,28 @@ export class TaxonomyRepository {
 			.orderBy("label", "asc")
 			.orderBy("id", "asc")
 			.execute();
-
 		return rows.map((row) => this.rowToTaxonomy(row));
 	}
 
 	/**
-	 * Update a taxonomy term
+	 * Every translation sibling of a term (including itself), identified by
+	 * their shared `translation_group`.
 	 */
+	async findTranslations(translationGroup: string): Promise<Taxonomy[]> {
+		const rows = await this.db
+			.selectFrom("taxonomies")
+			.selectAll()
+			.where("translation_group", "=", translationGroup)
+			.orderBy("locale", "asc")
+			.execute();
+		return rows.map((row) => this.rowToTaxonomy(row));
+	}
+
 	async update(id: string, input: UpdateTaxonomyInput): Promise<Taxonomy | null> {
 		const existing = await this.findById(id);
 		if (!existing) return null;
 
-		const updates: Partial<TaxonomyTable> = {};
+		const updates: Record<string, unknown> = {};
 		if (input.slug !== undefined) updates.slug = input.slug;
 		if (input.label !== undefined) updates.label = input.label;
 		if (input.parentId !== undefined) {
@@ -153,31 +192,42 @@ export class TaxonomyRepository {
 		return this.findById(id);
 	}
 
-	/**
-	 * Delete a taxonomy term
-	 */
 	async delete(id: string): Promise<boolean> {
-		// First remove any content associations
-		await this.db.deleteFrom("content_taxonomies").where("taxonomy_id", "=", id).execute();
+		const term = await this.findById(id);
+		if (!term) return false;
+
+		// When deleting the last translation of a group the pivot rows that
+		// reference that translation_group become orphaned — purge them.
+		if (term.translationGroup) {
+			const siblings = await this.db
+				.selectFrom("taxonomies")
+				.select("id")
+				.where("translation_group", "=", term.translationGroup)
+				.where("id", "!=", id)
+				.execute();
+			if (siblings.length === 0) {
+				await this.db
+					.deleteFrom("content_taxonomies")
+					.where("taxonomy_id", "=", term.translationGroup)
+					.execute();
+			}
+		}
 
 		const result = await this.db.deleteFrom("taxonomies").where("id", "=", id).executeTakeFirst();
-
-		return (result.numDeletedRows ?? 0) > 0;
+		return (result.numDeletedRows ?? 0n) > 0n;
 	}
 
-	// --- Content-Taxonomy Junction ---
+	// --- Content-Taxonomy Junction (taxonomy_id stores the translation_group) ---
 
-	/**
-	 * Attach a taxonomy term to a content entry
-	 */
 	async attachToEntry(collection: string, entryId: string, taxonomyId: string): Promise<void> {
+		const group = await this.resolveTranslationGroup(taxonomyId);
+		if (!group) return;
+
 		const row: ContentTaxonomyTable = {
 			collection,
 			entry_id: entryId,
-			taxonomy_id: taxonomyId,
+			taxonomy_id: group,
 		};
-
-		// Use INSERT OR IGNORE pattern for idempotency
 		await this.db
 			.insertInto("content_taxonomies")
 			.values(row)
@@ -185,58 +235,72 @@ export class TaxonomyRepository {
 			.execute();
 	}
 
-	/**
-	 * Detach a taxonomy term from a content entry
-	 */
 	async detachFromEntry(collection: string, entryId: string, taxonomyId: string): Promise<void> {
+		const group = await this.resolveTranslationGroup(taxonomyId);
+		if (!group) return;
+
 		await this.db
 			.deleteFrom("content_taxonomies")
 			.where("collection", "=", collection)
 			.where("entry_id", "=", entryId)
-			.where("taxonomy_id", "=", taxonomyId)
+			.where("taxonomy_id", "=", group)
 			.execute();
 	}
 
 	/**
-	 * Get all taxonomy terms for a content entry
+	 * Taxonomy terms assigned to a content entry, resolved into a specific locale.
+	 * Terms whose translation_group lacks a row in the requested locale are
+	 * omitted — callers wanting fallback behaviour apply it themselves.
 	 */
 	async getTermsForEntry(
 		collection: string,
 		entryId: string,
 		taxonomyName?: string,
+		locale?: string,
 	): Promise<Taxonomy[]> {
 		let query = this.db
 			.selectFrom("content_taxonomies")
-			.innerJoin("taxonomies", "taxonomies.id", "content_taxonomies.taxonomy_id")
+			.innerJoin("taxonomies", "taxonomies.translation_group", "content_taxonomies.taxonomy_id")
 			.selectAll("taxonomies")
 			.where("content_taxonomies.collection", "=", collection)
 			.where("content_taxonomies.entry_id", "=", entryId);
 
-		if (taxonomyName) {
-			query = query.where("taxonomies.name", "=", taxonomyName);
-		}
+		if (taxonomyName) query = query.where("taxonomies.name", "=", taxonomyName);
+		if (locale !== undefined) query = query.where("taxonomies.locale", "=", locale);
 
-		const rows = await query.execute();
+		const rows = await query.orderBy("taxonomies.locale", "asc").execute();
 		return rows.map((row) => this.rowToTaxonomy(row));
 	}
 
 	/**
-	 * Set all taxonomy terms for a content entry (replaces existing)
-	 * Uses batch operations to avoid N+1 queries.
+	 * Replace all assignments of a given taxonomy for one content entry.
+	 * Term ids OR translation_groups are accepted and normalised to groups.
 	 */
 	async setTermsForEntry(
 		collection: string,
 		entryId: string,
 		taxonomyName: string,
-		taxonomyIds: string[],
+		termIds: string[],
 	): Promise<void> {
-		// Get current terms of this taxonomy type
-		const current = await this.getTermsForEntry(collection, entryId, taxonomyName);
-		const currentIds = new Set(current.map((t) => t.id));
-		const newIds = new Set(taxonomyIds);
+		const groups: string[] = [];
+		for (const id of termIds) {
+			const group = await this.resolveTranslationGroup(id);
+			if (group) groups.push(group);
+		}
+		const newGroups = new Set(groups);
+
+		const current = await this.db
+			.selectFrom("content_taxonomies")
+			.innerJoin("taxonomies", "taxonomies.translation_group", "content_taxonomies.taxonomy_id")
+			.select(["content_taxonomies.taxonomy_id as group"])
+			.distinct()
+			.where("content_taxonomies.collection", "=", collection)
+			.where("content_taxonomies.entry_id", "=", entryId)
+			.where("taxonomies.name", "=", taxonomyName)
+			.execute();
+		const currentGroups = new Set(current.map((r) => r.group));
 
-		// Batch remove terms no longer present
-		const toRemove = current.filter((t) => !newIds.has(t.id)).map((t) => t.id);
+		const toRemove = [...currentGroups].filter((g) => !newGroups.has(g));
 		if (toRemove.length > 0) {
 			await this.db
 				.deleteFrom("content_taxonomies")
@@ -246,8 +310,7 @@ export class TaxonomyRepository {
 				.execute();
 		}
 
-		// Batch add new terms
-		const toAdd = taxonomyIds.filter((id) => !currentIds.has(id));
+		const toAdd = [...newGroups].filter((g) => !currentGroups.has(g));
 		if (toAdd.length > 0) {
 			await this.db
 				.insertInto("content_taxonomies")
@@ -263,44 +326,86 @@ export class TaxonomyRepository {
 		}
 	}
 
-	/**
-	 * Remove all taxonomy associations for an entry (use when entry is deleted)
-	 */
 	async clearEntryTerms(collection: string, entryId: string): Promise<number> {
 		const result = await this.db
 			.deleteFrom("content_taxonomies")
 			.where("collection", "=", collection)
 			.where("entry_id", "=", entryId)
 			.executeTakeFirst();
-
 		return Number(result.numDeletedRows ?? 0);
 	}
 
 	/**
-	 * Count entries that have a specific taxonomy term
+	 * Copy every term assignment from one content entry to another. Used when
+	 * creating a translation of a post so the new translation inherits the
+	 * source's term assignments. Safe to call when the source has no terms.
+	 */
+	async copyEntryTerms(
+		collection: string,
+		sourceEntryId: string,
+		targetEntryId: string,
+	): Promise<void> {
+		const rows = await this.db
+			.selectFrom("content_taxonomies")
+			.select(["taxonomy_id"])
+			.where("collection", "=", collection)
+			.where("entry_id", "=", sourceEntryId)
+			.execute();
+		if (rows.length === 0) return;
+
+		await this.db
+			.insertInto("content_taxonomies")
+			.values(
+				rows.map((r) => ({
+					collection,
+					entry_id: targetEntryId,
+					taxonomy_id: r.taxonomy_id,
+				})),
+			)
+			.onConflict((oc) => oc.doNothing())
+			.execute();
+	}
+
+	/**
+	 * Count content entries that use any translation of this term. Accepts
+	 * either a term id or a translation_group — we normalise to the group.
 	 */
-	async countEntriesWithTerm(taxonomyId: string): Promise<number> {
+	async countEntriesWithTerm(termIdOrGroup: string): Promise<number> {
+		const group = await this.resolveTranslationGroup(termIdOrGroup);
+		if (!group) return 0;
+
 		const result = await this.db
 			.selectFrom("content_taxonomies")
 			.select((eb) => eb.fn.count("entry_id").as("count"))
-			.where("taxonomy_id", "=", taxonomyId)
+			.where("taxonomy_id", "=", group)
 			.executeTakeFirst();
+		return Number(result?.count ?? 0);
+	}
 
-		return Number(result?.count || 0);
+	private async resolveTranslationGroup(idOrGroup: string): Promise<string | null> {
+		const row = await this.db
+			.selectFrom("taxonomies")
+			.select(["translation_group"])
+			.where((eb) => eb.or([eb("id", "=", idOrGroup), eb("translation_group", "=", idOrGroup)]))
+			.executeTakeFirst();
+		return row?.translation_group ?? null;
 	}
 
 	/**
-	 * Batch count entries for multiple taxonomy term IDs.
+	 * Batch count entries for multiple taxonomy translation_groups.
 	 * Chunks the query at SQL_BATCH_SIZE to stay below D1's bind-parameter limit.
-	 * Returns a Map from term ID to count.
+	 * Returns a Map from translation_group to count.
+	 *
+	 * Pass translation_groups (not term ids) — `content_taxonomies.taxonomy_id`
+	 * stores the translation_group so a single assignment spans every locale.
 	 */
-	async countEntriesForTerms(termIds: string[]): Promise<Map<string, number>> {
-		if (termIds.length === 0) return new Map();
+	async countEntriesForTerms(translationGroups: string[]): Promise<Map<string, number>> {
+		if (translationGroups.length === 0) return new Map();
 
 		const { chunks, SQL_BATCH_SIZE } = await import("../../utils/chunks.js");
 
 		const counts = new Map<string, number>();
-		for (const chunk of chunks(termIds, SQL_BATCH_SIZE)) {
+		for (const chunk of chunks(translationGroups, SQL_BATCH_SIZE)) {
 			const rows = await this.db
 				.selectFrom("content_taxonomies")
 				.select(["taxonomy_id", (eb) => eb.fn.count("entry_id").as("count")])
@@ -315,10 +420,7 @@ export class TaxonomyRepository {
 		return counts;
 	}
 
-	/**
-	 * Convert database row to Taxonomy object
-	 */
-	private rowToTaxonomy(row: TaxonomyTable): Taxonomy {
+	private rowToTaxonomy(row: Selectable<TaxonomyTable>): Taxonomy {
 		return {
 			id: row.id,
 			name: row.name,
@@ -326,6 +428,8 @@ export class TaxonomyRepository {
 			label: row.label,
 			parentId: row.parent_id,
 			data: row.data ? JSON.parse(row.data) : null,
+			locale: row.locale,
+			translationGroup: row.translation_group,
 		};
 	}
 }

package/src/database/types.ts

@@ -20,12 +20,14 @@ export interface TaxonomyTable {
 	label: string;
 	parent_id: string | null;
 	data: string | null; // JSON
+	locale: Generated<string>; // e.g. 'en', 'es', 'fr'
+	translation_group: string | null; // shared across translations of the same term
 }
 
 export interface ContentTaxonomyTable {
 	collection: string; // e.g., 'posts'
 	entry_id: string; // ID in the ec_* table
-	taxonomy_id: string;
+	taxonomy_id: string; // stores taxonomies.translation_group (locale-agnostic)
 }
 
 export interface TaxonomyDefTable {
@@ -36,6 +38,8 @@ export interface TaxonomyDefTable {
 	hierarchical: number; // 0 or 1 (SQLite boolean)
 	collections: string | null; // JSON array
 	created_at: Generated<string>;
+	locale: Generated<string>;
+	translation_group: string | null;
 }
 
 export interface MediaTable {
@@ -292,6 +296,8 @@ export interface MenuTable {
 	label: string;
 	created_at: Generated<string>;
 	updated_at: Generated<string>;
+	locale: Generated<string>;
+	translation_group: string | null;
 }
 
 export interface MenuItemTable {
@@ -301,13 +307,15 @@ export interface MenuItemTable {
 	sort_order: number;
 	type: string;
 	reference_collection: string | null;
-	reference_id: string | null;
+	reference_id: string | null; // stores translation_group of referenced content/term
 	custom_url: string | null;
 	label: string;
 	title_attr: string | null;
 	target: string | null;
 	css_classes: string | null;
 	created_at: Generated<string>;
+	locale: Generated<string>;
+	translation_group: string | null;
 }
 
 // Widget Areas

package/src/i18n/resolve.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared locale-resolution helpers.
+ *
+ * Matches the pattern used by `query.ts` for content: an explicit locale wins,
+ * otherwise we fall back to the request-context locale, otherwise to
+ * `defaultLocale` when i18n is enabled, otherwise to `undefined` (meaning "do
+ * not filter by locale" — legacy single-locale behaviour).
+ */
+
+import { getRequestContext } from "../request-context.js";
+import { getFallbackChain, getI18nConfig, isI18nEnabled } from "./config.js";
+
+/**
+ * Resolve the locale to use for a query given an optional explicit value.
+ * Returns `undefined` when no locale information is available; callers should
+ * treat that as "do not filter by locale".
+ */
+export function resolveLocale(explicit?: string): string | undefined {
+	if (explicit !== undefined) return explicit;
+	const ctxLocale = getRequestContext()?.locale;
+	if (ctxLocale !== undefined) return ctxLocale;
+	const cfg = getI18nConfig();
+	if (cfg && isI18nEnabled()) return cfg.defaultLocale;
+	return undefined;
+}
+
+/**
+ * Fallback chain to try when looking up a single item. When i18n is disabled
+ * or the locale is unspecified, returns a single-element array (or empty when
+ * no locale resolves) so callers can iterate uniformly.
+ */
+export function resolveLocaleChain(explicit?: string): string[] {
+	const locale = resolveLocale(explicit);
+	if (locale === undefined) return [];
+	if (!isI18nEnabled()) return [locale];
+	return getFallbackChain(locale);
+}

package/src/loader.ts

@@ -125,12 +125,59 @@ const DATE_COLUMNS = new Set(["created_at", "updated_at", "published_at", "sched
  */
 export const CURSOR_RAW_VALUES: unique symbol = Symbol("emdash:cursorRawValues");
 
+const LOCAL_MEDIA_FILE_PREFIX = "/_emdash/api/media/file/";
+const URL_SCHEME_PATTERN = /^[a-zA-Z][a-zA-Z\d+\-.]*:/;
+
 /** Safely extract a string value from a record, returning fallback if not a string */
 function rowStr(row: Record<string, unknown>, key: string, fallback = ""): string {
 	const val = row[key];
 	return typeof val === "string" ? val : fallback;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isBareMediaKey(src: string): boolean {
+	return !src.startsWith("/") && !URL_SCHEME_PATTERN.test(src);
+}
+
+function normalizeLocalMediaValue(value: unknown): unknown {
+	if (Array.isArray(value)) {
+		return value.map(normalizeLocalMediaValue);
+	}
+
+	if (!isRecord(value)) {
+		return value;
+	}
+
+	const normalized: Record<string, unknown> = {};
+	for (const [key, child] of Object.entries(value)) {
+		normalized[key] = normalizeLocalMediaValue(child);
+	}
+
+	if (
+		normalized.provider === "local" &&
+		typeof normalized.src === "string" &&
+		normalized.src.length > 0
+	) {
+		const src = normalized.src;
+		if (src.startsWith(LOCAL_MEDIA_FILE_PREFIX)) {
+			const id = src.slice(LOCAL_MEDIA_FILE_PREFIX.length);
+			if (!normalized.id && id) {
+				normalized.id = id;
+			}
+		} else if (isBareMediaKey(src)) {
+			if (!normalized.id) {
+				normalized.id = src;
+			}
+			normalized.src = `${LOCAL_MEDIA_FILE_PREFIX}${src}`;
+		}
+	}
+
+	return normalized;
+}
+
 /**
  * Map a database row to entry data
  * Extracts content fields (non-system columns) and parses JSON where needed.
@@ -164,7 +211,7 @@ function mapRowToData(row: Record<string, unknown>): Record<string, unknown> {
 			try {
 				// Only parse if it looks like JSON (starts with { or [)
 				if (value.startsWith("{") || value.startsWith("[")) {
-					data[key] = JSON.parse(value);
+					data[key] = normalizeLocalMediaValue(JSON.parse(value));
 				} else {
 					data[key] = value;
 				}
@@ -194,7 +241,7 @@ function mapRevisionData(data: Record<string, unknown>): Record<string, unknown>
 	const result: Record<string, unknown> = {};
 	for (const [key, value] of Object.entries(data)) {
 		if (key.startsWith("_")) continue; // revision metadata
-		result[key] = value;
+		result[key] = normalizeLocalMediaValue(value);
 	}
 	return result;
 }