emdash 0.29.0 → 0.30.0

package/src/astro/routes/api/settings/backups/index.ts

@@ -0,0 +1,76 @@
+/**
+ * Backup settings + archive listing
+ *
+ * GET /_emdash/api/settings/backups — scheduled-backup settings, stored
+ *   archives, and whether a storage backend is available.
+ * PUT /_emdash/api/settings/backups — update scheduled-backup settings.
+ */
+
+import type { APIRoute } from "astro";
+import { z } from "zod";
+
+import { requirePerm } from "#api/authorize.js";
+import { apiError, apiSuccess, handleError, unwrapResult } from "#api/error.js";
+import { ErrorCode } from "#api/errors.js";
+import {
+	BACKUP_RETENTION_MAX,
+	BACKUP_RETENTION_MIN,
+	getBackupSettings,
+	listBackupArchives,
+	updateBackupSettings,
+	type BackupArchive,
+} from "#api/handlers/backup.js";
+import { isParseError, parseBody } from "#api/parse.js";
+
+export const prerender = false;
+
+export const GET: APIRoute = async ({ locals }) => {
+	const { emdash, user } = locals;
+
+	if (!emdash?.db) {
+		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+	}
+
+	const denied = requirePerm(user, "backups:manage");
+	if (denied) return denied;
+
+	try {
+		const settings = await getBackupSettings(emdash.db);
+
+		let archives: BackupArchive[] = [];
+		const storageAvailable = !!emdash.storage;
+		if (emdash.storage) {
+			const listed = await listBackupArchives(emdash.storage);
+			if (listed.success) archives = listed.data;
+		}
+
+		return apiSuccess({ settings, archives, storageAvailable });
+	} catch (error) {
+		return handleError(
+			error,
+			"Failed to load backup settings",
+			ErrorCode.BACKUP_SETTINGS_READ_ERROR,
+		);
+	}
+};
+
+const settingsBody = z.object({
+	enabled: z.boolean(),
+	retention: z.number().int().min(BACKUP_RETENTION_MIN).max(BACKUP_RETENTION_MAX),
+});
+
+export const PUT: APIRoute = async ({ request, locals }) => {
+	const { emdash, user } = locals;
+
+	if (!emdash?.db) {
+		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+	}
+
+	const denied = requirePerm(user, "backups:manage");
+	if (denied) return denied;
+
+	const body = await parseBody(request, settingsBody);
+	if (isParseError(body)) return body;
+
+	return unwrapResult(await updateBackupSettings(emdash.db, body));
+};

package/src/astro/routes/api/setup/admin-verify.ts

