emdash 0.29.0 → 0.30.0

package/src/plugin-types.ts

@@ -38,6 +38,9 @@
  * per-hook return contracts so misuse fails at compile time.
  */
 
+import type { Permission } from "@emdash-cms/auth";
+import type { ZodType } from "zod";
+
 import type {
 	CommentAfterCreateEvent,
 	CommentAfterCreateHandler,
@@ -200,9 +203,24 @@ export type RouteEntry =
 	| {
 			handler: RouteHandler;
 			public?: boolean;
+			/**
+			 * Cache-Control value for successful GET responses. Only honored on
+			 * routes that are also `public: true` — authenticated responses
+			 * always keep `private, no-store`.
+			 */
+			cacheControl?: string;
 			input?: unknown;
+			permission?: Permission;
 	  };
 
+export interface SandboxedMcpTool {
+	description: string;
+	route: string;
+	input: ZodType;
+	output?: ZodType;
+	destructive?: boolean;
+}
+
 /**
  * The shape of a sandboxed plugin's default export.
  *
@@ -217,6 +235,7 @@ export interface SandboxedPlugin {
 		[K in keyof HookHandlers]?: HookEntry<K>;
 	};
 	routes?: Record<string, RouteEntry>;
+	mcp?: { tools: Record<string, SandboxedMcpTool> };
 }
 
 /**

package/src/plugin-utils.ts

@@ -44,13 +44,14 @@ export function getPublicPluginApiRouteHandler(
 }
 
 /**
- * Parse an API response, unwrapping the `{ data: T }` envelope.
+ * Parse an API response, unwrapping the `{ success, data: T }` envelope.
  *
- * All plugin API routes return success responses wrapped in `{ data: ... }`
- * by `apiSuccess()`. This helper unwraps that envelope and handles errors.
+ * All plugin API routes return success responses wrapped in
+ * `{ success: true, data: ... }` by `apiSuccess()`. This helper unwraps that
+ * envelope and handles errors.
  *
  * On error responses (non-2xx), throws an Error with the server's message
- * (from `{ error: { message } }`) or the fallback message.
+ * (from `{ success: false, error: { message } }`) or the fallback message.
  *
  * @example
  * ```ts
@@ -72,8 +73,9 @@ export async function parseApiResponse<T>(
 /**
  * Extract the error message from a failed API response.
  *
- * Error responses use the shape `{ error: { code, message } }`. This helper
- * parses that body and returns the message, falling back to the provided default.
+ * Error responses use the shape `{ success: false, error: { code, message } }`.
+ * This helper parses that body and returns the message, falling back to the
+ * provided default.
  * Swallows JSON parse failures gracefully.
  *
  * @example

package/src/plugins/adapt-sandbox-entry.ts

@@ -108,7 +108,9 @@ function resolveSandboxedHook(entry: AnyHookEntry, pluginId: string): ResolvedHo
 function normalizeRouteEntry(entry: RouteEntry): {
 	handler: RouteHandler;
 	public?: boolean;
+	cacheControl?: string;
 	input?: PluginRoute["input"];
+	permission?: PluginRoute["permission"];
 } {
 	if (typeof entry === "function") {
 		return { handler: entry };
@@ -116,6 +118,8 @@ function normalizeRouteEntry(entry: RouteEntry): {
 	return {
 		handler: entry.handler,
 		public: entry.public,
+		permission: entry.permission,
+		cacheControl: entry.cacheControl,
 		// eslint-disable-next-line typescript-eslint/no-unsafe-type-assertion -- RouteEntry.input is intentionally `unknown` (sandboxed plugins) and validated by the runtime at invocation time
 		input: entry.input as PluginRoute["input"],
 	};
@@ -196,10 +200,18 @@ export function adaptSandboxEntry(
 	if (definition.routes) {
 		for (const [routeName, rawEntry] of Object.entries(definition.routes)) {
 			const normalized = normalizeRouteEntry(rawEntry);
-			const { handler, public: publicFlag, input: inputSchema } = normalized;
+			const {
+				handler,
+				public: publicFlag,
+				cacheControl,
+				input: inputSchema,
+				permission,
+			} = normalized;
 			resolvedRoutes[routeName] = {
 				input: inputSchema,
 				public: publicFlag,
+				permission,
+				cacheControl,
 				handler: async (ctx) => {
 					// `ctx.request` is a real WHATWG `Request` (this is the
 					// in-process adapter; the worker-sandbox adapter handles
@@ -290,6 +302,9 @@ export function adaptSandboxEntry(
 	if (descriptor.adminWidgets) {
 		admin.widgets = descriptor.adminWidgets;
 	}
+	if (descriptor.settingsSchema) {
+		admin.settingsSchema = descriptor.settingsSchema;
+	}
 	if (descriptor.portableTextBlocks) {
 		admin.portableTextBlocks = descriptor.portableTextBlocks;
 	}
@@ -305,6 +320,20 @@ export function adaptSandboxEntry(
 		storage,
 		hooks: resolvedHooks,
 		routes: resolvedRoutes,
+		mcp: {
+			tools: Object.fromEntries(
+				Object.entries(definition.mcp?.tools ?? {}).map(([name, tool]) => [
+					name,
+					{
+						description: tool.description,
+						route: tool.route,
+						input: tool.input,
+						output: tool.output,
+						destructive: tool.destructive,
+					},
+				]),
+			),
+		},
 		admin,
 	};
 }

package/src/plugins/context.ts

@@ -252,6 +252,7 @@ export function createContentAccess(db: Kysely<Database>): ContentAccess {
 				updatedAt: item.updatedAt,
 				locale: item.locale,
 				publishedAt: item.publishedAt,
+				scheduledAt: item.scheduledAt,
 			};
 
 			if (await seoRepo.isEnabled(collection)) {
@@ -292,6 +293,7 @@ export function createContentAccess(db: Kysely<Database>): ContentAccess {
 				updatedAt: item.updatedAt,
 				locale: item.locale,
 				publishedAt: item.publishedAt,
+				scheduledAt: item.scheduledAt,
 			}));
 
 			if (items.length > 0 && (await seoRepo.isEnabled(collection))) {
@@ -398,6 +400,7 @@ export function createContentAccessWithWrite(db: Kysely<Database>): ContentAcces
 						updatedAt: item.updatedAt,
 						locale: item.locale,
 						publishedAt: item.publishedAt,
+						scheduledAt: item.scheduledAt,
 					};
 
 					if (hasSeo) {
@@ -455,6 +458,7 @@ export function createContentAccessWithWrite(db: Kysely<Database>): ContentAcces
 						updatedAt: item.updatedAt,
 						locale: item.locale,
 						publishedAt: item.publishedAt,
+						scheduledAt: item.scheduledAt,
 					};
 
 					if (hasSeo) {
@@ -878,6 +882,8 @@ export interface SiteInfoOptions {
 	siteUrl?: string;
 	/** Site locale from options table */
 	locale?: string;
+	/** Astro's `trailingSlash` config (from `virtual:emdash/config`). */
+	trailingSlash?: "always" | "never" | "ignore";
 }
 
 /**
@@ -893,6 +899,7 @@ export function createSiteInfo(options: SiteInfoOptions): SiteInfo {
 		name: options.siteName ?? "",
 		url: (options.siteUrl ?? "").replace(TRAILING_SLASH_RE, ""), // strip trailing slash
 		locale: options.locale ?? "en",
+		trailingSlash: options.trailingSlash ?? "ignore", // Astro's default
 	};
 }
 

package/src/plugins/define-plugin.ts

@@ -22,6 +22,8 @@ import type {
 	PluginStorageConfig,
 } from "./types.js";
 
+const MCP_TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
+
 /**
  * Define a native EmDash plugin.
  *
@@ -110,6 +112,7 @@ function defineNativePlugin<TStorage extends PluginStorageConfig>(
 		allowedHosts = [],
 		hooks = {},
 		routes = {},
+		mcp = { tools: {} },
 		admin = {},
 	} = definition;
 
@@ -132,6 +135,18 @@ function defineNativePlugin<TStorage extends PluginStorageConfig>(
 		throw new Error(`Invalid plugin version "${version}". Must be semver format (e.g., "1.0.0").`);
 	}
 
+	for (const [name, tool] of Object.entries(mcp.tools)) {
+		if (!MCP_TOOL_NAME_PATTERN.test(name)) {
+			throw new Error(`Invalid MCP tool name "${name}" in plugin "${id}".`);
+		}
+		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.permission) {
+			throw new Error(`MCP route "${tool.route}" must declare a permission.`);
+		}
+	}
+
 	// 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
@@ -202,6 +217,7 @@ function defineNativePlugin<TStorage extends PluginStorageConfig>(
 		storage,
 		hooks: resolvedHooks,
 		routes,
+		mcp,
 		admin,
 	};
 }

package/src/plugins/manifest-schema.ts

@@ -8,6 +8,7 @@
  * - Marketplace ingest extends this with publishing-specific fields
  */
 
