emdash 0.16.1 → 0.17.1

package/src/schema/types.ts

@@ -312,3 +312,136 @@ export const RESERVED_COLLECTION_SLUGS = [
 	"options",
 	"audit_logs",
 ];
+
+/**
+ * Byline custom fields (Discussion #1174).
+ *
+ * Sites declare site-specific byline metadata (`job_title`, `pronouns`,
+ * `twitter_handle`, `company`, …) without touching emdash core. Definitions
+ * live in `_emdash_byline_fields`; values in either
+ * `_emdash_byline_field_values` (translatable, keyed by `byline_id`) or
+ * `_emdash_byline_field_group_values` (non-translatable, keyed by
+ * `translation_group`). The per-field `translatable` flag decides which
+ * value table is used. See migration 041.
+ */
+
+/**
+ * The five v1 field types supported on byline custom fields. Deliberately
+ * narrower than the content `FieldType` union — bylines don't need
+ * `portableText`, `reference`, `image`, etc. v2 may extend this; v1 keeps
+ * the storage and UI surfaces small.
+ */
+export type BylineFieldType = "string" | "text" | "url" | "boolean" | "select";
+
+export const BYLINE_FIELD_TYPES: readonly BylineFieldType[] = [
+	"string",
+	"text",
+	"url",
+	"boolean",
+	"select",
+] as const;
+
+/**
+ * Validation rules for a byline custom field. v1 only exposes `options`
+ * (the choice list for `select` fields). The shape mirrors the content-
+ * field convention so the admin UI patterns transfer.
+ */
+export interface BylineFieldValidation {
+	/** Choices for `select`-type fields. Ignored for other types. */
+	options?: string[];
+}
+
+/**
+ * Runtime shape of a registered byline custom field. Stored in
+ * `_emdash_byline_fields` (see migration 041).
+ */
+export interface BylineFieldDefinition {
+	id: string;
+	slug: string;
+	label: string;
+	type: BylineFieldType;
+	required: boolean;
+	/**
+	 * Whether values are stored per-locale (`true`, in
+	 * `_emdash_byline_field_values` keyed by `byline_id`) or shared across
+	 * every locale variant of the same byline identity (`false`, in
+	 * `_emdash_byline_field_group_values` keyed by `translation_group`).
+	 * Defaults to `true` at the DB level.
+	 */
+	translatable: boolean;
+	validation: BylineFieldValidation | null;
+	sortOrder: number;
+	createdAt: string;
+	updatedAt: string;
+}
+
+/**
+ * Input for creating a byline custom field. `slug` and `type` are not
+ * updatable post-create — changing either would invalidate stored values.
+ */
+export interface CreateBylineFieldInput {
+	slug: string;
+	label: string;
+	type: BylineFieldType;
+	required?: boolean;
+	translatable?: boolean;
+	validation?: BylineFieldValidation | null;
+	sortOrder?: number;
+}
+
+/**
+ * Input for updating a byline custom field. `slug` and `type` are
+ * intentionally not present — see `CreateBylineFieldInput`.
+ */
+export interface UpdateBylineFieldInput {
+	label?: string;
+	required?: boolean;
+	translatable?: boolean;
+	validation?: BylineFieldValidation | null;
+	sortOrder?: number;
+}
+
+/**
+ * Runtime value type for a byline custom field. The narrow union mirrors
+ * what the five v1 field types can produce: `string`/`text`/`url`/`select`
+ * → string, `boolean` → boolean, plus `null` for cleared values.
+ */
+export type CustomFieldValue = string | boolean | null;
+
+/**
+ * Reserved byline-field slugs. Two reasons a slug ends up here:
+ *
+ * 1. **Column collision.** Slugs that match a fixed column on
+ *    `_emdash_bylines` (migrations 031 + 040) would shadow that column
+ *    on hydration. The first 12 entries cover this.
+ * 2. **Route collision.** Static file routes under
+ *    `/_emdash/api/admin/byline-fields/` take precedence over the
+ *    `[slug].ts` dynamic route in Astro, so a custom field whose slug
+ *    matches a sibling static file (e.g. `reorder.ts`) is unreachable
+ *    via single-field CRUD — the static route handles only its own
+ *    method (POST for `reorder`) and 405s everything else.
+ *    `reorder` is the only such sibling today; new sibling routes
+ *    (e.g. a hypothetical `import.ts`) must be added here.
+ *    `[slug]/usage.ts` lives a level deeper so a slug of `usage` does
+ *    not collide — it resolves cleanly to `[slug].ts`.
+ *
+ * Enforced at the registry layer (Phase 2) and the admin API zod layer
+ * (Phase 4) so non-HTTP callers (seeds, scripts) get the same guarantee.
+ */
+export const RESERVED_BYLINE_FIELD_SLUGS = [
+	// 1. Column-collision slugs (matches `_emdash_bylines` fixed columns).
+	"id",
+	"slug",
+	"display_name",
+	"bio",
+	"avatar_media_id",
+	"website_url",
+	"user_id",
+	"is_guest",
+	"locale",
+	"translation_group",
+	"created_at",
+	"updated_at",
+	// 2. Route-collision slugs (matches static sibling files of `[slug].ts`).
+	"reorder",
+] as const;

