emdash 0.28.1 → 0.30.0

package/src/api/handlers/plugin-settings.ts

@@ -0,0 +1,218 @@
+/**
+ * Plugin settings handlers
+ *
+ * Auto-generated settings UI backend for plugins that declare
+ * `admin.settingsSchema`. Values are stored in the options table under
+ * `plugin:{pluginId}:settings:{key}` — the same keys the plugin itself
+ * reads via `ctx.kv.get("settings:{key}")`.
+ */
+
+import type { Kysely } from "kysely";
+
+import { OptionsRepository } from "../../database/repositories/options.js";
+import { withTransaction } from "../../database/transaction.js";
+import type { Database } from "../../database/types.js";
+import type { SandboxedPluginEntry } from "../../emdash-runtime.js";
+import type { ResolvedPlugin, SettingField } from "../../plugins/types.js";
+import { ErrorCode } from "../errors.js";
+import type { ApiResult } from "../types.js";
+
+export interface PluginSettingsResponse {
+	/** The plugin's declared settings schema, keyed by setting name */
+	schema: Record<string, SettingField>;
+	/**
+	 * Current values keyed by setting name. Secret fields are never
+	 * included here — check `secretsSet` instead.
+	 */
+	values: Record<string, unknown>;
+	/** For secret fields: whether a value is currently stored */
+	secretsSet: Record<string, boolean>;
+}
+
+function settingsKey(pluginId: string, key: string): string {
+	return `plugin:${pluginId}:settings:${key}`;
+}
+
+/**
+ * Resolve a plugin's settings schema from either the configured
+ * (in-process) plugin list or the statically-sandboxed entries.
+ * Returns null when the plugin doesn't exist, undefined-equivalent
+ * empty object when it declares no schema.
+ */
+export function getPluginSettingsSchema(
+	configuredPlugins: ResolvedPlugin[],
+	sandboxedPluginEntries: SandboxedPluginEntry[],
+	pluginId: string,
+): Record<string, SettingField> | null {
+	const plugin = configuredPlugins.find((p) => p.id === pluginId);
+	if (plugin) return plugin.admin.settingsSchema ?? {};
+
+	const sandboxed = sandboxedPluginEntries.find((e) => e.id === pluginId);
+	if (sandboxed) return sandboxed.settingsSchema ?? {};
+
+	return null;
+}
+
+/**
+ * Validate a single value against its schema field.
+ * Returns an error message, or null when valid.
+ */
+function validateValue(key: string, field: SettingField, value: unknown): string | null {
+	switch (field.type) {
+		case "string":
+		case "secret":
+		case "url":
+		case "email":
+			if (typeof value !== "string") return `Setting "${key}" must be a string`;
+			if (field.type === "url" && value !== "" && !URL.canParse(value)) {
+				return `Setting "${key}" must be a valid URL`;
+			}
+			if (field.type === "email" && value !== "" && !value.includes("@")) {
+				return `Setting "${key}" must be a valid email address`;
+			}
+			return null;
+		case "number": {
+			if (typeof value !== "number" || Number.isNaN(value)) {
+				return `Setting "${key}" must be a number`;
+			}
+			if (field.min !== undefined && value < field.min) {
+				return `Setting "${key}" must be at least ${field.min}`;
+			}
+			if (field.max !== undefined && value > field.max) {
+				return `Setting "${key}" must be at most ${field.max}`;
+			}
+			return null;
+		}
+		case "boolean":
+			return typeof value === "boolean" ? null : `Setting "${key}" must be a boolean`;
+		case "select":
+			if (typeof value !== "string" || !field.options.some((o) => o.value === value)) {
+				return `Setting "${key}" must be one of the defined options`;
+			}
+			return null;
+		default: {
+			const _exhaustive: never = field;
+			return `Setting "${key}" has an unknown field type`;
+		}
+	}
+}
+
+async function buildSettingsResponse(
+	optionsRepo: OptionsRepository,
+	pluginId: string,
+	schema: Record<string, SettingField>,
+): Promise<PluginSettingsResponse> {
+	const keys = Object.keys(schema);
+	const stored = await optionsRepo.getMany(keys.map((key) => settingsKey(pluginId, key)));
+
+	const values: Record<string, unknown> = {};
+	const secretsSet: Record<string, boolean> = {};
+
+	for (const key of keys) {
+		const field = schema[key];
+		if (!field) continue;
+		const storedValue = stored.get(settingsKey(pluginId, key));
+
+		if (field.type === "secret") {
+			secretsSet[key] = typeof storedValue === "string" && storedValue.length > 0;
+			continue;
+		}
+
+		if (storedValue !== undefined && storedValue !== null) {
+			values[key] = storedValue;
+		} else if ("default" in field && field.default !== undefined) {
+			values[key] = field.default;
+		} else {
+			values[key] = null;
+		}
+	}
+
+	return { schema, values, secretsSet };
+}
+
+/**
+ * Get a plugin's settings (schema + current values, secrets masked)
+ */
+export async function handlePluginSettingsGet(
+	db: Kysely<Database>,
+	pluginId: string,
+	schema: Record<string, SettingField>,
+): Promise<ApiResult<PluginSettingsResponse>> {
+	try {
+		const optionsRepo = new OptionsRepository(db);
+		return { success: true, data: await buildSettingsResponse(optionsRepo, pluginId, schema) };
+	} catch {
+		return {
+			success: false,
+			error: {
+				code: ErrorCode.PLUGIN_SETTINGS_READ_ERROR,
+				message: "Failed to read plugin settings",
+			},
+		};
+	}
+}
+
+/**
+ * Update a plugin's settings.
+ *
+ * Only keys present in `updates` are written. A `null` value deletes the
+ * stored value (reverting to the schema default). Secret fields are
+ * write-only: they accept a new string value or `null` to clear, and the
+ * response never echoes them back.
+ */
+export async function handlePluginSettingsUpdate(
+	db: Kysely<Database>,
+	pluginId: string,
+	schema: Record<string, SettingField>,
+	updates: Record<string, unknown>,
+): Promise<ApiResult<PluginSettingsResponse>> {
+	try {
+		// Validate everything before writing anything.
+		for (const [key, value] of Object.entries(updates)) {
+			const field = schema[key];
+			if (!field) {
+				return {
+					success: false,
+					error: {
+						code: ErrorCode.VALIDATION_ERROR,
+						message: `Unknown setting "${key}" for plugin "${pluginId}"`,
+					},
+				};
+			}
+			if (value === null) continue;
+			const error = validateValue(key, field, value);
+			if (error) {
+				return {
+					success: false,
+					error: { code: ErrorCode.VALIDATION_ERROR, message: error },
+				};
+			}
+		}
+
+		// Wrap the writes + read-back in a transaction so a partial failure
+		// can't leave some settings updated and others not. On D1
+		// withTransaction degrades to running the callback directly — D1 is
+		// single-writer, so per-statement atomicity still holds.
+		const data = await withTransaction(db, async (trx) => {
+			const txRepo = new OptionsRepository(trx);
+			for (const [key, value] of Object.entries(updates)) {
+				if (value === null) {
+					await txRepo.delete(settingsKey(pluginId, key));
+				} else {
+					await txRepo.set(settingsKey(pluginId, key), value);
+				}
+			}
+			return buildSettingsResponse(txRepo, pluginId, schema);
+		});
+
+		return { success: true, data };
+	} catch {
+		return {
+			success: false,
+			error: {
+				code: ErrorCode.PLUGIN_SETTINGS_UPDATE_ERROR,
+				message: "Failed to update plugin settings",
+			},
+		};
+	}
+}