@@ -33,19 +33,23 @@ export const POST: APIRoute = async ({ cookies, request, locals }) => {
 		// Check if setup is already complete
 		const options = new OptionsRepository(emdash.db);
 		const setupComplete = await options.get("emdash:setup_complete");
-
-		if (setupComplete === true || setupComplete === "true") {
-			return apiError("SETUP_COMPLETE", "Setup already complete", 400);
-		}
+		const isComplete = setupComplete === true || setupComplete === "true";
 
 		// Check if any users exist
 		const adapter = createKyselyAdapter(emdash.db);
 		const userCount = await adapter.countUsers();
 
 		if (userCount > 0) {
+			if (isComplete) {
+				return apiError("SETUP_COMPLETE", "Setup already complete", 400);
+			}
 			return apiError("ADMIN_EXISTS", "Admin user already exists", 400);
 		}
 
+		// `setup_complete` with ZERO users is a recoverable half-state —
+		// see the matching guard in ./admin.ts. The verify step must
+		// accept it too, or the wizard dies between its two calls.
+
 		// Get setup state
 		const setupState = await options.get<{
 			step?: string;

package/src/astro/routes/api/setup/admin.ts

@@ -32,19 +32,26 @@ export const POST: APIRoute = async ({ cookies, request, locals }) => {
 		// Check if setup is already complete
 		const options = new OptionsRepository(emdash.db);
 		const setupComplete = await options.get("emdash:setup_complete");
-
-		if (setupComplete === true || setupComplete === "true") {
-			return apiError("SETUP_COMPLETE", "Setup already complete", 400);
-		}
+		const isComplete = setupComplete === true || setupComplete === "true";
 
 		// Check if any users exist
 		const adapter = createKyselyAdapter(emdash.db);
 		const userCount = await adapter.countUsers();
 
 		if (userCount > 0) {
+			if (isComplete) {
+				return apiError("SETUP_COMPLETE", "Setup already complete", 400);
+			}
 			return apiError("ADMIN_EXISTS", "Admin user already exists", 400);
 		}
 
+		// `setup_complete` with ZERO users is a recoverable half-state (a
+		// wiped/sanitised users table — e.g. a DB copied between
+		// environments). /api/setup/status already resumes the wizard at
+		// the admin step for exactly this state, so admin creation must be
+		// allowed here too — rejecting on the stale flag alone leaves the
+		// instance with no UI path to an admin account.
+
 		// Parse request body
 		const body = await parseBody(request, setupAdminBody);
 		if (isParseError(body)) return body;

package/src/astro/routes/api/well-known/oauth-authorization-server.ts

@@ -10,6 +10,8 @@
  */
 
 import type { APIRoute } from "astro";
+// @ts-ignore - virtual module
+import virtualConfig from "virtual:emdash/config";
 
 import { getPublicOrigin } from "#api/public-url.js";
 import { VALID_SCOPES } from "#auth/api-tokens.js";
@@ -17,7 +19,8 @@ import { VALID_SCOPES } from "#auth/api-tokens.js";
 export const prerender = false;
 
 export const GET: APIRoute = async ({ url, locals }) => {
-	const origin = getPublicOrigin(url, locals.emdash?.config);
+	// Same fallback as oauth-protected-resource.ts (#2016).
+	const origin = getPublicOrigin(url, locals.emdash?.config ?? virtualConfig);
 	const issuer = `${origin}/_emdash`;
 
 	return Response.json(

package/src/astro/routes/api/well-known/oauth-protected-resource.ts

@@ -12,6 +12,8 @@
  */
 
 import type { APIRoute } from "astro";
+// @ts-ignore - virtual module
+import virtualConfig from "virtual:emdash/config";
 
 import { getPublicOrigin } from "#api/public-url.js";
 import { VALID_SCOPES } from "#auth/api-tokens.js";
@@ -19,7 +21,9 @@ import { VALID_SCOPES } from "#auth/api-tokens.js";
 export const prerender = false;
 
 export const GET: APIRoute = async ({ url, locals }) => {
-	const origin = getPublicOrigin(url, locals.emdash?.config);
+	// Anonymous discovery requests omit runtime config; use build-time config
+	// so `siteUrl` can override the proxy's internal origin (#2016).
+	const origin = getPublicOrigin(url, locals.emdash?.config ?? virtualConfig);
 
 	return Response.json(
 		{

package/src/astro/types.ts

@@ -8,6 +8,8 @@
 import type { Element } from "@emdash-cms/blocks";
 import type { Kysely } from "kysely";
 
+import type { RouteMeta } from "../plugins/routes.js";
+
 // Re-export core types
 export type {
 	ContentItem,
@@ -410,8 +412,52 @@ export interface EmDashHandlers {
 		request: Request,
 	) => Promise<HandlerResponse>;
 
-	// Plugin route metadata (for auth decisions before dispatch)
-	getPluginRouteMeta: (pluginId: string, path: string) => { public: boolean } | null;
+	// Plugin route metadata (for auth/caching decisions before dispatch)
+	getPluginRouteMeta: (pluginId: string, path: string) => RouteMeta | null;
+	getEnabledPluginMcpTools: () => Promise<
+		Array<{
+			pluginId: string;
+			name: string;
+			description: string;
+			route: string;
+			permission: string;
+			destructive: boolean;
+			inputSchema: import("zod").ZodType;
+			outputSchema?: import("zod").ZodType;
+		}>
+	>;
+	getPluginMcpTools: (pluginId?: string) => Promise<
+		Array<{
+			pluginId: string;
+			name: string;
+			description: string;
+			route: string;
+			permission: string;
+			destructive: boolean;
+			inputSchema: import("zod").ZodType;
+			outputSchema?: import("zod").ZodType;
+		}>
+	>;
+	serializePluginMcpConsent: (
+		tools: Awaited<ReturnType<EmDashHandlers["getPluginMcpTools"]>>,
+		pluginId: string,
+	) => string;
+	handlePluginMcpTool: (
+		pluginId: string,
+		toolName: string,
+		route: string,
+		input: unknown,
+		actorId: string,
+		request: Request,
+	) => Promise<HandlerResponse>;
+	handlePluginMcpDenied: (
+		pluginId: string,
+		toolName: string,
+		route: string,
+		actorId: string,
+		request: Request,
+		reason: string,
+	) => Promise<void>;
 
 	// Media provider handlers
 	getMediaProvider: (providerId: string) => import("../media/types.js").MediaProvider | undefined;

package/src/auth/api-tokens.ts

@@ -19,6 +19,7 @@ export {
 	hashPrefixedToken as hashApiToken,
 	VALID_SCOPES,
 	validateScopes,
+	isValidScope,
 	hasScope,
 	computeS256Challenge,
 	type ApiTokenScope,

package/src/auth/oauth-state-store.ts

@@ -79,6 +79,9 @@ export function createOAuthStateStore(db: Kysely<Database>): StateStore {
 				if ("nonce" in parsed && typeof parsed.nonce === "string") {
 					oauthState.nonce = parsed.nonce;
 				}
+				if ("inviteToken" in parsed && typeof parsed.inviteToken === "string") {
+					oauthState.inviteToken = parsed.inviteToken;
+				}
 				return oauthState;
 			} catch {
 				return null;

package/src/auth/providers/github-admin.tsx

@@ -15,13 +15,12 @@ function GitHubIcon({ className }: { className?: string }) {
 	);
 }
 
-export function LoginButton() {
+export function LoginButton({ inviteToken }: { inviteToken?: string } = {}) {
+	const href = inviteToken
+		? `/_emdash/api/auth/oauth/github?invite=${encodeURIComponent(inviteToken)}`
+		: "/_emdash/api/auth/oauth/github";
 	return (
-		<LinkButton
-			href="/_emdash/api/auth/oauth/github"
-			variant="outline"
-			className="w-full justify-center"
-		>
+		<LinkButton href={href} variant="outline" className="w-full justify-center">
 			<GitHubIcon className="h-5 w-5" />
 			<span>GitHub</span>
 		</LinkButton>

package/src/auth/providers/google-admin.tsx

@@ -30,13 +30,12 @@ function GoogleIcon({ className }: { className?: string }) {
 	);
 }
 
-export function LoginButton() {
+export function LoginButton({ inviteToken }: { inviteToken?: string } = {}) {
+	const href = inviteToken
+		? `/_emdash/api/auth/oauth/google?invite=${encodeURIComponent(inviteToken)}`
+		: "/_emdash/api/auth/oauth/google";
 	return (
-		<LinkButton
-			href="/_emdash/api/auth/oauth/google"
-			variant="outline"
-			className="w-full justify-center"
-		>
+		<LinkButton href={href} variant="outline" className="w-full justify-center">
 			<GoogleIcon className="h-5 w-5" />
 			<span>Google</span>
 		</LinkButton>

package/src/auth/scopes.ts

@@ -6,6 +6,8 @@
  * Token-authenticated requests must have the required scope (or "admin").
  */
 
+import { apiError } from "#api/error.js";
+
 import { hasScope } from "./api-tokens.js";
 
 /**
@@ -21,13 +23,5 @@ export function requireScope(locals: { tokenScopes?: string[] }, scope: string):
 
 	if (hasScope(locals.tokenScopes, scope)) return null;
 
-	return new Response(
-		JSON.stringify({
-			error: {
-				code: "INSUFFICIENT_SCOPE",
-				message: `Token lacks required scope: ${scope}`,
-			},
-		}),
-		{ status: 403, headers: { "Content-Type": "application/json" } },
-	);
+	return apiError("INSUFFICIENT_SCOPE", `Token lacks required scope: ${scope}`, 403);
 }

package/src/cli/client-factory.ts

@@ -17,7 +17,6 @@ export const connectionArgs = {
 		type: "string" as const,
 		alias: "u",
 		description: "EmDash instance URL",
-		default: "http://localhost:4321",
 	},
 	token: {
 		type: "string" as const,

package/src/cli/commands/bundle-utils.ts

@@ -9,9 +9,11 @@ import { createWriteStream } from "node:fs";
 import { readdir, stat, access } from "node:fs/promises";
 import { resolve, join } from "node:path";
 import { pipeline } from "node:stream/promises";
+import { pathToFileURL } from "node:url";
 
 import { imageSize } from "image-size";
 import { packTar } from "modern-tar/fs";
+import { z } from "zod";
 
 import { capabilitiesToDeclaredAccess } from "../../plugins/types.js";
 import type {
@@ -19,6 +21,8 @@ import type {
 	ResolvedPlugin,
 	HookName,
 	ManifestHookEntry,
+	ManifestMcpTool,
+	ManifestRouteEntry,
 } from "../../plugins/types.js";
 
 // ── Constants ────────────────────────────────────────────────────────────────
@@ -33,6 +37,7 @@ export const MAX_SCREENSHOTS = 5;
 export const MAX_SCREENSHOT_WIDTH = 1920;
 export const MAX_SCREENSHOT_HEIGHT = 1080;
 export const ICON_SIZE = 256;
+const MCP_TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
 
 // ── Regex patterns (module-scope to avoid re-compilation) ────────────────────
 
@@ -105,6 +110,11 @@ export async function fileExists(path: string): Promise<boolean> {
 	}
 }
 
+/** Convert an absolute build artifact path into a portable ESM import specifier. */
+export function toFileImportSpecifier(path: string): string {
+	return pathToFileURL(path).href;
+}
+
 // ── Image dimension readers ──────────────────────────────────────────────────
 
 /**
@@ -149,6 +159,44 @@ export function extractManifest(plugin: ResolvedPlugin): PluginManifest {
 		}
 	}
 
+	const routes: Array<ManifestRouteEntry | string> = Object.entries(plugin.routes).map(
+		([name, route]) => {
+			if (
+				route.public === undefined &&
+				route.permission === undefined &&
+				route.cacheControl === undefined
+			) {
+				return name;
+			}
+
+			const entry: ManifestRouteEntry = { name };
+			if (route.public !== undefined) entry.public = route.public;
+			if (route.permission !== undefined) entry.permission = route.permission;
+			if (route.cacheControl !== undefined) entry.cacheControl = route.cacheControl;
+			return entry;
+		},
+	);
+	const tools: ManifestMcpTool[] = Object.entries(plugin.mcp?.tools ?? {}).map(([name, tool]) => {
+		if (!MCP_TOOL_NAME_PATTERN.test(name)) throw new Error(`Invalid MCP tool name "${name}"`);
+		const route = plugin.routes[tool.route];
+		if (!route?.permission || route.public) {
+			throw new Error(`MCP tool "${name}" must reference a private route with a permission`);
+		}
+		return {
+			name,
+			description: tool.description,
+			route: tool.route,
+			permission: route.permission,
+			destructive: tool.destructive ?? false,
+			inputSchema: z.toJSONSchema(tool.input, { target: "draft-7" }),
+			...(tool.output
+				? {
+						outputSchema: z.toJSONSchema(tool.output, { target: "draft-7" }),
+					}
+				: {}),
+		};
+	});
+
 	return {
 		id: plugin.id,
 		version: plugin.version,
@@ -157,7 +205,8 @@ export function extractManifest(plugin: ResolvedPlugin): PluginManifest {
 		allowedHosts: plugin.allowedHosts,
 		storage: plugin.storage,
 		hooks,
-		routes: Object.keys(plugin.routes),
+		routes,
+		...(tools.length > 0 ? { mcp: { tools } } : {}),
 		admin: {
 			// Omit entry (it's a module specifier for the host, not relevant in bundles)
 			settingsSchema: plugin.admin.settingsSchema,

package/src/cli/commands/bundle.ts

@@ -37,6 +37,7 @@ import {
 	MAX_SCREENSHOT_HEIGHT,
 	readImageDimensions,
 	resolveSourceEntry,
+	toFileImportSpecifier,
 	totalBundleBytes,
 	validateBundleSize,
 } from "./bundle-utils.js";
@@ -202,7 +203,10 @@ export const bundleCommand = defineCommand({
 			}
 
 			// Dynamic import of the built plugin
-			const pluginModule = (await import(mainOutputPath)) as Record<string, unknown>;
+			const pluginModule = (await import(toFileImportSpecifier(mainOutputPath))) as Record<
+				string,
+				unknown
+			>;
 
 			// Extract manifest from the imported module.
 			// Supports three patterns:
@@ -269,7 +273,9 @@ export const bundleCommand = defineCommand({
 								const backendBaseName = basename(backendEntry).replace(TS_EXT_RE, "");
 								const backendProbePath = await findBuildOutput(backendProbeDir, backendBaseName);
 								if (backendProbePath) {
-									const backendModule = (await import(backendProbePath)) as Record<string, unknown>;
+									const backendModule = (await import(
+										toFileImportSpecifier(backendProbePath)
+									)) as Record<string, unknown>;
 									const standardDef = (backendModule.default ?? {}) as Record<string, unknown>;
 									const hooks = standardDef.hooks as Record<string, unknown> | undefined;
 									const routes = standardDef.routes as Record<string, unknown> | undefined;
@@ -300,6 +306,7 @@ export const bundleCommand = defineCommand({
 											(resolvedPlugin.routes as Record<string, unknown>)[name] = {
 												handler: routeObj.handler,
 												public: routeObj.public,
+												cacheControl: routeObj.cacheControl,
 											};
 										}
 									}

package/src/cli/commands/media.ts

@@ -10,9 +10,12 @@ import { basename } from "node:path";
 import { defineCommand } from "citty";
 import { consola } from "consola";
 
+import type { MediaUsageRepairInput, MediaUsageRepairResponse } from "../../client/index.js";
 import { connectionArgs, createClientFromArgs } from "../client-factory.js";
 import { configureOutputMode, output } from "../output.js";
 
+const repairScopeError = "Specify exactly one of --collection or --all";
+
 const listCommand = defineCommand({
 	meta: {
 		name: "list",
@@ -155,6 +158,129 @@ const deleteCommand = defineCommand({
 	},
 });
 
+const repairUsageCommand = defineCommand({
+	meta: {
+		name: "repair-usage",
+		description:
+			"Repair content media usage indexes. partial/stale exit 0; automation should use --json and parse status.",
+	},
+	args: {
+		...connectionArgs,
+		collection: {
+			type: "string",
+			alias: "c",
+			description: "Repair one content collection",
+		},
+		all: {
+			type: "boolean",
+			description: "Repair every content collection",
+		},
+	},
+	async run({ args }) {
+		configureOutputMode(args);
+
+		const hasCollectionArg = args.collection !== undefined;
+		const hasCollection = typeof args.collection === "string";
+		const hasAll = args.all === true;
+		if ((hasCollectionArg && !hasCollection) || hasCollection === hasAll) {
+			consola.error(repairScopeError);
+			process.exit(1);
+		}
+
+		const client = createClientFromArgs(args);
+
+		try {
+			const repairInput: MediaUsageRepairInput = hasCollection
+				? { scope: "collection", collection: args.collection }
+				: { scope: "all" };
+			const result = await client.mediaRepairUsage(repairInput);
+
+			if (args.json || !process.stdout.isTTY) {
+				output(result, args);
+			} else {
+				printRepairUsageSummary(result, repairInput);
+			}
+
+			if (result.status === "failed") {
+				process.exitCode = 1;
+			}
+		} catch (error) {
+			consola.error(
+				"Failed to repair media usage:",
+				error instanceof Error ? error.message : error,
+			);
+			process.exit(1);
+		}
+	},
+});
+
+type RepairUsageSummary = {
+	level: "success" | "warn";
+	message: string;
+};
+
+export function formatRepairUsageSummary(
+	result: MediaUsageRepairResponse,
+	input: MediaUsageRepairInput,
+): RepairUsageSummary {
+	const counts = `indexed ${result.indexedSourceCount}, failed ${result.failedSourceCount}, skipped ${result.skippedSourceCount}, deleted ${result.deletedSourceCount}`;
+	const scope =
+		input.scope === "collection"
+			? `collection ${input.collection}`
+			: `all content (${formatCollectionCount(result.collections.length)})`;
+
+	if (result.status === "complete") {
+		return {
+			level: "success",
+			message: `Media usage repair complete for ${scope} (${counts}).`,
+		};
+	}
+
+	const details = result.collections
+		.filter((collection) => collection.status !== "complete")
+		.map((collection) => {
+			const error = collection.lastErrorCode ? `, ${collection.lastErrorCode}` : "";
+			return `${collection.collection}: ${collection.status}${error}`;
+		})
+		.join("; ");
+	const suffix = details ? ` ${details}.` : "";
+
+	if (result.status === "stale") {
+		return {
+			level: "warn",
+			message: `Media usage repair is stale for ${scope}; trustworthy complete coverage was not established because another writer, repair, or stale marker won the race. Rerun when writes are quiet (${counts}).${suffix}`,
+		};
+	}
+
+	if (result.status === "partial") {
+		return {
+			level: "warn",
+			message: `Media usage repair is partial for ${scope}; some sources or collections need attention (${counts}).${suffix}`,
+		};
+	}
+
+	return {
+		level: "warn",
+		message: `Media usage repair failed for ${scope} (${counts}).${suffix}`,
+	};
+}
+
+function printRepairUsageSummary(
+	result: MediaUsageRepairResponse,
+	input: MediaUsageRepairInput,
+): void {
+	const summary = formatRepairUsageSummary(result, input);
+	if (summary.level === "success") {
+		consola.success(summary.message);
+	} else {
+		consola.warn(summary.message);
+	}
+}
+
+function formatCollectionCount(count: number): string {
+	return `${count} collection${count === 1 ? "" : "s"}`;
+}
+
 export const mediaCommand = defineCommand({
 	meta: {
 		name: "media",
@@ -165,5 +291,6 @@ export const mediaCommand = defineCommand({
 		upload: uploadCommand,
 		get: getCommand,
 		delete: deleteCommand,
+		"repair-usage": repairUsageCommand,
 	},
 });