emdash 0.29.0 → 0.31.0

package/src/api/openapi/document.ts

@@ -37,14 +37,22 @@ import {
 	contentUpdateBody,
 	trashedContentListResponseSchema,
 } from "../schemas/content.js";
-import { mediaUsageRepairBody, mediaUsageRepairResponseSchema } from "../schemas/media-usage.js";
+import {
+	mediaUsageDetailsQuery,
+	mediaUsageDetailsResponseSchema,
+	mediaUsageRepairBody,
+	mediaUsageRepairResponseSchema,
+} from "../schemas/media-usage.js";
 import {
 	DEFAULT_MAX_UPLOAD_SIZE,
 	mediaConfirmBody,
 	mediaConfirmResponseSchema,
 	mediaExistingResponseSchema,
+	mediaGetQuery,
 	mediaListQuery,
+	mediaListReadResponseSchema,
 	mediaListResponseSchema,
+	mediaReadResponseSchema,
 	mediaResponseSchema,
 	mediaUpdateBody,
 	mediaUploadUrlBody,
@@ -661,15 +669,19 @@ function buildMediaPaths(maxUploadSize: number) {
 			get: {
 				operationId: "listMedia",
 				summary: "List media items",
+				description:
+					"Lists media items. Set `includeUsage=1` to attach coverage-aware advisory usage counts; a count may be null when the caller cannot read draft-derived usage.",
 				tags: ["Media"],
 				requestParams: { query: mediaListQuery },
 				responses: {
 					"200": {
 						description: "Media list",
-						content: { [JSON_CONTENT]: { schema: successEnvelope(mediaListResponseSchema) } },
+						content: {
+							[JSON_CONTENT]: { schema: successEnvelope(mediaListReadResponseSchema) },
+						},
 					},
 					...authErrors,
-					...standardErrors(500),
+					...standardErrors(400, 500),
 				},
 			},
 		},
@@ -677,17 +689,20 @@ function buildMediaPaths(maxUploadSize: number) {
 			get: {
 				operationId: "getMedia",
 				summary: "Get a media item",
+				description:
+					"Gets a media item. Set `includeUsage=1` to attach a coverage-aware advisory usage count; the count may be null when the caller cannot read draft-derived usage.",
 				tags: ["Media"],
 				requestParams: {
 					path: z.object({ id: z.string().meta({ description: "Media ID" }) }),
+					query: mediaGetQuery,
 				},
 				responses: {
 					"200": {
 						description: "Media item",
-						content: { [JSON_CONTENT]: { schema: successEnvelope(mediaResponseSchema) } },
+						content: { [JSON_CONTENT]: { schema: successEnvelope(mediaReadResponseSchema) } },
 					},
 					...authErrors,
-					...standardErrors(404, 500),
+					...standardErrors(400, 404, 500),
 				},
 			},
 			put: {
@@ -724,6 +739,29 @@ function buildMediaPaths(maxUploadSize: number) {
 				},
 			},
 		},
+		"/_emdash/api/media/{id}/usage": {
+			get: {
+				operationId: "getMediaUsage",
+				summary: "Get media usage details",
+				description:
+					"Returns paginated content entry groups whose current indexed sources reference a local media item. Results include aggregate coverage and are advisory during concurrent writes. Requires media read and draft-content read permission; token-authenticated callers also require admin scope.",
+				tags: ["Media"],
+				requestParams: {
+					path: z.object({ id: z.string().meta({ description: "Media ID" }) }),
+					query: mediaUsageDetailsQuery,
+				},
+				responses: {
+					"200": {
+						description: "Entry-grouped media usage details",
+						content: {
+							[JSON_CONTENT]: { schema: successEnvelope(mediaUsageDetailsResponseSchema) },
+						},
+					},
+					...authErrors,
+					...standardErrors(400, 404, 500),
+				},
+			},
+		},
 		"/_emdash/api/admin/media-usage/repair": {
 			post: {
 				operationId: "repairMediaUsage",
@@ -2351,7 +2389,7 @@ export function generateOpenApiDocument(
 			title: "EmDash CMS API",
 			version: "0.1.0",
 			description:
-				"REST API for the EmDash CMS. All endpoints require authentication and return responses wrapped in a `{ data }` envelope.",
+				"REST API for the EmDash CMS. All endpoints require authentication and return responses wrapped in a `{ success, data }` envelope.",
 		},
 		servers: [
 			{
@@ -2417,6 +2455,10 @@ export function generateOpenApiDocument(
 			},
 		],
 		components: {
+			schemas: {
+				// Preserve the previously published component while media reads use richer schemas.
+				MediaListResponse: mediaListResponseSchema,
+			},
 			securitySchemes: {
 				session: {
 					type: "apiKey",

package/src/api/parse.ts

@@ -113,21 +113,7 @@ function validate<T extends z.ZodType>(schema: T, data: unknown): ParseResult<z.
 		message: issue.message,
 	}));
 
-	return Response.json(
-		{
-			error: {
-				code: "VALIDATION_ERROR",
-				message: "Invalid request data",
-				details: { issues },
-			},
-		},
-		{
-			status: 400,
-			headers: {
-				"Cache-Control": "private, no-store",
-			},
-		},
-	);
+	return apiError("VALIDATION_ERROR", "Invalid request data", 400, { issues });
 }
 
 /**

package/src/api/public-url.ts

@@ -22,8 +22,10 @@ interface SiteUrlConfig {
  * the build. Container deployments set env vars at runtime, so we must read
  * process.env which Vite leaves untouched.
  *
- * On Cloudflare Workers process.env is unavailable (returns undefined),
- * so the fallback chain continues to url.origin.
+ * On Cloudflare Workers process.env is empty by default, so the fallback
+ * chain continues to url.origin — unless the Worker enables the
+ * `nodejs_compat_populate_process_env` compatibility flag, in which case
+ * `vars`/secrets (e.g. EMDASH_SITE_URL) are readable here too.
  *
  * Caches after first call.
  */

package/src/api/schemas/bylines.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 
-import { cursorPaginationQuery, httpUrl } from "./common.js";
+import { cursorPaginationQuery, httpUrl, localeCode } from "./common.js";
 
 /** Slug pattern: lowercase letters, digits, and hyphens; must start with a letter */
 const bylineSlugPattern = /^[a-z][a-z0-9-]*$/;
@@ -81,7 +81,7 @@ export const bylinesListQuery = cursorPaginationQuery
 		 * Rejects empty strings so the picker can't silently fetch the
 		 * unfiltered list when the admin URL has `?locale=` with no value.
 		 */
-		locale: z.string().min(1).optional(),
+		locale: localeCode.optional(),
 	})
 	.meta({ id: "BylinesListQuery" });
 
@@ -102,7 +102,7 @@ export const bylineCreateBody = z
 		 * configured `defaultLocale`) is used. Rejects empty strings — an
 		 * empty locale would create rows no resolver requests.
 		 */