+import { Permissions } from "@emdash-cms/auth";
 import {
 	capabilitiesToDeclaredAccess,
 	declaredAccessToCapabilities,
@@ -137,6 +138,27 @@ const routeNamePattern = /^[a-zA-Z0-9][a-zA-Z0-9_\-/]*$/;
 const manifestRouteEntrySchema = z.object({
 	name: z.string().min(1).regex(routeNamePattern, "Route name must be a safe path segment"),
 	public: z.boolean().optional(),
+	permission: z
+		.string()
+		.refine((permission) => permission in Permissions)
+		.optional(),
+	cacheControl: z.string().min(1).optional(),
+});
+
+const pluginJsonSchema = z.record(z.string(), z.unknown());
+const mcpToolNamePattern = /^[a-zA-Z0-9_-]+$/;
+const pluginMcpConfigSchema = z.object({
+	tools: z.array(
+		z.object({
+			name: z.string().min(1).max(64).regex(mcpToolNamePattern, "Invalid MCP tool name"),
+			description: z.string().min(1),
+			route: z.string().min(1).regex(routeNamePattern, "Route name must be a safe path segment"),
+			permission: z.string().refine((permission) => permission in Permissions),
+			destructive: z.boolean(),
+			inputSchema: pluginJsonSchema,
+			outputSchema: pluginJsonSchema.optional(),
+		}),
+	),
 });
 
 // ── Sub-schemas ─────────────────────────────────────────────────
@@ -307,6 +329,7 @@ export const pluginManifestSchema = z.object({
 			manifestRouteEntrySchema,
 		]),
 	),