package/src/api/handlers/plugins.ts

@@ -29,6 +29,8 @@ export interface PluginInfo {
 	hasAdminPages: boolean;
 	hasDashboardWidgets: boolean;
 	hasHooks: boolean;
+	/** True when the plugin declares `admin.settingsSchema` (auto-generated settings form) */
+	hasSettings: boolean;
 	installedAt?: string;
 	activatedAt?: string;
 	deactivatedAt?: string;
@@ -36,6 +38,14 @@ export interface PluginInfo {
 	description?: string;
 	/** URL to the plugin icon on the marketplace */
 	iconUrl?: string;
+	mcpToolsEnabled: boolean;
+	mcpTools: Array<{
+		name: string;
+		description: string;
+		route: string;
+		permission: string;
+		destructive: boolean;
+	}>;
 }
 
 export interface PluginListResponse {
@@ -78,12 +88,28 @@ function buildPluginInfo(
 		hasAdminPages: (plugin.admin.pages?.length ?? 0) > 0,
 		hasDashboardWidgets: (plugin.admin.widgets?.length ?? 0) > 0,
 		hasHooks: Object.keys(plugin.hooks ?? {}).length > 0,
+		hasSettings: Object.keys(plugin.admin.settingsSchema ?? {}).length > 0,
 		installedAt: state?.installedAt?.toISOString(),
 		activatedAt: state?.activatedAt?.toISOString() ?? undefined,
 		deactivatedAt: state?.deactivatedAt?.toISOString() ?? undefined,
 		description: state?.description ?? undefined,
 		iconUrl:
 			isMarketplace && marketplaceUrl ? marketplaceIconUrl(marketplaceUrl, plugin.id) : undefined,
+		mcpToolsEnabled: state?.mcpToolsEnabled ?? false,
+		mcpTools: Object.entries(plugin.mcp?.tools ?? {}).flatMap(([name, tool]) => {
+			const permission = plugin.routes[tool.route]?.permission;
+			return permission
+				? [
+						{
+							name,
+							description: tool.description,
+							route: tool.route,
+							permission,
+							destructive: tool.destructive ?? false,
+						},
+					]
+				: [];
+		}),
 	};
 }
 
@@ -110,10 +136,13 @@ function buildSandboxedPluginInfo(
 		hasAdminPages: (entry.adminPages?.length ?? 0) > 0,
 		hasDashboardWidgets: (entry.adminWidgets?.length ?? 0) > 0,
 		hasHooks: false,
+		hasSettings: Object.keys(entry.settingsSchema ?? {}).length > 0,
 		installedAt: state?.installedAt?.toISOString(),
 		activatedAt: state?.activatedAt?.toISOString() ?? undefined,
 		deactivatedAt: state?.deactivatedAt?.toISOString() ?? undefined,
 		description: state?.description ?? undefined,
+		mcpToolsEnabled: state?.mcpToolsEnabled ?? false,
+		mcpTools: entry.mcp?.tools.map(({ inputSchema: _, outputSchema: __, ...tool }) => tool) ?? [],
 	};
 }
 
