emdash 0.9.0 → 0.11.0

package/src/plugins/types.ts

@@ -10,187 +10,56 @@
  */
 
 import type { Element } from "@emdash-cms/blocks";
+// The plugin capability vocabulary, the legacy-rename map, and the manifest
+// shape are authored once in @emdash-cms/plugin-types and shared between core
+// (the manifest reader at install/runtime) and @emdash-cms/registry-cli (the
+// manifest writer at bundle/publish time).
+//
+// We import-and-re-export here so existing internal callers keep working
+// (e.g. `import { PluginCapability } from "../plugins/types.js"`).
+import {
+	CAPABILITY_RENAMES,
+	isDeprecatedCapability,
+	normalizeCapabilities,
+	normalizeCapability,
+	type CurrentPluginCapability,
+	type DeprecatedPluginCapability,
+	type ManifestHookEntry,
+	type ManifestRouteEntry,
+	type PluginCapability,
+	type PluginStorageConfig,
+	type StorageCollectionConfig,
+} from "@emdash-cms/plugin-types";
 import type { JSX } from "astro/jsx-runtime";
 import type { z } from "astro/zod";
-
-import type { FieldType } from "../schema/types.js";
-
 // =============================================================================
 // Core Types
 // =============================================================================
 
-/**
- * Plugin capabilities determine what APIs are available in context.
- *
- * Capabilities follow the formula `<resource>[.<sub-resource>]:<verb>[:<qualifier>]`
- * — resource first, verb second, matching RBAC. The `unrestricted` qualifier
- * (used by `network:request:unrestricted`) is intentionally verbose so that
- * granting it stands out in manifest review.
- *
- * Hook-registration capabilities (`hooks.<family>:register`) are a distinct
- * audit category from data-access capabilities — they gate which hooks a
- * plugin is allowed to register, not which context APIs it gets.
- *
- * @see CAPABILITY_RENAMES for the legacy → current mapping, and
- *      `normalizeCapability()` for the runtime alias layer.
- */
-export type PluginCapability =
-	// ── Network ─────────────────────────────────────────────────
-	| "network:request" // ctx.http is available (host-restricted via allowedHosts)
-	| "network:request:unrestricted" // ctx.http is available (unrestricted outbound — use for user-configured URLs)
-	// ── Content ─────────────────────────────────────────────────
-	| "content:read" // ctx.content.get/list available
-	| "content:write" // ctx.content.create/update/delete available
-	// ── Media ───────────────────────────────────────────────────
-	| "media:read" // ctx.media.get/list available
-	| "media:write" // ctx.media.getUploadUrl/delete available
-	// ── Users ───────────────────────────────────────────────────
-	| "users:read" // ctx.users is available
-	// ── Email ───────────────────────────────────────────────────
-	| "email:send" // ctx.email is available (when a provider is configured)
-	// ── Hook registration ───────────────────────────────────────
-	| "hooks.email-transport:register" // can register email:deliver exclusive hook (transport provider)
-	| "hooks.email-events:register" // can register email:beforeSend / email:afterSend hooks
-	| "hooks.page-fragments:register" // can register page:fragments hook (inject scripts/styles into pages)
-	// ── Deprecated (legacy aliases) ─────────────────────────────
-	// Kept in the union for one minor with @deprecated tags so existing
-	// plugins typecheck during migration. Normalized to current names at
-	// definition time via normalizeCapability(). Will be removed in the
-	// following minor.
-	/** @deprecated Use `network:request` instead. */
-	| "network:fetch"
-	/** @deprecated Use `network:request:unrestricted` instead. */
-	| "network:fetch:any"
-	/** @deprecated Use `content:read` instead. */
-	| "read:content"
-	/** @deprecated Use `content:write` instead. */
-	| "write:content"
-	/** @deprecated Use `media:read` instead. */
-	| "read:media"
-	/** @deprecated Use `media:write` instead. */
-	| "write:media"
-	/** @deprecated Use `users:read` instead. */
-	| "read:users"
-	/** @deprecated Use `hooks.email-transport:register` instead. */
-	| "email:provide"
-	/** @deprecated Use `hooks.email-events:register` instead. */
-	| "email:intercept"
-	/** @deprecated Use `hooks.page-fragments:register` instead. */
-	| "page:inject";
-
-/**
- * Deprecated capability names that map to current names.
- *
- * These are accepted at every external boundary (manifest parse, definePlugin,
- * adaptSandboxEntry) and silently normalized to the new names before reaching
- * the runtime. The runtime never sees deprecated names.
- *
- * Authors are warned at `bundle` / `validate`, and hard-failed at `publish`.
- */
-export type DeprecatedPluginCapability =
-	| "network:fetch"
-	| "network:fetch:any"
-	| "read:content"
-	| "write:content"
-	| "read:media"
-	| "write:media"
-	| "read:users"
-	| "email:provide"
-	| "email:intercept"
-	| "page:inject";
-
-/**
- * Current (non-deprecated) capability names.
- */
-export type CurrentPluginCapability = Exclude<PluginCapability, DeprecatedPluginCapability>;
-
-/**
- * Mapping from deprecated capability names to their current replacements.
- *
- * Used by `normalizeCapability()` and the marketplace `diffCapabilities`
- * helper to compare manifests across the rename without flagging spurious
- * "capability changed" prompts on upgrade.
- */
-export const CAPABILITY_RENAMES: Readonly<
-	Record<DeprecatedPluginCapability, CurrentPluginCapability>
-> = Object.freeze({
-	"network:fetch": "network:request",
-	"network:fetch:any": "network:request:unrestricted",
-	"read:content": "content:read",
-	"write:content": "content:write",
-	"read:media": "media:read",
-	"write:media": "media:write",
-	"read:users": "users:read",
-	"email:provide": "hooks.email-transport:register",
-	"email:intercept": "hooks.email-events:register",
-	"page:inject": "hooks.page-fragments:register",
-});
-
-/**
- * Type guard: is this capability one of the deprecated legacy names?
- *
- * Uses an own-property check so that prototype keys like "toString" or
- * "constructor" don't accidentally pass.
- */
-export function isDeprecatedCapability(cap: string): cap is DeprecatedPluginCapability {
-	return Object.hasOwn(CAPABILITY_RENAMES, cap);
-}
-
-/**
- * Normalize a capability string — deprecated names map to current names,
- * current names pass through unchanged. Unknown strings are returned as-is
- * so that downstream validators can produce a precise error.
- */
-export function normalizeCapability(cap: string): string {
-	if (isDeprecatedCapability(cap)) {
-		return CAPABILITY_RENAMES[cap];
-	}
-	return cap;
-}
+import type { FieldType } from "../schema/types.js";
 