package/src/seed/apply.ts

@@ -33,6 +33,7 @@ import type {
 	SeedMenuItem,
 	SeedWidget,
 	SeedMediaReference,
+	SeedBylineAvatar,
 } from "./types.js";
 
 const FILE_EXTENSION_PATTERN = /\.([a-z0-9]+)(?:\?|$)/i;
@@ -351,14 +352,34 @@ export async function applySeed(
 				}
 
 				if (onConflict === "update") {
-					await bylineRepo.update(existing.id, {
-						displayName: byline.displayName,
-						bio: byline.bio ?? null,
-						websiteUrl: byline.websiteUrl ?? null,
-						isGuest: byline.isGuest,
-					});
+					// Resolve the avatar (reusing an existing media row by storage
+					// key, so re-running an update stays idempotent). Only relink
+					// when the seed supplies an avatar; otherwise leave the existing
+					// one untouched.
+					const avatar = byline.avatar ? await resolveSeedBylineAvatar(db, byline.avatar) : null;
+					try {
+						const updated = await bylineRepo.update(existing.id, {
+							displayName: byline.displayName,
+							bio: byline.bio ?? null,
+							websiteUrl: byline.websiteUrl ?? null,
+							isGuest: byline.isGuest,
+							...(avatar ? { avatarMediaId: avatar.id } : {}),
+						});
+						// update() returns null (no throw) if the row vanished between
+						// findBySlug and here; treat that as a failure so the catch
+						// cleans up any freshly-created avatar media instead of leaking it.
+						if (!updated) {
+							throw new Error(`Byline "${byline.slug}" disappeared during update`);
+						}
+					} catch (error) {
+						// withTransaction is a no-op on D1, so undo a freshly-created
+						// media row by hand to avoid orphaning it.
+						if (avatar?.created) await deleteMediaRow(db, avatar.id);
+						throw error;
+					}
 					seedBylineIdMap.set(byline.id, existing.id);
 					result.bylines.updated++;
+					if (avatar?.created) result.media.created++;
 					continue;
 				}
 
@@ -368,15 +389,25 @@ export async function applySeed(
 				continue;
 			}
 
-			const created = await bylineRepo.create({
-				slug: byline.slug,
-				displayName: byline.displayName,
-				bio: byline.bio ?? null,
-				websiteUrl: byline.websiteUrl ?? null,
-				isGuest: byline.isGuest,
-			});
-			seedBylineIdMap.set(byline.id, created.id);
+			const avatar = byline.avatar ? await resolveSeedBylineAvatar(db, byline.avatar) : null;
+			let createdId: string;
+			try {
+				const created = await bylineRepo.create({
+					slug: byline.slug,
+					displayName: byline.displayName,
+					bio: byline.bio ?? null,
+					websiteUrl: byline.websiteUrl ?? null,
+					isGuest: byline.isGuest,
+					avatarMediaId: avatar?.id ?? null,
+				});
+				createdId = created.id;
+			} catch (error) {
+				if (avatar?.created) await deleteMediaRow(db, avatar.id);
+				throw error;
+			}
+			seedBylineIdMap.set(byline.id, createdId);
 			result.bylines.created++;
+			if (avatar?.created) result.media.created++;
 		}
 	}
 
@@ -1121,6 +1152,62 @@ async function resolveValue(
 	return value;
 }
 