@@ -125,6 +154,12 @@ export async function handlePluginList(
 	configuredPlugins: ResolvedPlugin[],
 	sandboxedPluginEntries: SandboxedPluginEntry[],
 	marketplaceUrl?: string,
+	/**
+	 * Settings-schema lookup for runtime-installed (marketplace/registry)
+	 * plugins, which aren't in either build-time list. Typically
+	 * `EmDashRuntime.getRuntimePluginSettingsSchema`.
+	 */
+	runtimeSettingsSchemaLookup?: (pluginId: string) => Record<string, unknown> | null,
 ): Promise<ApiResult<PluginListResponse>> {
 	try {
 		const stateRepo = new PluginStateRepository(db);
@@ -166,6 +201,7 @@ export async function handlePluginList(
 				hasAdminPages: false,
 				hasDashboardWidgets: false,
 				hasHooks: false,
+				hasSettings: Object.keys(runtimeSettingsSchemaLookup?.(state.pluginId) ?? {}).length > 0,
 				installedAt: state.installedAt?.toISOString(),
 				activatedAt: state.activatedAt?.toISOString() ?? undefined,
 				deactivatedAt: state.deactivatedAt?.toISOString() ?? undefined,
@@ -174,6 +210,8 @@ export async function handlePluginList(
 					state.source === "marketplace" && marketplaceUrl
 						? marketplaceIconUrl(marketplaceUrl, state.pluginId)
 						: undefined,
+				mcpToolsEnabled: state.mcpToolsEnabled,
+				mcpTools: [],
 			});
 		}
 
@@ -266,10 +304,13 @@ function buildStateOnlyPluginInfo(
 		hasAdminPages: false,
 		hasDashboardWidgets: false,
 		hasHooks: false,
+		hasSettings: false,
 		installedAt: state.installedAt?.toISOString(),
 		activatedAt: state.activatedAt?.toISOString() ?? undefined,
 		deactivatedAt: state.deactivatedAt?.toISOString() ?? undefined,
 		description: state.description ?? undefined,
+		mcpToolsEnabled: state.mcpToolsEnabled,
+		mcpTools: [],
 	};
 }
 

