emdash-multisite 0.0.0-stage → 0.7.0

package/src/orgs.ts

@@ -0,0 +1,343 @@
+/**
+ * "Creating an organization creates a site."
+ *
+ * Watches ONE Better Auth call on the control-plane site, POST
+ * /api/auth/organization/create, without changing the (open-source) plugin:
+ *   - before: rejects a slug that cannot be a site name;
+ *   - after a 200: provisions the site in the background and tracks status.
+ *
+ * The org slug is the site id and therefore the subdomain: `acme` -> acme.<domain>.
+ */
+import { sql } from "kysely";
+import { applySeed } from "emdash";
+// @ts-ignore - virtual module provided by EmDash's integration (the bundled seed)
+import { userSeed } from "virtual:emdash/seed";
+import { runAsSite } from "./dialect.ts";
+import { isSiteId } from "./rewrite.ts";
+import { BUNDLED_THEME, DEFAULT_CONCURRENT_PROVISIONS, SLOT_WAIT_MS, STALE_PROVISIONING_MS, templateId, effectiveTheme, needsReconcile, themeFromMetadata, type ProvisionStep, type SiteStatus } from "./rules.ts";
+import { siteUrl, type SitesConfig } from "./sites.ts";
+import { controlDb, forgetSiteTheme, readAllStates, readOrgs, readSiteTheme, siteHasTables } from "./registry.ts";
+import { scopeState } from "./scope.ts";
+import { provisionWith } from "./provision.ts";
+import { log } from "./log.ts";
+import { cloneTemplate, hasTemplate } from "./clone-run.ts";
+import { sitesConfig } from "./config.ts";
+import { acquireSlot, releaseSlot } from "./slots.ts";
+import { dropSiteTables } from "./purge.ts";
+
+export { ORG_CREATE_PATH, RESERVED_SITE_IDS, parseCreatedOrg, slugProblem, type SiteStatus } from "./rules.ts";
+
+const statusKey = (slug: string) => `multisite:site:${slug}`;
+
+export async function readStatus(slug: string): Promise<SiteStatus | null> {
+	const db = controlDb();
+	const row = await runAsSite(scopeState().primary, () =>
+		sql<{ value: string }>`SELECT value FROM options WHERE name = ${statusKey(slug)}`.execute(db),
+	);
+	const v = row.rows[0]?.value;
+	return v ? (JSON.parse(v) as SiteStatus) : null;
+}
+
+export async function writeStatus(slug: string, s: SiteStatus): Promise<void> {
+	const db = controlDb();
+	await runAsSite(scopeState().primary, () =>
+		sql`INSERT INTO options (name, value) VALUES (${statusKey(slug)}, ${JSON.stringify(s)})
+			ON CONFLICT(name) DO UPDATE SET value = excluded.value`.execute(db),
+	);
+}
+
+const BA_SETTINGS = "plugin:better-auth-settings:settings:";
+// SMTP provider config + state (settings:global, settings:provider:*, state:selectedProviderId). Inherited so every tenant
+// sends mail through the platform's email provider out of the box.
+const SMTP_SETTINGS = "plugin:emdash-smtp:";
+/** Settings not inherited by customer sites: they decide for themselves. */
+const NOT_INHERITED = new Set([`${BA_SETTINGS}orgEnabled`, `${BA_SETTINGS}teamsEnabled`, `${BA_SETTINGS}signUpEnabled`]);
+
+/** Can visitors register on this site? Unset means open (Better Auth's default; sites made before the setting existed). */
+export async function signUpOpen(slug: string): Promise<boolean> {
+	const db = controlDb();
+	const r = await runAsSite(slug, () => sql<{ value: string }>`SELECT value FROM options WHERE name = ${`${BA_SETTINGS}signUpEnabled`}`.execute(db));
+	return r.rows[0]?.value !== "false";
+}
+
+const SIGNUP_MEMO = Symbol.for("emdash-multisite:signup-memo");
+/** `signUpOpen`, remembered for 30 s per isolate: it is asked for on every public page view. */
+export async function signUpOpenCached(slug: string): Promise<boolean> {
+	const g = globalThis as Record<symbol, Map<string, { v: boolean; t: number }> | undefined>;
+	const memo = (g[SIGNUP_MEMO] ??= new Map());
+	const hit = memo.get(slug);
+	if (hit && Date.now() - hit.t < 30_000) return hit.v;
+	const v = await signUpOpen(slug);
+	if (memo.size > 2000) memo.clear();
+	memo.set(slug, { v, t: Date.now() });
+	return v;
+}
+
+/** Free core's migration lock if it has been held longer than a provisioning run can last. */
+async function releaseStaleLock(db: ReturnType<typeof controlDb>, slug: string): Promise<void> {
+	const cutoff = Date.now() - STALE_PROVISIONING_MS;
+	await runAsSite(slug, () =>
+		sql`UPDATE _emdash_migrations_lock SET is_locked = 0 WHERE is_locked > 0 AND is_locked < ${cutoff}`
+			.execute(db)
+			.catch(() => {}), // first run: the table does not exist yet
+	);
+}
+
+/**
+ * A site's tables (core migrations, run as that site) and its starter content.
+ * Migrations alone leave an empty schema with no collections, so without the
+ * seed a new tenant has nothing to edit. core's applySeed upserts, so a retry is
+ * safe. Media is not downloaded: see "Media (uploads)" in the README.
+ */
+async function buildSchemaAndSeed(
+	db: ReturnType<typeof controlDb>,
+	slug: string,
+	seed: unknown,
+	done?: (ended: ProvisionStep, next?: ProvisionStep) => Promise<void>,
+): Promise<void> {
+	await provisionWith(db, slug);
+	await done?.("tables", "content");
+	if (seed) {
+		// eslint-disable-next-line typescript/no-explicit-any -- core types its own Database/Seed
+		await runAsSite(slug, () => applySeed(db as any, seed as any, { includeContent: true, skipMediaDownload: true }));
+	}
+}
+
+/**
+ * Build the template site for a theme (`tpl-<theme>`): the pre-built copy that new
+ * sites are cloned from. Slow (the full migrate-and-seed), so run it once, not per
+ * customer. It has no owner and no organization. Refuses to overwrite unless `rebuild` is set, which
+ * drops the template first (after an EmDash upgrade or a theme seed change). New sites made while it is
+ * being rebuilt take the slow path.
+ */
+export async function buildTemplate(sites: SitesConfig, theme: string, opts: { rebuild?: boolean } = {}): Promise<"built" | "exists" | "unknown-theme"> {
+	const seed = sites.themes?.[theme]?.seed;
+	if (!seed) return "unknown-theme";
+	const slug = templateId(theme);
+	if (await hasTemplate(theme)) {
+		if (!opts.rebuild) return "exists";
+		const dropped = await runAsSite(scopeState().primary, () => dropSiteTables(slug));
+		if (dropped.remaining) throw new Error(`[multisite] could not clear ${dropped.remaining} tables of ${slug}`);
+	}
+	await buildSchemaAndSeed(controlDb(), slug, seed);
+	await runAsSite(slug, async () => {
+		// Without this flag EmDash's APIs answer NOT_CONFIGURED (the template doubles as a public demo, whose
+		// search needs them). Clones get it again from the identity step either way.
+		await sql`INSERT INTO options (name, value) VALUES ('emdash:setup_complete', 'true')
+			ON CONFLICT(name) DO UPDATE SET value = 'true'`.execute(controlDb());
+		// Written last: it marks the template complete.
+		await sql`INSERT INTO options (name, value) VALUES ('multisite:theme', ${JSON.stringify(theme)})
+			ON CONFLICT(name) DO UPDATE SET value = excluded.value`.execute(controlDb());
+	});
+	log("template.built", { theme });
+	return "built";
+}
+
+/**
+ * Create the site `slug` and hand it to `ownerUserId`. Idempotent: running it
+ * again on a half-provisioned site completes it.
+ */
+export async function createSiteForOrg(
+	org: { slug: string; name: string; ownerUserId: string },
+	plan: { theme: string; seed?: unknown } = { theme: BUNDLED_THEME },
+): Promise<void> {
+	const st = scopeState();
+	const startedAt = new Date().toISOString();
+	await writeStatus(org.slug, { status: "provisioning", startedAt, step: "tables" });
+	// Wait for one of the platform's provisioning slots; if none frees up soon, say "queued" and let the next poll or cron retry.
+	const max = sitesConfig()?.limits?.concurrentProvisions ?? DEFAULT_CONCURRENT_PROVISIONS;
+	if (!(await acquireSlot(org.slug, max, SLOT_WAIT_MS))) {
+		await writeStatus(org.slug, { status: "provisioning", startedAt: new Date().toISOString(), step: "queued" });
+		log("site.queued", { site: org.slug });
+		return;
+	}
+	const timings: Partial<Record<ProvisionStep, number>> = {};
+	let lap = Date.now();
+	/** Record how long the step that just ended took, and announce the next one. */
+	const done = async (ended: ProvisionStep, next?: ProvisionStep) => {
+		const now = Date.now();
+		timings[ended] = now - lap;
+		lap = now;
+		if (next) await writeStatus(org.slug, { status: "provisioning", startedAt, step: next });
+	};
+	try {
+		const db = controlDb();
+
+		// 0. a run that was killed mid-migration (Worker evicted) leaves core's
+		//    migration lock held, and every retry then refuses to start. Release a
+		//    lock old enough that its owner is certainly gone.
+		await releaseStaleLock(db, org.slug);
+
+		// 1. the site's tables and starter content: copied from the theme's template in one
+		//    D1 batch when there is one, else core migrations + the theme's seed (slow: ~70 s).
+		//    A site that already has tables is a retry of a partial run; it takes the slow path.
+		const cloned = !(await siteHasTables(org.slug)) && (await cloneTemplate(plan.theme, org.slug));
+		if (cloned) {
+			await done("tables", "content");
+		} else {
+			await buildSchemaAndSeed(db, org.slug, plan.seed ?? userSeed, done);
+		}
+		await done("content", "identity");
+		// 2. read the owner's identity and platform auth policy from the control plane
+		const { owner, storage, inherited } = await runAsSite(st.primary, async () => {
+			const u = await sql<Record<string, unknown>>`SELECT * FROM users WHERE id = ${org.ownerUserId}`.execute(db);
+			const s = await sql<Record<string, unknown>>`
+				SELECT * FROM _plugin_storage
+				WHERE collection IN ('accounts', 'usernames') AND data LIKE ${`%"userId":"${org.ownerUserId}"%`}`.execute(db);
+			// Better Auth policy + the SMTP provider config (stored in `options` under plugin:emdash-smtp:). Copying the SMTP
+			// settings/state gives every tenant the platform's own email provider (Resend) so plugins and auth can send mail
+			// without the owner configuring anything. SECURITY: the Resend API key is a secret and becomes readable in the
+			// tenant's own SMTP admin — acceptable here because every tenant shares one platform key (rotate platform-wide).
+			const o = await sql<{ name: string; value: string }>`
+				SELECT name, value FROM options WHERE name LIKE ${`${BA_SETTINGS}%`} OR name LIKE ${`${SMTP_SETTINGS}%`}`.execute(db);
+			return { owner: u.rows[0], storage: s.rows, inherited: o.rows.filter((r) => !NOT_INHERITED.has(r.name)) };
+		});
+		if (!owner) throw new Error(`owner ${org.ownerUserId} not found on the control plane`);
+
+		// 3. write them into the new site: owner becomes admin (EmDash role 50 and Better Auth role "admin", or the
+		//    Users page and Make premium would be refused for the person who owns the site), verified
+		await runAsSite(org.slug, async () => {
+			await sql`INSERT INTO users (id, email, name, avatar_url, role, email_verified, data, created_at, updated_at, disabled)
+				VALUES (${owner.id}, ${owner.email}, ${owner.name}, ${owner.avatar_url}, 50, 1, json_set(COALESCE(${owner.data}, '{}'), '$.role', 'admin'),
+					${owner.created_at}, ${owner.updated_at}, 0)
+				ON CONFLICT(id) DO UPDATE SET role = 50, email_verified = 1, data = json_set(COALESCE(users.data, '{}'), '$.role', 'admin')`.execute(db);
+			for (const r of storage) {
+				await sql`INSERT INTO _plugin_storage (plugin_id, collection, id, data, created_at, updated_at, revision)
+					VALUES (${r.plugin_id}, ${r.collection}, ${r.id}, ${r.data}, ${r.created_at}, ${r.updated_at}, ${r.revision})
+					ON CONFLICT(plugin_id, collection, id) DO NOTHING`.execute(db);
+			}
+			for (const r of inherited) {
+				await sql`INSERT INTO options (name, value) VALUES (${r.name}, ${r.value})
+					ON CONFLICT(name) DO NOTHING`.execute(db);
+			}
+			// A new customer site is closed to public registration; its owner turns it on in Settings
+			// ("Allow new sign-ups", emdash-better-auth 0.11) if they want subscribers. DO NOTHING so a
+			// retry of provisioning never undoes the owner's choice.
+			await sql`INSERT INTO options (name, value) VALUES (${`${BA_SETTINGS}signUpEnabled`}, 'false')
+				ON CONFLICT(name) DO NOTHING`.execute(db);
+			await sql`INSERT INTO options (name, value) VALUES ('multisite:theme', ${JSON.stringify(plan.theme)})
+				ON CONFLICT(name) DO UPDATE SET value = excluded.value`.execute(db);
+			await sql`INSERT INTO options (name, value) VALUES ('site:title', ${JSON.stringify(org.name)})
+				ON CONFLICT(name) DO UPDATE SET value = excluded.value`.execute(db);
+			// EmDash's runtime (and so every plugin's `ctx.site.name`) reads `emdash:site_title`, which only first-run setup writes;
+			// `site:title` is the user-facing alias. Keep both so plugins see the site's name.
+			await sql`INSERT INTO options (name, value) VALUES ('emdash:site_title', ${JSON.stringify(org.name)})
+				ON CONFLICT(name) DO UPDATE SET value = excluded.value`.execute(db);
+			// The site's own public origin. EmDash plugins build absolute URLs from it (the SEO plugin's llms.txt, sitemaps, canonical
+			// links); a cloned tenant never ran first-run setup, so without this they have no origin and emit nothing.
+			const origin = siteUrl(org.slug, sitesConfig() ?? ({} as SitesConfig));
+			if (origin) {
+				await sql`INSERT INTO options (name, value) VALUES ('site:url', ${JSON.stringify(origin)})
+					ON CONFLICT(name) DO UPDATE SET value = excluded.value`.execute(db);
+			}
+			// The site is born with an admin (the owner, above), so EmDash's
+			// first-run setup wizard must never run on it. Without this flag the
+			// wizard appears and then refuses ("admin user already exists").
+			await sql`INSERT INTO options (name, value) VALUES ('emdash:setup_complete', 'true')
+				ON CONFLICT(name) DO UPDATE SET value = 'true'`.execute(db);
+		});
+
+		await done("identity");
+		await writeStatus(org.slug, { status: "ready", startedAt, readyAt: new Date().toISOString(), timings });
+		log("site.ready", { site: org.slug, theme: plan.theme, cloned, ms: Date.now() - Date.parse(startedAt), timings });
+		// Pre-warm the new site's cold public routes so the FIRST real visitor (or a PageSpeed/agent
+		// crawler) hits a warm edge cache instead of the ~450ms cold render. The SEO plugin generates
+		// robots.txt / llms.txt / sitemap live on a cold isolate; that cold render exceeded Lighthouse's
+		// tight fetch budget on a brand-new site, flagging robots.txt/llms.txt as "failed to fetch"
+		// (SEO 92, Agentic 2/3). One request per route fills the host-keyed edge cache. Best-effort and
+		// non-blocking: the site is already "ready"; failures are ignored.
+		{
+			const warmOrigin = siteUrl(org.slug, sitesConfig() ?? ({} as SitesConfig));
+			if (warmOrigin) {
+				await Promise.allSettled(
+					["/", "/robots.txt", "/llms.txt", "/sitemap.xml"].map((p) =>
+						fetch(new URL(p, warmOrigin), { headers: { "user-agent": "hostmyemdash-prewarm" } }),
+					),
+				).catch(() => {});
+			}
+		}
+	} catch (error) {
+		console.error(`[multisite] provisioning "${org.slug}" failed:`, error);
+		log("site.failed", { site: org.slug, error: error instanceof Error ? error.message : String(error) });
+		await writeStatus(org.slug, {
+			status: "failed",
+			startedAt,
+			error: error instanceof Error ? error.message : String(error),
+		}).catch(() => {});
+	} finally {
+		await releaseSlot(org.slug).catch(() => {});
+	}
+}
+
+/** Theme id and seed for a site, from what was requested at creation (org metadata). */
+export function planFor(sites: SitesConfig, metadata: unknown): { theme: string; seed?: unknown } {
+	const theme = effectiveTheme(themeFromMetadata(metadata), sites.themes, sites.defaultTheme);
+	return { theme, seed: sites.themes?.[theme]?.seed };
+}
+
+/**
+ * Sites that need provisioning (again): `failed`, a `provisioning` row old
+ * enough to be a dead run, or no status row at all. A site with no status row
+ * but with tables predates status tracking; it is adopted as `ready` instead of
+ * being provisioned a second time on top of live content.
+ */
+export async function pendingReconcile(only?: string): Promise<string[]> {
+	const out: string[] = [];
+	// Suspended and deleted sites are left alone: provisioning would wake their runtime
+	// and re-create what a purge removed.
+	const inactive = await readAllStates();
+	for (const org of await readOrgs()) {
+		if (only && org.slug !== only) continue;
+		if (!org.ownerUserId || !isSiteId(org.slug) || inactive.has(org.slug)) continue;
+		const status = await readStatus(org.slug);
+		if (!needsReconcile(status, Date.now())) continue;
+		if (!status && (await siteHasTables(org.slug))) {
+			const now = new Date().toISOString();
+			await writeStatus(org.slug, { status: "ready", startedAt: now, readyAt: now });
+			continue;
+		}
+		out.push(org.slug);
+	}
+	return out;
+}
+
+/**
+ * Re-provision ONE stuck site (the first pending, or `only`). One per call on
+ * purpose: a run is ~20 s of D1 work and the background budget after a response
+ * (`waitUntil`) is ~30 s, so a loop would be killed half way and leave a site
+ * stuck in `provisioning`. Call again for the next one.
+ * ponytail: upgrade path is a Queue or Workflow that runs one site per message.
+ */
+export async function reconcile(sites: SitesConfig, only?: string): Promise<string[]> {
+	const [slug] = await pendingReconcile(only);
+	if (!slug) return [];
+	const org = (await readOrgs()).find((o) => o.slug === slug)!;
+	// A switched site keeps its current theme; the org metadata only records the first choice.
+	const current = await readSiteTheme(slug);
+	await createSiteForOrg({ slug, name: org.name, ownerUserId: org.ownerUserId! }, planFor(sites, current ? { theme: current } : org.metadata));
+	return [slug];
+}
+
+/**
+ * Switch a live site to another theme. Additive and non-destructive: the target
+ * theme's seed is applied with skip-on-conflict (core creates only what is
+ * missing, never overwrites settings, menus or content), then the site's theme
+ * option is flipped. Content of the old theme stays in the database, hidden.
+ */
+export async function switchTheme(
+	sites: SitesConfig,
+	slug: string,
+	theme: string,
+	opts: { includeContent: boolean },
+): Promise<void> {
+	const seed = sites.themes?.[theme]?.seed;
+	if (!seed) throw new Error(`unknown theme: ${theme}`);
+	const db = controlDb();
+	await runAsSite(slug, async () => {
+		// eslint-disable-next-line typescript/no-explicit-any -- core types its own Database/Seed
+		await applySeed(db as any, seed as any, { includeContent: opts.includeContent, skipMediaDownload: true, onConflict: "skip" });
+		await sql`INSERT INTO options (name, value) VALUES ('multisite:theme', ${JSON.stringify(theme)})
+			ON CONFLICT(name) DO UPDATE SET value = excluded.value`.execute(db);
+	});
+	forgetSiteTheme(slug);
+}

