emdash 0.33.0 → 0.34.0

package/src/plugins/routes.ts

@@ -8,9 +8,10 @@
  *
  */
 
+import { MediaUsageActivationWriteBlockedError } from "../api/media-usage-write-fence.js";
 import { PluginContextFactory, type PluginContextFactoryOptions } from "./context.js";
 import { extractRequestMeta } from "./request-meta.js";
-import type { ResolvedPlugin, RouteContext, PluginRoute } from "./types.js";
+import type { ResolvedPlugin, RouteContext, PluginRoute, UserInfo } from "./types.js";
 
 /**
  * Body-reading methods on `Request`. EmDash parses the request body once before
@@ -130,6 +131,34 @@ export interface RouteResult<T = unknown> {
 	status: number;
 }
 
+/**
+ * Host-side user shape accepted when dispatching a plugin route. Structurally
+ * matches `User` from `@emdash-cms/auth` so hosts can pass `locals.user`
+ * directly without the plugin layer depending on the auth package.
+ */
+export interface RouteCallerInput {
+	id: string;
+	email: string;
+	name: string | null;
+	role: number;
+	createdAt: Date | string;
+}
+
+/**
+ * Convert the host's authenticated user into the read-only `UserInfo` shape
+ * exposed to plugins as `ctx.user`. Strips sensitive/irrelevant fields and
+ * keeps the value structured-clone-safe for sandboxed plugins.
+ */
+export function toRouteCallerInfo(user: RouteCallerInput): UserInfo {
+	return {
+		id: user.id,
+		email: user.email,
+		name: user.name,
+		role: user.role,
+		createdAt: typeof user.createdAt === "string" ? user.createdAt : user.createdAt.toISOString(),
+	};
+}
+
 /**
  * Route invocation options
  */
@@ -138,6 +167,11 @@ export interface InvokeRouteOptions {
 	request: Request;
 	/** Request body (already parsed) */
 	body?: unknown;
+	/**
+	 * Authenticated caller resolved by the host, exposed to the handler as
+	 * `ctx.user`. Undefined for public routes and unbound machine tokens.
+	 */
+	user?: UserInfo;
 }
 
 /**
@@ -201,6 +235,7 @@ export class PluginRouteHandler {
 			// (#1293). Metadata extraction uses the original request (headers only).
 			request: guardConsumedRequestBody(options.request),
 			requestMeta: extractRequestMeta(options.request, this.trustedProxyHeaders),
+			user: options.user,
 		};
 
 		// Execute handler
@@ -212,6 +247,13 @@ export class PluginRouteHandler {
 				status: 200,
 			};
 		} catch (error) {
+			if (error instanceof MediaUsageActivationWriteBlockedError) {
+				return {
+					success: false,
+					error: { code: error.code, message: error.message },
+					status: error.status,
+				};
+			}
 			// Handle known error types
 			if (error instanceof PluginRouteError) {
 				return {

package/src/plugins/sandbox/index.ts

@@ -4,7 +4,13 @@
  */
 
 export { NoopSandboxRunner, SandboxNotAvailableError, createNoopSandboxRunner } from "./noop.js";