package/src/api/handlers/registry.ts

@@ -121,6 +121,7 @@ export interface RegistryInstallInput {
 	 * surface a consent UI before posting (e.g. CI scripts) opt out.
 	 */
 	acknowledgedDeclaredAccess?: unknown;
+	acknowledgedMcpTools?: unknown;
 }
 
 export interface RegistryInstallResult {
@@ -1098,6 +1099,22 @@ export async function handleRegistryInstall(
 			}
 		}
 
+		const actualMcpTools = (bundle.manifest.mcp?.tools ?? []).map(
+			({ inputSchema: _, outputSchema: __, ...tool }) => tool,
+		);
+		if (actualMcpTools.length > 0) {
+			if (JSON.stringify(input.acknowledgedMcpTools) !== JSON.stringify(actualMcpTools)) {
+				return {
+					success: false,
+					error: {
+						code: "MCP_TOOL_CONSENT_REQUIRED",
+						message: "Plugin MCP tools require explicit consent",
+						details: { mcpTools: actualMcpTools },
+					},
+				};
+			}
+		}
+
 		// Step 7: store in R2 under the registry prefix.
 		await storeBundleInR2(storage, pluginId, version, bundle, "registry");
 
@@ -1318,6 +1335,7 @@ export async function handleRegistryUpdate(
 		version?: string;
 		confirmCapabilityChanges?: boolean;
 		confirmRouteVisibilityChanges?: boolean;
+		confirmMcpTools?: boolean;
 		hostEnv?: HostEnv;
 	},
 ): Promise<ApiResult<RegistryUpdateResult>> {
@@ -1590,6 +1608,25 @@ export async function handleRegistryUpdate(
 			};
 		}
 
+		const oldMcpTools = [...(oldBundle?.manifest.mcp?.tools ?? [])].toSorted((a, b) =>
+			a.name.localeCompare(b.name),
+		);
+		const newMcpTools = [...(bundle.manifest.mcp?.tools ?? [])].toSorted((a, b) =>
+			a.name.localeCompare(b.name),
+		);
+		if (JSON.stringify(oldMcpTools) !== JSON.stringify(newMcpTools) && !opts?.confirmMcpTools) {
+			return {
+				success: false,
+				error: {
+					code: "MCP_TOOL_CONSENT_REQUIRED",
+					message: "Plugin update changes its MCP tools",
+					details: {
+						mcpTools: newMcpTools.map(({ inputSchema: _, outputSchema: __, ...tool }) => tool),
+					},
+				},
+			};
+		}
+
 		// Store new bundle. R2 prefix is deterministic per (pluginId, version),
 		// so a retry of the same update is idempotent.
 		await storeBundleInR2(storage, pluginId, newVersion, bundle, "registry");
@@ -1605,6 +1642,8 @@ export async function handleRegistryUpdate(
 			registrySlug: slug,
 			displayName: existing.displayName ?? slug,
 			description: existing.description ?? undefined,
+			mcpToolsEnabled: false,
+			mcpToolsConsent: null,
 		});
 
 		// Best-effort cleanup of the old bundle. Failures here don't roll