emdash 0.12.0 → 0.13.0

package/src/index.ts

@@ -164,6 +164,7 @@ export type {
 	WxrAttachment,
 	WxrCategory,
 	WxrTag,
+	WxrTerm,
 	WxrAuthor,
 } from "./cli/wxr/parser.js";
 
@@ -188,7 +189,6 @@ export { EmDashStorageError } from "./storage/types.js";
 export {
 	definePlugin,
 	adaptSandboxEntry,
-	isStandardPluginDefinition,
 	pluginManifestSchema,
 	createHookPipeline,
 	HookPipeline,
@@ -243,16 +243,9 @@ export type {
 	CollectionCommentSettings,
 	StoredComment,
 
-	// Standard plugin format
-	StandardPluginDefinition,
-	StandardHookHandler,
-	StandardHookEntry,
-	StandardRouteHandler,
-	StandardRouteEntry,
-
-	// Sandbox types
+	// Sandbox runtime types
 	SandboxRunner,
-	SandboxedPlugin,
+	SandboxedPluginInstance,
 	SandboxRunnerFactory,
 	SandboxOptions,
 	SandboxEmailMessage,

package/src/media/normalize.ts

@@ -20,6 +20,7 @@ const URL_PATTERN = /^https?:\/\//;
  * - `null`/`undefined` → `null`
  * - Bare URL string → `{ provider: "external", id: "", src: url }`
  * - Bare internal media URL → resolved via local provider's `get()`
+ * - Bare local media ID → resolved via local provider's `get()`
  * - Object with `provider` + `id` → enriched with missing fields from provider
  */
 export async function normalizeMediaValue(
@@ -79,7 +80,7 @@ export async function normalizeMediaValue(
 	return mergeProviderData(result, providerItem);
 }
 
-function normalizeStringUrl(
+async function normalizeStringUrl(
 	url: string,
 	getProvider: (id: string) => MediaProvider | undefined,
 ): Promise<MediaValue | null> {
@@ -97,12 +98,15 @@ function normalizeStringUrl(
 		});
 	}
 
-	// Unrecognized string — treat as external
-	return Promise.resolve({
+	const localMedia = await resolveLocalId(url, getProvider);
+	if (localMedia) return localMedia;
+
+	// Unrecognized string — preserve legacy behavior and treat as external
+	return {
 		provider: "external",
 		id: "",
 		src: url,
-	});
+	};
 }
 
 async function resolveInternalUrl(
@@ -139,6 +143,35 @@ async function resolveInternalUrl(
 	};
 }
 
+async function resolveLocalId(
+	id: string,
+	getProvider: (id: string) => MediaProvider | undefined,
+): Promise<MediaValue | null> {
+	const localProvider = getProvider("local");
+
+	if (!localProvider?.get) return null;
+
+	let item: MediaProviderItem | null;
+	try {
+		item = await localProvider.get(id);
+	} catch {
+		return null;
+	}
+
+	if (!item) return null;
+
+	return {
+		provider: "local",
+		id: item.id,
+		filename: item.filename,
+		mimeType: item.mimeType,
+		width: item.width,
+		height: item.height,
+		alt: item.alt,
+		meta: item.meta,
+	};
+}
+
 /**
  * Merge provider data into an existing MediaValue, preserving caller-supplied fields.
  * Caller `alt` takes priority over provider `alt` (per-usage, not per-image).

package/src/plugin-types.ts

@@ -0,0 +1,240 @@
+/**
+ * `emdash/plugin` — types for authoring sandboxed plugins.
+ *
+ * This is a **type-only** subpath. The package.json export map only
+ * declares a `types` condition, so the bundler erases `import type`
+ * statements against this entry and the build never tries to resolve a
+ * JavaScript module. That's how a sandboxed plugin can import these
+ * types without dragging the `emdash` runtime into its bundle.
+ *
+ * Recommended authoring pattern:
+ *
+ * ```ts
+ * import type { SandboxedPlugin } from "emdash/plugin";
+ *
+ * export default {
+ *   hooks: {
+ *     "content:beforeSave": async (event, ctx) => {
+ *       // event: ContentHookEvent, ctx: PluginContext — both inferred.
+ *       return event.content;
+ *     },
+ *   },
+ *   routes: {
+ *     health: async (routeCtx, ctx) => ({ ok: true }),
+ *   },
+ * } satisfies SandboxedPlugin;
+ * ```
+ *
+ * The `satisfies SandboxedPlugin` annotation drives full inference on
+ * every hook handler. Authors should not need to annotate handler
+ * params — TypeScript reads the event type from the hook name. The
+ * runtime probe at build time reads `default.hooks` and `default.routes`
+ * directly; the shape declared here mirrors what the probe consumes.
+ *
+ * Return types matter: `content:beforeSave` may return a mutated
+ * `content` to override the saved fields; `content:beforeDelete` and
+ * `comment:beforeCreate` may return `false` to veto; `page:metadata`
+ * returns the metadata contribution. The mapped type captures these
+ * per-hook return contracts so misuse fails at compile time.
+ */
+
+import type {
+	CommentAfterCreateEvent,
+	CommentAfterCreateHandler,
+	CommentAfterModerateEvent,
+	CommentAfterModerateHandler,
+	CommentBeforeCreateEvent,
+	CommentBeforeCreateHandler,
+	CommentModerateEvent,
+	CommentModerateHandler,
+	ContentAfterDeleteHandler,
+	ContentAfterPublishHandler,
+	ContentAfterSaveHandler,
+	ContentAfterUnpublishHandler,
+	ContentBeforeDeleteHandler,
+	ContentBeforeSaveHandler,
+	ContentDeleteEvent,
+	ContentHookEvent,
+	ContentPublishStateChangeEvent,
+	CronEvent,
+	CronHandler,
+	EmailAfterSendEvent,
+	EmailAfterSendHandler,
+	EmailBeforeSendEvent,
+	EmailBeforeSendHandler,
+	EmailDeliverEvent,
+	EmailDeliverHandler,
+	LifecycleEvent,
+	LifecycleHandler,
+	MediaAfterUploadEvent,
+	MediaAfterUploadHandler,
+	MediaBeforeUploadHandler,
+	MediaUploadEvent,
+	PageFragmentEvent,
+	PageFragmentHandler,
+	PageMetadataEvent,
+	PageMetadataHandler,
+	PluginContext,
+	UninstallEvent,
+	UninstallHandler,
+} from "./plugins/types.js";
+
+/**
+ * Map from hook name to its handler signature. Adding or changing a
+ * hook signature in the runtime means updating this map; the rest of
+ * the type story flows from it. Authors writing
+ * `"content:beforeSave": async (event, ctx) => { ... }` get `event`
+ * typed as `ContentHookEvent` and `ctx` as `PluginContext` for free.
+ */
+export interface HookHandlers {
+	"plugin:install": LifecycleHandler;
+	"plugin:activate": LifecycleHandler;
+	"plugin:deactivate": LifecycleHandler;
+	"plugin:uninstall": UninstallHandler;
+	"content:beforeSave": ContentBeforeSaveHandler;
+	"content:afterSave": ContentAfterSaveHandler;
+	"content:beforeDelete": ContentBeforeDeleteHandler;
+	"content:afterDelete": ContentAfterDeleteHandler;
+	"content:afterPublish": ContentAfterPublishHandler;
+	"content:afterUnpublish": ContentAfterUnpublishHandler;
+	"media:beforeUpload": MediaBeforeUploadHandler;
+	"media:afterUpload": MediaAfterUploadHandler;
+	cron: CronHandler;
+	"email:beforeSend": EmailBeforeSendHandler;
+	"email:deliver": EmailDeliverHandler;
+	"email:afterSend": EmailAfterSendHandler;
+	"comment:beforeCreate": CommentBeforeCreateHandler;
+	"comment:moderate": CommentModerateHandler;
+	"comment:afterCreate": CommentAfterCreateHandler;
+	"comment:afterModerate": CommentAfterModerateHandler;
+	"page:metadata": PageMetadataHandler;
+	"page:fragments": PageFragmentHandler;
+}
+
+/**
+ * Hook-handler config form. The bare-function form is also accepted
+ * (see `HookEntry`) — this is the long form that lets authors override
+ * priority, timeout, exclusivity. `errorPolicy` and `dependencies` are
+ * read by the host but rarely set by authors.
+ */
+export interface HookConfig<K extends keyof HookHandlers> {
+	handler: HookHandlers[K];
+	priority?: number;
+	timeout?: number;
+	dependencies?: string[];
+	errorPolicy?: "continue" | "abort";
+	exclusive?: boolean;
+}
+
+/**
+ * Either a bare handler or the config form. The build probe accepts
+ * both shapes and the runtime normalises to the config form before
+ * dispatch.
+ */
+export type HookEntry<K extends keyof HookHandlers> = HookHandlers[K] | HookConfig<K>;
+
+/**
+ * Request fields a route handler can rely on across both trusted and
+ * sandboxed execution. Trusted handlers receive a real `Request`
+ * (which is structurally compatible — has `url`, `method`, `headers`);
+ * sandboxed handlers receive a serialised `{ url, method, headers }`
+ * record because Worker Loader can't pass `Request` objects across
+ * the boundary. The shared shape is what's actually portable.
+ *
+ * `headers` is intentionally `Record<string, string>` rather than
+ * `Headers` so the sandboxed serialised form (which is a plain
+ * record) typechecks. Trusted handlers receiving a real `Headers`
+ * object can still call `.get(...)`, but reading via this type's
+ * indexing requires the lookup to be lowercased and exact. Authors
+ * iterating headers in a portable way should use `Object.entries`.
+ */
+export interface SandboxedRequest {
+	url: string;
+	method: string;
+	headers: Record<string, string>;
+}
+
+/**
+ * Context passed to a route handler. Routes get an extra `routeCtx`
+ * argument with the call-site input + the originating request, in
+ * addition to the standard `PluginContext`.
+ *
+ * `input` is `unknown` because plugins validate it themselves — no
+ * central schema for route payloads.
+ */
+export interface SandboxedRouteContext {
+	input: unknown;
+	request: SandboxedRequest;
+	requestMeta?: unknown;
+}
+
+/**
+ * Route handler. The two-arg shape (`routeCtx`, `pluginCtx`) matches
+ * how the standard-format runtime invokes routes — distinct from
+ * native plugins, where routes take a single context with the input
+ * merged in.
+ *
+ * Return type is `unknown` because routes serialise their return value
+ * to JSON for the caller; authors define their own response shape.
+ */
+export type RouteHandler = (
+	routeCtx: SandboxedRouteContext,
+	ctx: PluginContext,
+) => Promise<unknown>;
+
+/**
+ * Route entry — either a bare handler or the config form with
+ * `public`, `input` schema, and so on. The build probe accepts both.
+ */
+export type RouteEntry =
+	| RouteHandler
+	| {
+			handler: RouteHandler;
+			public?: boolean;
+			input?: unknown;
+	  };
+
+/**
+ * The shape of a sandboxed plugin's default export.
+ *
+ * Both `hooks` and `routes` are optional — a plugin that only declares
+ * one is valid. Hook keys are constrained to the runtime's hook
+ * vocabulary so a typo (`"content:beforSave"`) is a compile error.
+ * Route keys are open because route names are author-chosen URL path
+ * segments.
+ */
+export interface SandboxedPlugin {
+	hooks?: {
+		[K in keyof HookHandlers]?: HookEntry<K>;
+	};
+	routes?: Record<string, RouteEntry>;
+}
+
+/**
+ * Re-export of event types so plugin authors can reference them
+ * explicitly when needed (helper functions, type predicates). Most
+ * authors won't need these — the mapped type infers them at handler
+ * call sites. But the default-export's inferred type also needs them
+ * publicly nameable so `satisfies SandboxedPlugin` can produce a
+ * portable `.d.mts`.
+ */
+export type {
+	CommentAfterCreateEvent,
+	CommentAfterModerateEvent,
+	CommentBeforeCreateEvent,
+	CommentModerateEvent,
+	ContentDeleteEvent,
+	ContentHookEvent,
+	ContentPublishStateChangeEvent,
+	CronEvent,
+	EmailAfterSendEvent,
+	EmailBeforeSendEvent,
+	EmailDeliverEvent,
+	LifecycleEvent,
+	MediaAfterUploadEvent,
+	MediaUploadEvent,
+	PageFragmentEvent,
+	PageMetadataEvent,
+	PluginContext,
+	UninstallEvent,
+};

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

@@ -11,12 +11,10 @@
  */
 
 import type { PluginDescriptor } from "../astro/integration/runtime.js";
+import type { SandboxedPlugin } from "../plugin-types.js";
 import { PLUGIN_CAPABILITIES, HOOK_NAMES } from "./manifest-schema.js";
 import { normalizeCapabilities } from "./types.js";
 import type {
-	StandardPluginDefinition,
-	StandardHookEntry,
-	StandardHookHandler,
 	ResolvedPlugin,
 	ResolvedPluginHooks,
 	ResolvedHook,
@@ -26,6 +24,29 @@ import type {
 	PluginAdminConfig,
 } from "./types.js";
 
+/**
+ * Loose per-hook entry shape used inside the adapter's iteration loop.
+ *
+ * `SandboxedPlugin.hooks` is a mapped type keyed by hook name, so each
+ * entry's type depends on the key. When the adapter iterates with
+ * `Object.entries`, the key is `string` (TypeScript can't see the
+ * narrowing), so we need a *union* type that covers every hook entry
+ * shape — bare handler or config form. This is that union, kept local
+ * because it has no use outside the adapter.
+ */
+// eslint-disable-next-line typescript-eslint/no-explicit-any -- must accept handlers with specific event types across all hook names
+type AnyHookHandler = (...args: any[]) => Promise<any>;
+type AnyHookEntry =
+	| AnyHookHandler
+	| {
+			handler: AnyHookHandler;
+			priority?: number;
+			timeout?: number;
+			dependencies?: string[];
+			errorPolicy?: "continue" | "abort";
+			exclusive?: boolean;
+	  };
+
 /**
  * Default hook configuration values
  */
@@ -34,27 +55,23 @@ const DEFAULT_TIMEOUT = 5000;
 const DEFAULT_ERROR_POLICY = "abort" as const;
 
 /**
- * Check if a standard hook entry is a config object (has a `handler` property)
+ * Check if a hook entry is the config form (has a `handler` property).
  */
-function isHookConfig(
-	entry: StandardHookEntry,
-): entry is Exclude<StandardHookEntry, StandardHookHandler> {
+function isHookConfig(entry: AnyHookEntry): entry is Exclude<AnyHookEntry, AnyHookHandler> {
 	return typeof entry === "object" && entry !== null && "handler" in entry;
 }
 
 /**
- * Resolve a single standard hook entry to a ResolvedHook.
+ * Resolve a single hook entry to a ResolvedHook.
  *
- * Standard-format hooks use the sandbox entry convention:
- *   handler(event, ctx) -- two args
+ * Sandboxed-format hooks use the standard two-arg convention:
+ *   handler(event, ctx)
  *
  * The HookPipeline dispatch methods also call handlers with (event, ctx),
- * so the handler is compatible as-is. We just need to wrap it for type safety.
+ * so the handler is compatible as-is — we just normalise the
+ * surrounding config (priority, timeout, etc.) to its defaults.
  */
-function resolveStandardHook(
-	entry: StandardHookEntry,
-	pluginId: string,
-): ResolvedHook<StandardHookHandler> {
+function resolveSandboxedHook(entry: AnyHookEntry, pluginId: string): ResolvedHook<AnyHookHandler> {
 	if (isHookConfig(entry)) {
 		return {
 			priority: entry.priority ?? DEFAULT_PRIORITY,
@@ -84,27 +101,46 @@ const VALID_CAPABILITIES_SET = new Set<string>(PLUGIN_CAPABILITIES);
 const VALID_HOOK_NAMES_SET = new Set<string>(HOOK_NAMES);
 
 /**
- * Adapt a standard-format plugin definition into a ResolvedPlugin.
+ * Adapt a sandboxed plugin's default export into a ResolvedPlugin.
  *
- * This is the core of the unified plugin format. It takes the `{ hooks, routes }`
- * export from a standard plugin and produces a ResolvedPlugin that can enter the
- * HookPipeline alongside native plugins.
+ * This is the in-process side of sandboxed-format plugins: it takes
+ * the `{ hooks, routes }` default export of a sandboxed plugin and
+ * produces a `ResolvedPlugin` that enters the HookPipeline alongside
+ * native plugins. The descriptor supplies identity (id, version) and
+ * the trust contract (capabilities, allowedHosts, storage); the
+ * definition supplies behaviour.
  *
- * @param definition - The standard plugin definition (from definePlugin() or raw export)
+ * @param definition - The plugin's default export (matching `SandboxedPlugin` from `emdash/plugin`).
  * @param descriptor - The plugin descriptor with id, version, capabilities, etc.
- * @returns A ResolvedPlugin compatible with HookPipeline
+ * @returns A ResolvedPlugin compatible with HookPipeline.
  */
 export function adaptSandboxEntry(
-	definition: StandardPluginDefinition,
+	definition: SandboxedPlugin,
 	descriptor: PluginDescriptor,
 ): ResolvedPlugin {
 	const pluginId = descriptor.id;
 	const version = descriptor.version;
 
-	// Resolve hooks
+	// A null / array / non-object `definition` would throw a generic
+	// `TypeError: Cannot read properties of null` further down the
+	// loop without the plugin id; surface a useful error first.
+	if (typeof definition !== "object" || definition === null || Array.isArray(definition)) {
+		throw new Error(
+			`Plugin "${pluginId}" default export must be an object with ` +
+				`\`hooks\` and/or \`routes\` (got ${
+					Array.isArray(definition) ? "array" : typeof definition
+				}). Did you forget \`export default {...} satisfies SandboxedPlugin\`?`,
+		);
+	}
+
+	// Resolve hooks. `SandboxedPlugin.hooks` is keyed by hook name with
+	// per-key entry types; iterating with `Object.entries` collapses
+	// keys to `string`, so we treat each entry as the union `AnyHookEntry`
+	// for the duration of the loop.
 	const resolvedHooks: ResolvedPluginHooks = {};
 	if (definition.hooks) {
-		for (const [hookName, entry] of Object.entries(definition.hooks)) {
+		const hookMap = definition.hooks as Record<string, AnyHookEntry>;
+		for (const [hookName, entry] of Object.entries(hookMap)) {
 			if (!VALID_HOOK_NAMES_SET.has(hookName)) {
 				throw new Error(
 					`Plugin "${pluginId}" declares unknown hook "${hookName}". ` +
@@ -115,33 +151,73 @@ export function adaptSandboxEntry(
 			// We store it as the generic type and let HookPipeline's typed dispatch
 			// methods handle the type narrowing at call time.
 			// eslint-disable-next-line typescript-eslint/no-unsafe-type-assertion -- bridging untyped map to typed interface
-			(resolvedHooks as Record<string, unknown>)[hookName] = resolveStandardHook(entry, pluginId);
+			(resolvedHooks as Record<string, unknown>)[hookName] = resolveSandboxedHook(entry, pluginId);
 		}
 	}
 
-	// Resolve routes: standard format uses (routeCtx, pluginCtx) two-arg pattern.
-	// Native format uses (ctx: RouteContext) single-arg pattern where RouteContext
-	// extends PluginContext with { input, request, requestMeta }.
-	// We wrap standard route handlers to merge the two args into one.
+	// Resolve routes: sandboxed format uses (routeCtx, pluginCtx) two-arg
+	// pattern. Native format uses (ctx: RouteContext) single-arg pattern
+	// where RouteContext extends PluginContext with
+	// { input, request, requestMeta }. We wrap sandboxed route handlers
+	// to merge the two args into one.
+	//
+	// Route entries can be bare functions or `{ handler, public?, input? }`
+	// config objects; normalise to the config shape inside the loop.
 	const resolvedRoutes: Record<string, PluginRoute> = {};
 	if (definition.routes) {
-		for (const [routeName, routeEntry] of Object.entries(definition.routes)) {
-			const standardHandler = routeEntry.handler;
+		for (const [routeName, rawEntry] of Object.entries(definition.routes)) {
+			const isConfig = typeof rawEntry === "object" && rawEntry !== null && "handler" in rawEntry;
+			const handler = isConfig
+				? (rawEntry as { handler: (...args: unknown[]) => Promise<unknown> }).handler
+				: (rawEntry as (...args: unknown[]) => Promise<unknown>);
+			const publicFlag = isConfig ? (rawEntry as { public?: boolean }).public : undefined;
+			const inputSchema = isConfig ? (rawEntry as { input?: unknown }).input : undefined;
 			resolvedRoutes[routeName] = {
-				// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- StandardRouteEntry.input is intentionally loosely typed; callers validate at runtime
-				input: routeEntry.input as PluginRoute["input"],
-				public: routeEntry.public,
+				// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- route entry.input is intentionally loosely typed; callers validate at runtime
+				input: inputSchema as PluginRoute["input"],
+				public: publicFlag,
 				handler: async (ctx) => {
-					// Build the routeCtx shape that standard handlers expect
+					// In-process, `ctx.request` is a real WHATWG `Request`
+					// with a `Headers` object. The author-facing
+					// `SandboxedRequest` type promises a plain
+					// `Record<string, string>` (the shape the sandbox's
+					// serialised form delivers). Normalise so handlers
+					// behave the same in-process and in-isolate.
+					const headers: Record<string, string> = {};
+					if (ctx.request && typeof ctx.request === "object") {
+						const h: unknown = (ctx.request as { headers?: unknown }).headers;
+						if (h && typeof h === "object") {
+							if (typeof (h as Headers).forEach === "function") {
+								(h as Headers).forEach((value, name) => {
+									headers[name] = value;
+								});
+							} else {
+								for (const [name, value] of Object.entries(h as Record<string, string>)) {
+									headers[name] = value;
+								}
+							}
+						}
+					}
+					const requestShape = {
+						url:
+							(ctx.request as { url?: unknown } | undefined)?.url &&
+							typeof (ctx.request as { url: unknown }).url === "string"
+								? (ctx.request as { url: string }).url
+								: "",
+						method:
+							(ctx.request as { method?: unknown } | undefined)?.method &&
+							typeof (ctx.request as { method: unknown }).method === "string"
+								? (ctx.request as { method: string }).method
+								: "GET",
+						headers,
+					};
 					const routeCtx = {
 						input: ctx.input,
-						request: ctx.request,
+						request: requestShape,
 						requestMeta: ctx.requestMeta,
 					};
-					// Pass only the PluginContext portion (without input/request/requestMeta)
-					// to match what sandboxed handlers receive.
 					const { input: _, request: __, requestMeta: ___, ...pluginCtx } = ctx;
-					return standardHandler(routeCtx, pluginCtx);
+					return handler(routeCtx, pluginCtx);
 				},
 			};
 		}