-		locale: z.string().min(1).optional(),
+		locale: localeCode.optional(),
 		/**
 		 * When set, the new row joins the source byline's translation_group
 		 * rather than minting a fresh one. Requires `locale`.
@@ -126,7 +126,7 @@ export const bylineCreateBody = z
 
 export const bylineTranslationCreateBody = z
 	.object({
-		locale: z.string().min(1),
+		locale: localeCode,
 		slug: z
 			.string()
 			.min(1)

package/src/api/schemas/common.ts

@@ -53,16 +53,17 @@ export const httpUrl = z
 	.url()
 	.refine((url) => HTTP_SCHEME_RE.test(url), "URL must use http or https");
 
-/** BCP 47 locale code — language with optional script/region subtags (e.g. en, en-US, pt-BR, es-419, zh-Hant) */
-export const localeCode = z
-	.string()
-	.regex(/^[a-z]{2,3}(-[a-z0-9]{2,8})*$/i, "Invalid locale code")
-	.transform((v) => v.toLowerCase());
+/**
+ * BCP 47 locale code — language with optional script/region subtags (e.g. en, en-US, pt-BR, es-419, zh-Hant).
+ * Validation is case-insensitive, but the value is preserved verbatim because the site config, stored
+ * `locale` columns, and public query path all keep the raw BCP-47 casing.
+ */
+export const localeCode = z.string().regex(/^[a-z]{2,3}(-[a-z0-9]{2,8})*$/i, "Invalid locale code");
 
 /** Shared `?locale=xx` query shape for endpoints that filter by locale. */
 export const localeFilterQuery = z
 	.object({
-		locale: z.string().min(1).optional(),
+		locale: localeCode.optional(),
 	})
 	.meta({ id: "LocaleFilterQuery" });
 
