dckc/captoys

0 Fork 0

Files

T

dckc 4b4ef8fea6 capsite: potluck, a fresh EmDash site (cloudflare:blog out of the box)

pnpm create emdash@latest potluck --pm pnpm --install --yes, per
https://docs.emdashcms.com/ ("Create your first EmDash site"); the
--yes defaults are cloudflare + blog. Replaces the old madmode/
starter (never committed).

Generated-by: create-emdash 1.2.0, run by Claude Opus 5.5

2026-10-07 19:57:43 -05:00

22 KiB

Raw Blame History

Hooks

Sandboxed plugins declare hooks in the typed default export from src/plugin.ts. The SandboxedPlugin type infers each event and return type from the hook name.

Signature

async (event: EventType, ctx: PluginContext) => ReturnType;

Configuration

Simple handler or full config:

import type { SandboxedPlugin } from "emdash/plugin";

const plugin: SandboxedPlugin = {
	hooks: {
		"content:afterSave": {
			priority: 100,
			timeout: 5000,
			handler: async (event, ctx) => {
				ctx.log.info("Saved", { id: event.content.id });
			},
		},
	},
};

export default plugin;

The plugin CLI manifest retains priority, timeout, dependencies, errorPolicy, and exclusive. Registry-installed and config-managed sandbox hooks enter the shared host pipeline, so these settings apply consistently with trusted plugins.

Put capabilities in emdash-plugin.jsonc, not in src/plugin.ts. The host pipeline skips sandboxed and trusted hooks whose required capability is absent.

Isolated sandbox support

The current isolated runtime dispatches these hooks to Cloudflare and Node/workerd sandbox instances through the shared host pipeline:

plugin:install, plugin:activate, plugin:deactivate, and plugin:uninstall
content:beforeSave, content:afterSave, content:beforeDelete, and content:afterDelete
content:beforePublish, content:beforeSchedule, content:beforeUnpublish, content:afterPublish, content:afterUnpublish, content:afterRestore, content:afterSchedule, and content:afterUnschedule
media:beforeUpload and media:afterUpload
email:beforeSend, email:deliver, and email:afterSend
comment:beforeCreate, comment:moderate, comment:afterCreate, and comment:afterModerate
cron
page:metadata

page:fragments is the only declared hook excluded from sandbox registration. The plugin CLI accepts it and emits a trusted-only warning; the sandbox host proxy drops it before the hook pipeline is built.

Lifecycle Hooks

`plugin:install`

Runs once on first install. Use to seed defaults.

"plugin:install": async (_event, ctx) => {
	await ctx.settings.set("enabled", true);
	await ctx.storage.items!.put("default", { name: "Default" });
}

Event: {} Returns: void

`plugin:activate`

Runs when plugin is enabled (after install or re-enable).

"plugin:activate": async (_event, ctx) => {
	ctx.log.info("Activated");
}

Event: {} Returns: void

`plugin:deactivate`

Runs when plugin is disabled (not removed).

"plugin:deactivate": async (_event, ctx) => {
	ctx.log.info("Deactivated");
}

Event: {} Returns: void

`plugin:uninstall`

Runs when plugin is removed. Only delete data if event.deleteData is true.

"plugin:uninstall": async (event, ctx) => {
	if (event.deleteData) {
		const result = await ctx.storage.items!.query({ limit: 1000 });
		await ctx.storage.items!.deleteMany(result.items.map(i => i.id));
	}
}

Event: { deleteData: boolean } Returns: void

Content Hooks

`content:beforeSave`

Runs before save. Return modified content, or void to keep it unchanged. To reject from the sandbox, return { __emdashSandboxHookResult: true, version: 1, error: { code: "SAVE_REJECTED", reason } }. The reason must be 1–500 characters of plain text. EmDash identifies the plugin and shows the reason as text; invalid or unknown error results fail with a generic hook error. From the host process, throw ContentSaveRejectedError (exported from emdash) instead. Any other exception from either execution mode fails the save with a generic message.

"content:beforeSave": async (event, ctx) => {
	const { content } = event;
	if (!content.title) {
		return {
			__emdashSandboxHookResult: true,
			version: 1,
			error: { code: "SAVE_REJECTED", reason: "Add a title before saving." },
		};
	}

	// Transform
	if (content.slug) {
		content.slug = content.slug.toLowerCase().replace(/\s+/g, "-");
	}

	return content;
}

Event: { content: Record<string, unknown>, collection: string, isNew: boolean, id?: string, actor?: { id: string, role: number } }. Authenticated REST, visual editing, and MCP saves include a read-only actor snapshot; internal writes may omit it. On updates, id identifies the existing item. The actor snapshot does not identify the request origin, so a hook cannot distinguish REST, visual editing, MCP, or another authenticated path from this field alone. Returns: Record<string, unknown> | SandboxHookErrorEnvelope | void

`content:afterSave`

Runs after successful save. Side effects only — logging, notifications, syncing.

"content:afterSave": async (event, ctx) => {
	const { content, collection, isNew } = event;
	ctx.log.info(`${isNew ? "Created" : "Updated"} ${collection}/${content.id}`);
}

Event: { content: Record<string, unknown>, collection: string, isNew: boolean, actor?: { id: string, role: number } }. Authenticated saves include a read-only actor snapshot; internal writes may omit it. Returns: void

`content:beforeDelete`

Runs before delete. Return false to cancel, true or void to allow.

"content:beforeDelete": async (event, ctx) => {
	if (event.collection === "pages" && event.id === "home") {
		ctx.log.warn("Cannot delete home page");
		return false;
	}
	return true;
}

Event: { id: string, collection: string } Returns: boolean | void

`content:afterDelete`

Runs after successful delete.

"content:afterDelete": async (event, ctx) => {
	ctx.log.info(`Deleted ${event.collection}/${event.id}`);
	await ctx.storage.cache!.delete(`${event.collection}:${event.id}`);
}

Event: { id: string, collection: string } Returns: void

Publication policy hooks

content:beforePublish, content:beforeSchedule, and content:beforeUnpublish require hooks.content-policy:register. This authority is independent of content:read, content:write, and publication actions.

Publish and schedule events expose the effective draft in content.data and the staged slug in content.slug. Unpublish events expose the currently live content that the action would remove.

Return void to allow the action or { cancel: true, reason } to reject it. The reason must contain 1–500 plain-text characters. Invalid decisions and unexpected abort-policy errors stop the action with a generic failure. Explicit cancellations return PUBLISH_REJECTED, SCHEDULE_REJECTED, or UNPUBLISH_REJECTED.

"content:beforePublish": async (event) => {
	const data = event.content.data;
	const approvalStatus =
		typeof data === "object" && data !== null && "approval_status" in data
			? data.approval_status
			: undefined;
	if (approvalStatus !== "approved") {
		return { cancel: true, reason: "Approve this entry before publishing." };
	}
},

Events contain { content, collection, origin, actor? }; content:beforeSchedule also contains scheduledAt. Human origins are api, mcp, or visual-editor and include the same value in actor.source. The visual-editor origin requires the signed short-lived token from an authenticated toolbar render. Other origins are plugin (with pluginId), scheduler, and system.

Scheduled content runs content:beforePublish again when it becomes due. An explicit scheduler rejection unschedules the entry and lists its reason on the dashboard until the entry is rescheduled, published, deleted, or the record is dismissed. There is no content:beforeUnschedule, so an administrator can always cancel a future publication.