package/src/passwords.ts

@@ -0,0 +1,60 @@
+/**
+ * Keep an owner's password the same on the control plane and on their sites.
+ *
+ * Provisioning copies the owner's Better Auth credential account into each site. A later password change or
+ * reset on the control plane would leave those copies on the old password. After such a request (and on every
+ * cron tick as a safety net) this copies recently changed credential accounts to the sites their user owns.
+ *
+ * Only owners: an editor who signed up on a site has a separate account there and keeps its own password.
+ * ponytail: matches by "changed in the last N minutes", so a missed window (Worker down for longer than the cron
+ * window) is not caught. Upgrade path: a per-account version stamp compared on every handoff.
+ */
+import { sql } from "kysely";
+import { runAsSite } from "./dialect.ts";
+import { log } from "./log.ts";
+import { controlDb, readAllStates, readOrgs } from "./registry.ts";
+import { scopeState } from "./scope.ts";
+
+export const PASSWORD_PATHS: ReadonlySet<string> = new Set(["/api/auth/change-password", "/api/auth/reset-password", "/api/auth/set-password"]);
+
+interface AccountRow {
+	plugin_id: string;
+	collection: string;
+	id: string;
+	data: string;
+	created_at: string;
+	updated_at: string;
+	revision: string;
+}
+
+/** Copy credential accounts changed within `withinMs` to the sites their user owns. Returns how many site copies were updated. */
+export async function syncRecentPasswords(withinMs: number): Promise<number> {
+	const db = controlDb();
+	const cutoff = new Date(Date.now() - withinMs).toISOString();
+	const rows = await runAsSite(scopeState().primary, async () =>
+		(await sql<AccountRow>`SELECT * FROM _plugin_storage WHERE collection = 'accounts' AND updated_at >= ${cutoff}`.execute(db)).rows,
+	);
+	const changed = rows.flatMap((r) => {
+		try {
+			const d = JSON.parse(r.data) as { providerId?: string; userId?: string };
+			return d.providerId === "credential" && d.userId ? [{ row: r, userId: d.userId }] : [];
+		} catch {
+			return [];
+		}
+	});
+	if (!changed.length) return 0;
+	const inactive = await readAllStates();
+	const orgs = (await readOrgs()).filter((o) => o.ownerUserId && !inactive.has(o.slug) && o.slug !== scopeState().primary);
+	let n = 0;
+	for (const { row, userId } of changed) {
+		for (const org of orgs.filter((o) => o.ownerUserId === userId)) {
+			await runAsSite(org.slug, () =>
+				sql`INSERT INTO _plugin_storage (plugin_id, collection, id, data, created_at, updated_at, revision)
+					VALUES (${row.plugin_id}, ${row.collection}, ${row.id}, ${row.data}, ${row.created_at}, ${row.updated_at}, ${row.revision})
+					ON CONFLICT(plugin_id, collection, id) DO UPDATE SET data = excluded.data, updated_at = excluded.updated_at, revision = excluded.revision`.execute(db),
+			).then(() => n++, (error) => console.error(`[multisite] password sync to "${org.slug}" failed:`, error));
+		}
+	}
+	if (n) log("password.synced", { copies: n });
+	return n;
+}