@@ -73,6 +74,7 @@ export const localeFilterQuery = z
 /** Standard API error response */
 export const apiErrorSchema = z
 	.object({
+		success: z.literal(false).meta({ description: "Discriminant: always false for errors" }),
 		error: z.object({
 			code: z.string().meta({ description: "Machine-readable error code", example: "NOT_FOUND" }),
 			message: z.string().meta({ description: "Human-readable error message" }),
@@ -80,9 +82,12 @@ export const apiErrorSchema = z
 	})
 	.meta({ id: "ApiError" });
 
-/** Wrap a data schema in the standard success envelope: { data: T } */
+/** Wrap a data schema in the standard success envelope: { success: true, data: T } */
 export function successEnvelope<T extends z.ZodType>(dataSchema: T) {
-	return z.object({ data: dataSchema });
+	return z.object({
+		success: z.literal(true).meta({ description: "Discriminant: always true for success" }),
+		data: dataSchema,
+	});
 }
 
 /** Standard delete response */

package/src/api/schemas/media-usage.ts

@@ -2,6 +2,71 @@ import { z } from "zod";
 
 import { slugPattern } from "./common.js";
 
+export const mediaUsageCoverageStatusSchema = z
+	.enum(["complete", "never", "running", "partial", "failed", "stale", "unknown"])
+	.meta({ id: "MediaUsageCoverageStatus" });
+
+export const mediaUsageCoverageSchema = z
+	.object({
+		scope: z.literal("all_content_collections"),
+		status: mediaUsageCoverageStatusSchema,
+	})
+	.meta({ id: "MediaUsageCoverage" });
+
+export const mediaUsageSummarySchema = z
+	.object({
+		count: z.number().int().min(0).nullable(),
+		coverage: mediaUsageCoverageSchema,
+	})
+	.meta({ id: "MediaUsageSummary" });
+
+export const mediaUsageDetailsQuery = z.object({
+	cursor: z.string().min(1).max(2048).optional().meta({
+		description: "Opaque content-entry-group cursor",
+	}),
+	limit: z.coerce.number().int().min(1).max(100).optional().default(50).meta({
+		description: "Maximum number of content entry groups to return (1-100, default 50)",
+	}),
+});
+
+export const mediaUsageOccurrenceDetailSchema = z
+	.object({
+		fieldSlug: z.string(),
+		fieldPath: z.string(),
+		occurrenceIndex: z.number().int().min(0),
+		referenceType: z.enum(["image_field", "file_field", "portable_text_image", "unknown"]),
+	})
+	.meta({ id: "MediaUsageOccurrenceDetail" });
+
+export const mediaUsageSourceDetailSchema = z
+	.object({
+		variant: z.enum(["columns", "draft_overlay"]),
+		occurrences: z.array(mediaUsageOccurrenceDetailSchema),
+	})
+	.meta({ id: "MediaUsageSourceDetail" });
+
+export const mediaUsageEntryDetailSchema = z
+	.object({
+		collection: z.string(),
+		contentId: z.string(),
+		title: z.string().nullable(),
+		slug: z.string().nullable(),
+		locale: z.string().nullable(),
+		status: z.string().nullable(),
+		scheduledAt: z.string().nullable(),
+		deletedAt: z.string().nullable(),
+		sources: z.array(mediaUsageSourceDetailSchema),
+	})
+	.meta({ id: "MediaUsageEntryDetail" });
+
+export const mediaUsageDetailsResponseSchema = z
+	.object({
+		items: z.array(mediaUsageEntryDetailSchema),
+		nextCursor: z.string().optional(),
+		coverage: mediaUsageCoverageSchema,
+	})
+	.meta({ id: "MediaUsageDetailsResponse" });
+
 export const mediaUsageRepairStatusSchema = z
 	.enum(["complete", "partial", "failed", "stale"])
 	.meta({ id: "MediaUsageRepairStatus" });
@@ -46,3 +111,10 @@ export const mediaUsageRepairResponseSchema = z
 
 export type MediaUsageRepairRequest = z.infer<typeof mediaUsageRepairBody>;
 export type MediaUsageRepairResponse = z.infer<typeof mediaUsageRepairResponseSchema>;
+export type MediaUsageCoverageStatus = z.infer<typeof mediaUsageCoverageStatusSchema>;
+export type MediaUsageCoverage = z.infer<typeof mediaUsageCoverageSchema>;
+export type MediaUsageSummary = z.infer<typeof mediaUsageSummarySchema>;
+export type MediaUsageOccurrenceDetail = z.infer<typeof mediaUsageOccurrenceDetailSchema>;
+export type MediaUsageSourceDetail = z.infer<typeof mediaUsageSourceDetailSchema>;
+export type MediaUsageEntryDetail = z.infer<typeof mediaUsageEntryDetailSchema>;
+export type MediaUsageDetailsResponse = z.infer<typeof mediaUsageDetailsResponseSchema>;

package/src/api/schemas/media.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 
 import { cursorPaginationQuery } from "./common.js";
+import { mediaUsageSummarySchema } from "./media-usage.js";
 
 // ---------------------------------------------------------------------------
 // Media: Input schemas
@@ -23,9 +24,20 @@ export const mediaListQuery = cursorPaginationQuery
 		mimeType: mimeTypeFilter,
 		/** Case-insensitive filename substring search (also matches extensions). */
 		q: z.string().trim().min(1).max(200).optional(),
+		includeUsage: z.literal("1").optional().meta({
+			description: "Include a coverage-aware usage summary on each media item",
+		}),
 	})
 	.meta({ id: "MediaListQuery" });
 
