emdash 0.12.0 → 0.14.0

package/src/plugins/define-plugin.ts

@@ -1,16 +1,13 @@
 /**
  * definePlugin() Helper
  *
- * Creates a properly typed and normalized plugin definition.
- * Supports two formats:
- *
- * 1. **Native format** -- full PluginDefinition with id, version, capabilities, etc.
- *    Returns a ResolvedPlugin.
- *
- * 2. **Standard format** -- just { hooks, routes }. No id/version/capabilities.
- *    Returns the same object (identity function for type inference).
- *    Metadata comes from the descriptor at config time.
+ * Native plugin authoring entry. Returns a fully-resolved
+ * `ResolvedPlugin` ready for the host integration to mount.
  *
+ * Sandboxed plugins do NOT use this function. They default-export
+ * a bare `{ hooks?, routes? }` object with a `satisfies SandboxedPlugin`
+ * annotation from `emdash/plugin`. See the `emdash` changeset for the
+ * authoring shape.
  */
 
 import { normalizeCapabilities } from "./types.js";
@@ -23,7 +20,6 @@ import type {
 	HookConfig,
 	PluginCapability,
 	PluginStorageConfig,
-	StandardPluginDefinition,
 } from "./types.js";
 
 // Plugin ID validation patterns
@@ -32,33 +28,13 @@ const SCOPED_ID = /^@[a-z0-9-]+\/[a-z0-9-]+$/;
 const SEMVER_PATTERN = /^\d+\.\d+\.\d+/;
 
 /**
- * Define an EmDash plugin.
- *
- * **Standard format** -- the canonical format for plugins that work in both
- * trusted and sandboxed modes. No id/version -- those come from the descriptor.
- *
- * @example
- * ```typescript
- * import { definePlugin } from "emdash";
- *
- * export default definePlugin({
- *   hooks: {
- *     "content:afterSave": {
- *       handler: async (event, ctx) => {
- *         await ctx.kv.set("lastSave", Date.now());
- *       },
- *     },
- *   },
- *   routes: {
- *     status: {
- *       handler: async (routeCtx, ctx) => ({ ok: true }),
- *     },
- *   },
- * });
- * ```
+ * Define a native EmDash plugin.
  *
- * **Native format** -- for plugins that need React admin, direct DB access,
- * or other capabilities not available in the sandbox.
+ * Native plugins ship as regular npm modules, get installed via
+ * `pnpm add` + an `astro.config.mjs` edit, and run in the host
+ * process. They have full access to the runtime — capabilities are
+ * still enforced by `PluginContextFactory`, but there is no isolation
+ * boundary.
  *
  * @example
  * ```typescript
@@ -83,30 +59,32 @@ const SEMVER_PATTERN = /^\d+\.\d+\.\d+/;
  *   }
  * });
  * ```
+ *
+ * Sandboxed-format plugins do not use `definePlugin`. They
+ * default-export a bare `{ hooks?, routes? }` object with a
+ * `satisfies SandboxedPlugin` annotation from `emdash/plugin`. Calling
+ * `definePlugin` with an object that has no `id` throws at runtime
+ * (the type system already rejects it at compile time — this check is
+ * for callers that bypass typechecking).
  */