package/src/platform-env.ts

@@ -0,0 +1,10 @@
+/**
+ * The Workers bindings (`env`), or undefined off Workers (Node/SQLite lab).
+ * Imported at run time, through a variable, so bundlers for other platforms do not
+ * try to resolve `cloudflare:workers` and fail the build.
+ */
+let cached: Promise<Record<string, unknown> | undefined> | undefined;
+export function platformEnv(): Promise<Record<string, unknown> | undefined> {
+	const specifier = "cloudflare:workers";
+	return (cached ??= import(/* @vite-ignore */ specifier).then((m) => m.env as Record<string, unknown>).catch(() => undefined));
+}

package/src/plugin-entry.ts

@@ -0,0 +1,145 @@
+/**
+ * Runtime of the multisite admin plugin: one Block Kit page, "Site", in each
+ * site's own EmDash admin.
+ *
+ * - **Appearance**: pick another theme for THIS site (additive, nothing is deleted;
+ *   see `switchTheme`). The site is the one the request is for, so the page works
+ *   unchanged on every tenant and on the control plane.
+ * - **Account**: links back to the app (account, my sites).
+ *
+ * The route is admin-only (`plugins:manage`), which on a tenant means its owner
+ * and any admins they appoint, and nobody else.
+ */
+import { definePlugin } from "emdash";
+import { purgeSiteCache } from "./edge-cache.ts";
+import { appearanceState } from "./console.ts";
+import { sitesConfig } from "./config.ts";
+import { PLUGIN_ID, PLUGIN_PAGE_PATH, PLUGIN_VERSION } from "./plugin.ts";
+import { signUpOpen } from "./orgs.ts";
+import { activeSite, scopeState } from "./scope.ts";
+import { listSites } from "./fleet.ts";
+import { runFleetAction } from "./fleet-actions.ts";
+import { PURGE_FORM_ACTION, fleetBlocks, parseFleetAction } from "./fleet-blocks.ts";
+import { isSiteId } from "./rewrite.ts";
+
+
+interface Interaction {
+	type?: string;
+	action_id?: string;
+	value?: unknown;
+	values?: Record<string, unknown>;
+}
+interface Page {
+	blocks: unknown[];
+	toast?: { message: string; type: "info" | "success" | "error" };
+}
+
+/** The control plane's Site page is the fleet: every site, with staff actions. */
+async function fleetPage(toast?: Page["toast"]): Promise<Page> {
+	return { blocks: fleetBlocks(await listSites(), scopeState().primary), ...(toast ? { toast } : {}) };
+}
+async function buildPage(toast?: Page["toast"]): Promise<Page> {
+	const sites = sitesConfig();
+	const slug = activeSite();
+	if (slug === scopeState().primary) return fleetPage(toast);
+	const state = sites ? await appearanceState(slug, sites) : null;
+	const blocks: unknown[] = [{ type: "header", text: "Site" }];
+
+	if (!sites || !state) {
+		blocks.push({
+			type: "context",
+			text: `This site is not managed by the multi-site platform (site "${slug}", ${sites ? (sites.themes ? "no matching organization" : "no themes configured") : "no multisite config"}).`,
+		});
+		return { blocks, ...(toast ? { toast } : {}) };
+	}
+
+	blocks.push({ type: "context", text: `${state.name} (${state.slug})` });
+	blocks.push({
+		type: "context",
+		text: `Public sign-up is ${(await signUpOpen(slug)) ? "ON: visitors can create an account" : "OFF: only people you add can sign in"}. Change it in Settings, Better Auth, "Allow new sign-ups".`,
+	});
+
+	if (state.themes.length > 1 && sites.appUrl) {
+		// One home for theme switching: the Sites tab of the account page (Better Auth UI).
+		const current = state.themes.find((t) => t.current);
+		blocks.push({ type: "divider" }, { type: "header", text: "Appearance" });
+		blocks.push({ type: "context", text: `Theme: ${current?.name ?? state.current}. Switching keeps all of your content; anything the new theme does not show is hidden and comes back if you switch back.` });
+		blocks.push({
+			type: "actions",
+			elements: [
+				{
+					type: "link" as const,
+					label: "Change theme",
+					target: { kind: "external" as const, url: `${sites.appUrl}/account/sites?appearance=${state.slug}` },
+					appearance: "secondary" as const,
+				},
+			],
+		});
+	}
+	if (sites.appUrl) {
+		const link = (path: string, label: string) => ({
+			type: "link" as const,
+			label,
+			target: { kind: "external" as const, url: `${sites.appUrl}${path}` },
+			appearance: "secondary" as const,
+		});
+		blocks.push({ type: "divider" }, { type: "header", text: "Account" });
+		blocks.push({ type: "actions", elements: [link("/account/sites", "My sites"), link("/account", "Account")] });
+	}
+	return { blocks, ...(toast ? { toast } : {}) };
+}
+
+export function createPlugin() {
+	return definePlugin({
+		id: PLUGIN_ID,
+		version: PLUGIN_VERSION,
+		capabilities: ["read:content"],
+		// Anything that changes a public page drops this site's cached pages (purge by `site:<slug>`, see edge-cache.ts).
+		// Draft autosaves of a published entry only stage a draft revision (`draftRevisionId` set), so they must NOT purge: the
+		// purge budget is tiny and shared by every tenant. Edits to menus, widgets, settings, taxonomies and so on have no hook;
+		// the middleware purges those after the successful admin write (see watchEdits in middleware.ts).
+		hooks: {
+			"content:afterPublish": { handler: async () => void (await purgeSiteCache(activeSite())) },
+			"content:afterUnpublish": { handler: async () => void (await purgeSiteCache(activeSite())) },
+			"content:afterDelete": { handler: async () => void (await purgeSiteCache(activeSite())) },
+			"content:afterSave": {
+				handler: async (event: { content?: Record<string, unknown> }) => {
+					// Collections without revisions write the live row directly.
+					if (event.content?.status === "published" && !event.content.draftRevisionId) await purgeSiteCache(activeSite());
+				},
+			},
+			"byline:afterSave": { handler: async () => void (await purgeSiteCache(activeSite())) },
+			"byline:afterDelete": { handler: async () => void (await purgeSiteCache(activeSite())) },
+		},
+		admin: { pages: [{ path: PLUGIN_PAGE_PATH, label: "Site", icon: "globe" }] },
+		routes: {
+			admin: {
+				// Admin-only: changing the theme changes the whole public site.
+				permission: "plugins:manage",
+				handler: async (routeCtx: { input?: unknown }): Promise<Page> => {
+					const interaction = (routeCtx.input ?? { type: "page_load" }) as Interaction;
+					const sitesConfigured = sitesConfig();
+					if (sitesConfigured && activeSite() === scopeState().primary) {
+						// Control plane: row menu actions and the purge form. (Only reachable with `plugins:manage`, i.e. staff.)
+						const row = interaction.type === "block_action" ? parseFleetAction(interaction.action_id, interaction.value) : null;
+						if (row) {
+							const r = await runFleetAction(sitesConfigured, row.slug, row.action);
+							return fleetPage({ message: r.message, type: r.ok ? "success" : "error" });
+						}
+						if (interaction.type === "form_submit" && interaction.action_id === PURGE_FORM_ACTION) {
+							const slug = interaction.values?.slug;
+							if (typeof slug !== "string" || !isSiteId(slug) || interaction.values?.confirm !== true) {
+								return fleetPage({ message: "Pick a site and tick the box to purge.", type: "error" });
+							}
+							const r = await runFleetAction(sitesConfigured, slug, "purge");
+							return fleetPage({ message: r.message, type: r.ok ? "success" : "error" });
+						}
+						return fleetPage();
+					}
+					return buildPage();
+				},
+			},
+		},
+	});
+}
+export default createPlugin;