+	mcp: pluginMcpConfigSchema.optional(),
 	admin: pluginAdminConfigSchema,
 });
 
@@ -349,9 +372,13 @@ export function normalizeManifestHook(
 /**
  * Normalize a manifest route entry — plain strings become `{ name }` objects.
  */
-export function normalizeManifestRoute(entry: string | { name: string; public?: boolean }): {
+export function normalizeManifestRoute(
+	entry: string | { name: string; public?: boolean; permission?: string; cacheControl?: string },
+): {
 	name: string;
 	public?: boolean;
+	permission?: string;
+	cacheControl?: string;
 } {
 	if (typeof entry === "string") {
 		return { name: entry };

package/src/plugins/routes.ts

@@ -54,6 +54,32 @@ function guardConsumedRequestBody(request: Request): Request {
  */
 export interface RouteMeta {
 	public: boolean;
+	permission?: string;
+	/**
+	 * Cache-Control value for successful GET responses. Only ever set for
+	 * public routes — authenticated responses must stay `private, no-store`.
+	 */
+	cacheControl?: string;
+}
+
+/**
+ * Build RouteMeta from a route's `public`/`cacheControl` flags. Single source
+ * of truth for the "cacheControl is only ever exposed on public routes"
+ * invariant — used for trusted routes and manifest-declared sandboxed routes.
+ */
+export function buildRouteMeta(route: {
+	public?: boolean;
+	permission?: string;
+	cacheControl?: string;
+}): RouteMeta {
+	const meta: RouteMeta = { public: route.public === true };
+	if (route.permission !== undefined) meta.permission = route.permission;
+	// Private responses are per-user and must never become cacheable, even if
+	// a route sets both flags.
+	if (meta.public && typeof route.cacheControl === "string" && route.cacheControl.length > 0) {
+		meta.cacheControl = route.cacheControl;
+	}
+	return meta;
 }
 
 /**
@@ -199,7 +225,7 @@ export class PluginRouteHandler {
 	getRouteMeta(name: string): RouteMeta | null {
 		const route: PluginRoute | undefined = this.plugin.routes[name];
 		if (!route) return null;
-		return { public: route.public === true };
+		return buildRouteMeta(route);
 	}
 }
 

package/src/plugins/sandbox/runner-options.ts

@@ -0,0 +1,16 @@
+import { createSiteInfo, type SiteInfoOptions } from "../context.js";
+import type { SandboxOptions } from "./types.js";
+
+/**
+ * Build platform sandbox options with the same normalized site context used
+ * by trusted plugin hooks and routes.
+ */
+export function createSandboxRunnerOptions(
+	options: Omit<SandboxOptions, "siteInfo">,
+	siteInfo?: SiteInfoOptions,
+): SandboxOptions {
+	return {
+		...options,
+		siteInfo: createSiteInfo(siteInfo ?? {}),
+	};
+}

package/src/plugins/sandbox/types.ts

@@ -72,7 +72,12 @@ export interface SandboxOptions {
 	/** Default resource limits */
 	limits?: ResourceLimits;
 	/** Site info for plugin context (injected into wrapper at generation time) */
-	siteInfo?: { name: string; url: string; locale: string };
+	siteInfo?: {
+		name: string;
+		url: string;
+		locale: string;
+		trailingSlash?: "always" | "never" | "ignore";
+	};
 	/** Email send callback, wired from the EmailPipeline by the runtime */
 	emailSend?: SandboxEmailSendCallback;
 	/**

package/src/plugins/state.ts

@@ -49,6 +49,8 @@ export interface PluginState {
 	 * `packages/core/src/registry/plugin-id.ts`.
 	 */
 	registrySlug: string | null;
+	mcpToolsEnabled: boolean;
+	mcpToolsConsent: string | null;
 }
 
 /**
@@ -121,6 +123,8 @@ export class PluginStateRepository {
 			description?: string;
 			registryPublisherDid?: string;
 			registrySlug?: string;
+			mcpToolsEnabled?: boolean;
+			mcpToolsConsent?: string | null;
 		},
 	): Promise<PluginState> {
 		const now = new Date().toISOString();
@@ -128,7 +132,7 @@ export class PluginStateRepository {
 
 		if (existing) {
 			// Update existing state
-			const updates: Record<string, string | null> = {
+			const updates: Record<string, string | number | null> = {
 				status,
 				version,
 			};
@@ -155,6 +159,12 @@ export class PluginStateRepository {
 			if (opts?.registrySlug !== undefined) {
 				updates.registry_slug = opts.registrySlug;
 			}
+			if (opts?.mcpToolsEnabled !== undefined) {
+				updates.mcp_tools_enabled = opts.mcpToolsEnabled ? 1 : 0;
+			}
+			if (opts?.mcpToolsConsent !== undefined) {
+				updates.mcp_tools_consent = opts.mcpToolsConsent;
+			}
 
 			await this.db
 				.updateTable("_plugin_state")
@@ -179,6 +189,8 @@ export class PluginStateRepository {
 					description: opts?.description ?? null,
 					registry_publisher_did: opts?.registryPublisherDid ?? null,
 					registry_slug: opts?.registrySlug ?? null,
+					mcp_tools_enabled: opts?.mcpToolsEnabled ? 1 : 0,
+					mcp_tools_consent: opts?.mcpToolsConsent ?? null,
 				})
 				.execute();
 		}
@@ -234,6 +246,8 @@ interface PluginStateRow {
 	description: string | null;
 	registry_publisher_did: string | null;
 	registry_slug: string | null;
+	mcp_tools_enabled: number;
+	mcp_tools_consent: string | null;
 }
 
 function rowToPluginState(row: PluginStateRow): PluginState {
@@ -250,5 +264,7 @@ function rowToPluginState(row: PluginStateRow): PluginState {
 		description: row.description ?? null,
 		registryPublisherDid: row.registry_publisher_did ?? null,
 		registrySlug: row.registry_slug ?? null,
+		mcpToolsEnabled: row.mcp_tools_enabled === 1,
+		mcpToolsConsent: row.mcp_tools_consent ?? null,
 	};
 }

package/src/plugins/storage-query.ts

@@ -8,8 +8,7 @@
 
 import type { Kysely } from "kysely";
 
-import { jsonExtractExpr } from "../database/dialect-helpers.js";
-import { validateJsonFieldName } from "../database/validate.js";
+import { pluginDataExtractExpr, pluginDataOrderExpr } from "../database/dialect-helpers.js";
 import type { WhereClause, WhereValue, RangeFilter, InFilter, StartsWithFilter } from "./types.js";
 
 /**
@@ -50,6 +49,15 @@ export function isStartsWithFilter(value: WhereValue): value is StartsWithFilter
 	return "startsWith" in value && typeof value.startsWith === "string";
 }
 
+/**
+ * Escape LIKE pattern metacharacters so a startsWith prefix matches
+ * literally. Without this, `%` and `_` in the prefix act as wildcards
+ * (e.g. `{ startsWith: "50%" }` would match "50x off").
+ */
+export function escapeLikePattern(value: string): string {
+	return value.replaceAll("\\", "\\\\").replaceAll("%", "\\%").replaceAll("_", "\\_");
+}
+
 /**
  * Get the set of indexed fields from index declarations
  */
@@ -108,15 +116,34 @@ export function validateOrderByClause(
 }
 
 /**
- * SQL expression for extracting JSON field.
+ * SQL expression for extracting a queryable field from the `_plugin_storage.data`
+ * column.
  *
- * Validates the field name before interpolation to prevent SQL injection
- * via crafted JSON path expressions.
+ * Delegates to `pluginDataExtractExpr`, which validates the field name before
+ * interpolation and applies the dialect-correct extraction: a `::jsonb` cast on
+ * Postgres (the `data` column is `text`) plus an optional type-guarded
+ * `::numeric` cast so numeric comparisons don't fall back to lexical text
+ * ordering.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Kysely instance
-export function jsonExtract(db: Kysely<any>, field: string): string {
-	validateJsonFieldName(field, "query field name");
-	return jsonExtractExpr(db, "data", field);
+export function jsonExtract(
+	db: Kysely<any>,
+	field: string,
+	options?: { numeric?: boolean },
+): string {
+	return pluginDataExtractExpr(db, field, options);
+}
+
+/**
+ * SQL expression for ordering by a `_plugin_storage.data` field.
+ *
+ * Delegates to `pluginDataOrderExpr`, which orders over the jsonb-native value
+ * on Postgres so numeric fields sort numerically (not lexically) while staying
+ * total across heterogeneous data. SQLite keeps `json_extract` (already numeric).
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Kysely instance
+export function jsonOrderExtract(db: Kysely<any>, field: string): string {
+	return pluginDataOrderExpr(db, field);
 }
 
 /**
@@ -128,33 +155,45 @@ export function buildCondition(
 	field: string,
 	value: WhereValue,
 ): { sql: string; params: unknown[] } {
-	const extract = jsonExtract(db, field);
+	// Numeric-vs-text is decided per condition from the JS type of the bound
+	// value. On Postgres a text extract compared to a bound number would sort
+	// lexically (`'9' >= '10'` is TRUE); a type-guarded `::numeric` cast on the
+	// extract fixes it. String/boolean operands keep text comparison. SQLite is
+	// unaffected — `json_extract` already returns a typed value.
+	const extractFor = (numeric: boolean): string => jsonExtract(db, field, { numeric });
 
 	if (value === null) {
-		return { sql: `${extract} IS NULL`, params: [] };
+		return { sql: `${extractFor(false)} IS NULL`, params: [] };
 	}
 
-	if (typeof value === "string" || typeof value === "number") {
-		return { sql: `${extract} = ?`, params: [value] };
+	if (typeof value === "number") {
+		return { sql: `${extractFor(true)} = ?`, params: [value] };
+	}
+
+	if (typeof value === "string") {
+		return { sql: `${extractFor(false)} = ?`, params: [value] };
 	}
 
 	if (typeof value === "boolean") {
 		// JSON booleans are stored as true/false strings
-		return { sql: `${extract} = ?`, params: [value] };
+		return { sql: `${extractFor(false)} = ?`, params: [value] };
 	}
 
 	if (isInFilter(value)) {
+		const numeric = value.in.length > 0 && value.in.every((v) => typeof v === "number");
 		const placeholders = value.in.map(() => "?").join(", ");
 		return {
-			sql: `${extract} IN (${placeholders})`,
+			sql: `${extractFor(numeric)} IN (${placeholders})`,
 			params: value.in,
 		};
 	}
 
 	if (isStartsWithFilter(value)) {
+		// ESCAPE '\' works on both SQLite and PostgreSQL. startsWith is a string
+		// operation, so always compare as text.
 		return {
-			sql: `${extract} LIKE ?`,
-			params: [`${value.startsWith}%`],
+			sql: `${extractFor(false)} LIKE ? ESCAPE '\\'`,
+			params: [`${escapeLikePattern(value.startsWith)}%`],
 		};
 	}
 
@@ -162,22 +201,17 @@ export function buildCondition(
 		const conditions: string[] = [];
 		const params: unknown[] = [];
 
-		if (value.gt !== undefined) {
-			conditions.push(`${extract} > ?`);
-			params.push(value.gt);
-		}
-		if (value.gte !== undefined) {
-			conditions.push(`${extract} >= ?`);
-			params.push(value.gte);
-		}
-		if (value.lt !== undefined) {
-			conditions.push(`${extract} < ?`);
-			params.push(value.lt);
-		}
-		if (value.lte !== undefined) {
-			conditions.push(`${extract} <= ?`);
-			params.push(value.lte);
-		}
+		// Each bound is cast to numeric only when its own operand is a number, so
+		// a mixed range (e.g. a string lower bound) stays correct per side.
+		const pushBound = (op: string, bound: string | number): void => {
+			conditions.push(`${extractFor(typeof bound === "number")} ${op} ?`);
+			params.push(bound);
+		};
+
+		if (value.gt !== undefined) pushBound(">", value.gt);
+		if (value.gte !== undefined) pushBound(">=", value.gte);
+		if (value.lt !== undefined) pushBound("<", value.lt);
+		if (value.lte !== undefined) pushBound("<=", value.lte);
 
 		return {
 			sql: conditions.join(" AND "),
@@ -229,7 +263,7 @@ export function buildOrderByClause(
 	const clauses: string[] = [];
 
 	for (const [field, direction] of Object.entries(orderBy)) {
-		clauses.push(`${jsonExtract(db, field)} ${direction.toUpperCase()}`);
+		clauses.push(`${jsonOrderExtract(db, field)} ${direction.toUpperCase()}`);
 	}
 
 	if (clauses.length === 0) {