emdash 0.37.0 → 0.39.0

package/src/plugins/cron.ts

@@ -17,6 +17,8 @@ import type { CronAccess, CronEvent, CronTaskInfo } from "./types.js";
 
 /** Stale lock threshold in minutes */
 const STALE_LOCK_MINUTES = 10;
+const ISO_DATETIME_PATTERN =
+	/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?$/;
 
 /**
  * Callback to invoke a plugin's cron hook.
@@ -52,6 +54,7 @@ export class CronExecutor {
 	constructor(
 		db: Kysely<Database> | (() => Kysely<Database>),
 		private invokeCronHook: InvokeCronHookFn,
+		private readonly now: () => Date = () => new Date(),
 	) {
 		this.resolveDb = typeof db === "function" ? db : () => db;
 	}
@@ -69,7 +72,8 @@ export class CronExecutor {
 	 * 4. On failure: reset to idle (retry on next tick).
 	 */
 	async tick(): Promise<number> {
-		const now = new Date().toISOString();
+		const currentTime = this.now();
+		const now = currentTime.toISOString();
 		let processed = 0;
 
 		// Claim overdue tasks atomically
@@ -151,7 +155,7 @@ export class CronExecutor {
 					} else {
 						// Retry with exponential backoff: 1m, 2m, 4m, 8m, 16m
 						const backoffMs = 60_000 * Math.pow(2, retryCount);
-						const retryAt = new Date(Date.now() + backoffMs).toISOString();
+						const retryAt = new Date(currentTime.getTime() + backoffMs).toISOString();
 						const updatedData = JSON.stringify({
 							...parsedData,
 							__emdash: { ...meta, retryCount: retryCount + 1 },
@@ -170,7 +174,7 @@ export class CronExecutor {
 				}
 			} else {
 				// Recurring: compute next run and reset
-				const nextRun = nextCronTime(task.schedule);
+				const nextRun = nextCronTime(task.schedule, currentTime);
 				await sql`
 					UPDATE _emdash_cron_tasks
 					SET status = 'idle',
@@ -192,7 +196,7 @@ export class CronExecutor {
 	 * These likely crashed mid-execution.
 	 */
 	async recoverStaleLocks(): Promise<number> {
-		const cutoff = new Date(Date.now() - STALE_LOCK_MINUTES * 60 * 1000).toISOString();
+		const cutoff = new Date(this.now().getTime() - STALE_LOCK_MINUTES * 60 * 1000).toISOString();
 
 		const result = await sql`
 			UPDATE _emdash_cron_tasks
@@ -230,6 +234,7 @@ export class CronAccessImpl implements CronAccess {
 		private db: Kysely<Database>,
 		private pluginId: string,
 		private reschedule: RescheduleFn,
+		private readonly now: () => Date = () => new Date(),
 	) {}
 
 	async schedule(
@@ -240,7 +245,7 @@ export class CronAccessImpl implements CronAccess {
 		validateSchedule(opts.schedule);
 
 		const oneshot = isOneShot(opts.schedule);
-		const nextRun = oneshot ? opts.schedule : nextCronTime(opts.schedule);
+		const nextRun = oneshot ? opts.schedule : nextCronTime(opts.schedule, this.now());
 		const dataJson = opts.data ? JSON.stringify(opts.data) : null;
 		const id = ulid();
 
@@ -323,9 +328,9 @@ export async function setCronTasksEnabled(
  * Supports standard cron (5-field), extended (6-field with seconds), and
  * aliases like @daily, @weekly, @hourly, @monthly, @yearly.
  */
-export function nextCronTime(expression: string): string {
+export function nextCronTime(expression: string, currentTime: Date = new Date()): string {
 	const job = new Cron(expression);
-	const next = job.nextRun();
+	const next = job.nextRun(currentTime);
 	if (!next) {
 		throw new Error(`Invalid cron expression or no future run: "${expression}"`);
 	}
@@ -350,12 +355,15 @@ function isCronExpression(schedule: string): boolean {
  * Check if a schedule string is a one-shot (ISO 8601 datetime) rather than
  * a recurring cron expression.
  *
- * Tries to parse as a cron expression first. Only if that fails does it
- * attempt Date.parse. This avoids misclassifying cron range expressions
- * like "1-5 * * * *" which Date.parse accepts as valid dates.
+ * Recognizes the supported ISO date-time shape before consulting the cron
+ * parser, which also accepts ISO timestamps. Other values are parsed as cron
+ * first so expressions like "1-5 * * * *" are not misclassified as dates.
  */
 export function isOneShot(schedule: string): boolean {
 	if (schedule.startsWith("@")) return false;
+	if (ISO_DATETIME_PATTERN.test(schedule)) {
+		return !isNaN(Date.parse(schedule));
+	}
 	if (isCronExpression(schedule)) return false;
 	return !isNaN(Date.parse(schedule));
 }

package/src/plugins/define-plugin.ts

@@ -10,7 +10,13 @@
  * authoring shape.
  */
 
-import { normalizeCapabilities } from "./types.js";
+import {
+	isJsonPostRouteContract,
+	PLUGIN_CAPABILITIES,
+	type PluginRouteBodyMode,
+} from "@emdash-cms/plugin-types";
+
+import { normalizePluginCapabilities } from "./types.js";
 import type {
 	PluginDefinition,
 	ResolvedPlugin,
@@ -18,7 +24,7 @@ import type {
 	ResolvedPluginHooks,
 	ResolvedHook,
 	HookConfig,
-	PluginCapability,
+	PluginRouteDefinition,
 	PluginStorageConfig,
 } from "./types.js";
 
@@ -85,6 +91,12 @@ export function definePlugin<TStorage extends PluginStorageConfig>(
 	return defineNativePlugin(definition);
 }
 
+export function definePluginRoute<TMode extends PluginRouteBodyMode>(
+	route: PluginRouteDefinition<TMode>,
+): PluginRouteDefinition<TMode> {
+	return route;
+}
+
 /**
  * Internal: define a native-format plugin with full validation and normalization.
  */
@@ -97,12 +109,12 @@ function defineNativePlugin<TStorage extends PluginStorageConfig>(
 	// initialize -> "Cannot access 'SIMPLE_ID' before initialization" -> every
 	// route 500s on Cloudflare Workers. Call-time consts evaluate after the
 	// literals are parsed, so the temporal dead zone cannot occur regardless of
-	// bundle ordering. See #1370.
-	// oxlint-disable-next-line e18e/prefer-static-regex -- call-time on purpose (see #1370)
+	// bundle ordering.
+	// oxlint-disable-next-line e18e/prefer-static-regex -- avoids circular-init TDZ
 	const SIMPLE_ID = /^[a-z0-9-]+$/;
-	// oxlint-disable-next-line e18e/prefer-static-regex -- call-time on purpose (see #1370)
+	// oxlint-disable-next-line e18e/prefer-static-regex -- avoids circular-init TDZ
 	const SCOPED_ID = /^@[a-z0-9-]+\/[a-z0-9-]+$/;
-	// oxlint-disable-next-line e18e/prefer-static-regex -- call-time on purpose (see #1370)
+	// oxlint-disable-next-line e18e/prefer-static-regex -- avoids circular-init TDZ
 	const SEMVER_PATTERN = /^\d+\.\d+\.\d+/;
 
 	const {
@@ -142,69 +154,58 @@ function defineNativePlugin<TStorage extends PluginStorageConfig>(
 		const route = routes[tool.route];
 		if (!route) throw new Error(`MCP tool "${name}" references unknown route "${tool.route}".`);
 		if (route.public) throw new Error(`MCP tool "${name}" cannot reference a public route.`);
+		if (route.response === "raw") {
+			throw new Error(`MCP tool "${name}" cannot reference a raw response route.`);
+		}
+		if (!isJsonPostRouteContract(route)) {
+			throw new Error(`MCP tool "${name}" must reference a POST-compatible JSON route.`);
+		}
 		if (!route.permission) {
 			throw new Error(`MCP route "${tool.route}" must declare a permission.`);
 		}
 	}
 
+	for (const [kind, extensions] of [
+		["editor panel", admin.editorPanels],
+		["editor action", admin.editorActions],
+	] as const) {
+		for (const extension of extensions ?? []) {
+			const route = routes[extension.route];
+			if (!route) {
+				throw new Error(
+					`Plugin ${kind} "${extension.id}" references unknown route "${extension.route}".`,
+				);
+			}
+			if (route.public) {
+				throw new Error(`Plugin ${kind} "${extension.id}" must reference a private route.`);
+			}
+			if (!isJsonPostRouteContract(route)) {
+				throw new Error(
+					`Plugin ${kind} "${extension.id}" must reference a route that accepts POST JSON requests and returns JSON.`,
+				);
+			}
+		}
+	}
+
+	if ((admin.pages?.length ?? 0) > 0 || (admin.widgets?.length ?? 0) > 0) {
+		const adminRoute = routes.admin;
+		if (adminRoute && (adminRoute.public === true || !isJsonPostRouteContract(adminRoute))) {
+			throw new Error("Block Kit admin route must accept POST JSON requests and return JSON.");
+		}
+	}
+
 	// Validate capabilities. Both current names and deprecated aliases are
 	// accepted; aliases are silently rewritten to current names below so the
 	// runtime only ever sees the canonical form. Authors are warned at
 	// bundle/validate and hard-failed at publish.
-	const validCapabilities = new Set<string>([
-		// Current names
-		"network:request",
-		"network:request:unrestricted",
-		"content:read",
-		"content:write",
-		"taxonomies:read",
-		"media:read",
-		"media:write",
-		"users:read",
-		"email:send",
-		"hooks.email-transport:register",
-		"hooks.email-events:register",
-		"hooks.page-fragments:register",
-		// Deprecated aliases
-		"network:fetch",
-		"network:fetch:any",
-		"read:content",
-		"write:content",
-		"read:media",
-		"write:media",
-		"read:users",
-		"email:provide",
-		"email:intercept",
-		"page:inject",
-	]);
+	const validCapabilities = new Set<string>(PLUGIN_CAPABILITIES);
 	for (const cap of capabilities) {
 		if (!validCapabilities.has(cap)) {
 			throw new Error(`Invalid capability "${cap}" in plugin "${id}".`);
 		}
 	}
 
-	// Silent normalization: rewrite deprecated names to current names. Done
-	// before the implication pass so implications work on canonical names.
-	// `as PluginCapability[]` is safe because `normalizeCapabilities` only
-	// returns strings from the validated input plus current names from the
-	// rename map, all of which are in the union.
-	const canonical = normalizeCapabilities(capabilities) as PluginCapability[];
-
-	// Capability implications: broader capabilities imply narrower ones.
-	// Operates on canonical names only.
-	const normalizedCapabilities: PluginCapability[] = [...canonical];
-	if (canonical.includes("content:write") && !canonical.includes("content:read")) {
-		normalizedCapabilities.push("content:read");
-	}
-	if (canonical.includes("media:write") && !canonical.includes("media:read")) {
-		normalizedCapabilities.push("media:read");
-	}
-	if (
-		canonical.includes("network:request:unrestricted") &&
-		!canonical.includes("network:request")
-	) {
-		normalizedCapabilities.push("network:request");
-	}
+	const normalizedCapabilities = normalizePluginCapabilities(capabilities);
 
 	// Normalize hooks
 	const resolvedHooks = resolveHooks(hooks, id);

package/src/plugins/editor-draft.ts

@@ -0,0 +1,257 @@
+import type {
+	EditorDraftFieldDefinition,
+	EditorDraftInvocationReceipt,
+	EditorDraftPatchEffect,
+	EditorDraftSnapshot,
+} from "@emdash-cms/blocks";
+import {
+	isEditorDraftPatchEffect,
+	validateEditorDraftPatchEffect,
+} from "@emdash-cms/blocks/server";
+
+import type { CollectionWithFields, Field } from "../schema/types.js";
+import { generateFieldSchema } from "../schema/zod-generator.js";
+import type { PluginEditorDraftFieldSelector } from "./types.js";
+
+export const EDITOR_DRAFT_LIMITS = {
+	maxFields: 32,
+	maxSnapshotBytes: 192 * 1024,
+	maxFieldBytes: 64 * 1024,
+} as const;
+
+export type EditorDraftErrorCode =
+	| "EDITOR_DRAFT_STALE"
+	| "EDITOR_DRAFT_FIELD_FORBIDDEN"
+	| "EDITOR_DRAFT_INVALID"
+	| "EDITOR_DRAFT_UNSUPPORTED_FIELD_TYPE"
+	| "EDITOR_DRAFT_TOO_LARGE"
+	| "EDITOR_DRAFT_CAPABILITY_REQUIRED";
+
+export interface EditorDraftValidationError {
+	code: EditorDraftErrorCode;
+	message: string;
+}
+
+interface BrowserDraftRequest {
+	collection: string;
+	entryId: string;
+	locale: string | null;
+	baseRevision: string;
+	generation: number;
+	invocationId: string;
+	fields: Record<string, unknown>;
+}
+
+export interface ValidatedEditorDraftRequest {
+	snapshot: EditorDraftSnapshot;
+	receipt: EditorDraftInvocationReceipt;
+	readFields: ReadonlySet<string>;
+	patchFields: ReadonlySet<string>;
+}
+
+const ENCODER = new TextEncoder();
+const INVOCATION_PATTERN = /^[A-Za-z0-9_-]{16,128}$/;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isBrowserDraftRequest(value: unknown): value is BrowserDraftRequest {
+	return (
+		isRecord(value) &&
+		typeof value.collection === "string" &&
+		typeof value.entryId === "string" &&
+		(value.locale === null || typeof value.locale === "string") &&
+		typeof value.baseRevision === "string" &&
+		typeof value.generation === "number" &&
+		typeof value.invocationId === "string" &&
+		isRecord(value.fields)
+	);
+}
+
+function jsonBytes(value: unknown): number | null {
+	try {
+		return ENCODER.encode(JSON.stringify(value)).byteLength;
+	} catch {
+		return null;
+	}
+}
+
+function selectedFields(
+	collection: CollectionWithFields,
+	selector: PluginEditorDraftFieldSelector | undefined,
+): Set<string> {
+	const selected = new Set(selector?.fields ?? []);
+	if (selector?.translatable) {
+		for (const field of collection.fields) {
+			if (field.translatable) selected.add(field.slug);
+		}
+	}
+	return selected;
+}
+
+function sanitizeField(field: Field): EditorDraftFieldDefinition {
+	return {
+		slug: field.slug,
+		label: field.label,
+		type: field.type,
+		required: field.required,
+		translatable: field.translatable,
+		...(field.validation ? { validation: { ...field.validation } } : {}),
+	};
+}
+
+function fail(code: EditorDraftErrorCode, message: string): EditorDraftValidationError {
+	return { code, message };
+}
+
+export function validateEditorDraftRequest(input: {
+	request: unknown;
+	collection: CollectionWithFields;
+	entry: { id: string; locale: string | null; revision: string };
+	readSelector?: PluginEditorDraftFieldSelector;
+	patchSelector?: PluginEditorDraftFieldSelector;
+	canRead: boolean;
+	canPatch: boolean;
+}): ValidatedEditorDraftRequest | EditorDraftValidationError {
+	if (!isBrowserDraftRequest(input.request)) {
+		return fail("EDITOR_DRAFT_INVALID", "Invalid editor draft snapshot");
+	}
+	const request = input.request;
+	if (
+		request.collection !== input.collection.slug ||
+		request.entryId !== input.entry.id ||
+		request.locale !== input.entry.locale
+	) {
+		return fail("EDITOR_DRAFT_STALE", "Editor draft identity is stale");
+	}
+	if (request.baseRevision !== input.entry.revision) {
+		return fail("EDITOR_DRAFT_STALE", "Editor draft base revision is stale");
+	}
+	if (
+		!Number.isSafeInteger(request.generation) ||
+		request.generation < 0 ||
+		typeof request.invocationId !== "string" ||
+		!INVOCATION_PATTERN.test(request.invocationId)
+	) {
+		return fail("EDITOR_DRAFT_INVALID", "Invalid editor draft invocation identity");
+	}
+	const size = jsonBytes(request);
+	if (size === null)
+		return fail("EDITOR_DRAFT_INVALID", "Editor draft snapshot must be JSON serializable");
+	if (size > EDITOR_DRAFT_LIMITS.maxSnapshotBytes) {
+		return fail("EDITOR_DRAFT_TOO_LARGE", "Editor draft snapshot exceeds the size limit");
+	}
+
+	const readFields = selectedFields(input.collection, input.readSelector);
+	const patchFields = selectedFields(input.collection, input.patchSelector);
+	if (
+		readFields.size > EDITOR_DRAFT_LIMITS.maxFields ||
+		patchFields.size > EDITOR_DRAFT_LIMITS.maxFields
+	) {
+		return fail("EDITOR_DRAFT_TOO_LARGE", "Editor draft selector exceeds the field limit");
+	}
+	const supplied = Object.keys(request.fields);
+	if (supplied.length > EDITOR_DRAFT_LIMITS.maxFields) {
+		return fail("EDITOR_DRAFT_TOO_LARGE", "Editor draft snapshot exceeds the field limit");
+	}
+	if (supplied.length > 0 && !input.canRead) {
+		return fail("EDITOR_DRAFT_CAPABILITY_REQUIRED", "Plugin cannot read unsaved editor content");
+	}
+	const bySlug = new Map(input.collection.fields.map((field) => [field.slug, field]));
+	const patchFieldDefinitions = Array.from(patchFields, (slug) => bySlug.get(slug))
+		.filter((field): field is Field => Boolean(field && !field.unsupportedType))
+		.map(sanitizeField);
+	const fields: Record<string, unknown> = {};
+	const fieldDefinitions: EditorDraftFieldDefinition[] = [];
+	for (const slug of supplied) {
+		if (!readFields.has(slug)) {
+			return fail("EDITOR_DRAFT_FIELD_FORBIDDEN", `Editor draft field '${slug}' is not allowed`);
+		}
+		const field = bySlug.get(slug);
+		if (!field || field.unsupportedType) {
+			return fail(
+				"EDITOR_DRAFT_UNSUPPORTED_FIELD_TYPE",
+				`Editor draft field '${slug}' has an unsupported type`,
+			);
+		}
+		const fieldSize = jsonBytes(request.fields[slug]);
+		if (fieldSize === null)
+			return fail("EDITOR_DRAFT_INVALID", `Editor draft field '${slug}' is invalid`);
+		if (fieldSize > EDITOR_DRAFT_LIMITS.maxFieldBytes) {
+			return fail("EDITOR_DRAFT_TOO_LARGE", `Editor draft field '${slug}' exceeds the size limit`);
+		}
+		if (!generateFieldSchema(field).safeParse(request.fields[slug]).success) {
+			return fail("EDITOR_DRAFT_INVALID", `Editor draft field '${slug}' is invalid`);
+		}
+		fields[slug] = request.fields[slug];
+		fieldDefinitions.push(sanitizeField(field));
+	}
+	if (input.readSelector && !input.canRead) {
+		return fail("EDITOR_DRAFT_CAPABILITY_REQUIRED", "Plugin cannot read unsaved editor content");
+	}
+	if (input.patchSelector && !input.canPatch) {
+		return fail("EDITOR_DRAFT_CAPABILITY_REQUIRED", "Plugin cannot propose unsaved editor changes");
+	}
+
+	return {
+		snapshot: {
+			collection: input.collection.slug,
+			entryId: input.entry.id,
+			locale: input.entry.locale,
+			baseRevision: input.entry.revision,
+			invocationId: request.invocationId,
+			fields,
+			fieldDefinitions,
+		},
+		receipt: {
+			entryId: input.entry.id,
+			locale: input.entry.locale,
+			baseRevision: input.entry.revision,
+			generation: request.generation,
+			invocationId: request.invocationId,
+			fieldDefinitions: patchFieldDefinitions,
+		},
+		readFields,
+		patchFields,
+	};
+}
+
+export function validateEditorDraftPatch(input: {
+	patch: unknown;
+	collection: CollectionWithFields;
+	allowedFields: ReadonlySet<string>;
+}): EditorDraftPatchEffect | EditorDraftValidationError {
+	const structural = validateEditorDraftPatchEffect(input.patch);
+	if (!structural.valid || !isEditorDraftPatchEffect(input.patch))
+		return fail("EDITOR_DRAFT_INVALID", "Plugin returned an invalid editor draft patch");
+	const patch = input.patch;
+	const bySlug = new Map(input.collection.fields.map((field) => [field.slug, field]));
+	for (const operation of patch.operations) {
+		if (!input.allowedFields.has(operation.field)) {
+			return fail(
+				"EDITOR_DRAFT_FIELD_FORBIDDEN",
+				`Editor draft field '${operation.field}' is not allowed`,
+			);
+		}
+		const field = bySlug.get(operation.field);
+		if (!field || field.unsupportedType) {
+			return fail(
+				"EDITOR_DRAFT_UNSUPPORTED_FIELD_TYPE",
+				`Editor draft field '${operation.field}' has an unsupported type`,
+			);
+		}
+		const value = operation.op === "clear" ? null : operation.value;
+		if (!generateFieldSchema(field).safeParse(value).success) {
+			return fail("EDITOR_DRAFT_INVALID", `Editor draft field '${operation.field}' is invalid`);
+		}
+		const fieldSize = jsonBytes(value);
+		if (fieldSize === null || fieldSize > EDITOR_DRAFT_LIMITS.maxFieldBytes) {
+			return fail(
+				"EDITOR_DRAFT_TOO_LARGE",
+				`Editor draft field '${operation.field}' exceeds the size limit`,
+			);
+		}
+	}
+	return patch;
+}