-/**
- * Normalize an array of capabilities. Deduplicates by normalized name so
- * that a plugin declaring both `read:content` and `content:read` ends up
- * with a single `content:read` entry.
- */
-export function normalizeCapabilities(caps: readonly string[]): string[] {
-	const seen = new Set<string>();
-	const out: string[] = [];
-	for (const cap of caps) {
-		const normalized = normalizeCapability(cap);
-		if (!seen.has(normalized)) {
-			seen.add(normalized);
-			out.push(normalized);
-		}
-	}
-	return out;
-}
+export {
+	CAPABILITY_RENAMES,
+	isDeprecatedCapability,
+	normalizeCapabilities,
+	normalizeCapability,
+	type CurrentPluginCapability,
+	type DeprecatedPluginCapability,
+	type ManifestHookEntry,
+	type ManifestRouteEntry,
+	type PluginCapability,
+	type PluginStorageConfig,
+	type StorageCollectionConfig,
+};
 
 // =============================================================================
 // Storage Types
 // =============================================================================
-
-/**
- * Storage collection declaration in plugin definition
- */
-export interface StorageCollectionConfig {
-	/**
-	 * Fields to index for querying.
-	 * Each entry can be a single field name or an array for composite indexes.
-	 */
-	indexes: Array<string | string[]>;
-	/**
-	 * Fields with unique constraints.
-	 * Each entry can be a single field name or an array for composite unique indexes.
-	 * Unique indexes are also queryable (no need to duplicate in `indexes`).
-	 */
-	uniqueIndexes?: Array<string | string[]>;
-}
-
-/**
- * Plugin storage configuration
- */
-export type PluginStorageConfig = Record<string, StorageCollectionConfig>;
+//
+// `StorageCollectionConfig` and `PluginStorageConfig` are re-exported above
+// from `@emdash-cms/plugin-types`. The manifest carries these shapes
+// verbatim; both this package (reader) and registry-cli (writer) agree on
+// the same types via the shared package.
 
 /**
  * Query filter operators
@@ -1128,27 +997,14 @@ export interface PluginHooks {
 /**
  * Hook names
  */
-export type HookName = keyof PluginHooks;
-
 /**
- * Hook metadata entry in a plugin manifest.
- * Replaces the plain hook name string with structured metadata.
+ * Hook name in a manifest. Core's exhaustive union of recognised hook names,
+ * derived from the `PluginHooks` registry. The serialised manifest carries
+ * these as opaque strings; this stricter type is only used for type-checking
+ * inside core. `ManifestHookEntry` is re-exported from
+ * `@emdash-cms/plugin-types` near the top of this file.
  */