-export { SandboxUnavailableError } from "./types.js";
+export {
+	SandboxUnavailableError,
+	createSandboxRouteError,
+	createSandboxRouteErrorEnvelope,
+	getSandboxRouteErrorDetails,
+	getSandboxRouteErrorEnvelope,
+} from "./types.js";
 
 export type {
 	SandboxRunner,
@@ -16,4 +22,7 @@ export type {
 	ResourceLimits,
 	PluginCodeStorage,
 	SerializedRequest,
+	SandboxRouteErrorCode,
+	SandboxRouteErrorDetails,
+	SandboxRouteErrorEnvelope,
 } from "./types.js";

package/src/plugins/sandbox/types.ts

@@ -10,7 +10,7 @@
 import type { Kysely } from "kysely";
 
 import type { Database } from "../../database/types.js";
-import type { PluginManifest, RequestMeta } from "../types.js";
+import type { PluginManifest, RequestMeta, UserInfo } from "../types.js";
 
 /**
  * Resource limits for sandboxed plugins.
@@ -69,6 +69,8 @@ export interface SandboxOptions {
 	storage?: PluginCodeStorage;
 	/** Database for bridge operations */
 	db: Kysely<Database>;
+	/** Called immediately before a sandboxed plugin content mutation. */
+	beforeContentWrite?: () => Promise<void>;
 	/** Default resource limits */
 	limits?: ResourceLimits;
 	/** Site info for plugin context (injected into wrapper at generation time) */
@@ -138,6 +140,81 @@ export interface SerializedRequest {
 	headers: Record<string, string>;
 	/** Normalized request metadata extracted before RPC serialization */
 	meta: RequestMeta;
+	/**
+	 * Authenticated caller for private routes, resolved by the host before
+	 * dispatch. Undefined for public routes and unbound machine tokens.
+	 */
+	user?: UserInfo;
+}
+
+const SANDBOX_ROUTE_ERROR_DEFINITIONS = {
+	MEDIA_USAGE_ACTIVATION_IN_PROGRESS: {
+		message: "Media usage activation is in progress",
+		status: 503,
+	},
+	MEDIA_USAGE_ACTIVATION_CHECK_FAILED: {
+		message: "Unable to verify media usage activation state",
+		status: 503,
+	},
+} as const;
+
+export type SandboxRouteErrorCode = keyof typeof SANDBOX_ROUTE_ERROR_DEFINITIONS;
+
+export interface SandboxRouteErrorDetails {
+	code: SandboxRouteErrorCode;
+	message: string;
+	status: 503;
+}
+
+export interface SandboxRouteErrorEnvelope {
+	__emdashSandboxRouteError: true;
+	error: SandboxRouteErrorDetails;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function isSandboxRouteErrorCode(value: unknown): value is SandboxRouteErrorCode {
+	return typeof value === "string" && value in SANDBOX_ROUTE_ERROR_DEFINITIONS;
+}
+
+export function getSandboxRouteErrorDetails(error: unknown): SandboxRouteErrorDetails | null {
+	if (!isRecord(error)) return null;
+
+	const propertyCode = isSandboxRouteErrorCode(error.code) ? error.code : null;
+	const nameCode =
+		error instanceof Error && isSandboxRouteErrorCode(error.name) ? error.name : null;
+	if (propertyCode && nameCode && propertyCode !== nameCode) return null;
+
+	const code = propertyCode ?? nameCode;
+	if (!code || (error.status !== undefined && error.status !== 503)) return null;
+
+	return {
+		code,
+		...SANDBOX_ROUTE_ERROR_DEFINITIONS[code],
+	};
+}
+
+export function createSandboxRouteError(
+	code: SandboxRouteErrorCode,
+): Error & SandboxRouteErrorDetails {
+	const details: SandboxRouteErrorDetails = {
+		code,
+		...SANDBOX_ROUTE_ERROR_DEFINITIONS[code],
+	};
+	return Object.assign(new Error(details.message), details, { name: code });
+}
+
+export function createSandboxRouteErrorEnvelope(error: unknown): SandboxRouteErrorEnvelope | null {
+	const details = getSandboxRouteErrorDetails(error);
+	return details ? { __emdashSandboxRouteError: true, error: details } : null;
+}
+
+export function getSandboxRouteErrorEnvelope(value: unknown): SandboxRouteErrorEnvelope | null {
+	if (!isRecord(value) || value.__emdashSandboxRouteError !== true) return null;
+	const details = getSandboxRouteErrorDetails(value.error);
+	return details ? { __emdashSandboxRouteError: true, error: details } : null;
 }
 
 /**

package/src/plugins/scheduler/node.ts

@@ -29,6 +29,7 @@ export class NodeCronScheduler implements CronScheduler {
 	private timer: ReturnType<typeof setTimeout> | null = null;
 	private running = false;
 	private systemCleanup: SystemCleanupFn | null = null;
+	private mediaUsageMaintenance: SystemCleanupFn | null = null;
 
 	constructor(private executor: CronExecutor) {}
 
@@ -36,6 +37,10 @@ export class NodeCronScheduler implements CronScheduler {
 		this.systemCleanup = fn;
 	}
 
+	setMediaUsageMaintenance(fn: SystemCleanupFn): void {
+		this.mediaUsageMaintenance = fn;
+	}
+
 	start(): void {
 		this.running = true;
 		this.arm();
@@ -112,12 +117,19 @@ export class NodeCronScheduler implements CronScheduler {
 		}
 
 		void Promise.allSettled(tasks)
-			.then((results) => {
+			.then(async (results) => {
 				for (const r of results) {
 					if (r.status === "rejected") {
 						console.error("[cron:node] Tick task failed:", r.reason);
 					}
 				}
+				if (this.mediaUsageMaintenance) {
+					try {
+						await this.mediaUsageMaintenance();
+					} catch (error) {
+						console.error("[cron:node] Media Usage maintenance failed:", error);
+					}
+				}
 				return undefined;
 			})
 			.finally(() => {

package/src/plugins/scheduler/types.ts

@@ -18,6 +18,8 @@ export interface CronScheduler {
 	reschedule(): void;
 	/** Register a system cleanup function to run alongside each tick. */
 	setSystemCleanup(fn: SystemCleanupFn): void;
+	/** Register bounded Media Usage maintenance to run after the general tick settles. */
+	setMediaUsageMaintenance?(fn: SystemCleanupFn): void;
 }
 
 /**

package/src/plugins/types.ts

@@ -42,8 +42,17 @@ import type { z } from "astro/zod";
 // Core Types
 // =============================================================================
 
+import type { ContentFieldFilters } from "../content-list-query.js";
 import type { FieldType } from "../schema/types.js";
 
+export type {
+	ContentFieldFilterScalar,
+	ContentFieldFilterValue,
+	ContentFieldFilters,
+	ContentFieldInFilter,
+	ContentFieldRangeFilter,
+} from "../content-list-query.js";
+
 export {
 	CAPABILITY_RENAMES,
 	capabilitiesToDeclaredAccess,
@@ -227,6 +236,8 @@ export interface ContentListWhere {
 	status?: string;
 	/** Exact match on `locale` (e.g. `"en"`, `"fr-CA"`). */
 	locale?: string;
+	/** AND-combined filters over custom fields explicitly marked as indexed. */
+	fieldFilters?: ContentFieldFilters;
 }
 
 /**
@@ -251,6 +262,12 @@ export type ContentWriteInput = Record<string, unknown> & {
 	seo?: ContentItemSeoInput;
 };
 
+/** Options accepted by `content.create`. */
+export interface ContentCreateOptions {
+	/** Locale for the new content row. Defaults to the configured site locale, then `en`. */
+	locale?: string;
+}
+
 /**
  * Taxonomy definition returned from the taxonomy API (e.g. "category", "tag").
  */