+/**
+ * Resolve a seeded byline avatar to a `media` row id. The file is assumed to
+ * already exist in storage (the caller supplies its `storageKey`), so nothing
+ * is downloaded or uploaded.
+ *
+ * Idempotent: if a media row with the same `storageKey` already exists it is
+ * reused rather than duplicated, so re-applying a seed in `update` mode does
+ * not leak rows. `created` reports whether a new row was inserted, so the
+ * caller can both account for it and delete it if the subsequent byline write
+ * fails (the only cross-dialect way to avoid an orphan — `withTransaction`
+ * is a no-op on D1).
+ */
+async function resolveSeedBylineAvatar(
+	db: Kysely<Database>,
+	avatar: SeedBylineAvatar,
+): Promise<{ id: string; created: boolean }> {
+	// `media.storage_key` has no unique constraint, so order deterministically
+	// to reuse the same row across runs if duplicates already exist. (Concurrent
+	// seed applies against one DB are out of scope; seeding is a single-shot
+	// init operation.)
+	const existing = await db
+		.selectFrom("media")
+		.select("id")
+		.where("storage_key", "=", avatar.storageKey)
+		.orderBy("id", "asc")
+		.executeTakeFirst();
+	if (existing) return { id: existing.id, created: false };
+
+	const basename = avatar.storageKey.split("/").pop();
+	const filename =
+		avatar.filename ?? (basename && basename.length > 0 ? basename : avatar.storageKey);
+	const created = await new MediaRepository(db).create({
+		filename,
+		mimeType: avatar.mimeType ?? "image/jpeg",
+		storageKey: avatar.storageKey,
+		alt: avatar.alt,
+		width: avatar.width,
+		height: avatar.height,
+		status: "ready",
+	});
+	return { id: created.id, created: true };
+}
+
+/**
+ * Delete a media row by id. Best-effort cleanup for a failed byline write: a
+ * failure here must not mask the original error that triggered the cleanup, so
+ * it is logged and swallowed rather than thrown.
+ */
+async function deleteMediaRow(db: Kysely<Database>, id: string): Promise<void> {
+	try {
+		await db.deleteFrom("media").where("id", "=", id).execute();
+	} catch (error) {
+		console.warn(`[seed] failed to clean up orphaned avatar media ${id}:`, error);
+	}
+}
+
 /**
  * Resolve a $media reference by downloading and uploading the media
  */

package/src/seed/types.ts

@@ -214,6 +214,27 @@ export interface SeedByline {
 	bio?: string;
 	websiteUrl?: string;
 	isGuest?: boolean;
+	/**
+	 * Avatar for the byline, seeded as an already-stored media item. Unlike a
+	 * content `$media` reference, nothing is downloaded: the caller supplies the
+	 * `storageKey` of a file that already exists in the configured storage (the
+	 * common case when seeding alongside a media migration). A `media` row is
+	 * created and linked via `avatarMediaId`.
+	 */
+	avatar?: SeedBylineAvatar;
+}
+
+export interface SeedBylineAvatar {
+	/** Storage key of an avatar file that already exists in the configured storage. */
+	storageKey: string;
+	/** Alt text for the avatar image. */
+	alt?: string;
+	/** Filename for the media record. Defaults to the storage key's basename. */
+	filename?: string;
+	/** MIME type for the media record. Defaults to `image/jpeg`. */
+	mimeType?: string;
+	width?: number;
+	height?: number;
 }
 
 /**

package/src/seed/validate.ts

@@ -471,6 +471,45 @@ export function validateSeed(data: unknown): ValidationResult {
 				if (!byline.displayName) {
 					errors.push(`${prefix}: displayName is required`);
 				}
+
+				if (byline.avatar !== undefined) {
+					const avatar: unknown = byline.avatar;
+					if (!isRecord(avatar)) {
+						errors.push(`${prefix}.avatar: must be an object`);
+					} else {
+						// storageKey is used verbatim in a `where storage_key = ?` lookup,
+						// so surrounding whitespace would silently never match a real key.
+						if (
+							typeof avatar.storageKey !== "string" ||
+							avatar.storageKey.length === 0 ||
+							avatar.storageKey !== avatar.storageKey.trim()
+						) {
+							errors.push(
+								`${prefix}.avatar.storageKey: must be a non-empty string with no leading or trailing whitespace`,
+							);
+						}
+						for (const key of ["alt", "filename", "mimeType"] as const) {
+							if (avatar[key] !== undefined && typeof avatar[key] !== "string") {
+								errors.push(`${prefix}.avatar.${key}: must be a string`);
+							}
+						}
+						// filename/mimeType are used verbatim, so reject blank or
+						// whitespace-padded values (an empty filename would create a
+						// media row with no basename; a padded mime type is invalid).
+						for (const key of ["filename", "mimeType"] as const) {
+							const v = avatar[key];
+							if (typeof v === "string" && (v.length === 0 || v !== v.trim())) {
+								errors.push(`${prefix}.avatar.${key}: must not be empty or whitespace-padded`);
+							}
+						}
+						for (const key of ["width", "height"] as const) {
+							const v = avatar[key];
+							if (v !== undefined && (typeof v !== "number" || !Number.isFinite(v) || v < 0)) {
+								errors.push(`${prefix}.avatar.${key}: must be a non-negative number`);
+							}
+						}
+					}
+				}
 			}
 		}
 	}