package/src/plugin.ts

@@ -0,0 +1,26 @@
+import type { PluginDescriptor } from "emdash";
+
+export const PLUGIN_ID = "multisite";
+export const PLUGIN_VERSION = "0.1.0";
+/** Sidebar page path inside the site's admin: `/_emdash/admin/plugins/multisite/site`. */
+export const PLUGIN_PAGE_PATH = "/site";
+
+/**
+ * Native EmDash plugin that adds a **Site** page to every site's own admin: change
+ * the theme (Appearance) and jump back to the account area. Register it next to
+ * the database wrapper:
+ *
+ * ```ts
+ * emdash({ database: withSites(...), plugins: [multisitePlugin()] })
+ * ```
+ *
+ * Runtime lives in `plugin-entry.ts` (loaded only on the server).
+ */
+export function multisitePlugin(): PluginDescriptor {
+	return {
+		id: PLUGIN_ID,
+		version: PLUGIN_VERSION,
+		format: "native",
+		entrypoint: "emdash-multisite/plugin-entry",
+	};
+}

package/src/provision.ts

@@ -0,0 +1,17 @@
+import type { Kysely } from "kysely";
+import { runMigrations } from "emdash/db";
+import { runAsSite } from "./dialect.ts";
+import { isSiteId } from "./rewrite.ts";
+
+/**
+ * Create (or upgrade) one site's tables by running core's migrations as that
+ * site. `db` must be a Kysely built on the wrapped dialect. Idempotent.
+ */
+export async function provisionWith(db: Kysely<never>, site: string): Promise<{ applied: string[] }> {
+	if (!isSiteId(site)) throw new Error(`[multisite] invalid site id: ${site}`);
+	// eslint-disable-next-line typescript/no-explicit-any -- core types its own Database
+	return runAsSite(site, () => runMigrations(db as any));
+}
+
+/** Public name used by scripts. */
+export const provisionSite = provisionWith;