-// Native overload first -- PluginDefinition (with id+version) is more specific
 export function definePlugin<TStorage extends PluginStorageConfig>(
 	definition: PluginDefinition<TStorage>,
-): ResolvedPlugin<TStorage>;
-// Standard overload second -- catches { hooks, routes } without id/version
-export function definePlugin(definition: StandardPluginDefinition): StandardPluginDefinition;
-export function definePlugin<TStorage extends PluginStorageConfig>(
-	definition: PluginDefinition<TStorage> | StandardPluginDefinition,
-): ResolvedPlugin<TStorage> | StandardPluginDefinition {
-	// Standard format: has hooks/routes but no id/version
-	if (!("id" in definition) || !("version" in definition)) {
-		// Validate that the standard format has at least hooks or routes
-		if (!("hooks" in definition) && !("routes" in definition)) {
-			throw new Error(
-				"Standard plugin format requires at least `hooks` or `routes`. " +
-					"For native format, provide `id` and `version`.",
-			);
-		}
-		// Identity function -- return as-is for type inference.
-		// The adapter (adaptSandboxEntry) will convert this to a ResolvedPlugin at build time.
-		return definition;
+): ResolvedPlugin<TStorage> {
+	// Semantic check, not a structural one: `id` is what makes this a
+	// native definition. Sandboxed plugins (the only other shape that
+	// might land here at runtime) intentionally never have an `id` —
+	// identity comes from the manifest's `slug` + `publisher`, computed
+	// at install time. So "no id" is the unambiguous signal that the
+	// caller meant the sandboxed authoring flow.
+	if (typeof definition.id !== "string" || definition.id.length === 0) {
+		throw new Error(
+			`definePlugin() requires \`id\` (got ${typeof definition.id}). ` +
+				"For native plugins, make sure your definition has both `id` and " +
+				"`version`. For sandboxed plugins, drop `definePlugin()` entirely " +
+				"and `export default { hooks, routes } satisfies SandboxedPlugin` " +
+				'from "emdash/plugin" — identity comes from `emdash-plugin.jsonc`.',
+		);
 	}
-
 	return defineNativePlugin(definition);
 }
 

package/src/plugins/index.ts

@@ -71,7 +71,7 @@ export {
 } from "./sandbox/index.js";
 export type {
 	SandboxRunner,
-	SandboxedPlugin,
+	SandboxedPluginInstance,
 	SandboxRunnerFactory,
 	SandboxOptions,
 	SandboxEmailMessage,
@@ -183,15 +183,7 @@ export type {
 	PluginDefinition,
 	ResolvedPlugin,
 	PluginManifest,
-
-	// Standard plugin format
-	StandardPluginDefinition,
-	StandardHookHandler,
-	StandardHookEntry,
-	StandardRouteHandler,
-	StandardRouteEntry,
 } from "./types.js";
-export { isStandardPluginDefinition } from "./types.js";
 
 // Capability normalization (legacy → canonical alias layer)
 export {

package/src/plugins/marketplace.ts

@@ -376,7 +376,26 @@ class MarketplaceClientImpl implements MarketplaceClient {
  *
  * We use a minimal tar parser since we only need to read a few small files.
  */
-async function extractBundle(tarballBytes: Uint8Array): Promise<PluginBundle> {
+/**
+ * Exported so the experimental registry install handler can reuse the
+ * same parse / validate / hash primitive. Despite the file name, this
+ * function predates the marketplace-vs-registry split and is generic
+ * over plugin bundle tarballs regardless of distribution channel.
+ */
+// Aligns with RFC 0001 §"Bundle size limits" (256 KiB decompressed,
+// 20 files). Matches `MAX_BUNDLE_SIZE` in cli/commands/bundle-utils.ts
+// (the publish-side cap). We don't import that constant to keep this
+// runtime module independent of the CLI; the two values are
+// load-bearing identical and must stay in sync.
+//
+// Tar adds per-file headers (~512 bytes each) plus directory entries,
+// so the entry count cap is set comfortably above RFC's 20-file limit.
+// Going over either is a strong signal the bundle isn't a legitimate
+// sandboxed plugin.
+const MAX_DECOMPRESSED_BUNDLE_BYTES = 256 * 1024;
+const MAX_BUNDLE_TAR_ENTRIES = 32;
+
+export async function extractBundle(tarballBytes: Uint8Array): Promise<PluginBundle> {
 	// Decompress fully into memory first, then parse the tar.
 	// Passing a pipeThrough() stream directly to unpackTar causes a backpressure
 	// deadlock in workerd: the tar decoder's body-stream pull() needs more
@@ -389,9 +408,42 @@ async function extractBundle(tarballBytes: Uint8Array): Promise<PluginBundle> {
 		},
 	}).pipeThrough(createGzipDecoder());
 
-	// Collect decompressed bytes fully before parsing
-	const decompressedBuf = await new Response(decompressedStream).arrayBuffer();
-	const decompressedBytes = new Uint8Array(decompressedBuf);
+	// Collect decompressed bytes with a hard cap. A gzip-bomb -- a small
+	// tarball that decompresses to gigabytes -- otherwise exhausts
+	// worker / Node memory before we know to reject it. The cap matches
+	// RFC 0001's publish-time bundle size limit (MAX_DECOMPRESSED_BUNDLE_BYTES);
+	// anything past that isn't a legitimate sandboxed plugin.
+	const reader = decompressedStream.getReader();
+	const chunks: Uint8Array[] = [];
+	let total = 0;
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		if (!value) continue;
+		total += value.byteLength;
+		if (total > MAX_DECOMPRESSED_BUNDLE_BYTES) {
+			try {
+				await reader.cancel();
+			} catch {
+				// nothing to do
+			}
+			throw new MarketplaceError(
+				`Bundle decompressed size exceeds limit (${MAX_DECOMPRESSED_BUNDLE_BYTES} bytes)`,
+				undefined,
+				"INVALID_BUNDLE",
+			);
+		}
+		chunks.push(value);
+	}
+	const decompressedBytes = new Uint8Array(total);
+	{
+		let offset = 0;
+		for (const chunk of chunks) {
+			decompressedBytes.set(chunk, offset);
+			offset += chunk.byteLength;
+		}
+	}
+
 	const decompressed = new ReadableStream<Uint8Array>({
 		start(controller) {
 			controller.enqueue(decompressedBytes);
@@ -400,6 +452,13 @@ async function extractBundle(tarballBytes: Uint8Array): Promise<PluginBundle> {
 	});
 
 	const entries = await unpackTar(decompressed);
+	if (entries.length > MAX_BUNDLE_TAR_ENTRIES) {
+		throw new MarketplaceError(
+			`Bundle has too many tar entries (${entries.length} > ${MAX_BUNDLE_TAR_ENTRIES})`,
+			undefined,
+			"INVALID_BUNDLE",
+		);
+	}
 
 	const decoder = new TextDecoder();
 	const files = new Map<string, string>();

package/src/plugins/sandbox/index.ts

@@ -7,7 +7,7 @@ export { NoopSandboxRunner, SandboxNotAvailableError, createNoopSandboxRunner }
 
 export type {
 	SandboxRunner,
-	SandboxedPlugin,
+	SandboxedPluginInstance,
 	SandboxRunnerFactory,
 	SandboxOptions,
 	SandboxEmailMessage,

package/src/plugins/sandbox/noop.ts

@@ -7,7 +7,7 @@
  */
 
 import type { PluginManifest } from "../types.js";
-import type { SandboxRunner, SandboxedPlugin, SandboxOptions } from "./types.js";
+import type { SandboxRunner, SandboxedPluginInstance, SandboxOptions } from "./types.js";
 
 /**
  * Error thrown when attempting to use sandboxing on an unsupported platform.
@@ -48,7 +48,7 @@ export class NoopSandboxRunner implements SandboxRunner {
 		_manifest: PluginManifest,
 		// eslint-disable-next-line @typescript-eslint/no-unused-vars
 		_code: string,
-	): Promise<SandboxedPlugin> {
+	): Promise<SandboxedPluginInstance> {
 		throw new SandboxNotAvailableError();
 	}
 

package/src/plugins/sandbox/types.ts

@@ -78,10 +78,13 @@ export interface SandboxOptions {
 }
 
 /**
- * A sandboxed plugin instance.
- * Provides methods to invoke hooks and routes in the isolated environment.
+ * Handle to a sandboxed plugin running inside an isolate. Returned
+ * by `SandboxRunner.load` and held by the runtime's cache so hooks /
+ * routes can be invoked across the isolate boundary. Distinct from
+ * the author-facing `SandboxedPlugin` type in `emdash/plugin`, which
+ * describes the source-level shape of a plugin's default export.
  */
-export interface SandboxedPlugin {
+export interface SandboxedPluginInstance {
 	/** Unique identifier: `${manifest.id}:${manifest.version}` */
 	readonly id: string;
 
@@ -142,7 +145,7 @@ export interface SandboxRunner {
 	 * @returns A sandboxed plugin instance
 	 * @throws If sandboxing is not available or plugin can't be loaded
 	 */
-	load(manifest: PluginManifest, code: string): Promise<SandboxedPlugin>;
+	load(manifest: PluginManifest, code: string): Promise<SandboxedPluginInstance>;
 
 	/**
 	 * Set the email send callback for sandboxed plugins.

package/src/plugins/state.ts

@@ -10,7 +10,7 @@ import type { Kysely } from "kysely";
 import type { Database } from "../database/types.js";
 
 export type PluginStatus = "active" | "inactive";
-export type PluginSource = "config" | "marketplace";
+export type PluginSource = "config" | "marketplace" | "registry";
 
 function toPluginStatus(value: string): PluginStatus {
 	if (value === "active") return "active";
@@ -19,6 +19,7 @@ function toPluginStatus(value: string): PluginStatus {
 
 function toPluginSource(value: string | undefined | null): PluginSource {
 	if (value === "marketplace") return "marketplace";
+	if (value === "registry") return "registry";
 	return "config";
 }
 
@@ -33,6 +34,21 @@ export interface PluginState {
 	marketplaceVersion: string | null;
 	displayName: string | null;
 	description: string | null;
+	/**
+	 * Publisher DID this plugin was published under. Populated only when
+	 * `source === "registry"`; null otherwise.
+	 */
+	registryPublisherDid: string | null;
+	/**
+	 * Slug under which the plugin was published in the publisher's repo
+	 * (the rkey of the `pm.fair.package.profile` record). Populated only
+	 * when `source === "registry"`; null otherwise.
+	 *
+	 * The opaque `pluginId` for registry installs is derived from
+	 * `(registryPublisherDid, registrySlug)` -- see
+	 * `packages/core/src/registry/plugin-id.ts`.
+	 */
+	registrySlug: string | null;
 }
 
 /**
@@ -53,18 +69,7 @@ export class PluginStateRepository {
 
 		if (!row) return null;
 
-		return {
-			pluginId: row.plugin_id,
-			status: toPluginStatus(row.status),
-			version: row.version,
-			installedAt: new Date(row.installed_at),
-			activatedAt: row.activated_at ? new Date(row.activated_at) : null,
-			deactivatedAt: row.deactivated_at ? new Date(row.deactivated_at) : null,
-			source: toPluginSource(row.source),
-			marketplaceVersion: row.marketplace_version ?? null,
-			displayName: row.display_name ?? null,
-			description: row.description ?? null,
-		};
+		return rowToPluginState(row);
 	}
 
 	/**
@@ -72,19 +77,7 @@ export class PluginStateRepository {
 	 */
 	async getAll(): Promise<PluginState[]> {
 		const rows = await this.db.selectFrom("_plugin_state").selectAll().execute();
-
-		return rows.map((row) => ({
-			pluginId: row.plugin_id,
-			status: toPluginStatus(row.status),
-			version: row.version,
-			installedAt: new Date(row.installed_at),
-			activatedAt: row.activated_at ? new Date(row.activated_at) : null,
-			deactivatedAt: row.deactivated_at ? new Date(row.deactivated_at) : null,
-			source: toPluginSource(row.source),
-			marketplaceVersion: row.marketplace_version ?? null,
-			displayName: row.display_name ?? null,
-			description: row.description ?? null,
-		}));
+		return rows.map(rowToPluginState);
 	}
 
 	/**
@@ -96,19 +89,22 @@ export class PluginStateRepository {
 			.selectAll()
 			.where("source", "=", "marketplace")
 			.execute();
+		return rows.map(rowToPluginState);
+	}
 
-		return rows.map((row) => ({
-			pluginId: row.plugin_id,
-			status: toPluginStatus(row.status),
-			version: row.version,
-			installedAt: new Date(row.installed_at),
-			activatedAt: row.activated_at ? new Date(row.activated_at) : null,
-			deactivatedAt: row.deactivated_at ? new Date(row.deactivated_at) : null,
-			source: toPluginSource(row.source),
-			marketplaceVersion: row.marketplace_version ?? null,
-			displayName: row.display_name ?? null,
-			description: row.description ?? null,
-		}));
+	/**
+	 * Get all registry-installed plugin states.
+	 *
+	 * The runtime's registry sync path uses this to discover which
+	 * registry plugins should be loaded into the sandbox on this worker.
+	 */
+	async getRegistryPlugins(): Promise<PluginState[]> {
+		const rows = await this.db
+			.selectFrom("_plugin_state")
+			.selectAll()
+			.where("source", "=", "registry")
+			.execute();
+		return rows.map(rowToPluginState);
 	}
 
 	/**
@@ -123,6 +119,8 @@ export class PluginStateRepository {
 			marketplaceVersion?: string;
 			displayName?: string;
 			description?: string;
+			registryPublisherDid?: string;
+			registrySlug?: string;
 		},
 	): Promise<PluginState> {
 		const now = new Date().toISOString();
@@ -151,6 +149,12 @@ export class PluginStateRepository {
 			if (opts?.description !== undefined) {
 				updates.description = opts.description;
 			}
+			if (opts?.registryPublisherDid !== undefined) {
+				updates.registry_publisher_did = opts.registryPublisherDid;
+			}
+			if (opts?.registrySlug !== undefined) {
+				updates.registry_slug = opts.registrySlug;
+			}
 
 			await this.db
 				.updateTable("_plugin_state")
@@ -173,6 +177,8 @@ export class PluginStateRepository {
 					marketplace_version: opts?.marketplaceVersion ?? null,
 					display_name: opts?.displayName ?? null,
 					description: opts?.description ?? null,
+					registry_publisher_did: opts?.registryPublisherDid ?? null,
+					registry_slug: opts?.registrySlug ?? null,
 				})
 				.execute();
 		}
@@ -206,3 +212,43 @@ export class PluginStateRepository {
 		return (result.numDeletedRows ?? 0) > 0;
 	}
 }
+
+/**
+ * Internal: map a `_plugin_state` row to the public `PluginState` shape.
+ *
+ * Kept at module scope so the three select paths (`get`, `getAll`,
+ * `getMarketplacePlugins`, `getRegistryPlugins`) stay byte-identical in
+ * their handling of nullable columns -- adding a new column to the table
+ * means changing this function and nothing else.
+ */
+interface PluginStateRow {
+	plugin_id: string;
+	status: string;
+	version: string;
+	installed_at: string;
+	activated_at: string | null;
+	deactivated_at: string | null;
+	source: string;
+	marketplace_version: string | null;
+	display_name: string | null;
+	description: string | null;
+	registry_publisher_did: string | null;
+	registry_slug: string | null;
+}
+
+function rowToPluginState(row: PluginStateRow): PluginState {
+	return {
+		pluginId: row.plugin_id,
+		status: toPluginStatus(row.status),
+		version: row.version,
+		installedAt: new Date(row.installed_at),
+		activatedAt: row.activated_at ? new Date(row.activated_at) : null,
+		deactivatedAt: row.deactivated_at ? new Date(row.deactivated_at) : null,
+		source: toPluginSource(row.source),
+		marketplaceVersion: row.marketplace_version ?? null,
+		displayName: row.display_name ?? null,
+		description: row.description ?? null,
+		registryPublisherDid: row.registry_publisher_did ?? null,
+		registrySlug: row.registry_slug ?? null,
+	};
+}

package/src/plugins/types.ts

@@ -12,7 +12,7 @@
 import type { Element } from "@emdash-cms/blocks";
 // The plugin capability vocabulary, the legacy-rename map, and the manifest
 // shape are authored once in @emdash-cms/plugin-types and shared between core
-// (the manifest reader at install/runtime) and @emdash-cms/registry-cli (the
+// (the manifest reader at install/runtime) and @emdash-cms/plugin-cli (the
 // manifest writer at bundle/publish time).
 //
 // We import-and-re-export here so existing internal callers keep working
@@ -58,7 +58,7 @@ export {
 //
 // `StorageCollectionConfig` and `PluginStorageConfig` are re-exported above
 // from `@emdash-cms/plugin-types`. The manifest carries these shapes
-// verbatim; both this package (reader) and registry-cli (writer) agree on
+// verbatim; both this package (reader) and plugin-cli (writer) agree on
 // the same types via the shared package.
 
 /**
@@ -1303,83 +1303,6 @@ export interface ResolvedPluginHooks {
 	"page:fragments"?: ResolvedHook<PageFragmentHandler>;
 }
 
-// =============================================================================
-// Standard Plugin Format (Unified Plugin Format)
-// =============================================================================
-
-/**
- * Standard plugin hook handler -- same as sandbox entry format.
- * Receives the event as the first argument and a PluginContext as the second.
- *
- * Plugin authors annotate their event parameters with specific types for IDE
- * support. At the type level, we accept any function with compatible arity.
- */
-// eslint-disable-next-line typescript-eslint/no-explicit-any -- must accept handlers with specific event types
-export type StandardHookHandler = (...args: any[]) => Promise<any>;
-
-/**
- * Standard plugin hook entry -- either a bare handler or a config object.
- */
-export type StandardHookEntry =
-	| StandardHookHandler
-	| {
-			handler: StandardHookHandler;
-			priority?: number;
-			timeout?: number;
-			dependencies?: string[];
-			errorPolicy?: "continue" | "abort";
-			exclusive?: boolean;
-	  };
-
-/**
- * Standard plugin route handler -- takes (routeCtx, pluginCtx) like sandbox entries.
- * The routeCtx contains input and request info; pluginCtx is the full plugin context.
- *
- * Uses `any` for routeCtx to allow plugins to access properties like
- * `routeCtx.request.url` without needing exact type matches across
- * trusted (Request object) and sandboxed (plain object) modes.
- */
-// eslint-disable-next-line typescript-eslint/no-explicit-any -- see above
-export type StandardRouteHandler = (routeCtx: any, ctx: PluginContext) => Promise<unknown>;
-
-/**
- * Standard plugin route entry -- either a config object with handler, or just a handler.
- */
-export interface StandardRouteEntry {
-	handler: StandardRouteHandler;
-	input?: unknown;
-	public?: boolean;
-}
-
-/**
- * Standard plugin definition -- the sandbox entry format.
- * Used by standard plugins that work in both trusted and sandboxed modes.
- * No id/version/capabilities -- those come from the descriptor.
- *
- * This is the input to definePlugin() for standard-format plugins.
- *
- * The hooks and routes use permissive types (Record<string, any>) so that
- * plugin authors can annotate their handlers with specific event types
- * without type errors from strictFunctionTypes contravariance.
- */
-export interface StandardPluginDefinition {
-	// eslint-disable-next-line typescript-eslint/no-explicit-any -- must accept handlers with specific event/route types
-	hooks?: Record<string, any>;
-	// eslint-disable-next-line typescript-eslint/no-explicit-any -- must accept handlers with specific event/route types
-	routes?: Record<string, any>;
-}
-
-/**
- * Check if a value is a StandardPluginDefinition (has hooks/routes but no id/version).
- */
-export function isStandardPluginDefinition(value: unknown): value is StandardPluginDefinition {
-	if (typeof value !== "object" || value === null) return false;
-	// Standard format: has hooks or routes, but NOT id+version (which are on PluginDefinition)
-	const hasPluginShape = "hooks" in value || "routes" in value;
-	const hasNativeShape = "id" in value && "version" in value;
-	return hasPluginShape && !hasNativeShape;
-}
-
 // =============================================================================
 // Plugin Admin Exports
 // =============================================================================