@@ -299,7 +316,11 @@ export interface ContentAccess {
 	list(collection: string, options?: ContentListOptions): Promise<PaginatedResult<ContentItem>>;
 
 	// Write operations (requires write:content) - optional on interface
-	create?(collection: string, data: ContentWriteInput): Promise<ContentItem>;
+	create?(
+		collection: string,
+		data: ContentWriteInput,
+		options?: ContentCreateOptions,
+	): Promise<ContentItem>;
 	update?(collection: string, id: string, data: ContentWriteInput): Promise<ContentItem>;
 	delete?(collection: string, id: string): Promise<boolean>;
 }
@@ -325,7 +346,11 @@ export interface TaxonomyAccess {
  * Full content access with write operations
  */
 export interface ContentAccessWithWrite extends ContentAccess {
-	create(collection: string, data: ContentWriteInput): Promise<ContentItem>;
+	create(
+		collection: string,
+		data: ContentWriteInput,
+		options?: ContentCreateOptions,
+	): Promise<ContentItem>;
 	update(collection: string, id: string, data: ContentWriteInput): Promise<ContentItem>;
 	delete(collection: string, id: string): Promise<boolean>;
 }
@@ -1175,6 +1200,18 @@ export interface RouteContext<TInput = unknown> extends PluginContext {
 	request: Request;
 	/** Normalized request metadata (IP, user agent, geo) */
 	requestMeta: RequestMeta;
+	/**
+	 * Authenticated caller, if the route is private. The host has already
+	 * authenticated and authorized this user before dispatch, so the value
+	 * is trustworthy — unlike a user id read from the request body.
+	 *
+	 * `undefined` for public routes (which skip auth entirely) and for
+	 * token-authed requests where no user is bound to the token.
+	 *
+	 * Not gated by the `users:read` capability: this is the caller's own
+	 * identity for the current request, not a user directory lookup.
+	 */
+	user?: UserInfo;
 }
 
 /**

package/src/query.ts

@@ -27,6 +27,7 @@
 import { encodeCursor } from "./database/repositories/types.js";
 import { getFallbackChain, getI18nConfig, isI18nEnabled } from "./i18n/config.js";
 import {
+	creditsFromFoldedBylines,
 	CURSOR_RAW_VALUES,
 	FOLDED_BYLINES,
 	FOLDED_BYLINES_EXIST,
@@ -41,6 +42,7 @@ import {
 } from "./object-cache/index.js";
 import { requestCached } from "./request-cache.js";
 import { getRequestContext } from "./request-context.js";
+import { compileUrlPattern } from "./schema/url-pattern.js";
 import type { TaxonomyTerm } from "./taxonomies/types.js";
 import { isMissingTableError } from "./utils/db-errors.js";
 import {
@@ -754,8 +756,8 @@ async function getEmDashCollectionUncached<T extends string, D = InferCollection
 	// round-trip cost on remote databases (D1 replicas, etc.).
 	await Promise.all([
 		hydrateEntryBylines(type, entriesWithEdit),
-		// Hydrate terms in the same locale the content rows were resolved to,
-		// otherwise localized entries get default-locale taxonomy terms (#1441).
+		// Use the content query locale as the preferred term locale; hydration
+		// falls back only to the configured default when a group lacks that variant.
 		hydrateEntryTerms(type, entriesWithEdit, resolvedLocale),
 	]);
 
@@ -834,10 +836,8 @@ export async function getEmDashEntry<T extends string, D = InferCollectionData<T
 		opts: { isPreview: boolean; fallbackLocale?: string; cacheHint: CacheHint },
 	): Promise<EntryResult<D>> {
 		if (!opts.isPreview) stripRevisionMetadata(wrapped);
-		// Hydrate terms in the entry's resolved locale (fallback-aware) so a
-		// localized entry never picks up default-locale taxonomy terms (#1441).
-		// When i18n is disabled we leave the locale unset to preserve the
-		// legacy "do not filter by locale" behaviour.
+		// No-i18n callers use the legacy wildcard cache key. The query path still
+		// resolves against the stored content-row locale when this is undefined.
 		const termLocale = isI18nEnabled()
 			? dataStr(entryData(wrapped), "locale") || undefined
 			: undefined;
@@ -1017,17 +1017,7 @@ async function hydrateEntryBylines<D>(type: string, entries: ContentEntry<D>[]):
 			const data = entryData(entry);
 			const folded = Reflect.get(data, FOLDED_BYLINES);
 			const rows = Array.isArray(folded) ? folded : [];
-			const credits = rows
-				.map((raw) => {
-					const b = raw?.byline ?? {};
-					return {
-						roleLabel: raw?.roleLabel ?? null,
-						sortOrder: Number(raw?.sortOrder ?? 0),
-						source: "explicit" as const,
-						byline: { ...b, isGuest: Boolean(b.isGuest), customFields: {} },
-					};
-				})
-				.toSorted((a, b) => a.sortOrder - b.sortOrder);
+			const credits = creditsFromFoldedBylines(rows);
 			return { data, credits };
 		});
 
@@ -1140,10 +1130,9 @@ async function hydrateEntryBylines<D>(type: string, entries: ContentEntry<D>[]):
  * results and call getEntryTerms() per entry. With hydration, the list page
  * stays at a single round-trip for term data.
  *
- * `locale` must be the locale the entries were resolved to. It is forwarded to
- * `getAllTermsForEntries` so terms are returned in the entry's locale rather
- * than falling back to the request-context / default locale (#1441). Pass
- * `undefined` to keep the legacy "do not filter by locale" behaviour.
+ * `locale` is the preferred locale the entries were resolved to. Each assigned
+ * group resolves that variant first, then the configured default. When it is
+ * omitted, the stored locale of each content row is preferred.
  *
  * Fails silently if the taxonomy tables don't exist yet (pre-migration).
  */
@@ -1310,26 +1299,27 @@ export interface ResolvePathResult<T = Record<string, unknown>> {
 	params: Record<string, string>;
 }
 
-/** Matches `{paramName}` placeholders in URL patterns */
-const URL_PARAM_PATTERN = /\{(\w+)\}/g;
-
-/** Convert a URL pattern like "/blog/{slug}" to a regex and param name list */
-function patternToRegex(pattern: string): { regex: RegExp; paramNames: string[] } {
-	const paramNames: string[] = [];
-	const regexStr = pattern.replace(URL_PARAM_PATTERN, (_match, name: string) => {
-		paramNames.push(name);
-		return "([^/]+)";
-	});
-	return { regex: new RegExp(`^${regexStr}$`), paramNames };
-}
-
 /** Cached compiled URL patterns for resolveEmDashPath */
 interface CachedPattern {
 	slug: string;
 	regex: RegExp;
 	paramNames: string[];
 }
-let cachedUrlPatterns: CachedPattern[] | null = null;
+
+interface UrlPatternCache {
+	patterns: CachedPattern[] | null;
+}
+
+const URL_PATTERN_CACHE_KEY = Symbol.for("emdash:url-pattern-cache");
+const queryGlobal = globalThis as Record<symbol, unknown>;
+const urlPatternCache: UrlPatternCache =
+	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- globalThis singleton pattern (see request-context.ts)
+	(queryGlobal[URL_PATTERN_CACHE_KEY] as UrlPatternCache | undefined) ??
+	(() => {
+		const cache: UrlPatternCache = { patterns: null };
+		queryGlobal[URL_PATTERN_CACHE_KEY] = cache;
+		return cache;
+	})();
 
 /**
  * Invalidate the cached URL patterns used by resolveEmDashPath.
@@ -1340,7 +1330,7 @@ let cachedUrlPatterns: CachedPattern[] | null = null;
  * every schema-mutation path already routes through here.
  */
 export function invalidateUrlPatternCache(): void {
-	cachedUrlPatterns = null;
+	urlPatternCache.patterns = null;
 	invalidateSchemaObjectCache();
 }
 
@@ -1367,6 +1357,7 @@ export async function resolveEmDashPath<T = Record<string, unknown>>(
 	path: string,
 ): Promise<ResolvePathResult<T> | null> {
 	// Build and cache compiled patterns on first call
+	let cachedUrlPatterns = urlPatternCache.patterns;
 	if (!cachedUrlPatterns) {
 		const { getDb } = await import("./loader.js");
 		const { SchemaRegistry } = await import("./schema/registry.js");
@@ -1377,9 +1368,10 @@ export async function resolveEmDashPath<T = Record<string, unknown>>(
 		cachedUrlPatterns = [];
 		for (const collection of collections) {
 			if (!collection.urlPattern) continue;
-			const { regex, paramNames } = patternToRegex(collection.urlPattern);
+			const { regex, paramNames } = compileUrlPattern(collection.urlPattern);
 			cachedUrlPatterns.push({ slug: collection.slug, regex, paramNames });
 		}
+		urlPatternCache.patterns = cachedUrlPatterns;
 	}
 
 	for (const pattern of cachedUrlPatterns) {

package/src/scheduler-health.ts

@@ -0,0 +1,46 @@
+import type { Kysely } from "kysely";
+
+import { OptionsRepository } from "./database/repositories/options.js";
+import type { Database } from "./database/types.js";
+
+export const SCHEDULER_HEARTBEAT_OPTION = "system:scheduler:last_completed_at";
+export const SCHEDULER_STALE_AFTER_MS = 5 * 60 * 1000;
+
+export interface SchedulerHealth {
+	status: "healthy" | "stale" | "unknown";
+	lastCompletedAt: string | null;
+}
+
+export async function recordSchedulerHeartbeat(
+	db: Kysely<Database>,
+	completedAt = new Date(),
+): Promise<void> {
+	await new OptionsRepository(db).set(SCHEDULER_HEARTBEAT_OPTION, completedAt.toISOString());
+}
+
+export async function recordSchedulerHeartbeatSafely(
+	db: Kysely<Database>,
+	completedAt = new Date(),
+): Promise<void> {
+	try {
+		await recordSchedulerHeartbeat(db, completedAt);
+	} catch (error) {
+		console.error("[scheduler] Failed to record heartbeat:", error);
+	}
+}
+
+export async function getSchedulerHealth(
+	db: Kysely<Database>,
+	now = new Date(),
+): Promise<SchedulerHealth> {
+	const lastCompletedAt = await new OptionsRepository(db).get<string>(SCHEDULER_HEARTBEAT_OPTION);
+	const lastCompletedAtMs = lastCompletedAt ? Date.parse(lastCompletedAt) : Number.NaN;
+	if (!lastCompletedAt || Number.isNaN(lastCompletedAtMs)) {
+		return { status: "unknown", lastCompletedAt: null };
+	}
+
+	return {
+		status: now.getTime() - lastCompletedAtMs > SCHEDULER_STALE_AFTER_MS ? "stale" : "healthy",
+		lastCompletedAt,
+	};
+}