-export interface ManifestHookEntry {
-	name: string;
-	exclusive?: boolean;
-	priority?: number;
-	timeout?: number;
-}
-
-/**
- * Route metadata entry in a plugin manifest.
- * Replaces the plain route name string with structured metadata.
- */
-export interface ManifestRouteEntry {
-	name: string;
-	public?: boolean;
-}
+export type HookName = keyof PluginHooks;
 
 /**
  * Resolved hook with normalized config
@@ -1543,8 +1399,16 @@ export interface PluginAdminExports {
 // =============================================================================
 
 /**
- * Plugin manifest - the metadata portion of a plugin bundle
- * Used for sandboxed plugins loaded from marketplace
+ * Plugin manifest — the metadata portion of a plugin bundle, used for
+ * sandboxed plugins loaded from the marketplace.
+ *
+ * This interface is core's stricter version of the manifest contract: it
+ * uses the exhaustive `HookName` union and core's typed `PluginAdminConfig`.
+ * The wire-shape lives in `@emdash-cms/plugin-types` as `PluginManifest`
+ * with looser types (so the registry CLI can serialise hook names it
+ * doesn't know about). Both must stay structurally compatible: every value
+ * of this type must be assignable to the shared one. The static assertion
+ * below catches any drift at compile time.
  */
 export interface PluginManifest {
 	id: string;
@@ -1558,3 +1422,29 @@ export interface PluginManifest {
 	routes: Array<ManifestRouteEntry | string>;
 	admin: PluginAdminConfig;
 }
+
+// Type-level guard: core's `PluginManifest` is intentionally a SUBTYPE of
+// the shared wire shape (`@emdash-cms/plugin-types` `PluginManifest`). The
+// wire shape uses looser types like `string` for hook names so the registry
+// CLI can serialise plugins targeting hook versions this core doesn't yet
+// know about. Core narrows `string` to `HookName` and `Record<string,
+// unknown>` to `PluginAdminConfig` because core's loader actually executes
+// against those types.
+//
+// We assert one direction at compile time: `core extends shared`. The
+// reverse direction (`shared extends core`) intentionally does NOT hold
+// because shared is wider -- a manifest written against the wire shape
+// could carry a hook name core doesn't know. That runtime narrowing is the
+// job of `manifest-schema.ts` (zod-validated, called at every JSON.parse
+// of a manifest.json), not of the type system. The static check below
+// catches the OTHER failure mode: core adding a required field or
+// non-assignable type that the wire shape doesn't allow.
+//
+// `type X = never` is itself legal as a type alias, so the assertion has to
+// be in a value position (`const _check: T = true`) for the compiler to
+// error when T resolves to `never`. Don't replace this with a bare type
+// alias.
+type _AssertManifestCompat =
+	PluginManifest extends import("@emdash-cms/plugin-types").PluginManifest ? true : never;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _MANIFEST_COMPAT: _AssertManifestCompat = true;

package/src/request-cache.ts

@@ -48,8 +48,12 @@ export function requestCached<T>(key: string, fn: () => Promise<T>): Promise<T>
 	}
 
 	const existing = cache.get(key);
-	// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- heterogeneous cache; key namespacing guarantees the stored promise resolves to T
-	if (existing) return existing as Promise<T>;
+	if (existing) {
+		if (ctx.metrics) ctx.metrics.cacheHits += 1;
+		// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- heterogeneous cache; key namespacing guarantees the stored promise resolves to T
+		return existing as Promise<T>;
+	}
+	if (ctx.metrics) ctx.metrics.cacheMisses += 1;
 
 	const promise = Promise.resolve()
 		.then(fn)

package/src/request-context.ts

@@ -5,8 +5,10 @@
  * without requiring explicit parameter passing. The middleware wraps next()
  * in als.run(), making the context available to all code during rendering.
  *
- * For logged-out users with no CMS signals (no edit cookie, no preview param),
- * the middleware skips ALS entirely — zero overhead for normal traffic.
+ * Middleware always wraps each request in a context so per-request
+ * metrics (db.*, cache.*) can be surfaced via Server-Timing. The cost is
+ * one ALS frame per request — sub-microsecond, negligible compared to
+ * any real work.
  *
  * The AsyncLocalStorage instance is stored on globalThis with a Symbol key
  * to guarantee a singleton even when bundlers duplicate this module across
@@ -19,6 +21,38 @@ import { AsyncLocalStorage } from "node:async_hooks";
 
 import type { QueryRecorder } from "./database/instrumentation.js";
 