+export const mediaGetQuery = z
+	.object({
+		includeUsage: z.literal("1").optional().meta({
+			description: "Include a coverage-aware usage summary on the media item",
+		}),
+	})
+	.meta({ id: "MediaGetQuery" });
+
 export const mediaUpdateBody = z
 	.object({
 		alt: z.string().optional(),
@@ -46,7 +58,7 @@ export function formatFileSize(bytes: number): string {
 
 // Matches a full MIME type (type/subtype) with an optional semicolon-delimited
 // parameter section. Forbids CR/LF to prevent header injection.
-const CONTENT_TYPE_RE = /^[a-z0-9][a-z0-9!#$&^_+\-.]*\/[a-z0-9!#$&^_+\-.]+(\s*;[^\r\n]*)?$/i;
+export const CONTENT_TYPE_RE = /^[a-z0-9][a-z0-9!#$&^_+\-.]*\/[a-z0-9!#$&^_+\-.]+(\s*;[^\r\n]*)?$/i;
 
 export function mediaUploadUrlBody(maxSize: number) {
 	if (!Number.isFinite(maxSize) || maxSize <= 0) {
@@ -115,6 +127,25 @@ export const mediaResponseSchema = z
 	.object({ item: mediaItemSchema })
 	.meta({ id: "MediaResponse" });
 
+export const mediaReadItemSchema = mediaItemSchema
+	.extend({ usage: mediaUsageSummarySchema.optional() })
+	.meta({ id: "MediaReadItem" });
+
+export const mediaReadResponseSchema = z
+	.object({ item: mediaReadItemSchema })
+	.meta({ id: "MediaReadResponse" });
+
+export const mediaListReadItemSchema = mediaReadItemSchema
+	.extend({ url: z.string() })
+	.meta({ id: "MediaListReadItem" });
+
+export const mediaListReadResponseSchema = z
+	.object({
+		items: z.array(mediaListReadItemSchema),
+		nextCursor: z.string().optional(),
+	})
+	.meta({ id: "MediaListReadResponse" });
+
 export const mediaListResponseSchema = z
 	.object({
 		items: z.array(mediaItemSchema),

package/src/api/schemas/menus.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 
 import { isSafeHref } from "../../utils/url.js";
+import { localeCode } from "./common.js";
 
 // ---------------------------------------------------------------------------
 // Menus: Input schemas
@@ -24,7 +25,7 @@ export const createMenuBody = z
 	.object({
 		name: z.string().min(1),
 		label: z.string().min(1),
-		locale: z.string().min(1).optional(),
+		locale: localeCode.optional(),
 		/** When set, clones the items from the source menu. The new menu joins
 		 * the source's translation_group. */
 		translationOf: z.string().min(1).optional(),

package/src/api/schemas/relations.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 
+import { localeCode } from "./common.js";
+
 const slugPattern = /^[a-z][a-z0-9_]*$/;
 const collectionSlug = z
 	.string()
@@ -18,7 +20,7 @@ export const createRelationBody = z
 		childCollection: collectionSlug.optional(),
 		parentLabel: z.string().min(1).max(200),
 		childLabel: z.string().min(1).max(200),
-		locale: z.string().min(1).optional(),
+		locale: localeCode.optional(),
 		translationOf: z.string().min(1).optional(),
 	})
 	// A translation inherits its structural fields (name, parentCollection,

package/src/api/schemas/taxonomies.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 
+import { localeCode } from "./common.js";
+
 // ---------------------------------------------------------------------------
 // Taxonomy definitions: Input schemas
 // ---------------------------------------------------------------------------
@@ -24,7 +26,7 @@ export const createTaxonomyDefBody = z
 			.max(100)
 			.optional()
 			.default([]),
-		locale: z.string().min(1).optional(),
+		locale: localeCode.optional(),
 		translationOf: z.string().min(1).optional(),
 	})
 	.meta({ id: "CreateTaxonomyDefBody" });
@@ -39,7 +41,7 @@ export const createTermBody = z
 		label: z.string().min(1),
 		parentId: z.string().nullish(),
 		description: z.string().optional(),
-		locale: z.string().min(1).optional(),
+		locale: localeCode.optional(),
 		translationOf: z.string().min(1).optional(),
 	})
 	.meta({ id: "CreateTermBody" });

package/src/astro/integration/index.ts

@@ -195,6 +195,34 @@ export function resolveImageEndpoint(opts: {
 	};
 }
 
+/**
+ * Warn when `@astrojs/react` is not registered in the host's `integrations`.
+ *
+ * The admin SPA is a React app hydrated via `client:only="react"`. Without the
+ * React integration the build succeeds and the admin route returns 200, but the
+ * bundle never hydrates -- the page sits on "Loading EmDash..." forever with no
+ * error anywhere (#962). Checked in `astro:config:done` so integrations added
+ * by other integrations are visible too.
+ *
+ * @internal Exported for unit testing.
+ */
+export function missingReactIntegrationWarning(
+	integrations: readonly { name: string }[],
+): string | undefined {
+	if (integrations.some((integration) => integration.name === "@astrojs/react")) {
+		return undefined;
+	}
+	return (
+		`@astrojs/react is not registered in your Astro config. The EmDash admin UI ` +
+		`will not hydrate without it (the page stays on "Loading EmDash..."). ` +
+		`Add it to your integrations:\n\n` +
+		`  import react from "@astrojs/react";\n` +
+		`  export default defineConfig({\n` +
+		`    integrations: [react(), emdash({ ... })],\n` +
+		`  });`
+	);
+}
+
 // Terminal formatting
 const dim = (s: string) => `\x1b[2m${s}\x1b[22m`;
 const bold = (s: string) => `\x1b[1m${s}\x1b[22m`;
@@ -381,6 +409,12 @@ export function emdash(config: EmDashConfig = {}): AstroIntegration {
 				if (astroVersion !== undefined) {
 					serializableConfig.astroVersion = astroVersion;
 				}
+				// EmDashHead must not access Astro.csp when the host has disabled
+				// Astro's built-in CSP runtime; Astro logs a warning for that access.
+				serializableConfig.astroCspEnabled = Boolean(astroConfig.security.csp);
+				// Expose Astro's trailingSlash routing policy so plugins can build
+				// URLs (sitemap/canonical/hreflang) that match what the site serves.
+				serializableConfig.trailingSlash = astroConfig.trailingSlash;
 				// Extract i18n config from Astro config
 				// Astro locales can be strings OR { path, codes } objects — normalize to paths
 				if (astroConfig.i18n) {
@@ -556,6 +590,10 @@ export function emdash(config: EmDashConfig = {}): AstroIntegration {
 				// dev server is listening (see astro:server:setup), since the
 				// port isn't known yet here. Nothing useful to print for build.
 			},
+			"astro:config:done": ({ config: finalConfig, logger }) => {
+				const warning = missingReactIntegrationWarning(finalConfig.integrations);
+				if (warning) logger.warn(warning);
+			},
 			"astro:server:setup": ({ server, logger }) => {
 				// Print route info with absolute, clickable URLs once the server
 				// is listening. Only in `astro dev` -- the dev-bypass shortcut is

package/src/astro/integration/routes.ts

@@ -213,6 +213,11 @@ export function injectCoreRoutes(
 		entrypoint: resolveRoute("api/media/[id].ts"),
 	});
 
+	injectRoute({
+		pattern: "/_emdash/api/media/[id]/usage",
+		entrypoint: resolveRoute("api/media/[id]/usage.ts"),
+	});
+
 	injectRoute({
 		pattern: "/_emdash/api/media/[id]/confirm",
 		entrypoint: resolveRoute("api/media/[id]/confirm.ts"),
@@ -346,6 +351,27 @@ export function injectCoreRoutes(
 		entrypoint: resolveRoute("api/settings/email.ts"),
 	});
 
+	// Backup routes
+	injectRoute({
+		pattern: "/_emdash/api/settings/backups",
+		entrypoint: resolveRoute("api/settings/backups/index.ts"),
+	});
+
+	injectRoute({
+		pattern: "/_emdash/api/settings/backups/export",
+		entrypoint: resolveRoute("api/settings/backups/export.ts"),
+	});
+
+	injectRoute({
+		pattern: "/_emdash/api/settings/backups/archives",
+		entrypoint: resolveRoute("api/settings/backups/archives/index.ts"),
+	});
+
+	injectRoute({
+		pattern: "/_emdash/api/settings/backups/archives/[name]",
+		entrypoint: resolveRoute("api/settings/backups/archives/[name].ts"),
+	});
+
 	// Snapshot route (for DO preview database population)
 	injectRoute({
 		pattern: "/_emdash/api/snapshot",
@@ -398,6 +424,15 @@ export function injectCoreRoutes(
 		pattern: "/_emdash/api/admin/plugins/[id]/disable",
 		entrypoint: resolveRoute("api/admin/plugins/[id]/disable.ts"),
 	});
+	injectRoute({
+		pattern: "/_emdash/api/admin/plugins/[id]/mcp",
+		entrypoint: resolveRoute("api/admin/plugins/[id]/mcp.ts"),
+	});
+
+	injectRoute({
+		pattern: "/_emdash/api/admin/plugins/[id]/settings",
+		entrypoint: resolveRoute("api/admin/plugins/[id]/settings.ts"),
+	});
 
 	// Marketplace plugin routes
 	injectRoute({

package/src/astro/integration/runtime.ts

@@ -13,8 +13,10 @@ import type { MediaProviderDescriptor } from "../../media/types.js";
 import type { ObjectCacheDescriptor } from "../../object-cache/types.js";
 import type {
 	FieldWidgetConfig,
+	PluginMcpManifestConfig,
 	PortableTextBlockConfig,
 	ResolvedPlugin,
+	SettingField,
 } from "../../plugins/types.js";
 import type { ExperimentalConfig } from "../../registry/types.js";
 import type { StorageDescriptor } from "../storage/types.js";
@@ -103,6 +105,8 @@ export interface PluginDescriptor<TOptions = Record<string, unknown>> {
 	adminPages?: PluginAdminPage[];
 	/** Dashboard widgets */
 	adminWidgets?: PluginDashboardWidget[];
+	/** Settings schema for the auto-generated admin settings form */
+	settingsSchema?: Record<string, SettingField>;
 	/**
 	 * Portable Text block types this plugin contributes to the editor.
 	 * Declarative (Block Kit) — surfaced in the admin slash menu and consumed
@@ -131,6 +135,8 @@ export interface PluginDescriptor<TOptions = Record<string, unknown>> {
 	 * Sandboxed plugins can only access declared collections.
 	 */
 	storage?: Record<string, StorageCollectionDeclaration>;
+	/** Serialized MCP declarations emitted by the plugin build. */
+	mcp?: PluginMcpManifestConfig;
 }
 
 /**