+/**
+ * Lightweight always-on counters surfaced in Server-Timing.
+ *
+ * Bumped by the Kysely log hook (db queries) and by `requestCached`
+ * (cache hits/misses). Read by middleware after the response is
+ * generated to emit `db.*` and `cache.*` Server-Timing fields.
+ *
+ * Offsets are milliseconds from `start` (the request's entry into
+ * middleware), captured via `performance.now()`.
+ */
+export interface RequestMetrics {
+	start: number;
+	dbCount: number;
+	dbTotalMs: number;
+	dbFirstOffset: number | null;
+	dbLastOffset: number | null;
+	cacheHits: number;
+	cacheMisses: number;
+}
+
+export function createRequestMetrics(start: number): RequestMetrics {
+	return {
+		start,
+		dbCount: 0,
+		dbTotalMs: 0,
+		dbFirstOffset: null,
+		dbLastOffset: null,
+		cacheHits: 0,
+		cacheMisses: 0,
+	};
+}
+
 export interface EmDashRequestContext {
 	/** Whether the current request is in visual editing mode */
 	editMode: boolean;
@@ -54,6 +88,12 @@ export interface EmDashRequestContext {
 	 * to NDJSON after the response.
 	 */
 	queryRecorder?: QueryRecorder;
+	/**
+	 * Per-request metrics for Server-Timing. Always attached by middleware
+	 * for requests that emit timing headers; bumped by the Kysely log hook
+	 * and `requestCached`.
+	 */
+	metrics?: RequestMetrics;
 }
 
 const ALS_KEY = Symbol.for("emdash:request-context");

package/src/schema/registry.ts

@@ -526,6 +526,10 @@ export class SchemaRegistry {
 			);
 		}
 
+		// `input.validation === undefined` means "no change" (keep existing);
+		// an explicit `null` clears the column.
+		const nextValidation = input.validation === undefined ? field.validation : input.validation;
+
 		return withTransaction(this.db, async (trx) => {
 			await trx
 				.updateTable("_emdash_fields")
@@ -550,11 +554,7 @@ export class SchemaRegistry {
 							: field.defaultValue !== undefined
 								? JSON.stringify(field.defaultValue)
 								: null,
-					validation: input.validation
-						? JSON.stringify(input.validation)
-						: field.validation
-							? JSON.stringify(field.validation)
-							: null,
+					validation: nextValidation ? JSON.stringify(nextValidation) : null,
 					widget: input.widget ?? field.widget ?? null,
 					options: input.options
 						? JSON.stringify(input.options)

package/src/schema/types.ts

@@ -131,6 +131,7 @@ export interface FieldValidation {
 	subFields?: RepeaterSubField[]; // For repeater fields
 	minItems?: number; // For repeater fields
 	maxItems?: number; // For repeater fields
+	allowedMimeTypes?: string[];
 }
 
 /**
@@ -238,7 +239,7 @@ export interface CreateFieldInput {
 	required?: boolean;
 	unique?: boolean;
 	defaultValue?: unknown;
-	validation?: FieldValidation;
+	validation?: FieldValidation | null;
 	widget?: string;
 	options?: FieldWidgetOptions;
 	sortOrder?: number;
@@ -256,7 +257,7 @@ export interface UpdateFieldInput {
 	required?: boolean;
 	unique?: boolean;
 	defaultValue?: unknown;
-	validation?: FieldValidation;
+	validation?: FieldValidation | null;
 	widget?: string;
 	options?: FieldWidgetOptions;
 	sortOrder?: number;

package/src/schema/zod-generator.ts

@@ -131,6 +131,12 @@ function getBaseSchema(type: FieldType, field: Field): ZodTypeAny {
 				alt: z.string().optional(),
 				width: z.number().optional(),
 				height: z.number().optional(),
+				/** Provider ID (e.g. "local", "cloudflare-images") */
+				provider: z.string().optional(),
+				/** Admin-side preview URL for external providers (not persisted by plugins) */
+				previewUrl: z.string().optional(),
+				/** Provider-specific metadata; for local media this carries storageKey */
+				meta: z.record(z.string(), z.unknown()).optional(),
 			});
 
 		case "file":
@@ -140,6 +146,10 @@ function getBaseSchema(type: FieldType, field: Field): ZodTypeAny {
 				filename: z.string().optional(),
 				mimeType: z.string().optional(),
 				size: z.number().optional(),
+				/** Provider ID (e.g. "local", "s3") */
+				provider: z.string().optional(),
+				/** Provider-specific metadata; for local media this carries storageKey */
+				meta: z.record(z.string(), z.unknown()).optional(),
 			});
 
 		case "reference":
@@ -384,10 +394,10 @@ function fieldTypeToTypeScript(field: Field): string {
 			return "PortableTextBlock[]";
 
 		case "image":
-			return "{ id: string; src?: string; alt?: string; width?: number; height?: number }";
+			return "{ id: string; src?: string; alt?: string; width?: number; height?: number; provider?: string; previewUrl?: string; meta?: Record<string, unknown> }";
 
 		case "file":
-			return "{ id: string; src?: string; filename?: string; mimeType?: string; size?: number }";
+			return "{ id: string; src?: string; filename?: string; mimeType?: string; size?: number; provider?: string; meta?: Record<string, unknown> }";
 
 		case "reference":
 			// Could be enhanced to include the referenced collection type