@coywolf/emdash 0.0.0-stage → 0.35.13

package/src/core/module.ts

@@ -0,0 +1,104 @@
+/**
+ * The shape every Coywolf Pack module implements. src/index.ts composes the
+ * modules into one EmDash plugin: routes are merged, hooks run in module
+ * order (skipping modules whose feature is off), and admin pages, widgets,
+ * Portable Text blocks and storage collections are concatenated.
+ */
+import type { MiddlewareHandler } from "astro";
+import type { PluginContext, PluginHooks } from "emdash";
+
+/** A switch on the Features page. */
+export interface FeatureDef {
+	/** Stable key, e.g. "codeBlocks" or "schema.breadcrumbs". Stored in the "features" setting. */
+	id: string;
+	label: string;
+	description: string;
+	/** Default when the site hasn't chosen. Keep new features off so installing changes nothing. */
+	default?: boolean;
+	/**
+	 * Legacy ids this feature took over (e.g. a sub-feature that became its own
+	 * module). When the stored map has no value for `id`, the first legacy id
+	 * found there decides, so existing sites keep their choice.
+	 */
+	replaces?: string[];
+}
+
+export interface AdminPageDef {
+	path: string;
+	label: string;
+	icon?: string;
+	/** Admin sidebar folder (EmDash 1.2.0+). The pack puts every page in the "Coywolf Pack" folder (see sidebar() in src/index.ts). */
+	group?: string;
+}
+
+export interface WidgetDef {
+	id: string;
+	title: string;
+	size: "full" | "half" | "third";
+}
+
+/** A scheduled job. `schedule` is cron syntax or @hourly/@daily/@weekly. */
+export interface TaskDef {
+	name: string;
+	schedule: string;
+	/** Feature that must be on for the task to run (defaults to the module's main feature). */
+	feature?: string;
+	handler: (ctx: PluginContext) => Promise<void>;
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: hook handler signatures vary per hook name.
+type AnyHandler = (event: any, ctx: PluginContext) => Promise<unknown> | unknown;
+
+export interface PackModule {
+	/** Module id; also the main feature id unless `features` says otherwise. */
+	id: string;
+	label: string;
+	/** Feature switches. The first one is the module's main switch; the rest are sub-features. */
+	features: FeatureDef[];
+	/** Plugin routes, served at /_emdash/api/plugins/coywolf-pack/<name>. Prefix names with the module id. */
+	// biome-ignore lint/suspicious/noExplicitAny: route definitions are opaque here.
+	routes?: Record<string, any>;
+	/**
+	 * Hook handlers. Return values follow EmDash: content:beforeSave may return
+	 * modified content (passed to the next module); page:metadata and
+	 * page:fragments return contributions (concatenated).
+	 * Each handler runs only when `hookFeature` (or the main feature) is on.
+	 */
+	hooks?: Partial<Record<keyof PluginHooks, AnyHandler>>;
+	/** Feature gating a hook, when it isn't the main feature. Keyed by hook name. */
+	hookFeature?: Partial<Record<keyof PluginHooks, string>>;
+	tasks?: TaskDef[];
+	adminPages?: AdminPageDef[];
+	widgets?: WidgetDef[];
+	/**
+	 * Secret settings (API keys and tokens) only, prefixed with the module id;
+	 * other fields are dropped. Prefer adding secrets to src/core/secrets.ts.
+	 * Non-secret settings aren't declared: edit them on the module's own admin
+	 * page (ctx.settings.get/set) and give every read its default in code.
+	 */
+	// biome-ignore lint/suspicious/noExplicitAny: SettingField shape is EmDash's.
+	settingsSchema?: Record<string, any>;
+	/** Portable Text block types this module adds to the editor (render components live in src/astro). */
+	// biome-ignore lint/suspicious/noExplicitAny: PortableTextBlockConfig shape is EmDash's.
+	portableTextBlocks?: any[];
+	/** Plugin storage collections ({ name: { indexes, uniqueIndexes } }). */
+	// biome-ignore lint/suspicious/noExplicitAny: storage config shape is EmDash's.
+	storage?: Record<string, any>;
+	/** Capabilities this module needs (e.g. "network:request", "email:send"). */
+	capabilities?: string[];
+	/** Hosts for network:request, if any. */
+	allowedHosts?: string[];
+}
+
+/**
+ * Site-level middleware a module contributes (see src/middleware.ts). Runs
+ * only when `feature` is on. Return a Response to answer the request, or
+ * undefined to pass it on.
+ */
+export interface PackMiddleware {
+	module: string;
+	feature: string;
+	/** Sets its own edge caching (context.cache) on the responses it returns; others' are never edge-cached. */
+	ownsCache?: boolean;
+	handle: (context: Parameters<MiddlewareHandler>[0], env: Record<string, unknown>, waitUntil: (p: Promise<unknown>) => void) => Promise<Response | undefined> | Response | undefined;
+}

package/src/core/read-failures.ts

@@ -0,0 +1,57 @@
+/**
+ * Reads that failed while pages were being answered. When the pack can't read
+ * what it needs (D1 unreachable for a moment, a query error), it fails closed:
+ * the feature switches read as their defaults (new features are off),
+ * settings as unset, redirect and robots.txt rules as absent, and a module
+ * whose page metadata failed adds none. That's the right answer for the one
+ * request, but the page it renders isn't the site's real page (no schema,
+ * reviews or videos, wrong links), so it mustn't go into the edge cache, where
+ * it would stay for the Page cache lifetime (days).
+ *
+ * Every such fallback calls noteReadFailure(). The pack middleware reads
+ * readFailures() before a request and again once the response is rendered,
+ * and keeps the response out of the edge cache when the count moved (see
+ * settlePage in src/pageCache/lib.ts).
+ *
+ * The count is per isolate, not per request: one read is often shared by
+ * several requests (concurrent requests wait for the same read of the
+ * switches), and the code that notices a failure has no request at hand. A
+ * failure while another request of the same isolate rendered keeps that one
+ * out of the cache too, which only costs a render. No imports, so tests can
+ * load it.
+ */
+
+let failures = 0;
+let last: string | undefined;
+
+/**
+ * A read failed and a fallback (off, unset, absent) was used instead. `what`
+ * names it for the log line of the page left out of the cache: a module that
+ * fails on every render (a bug, not a blip) keeps every page out of the cache
+ * until it's fixed, and the log says which.
+ */
+export function noteReadFailure(what: string): void {
+	failures++;
+	last = what;
+}
+
+/** How many reads have failed in this isolate; compare two counts to tell whether one failed in between. */
+export function readFailures(): number {
+	return failures;
+}
+
+/** What failed most recently in this isolate (for the log). */
+export function lastReadFailure(): string | undefined {
+	return last;
+}
+
+/**
+ * A plugin route's result that failed on the server, as EmDash's HTTP wiring
+ * would answer it (plugins/http-route-dispatch.ts: a missing status is 404 for
+ * NOT_FOUND, else 400): a 5xx means a read failed. Not found (a feature that's
+ * off, the plugin not enabled), bad input and the like don't count.
+ */
+export function routeFailed(result: { success?: boolean; status?: number; error?: { code?: string } } | null | undefined): boolean {
+	if (!result || result.success) return false;
+	return (result.status ?? (result.error?.code === "NOT_FOUND" ? 404 : 400)) >= 500;
+}

package/src/core/request-memo.ts

@@ -0,0 +1,71 @@
+/**
+ * Request-scoped memo: share a read between everything that renders one page
+ * (page:metadata hooks, block components, public plugin routes they call), so
+ * the same data is read from D1 once per request instead of once per caller.
+ *
+ * Keyed on EmDash's request context (an AsyncLocalStorage store that EmDash's
+ * middleware opens for every request; found through its global symbol, so no
+ * import of emdash is needed here). Outside a request (tests, cron, scripts)
+ * nothing is shared: each call runs its read.
+ *
+ * Promises are cached, so callers that start at the same time share one
+ * in-flight read; a read that fails is forgotten, so the next caller retries.
+ */
+
+const ALS_KEY = Symbol.for("emdash:request-context");
+const memos = new WeakMap<object, Map<string, Promise<unknown>>>();
+
+/** The current request's EmDash context object (undefined outside a request). */
+export function requestStore(): object | undefined {
+	const als = (globalThis as Record<symbol, { getStore?(): unknown } | undefined>)[ALS_KEY];
+	const store = als?.getStore?.();
+	return store && typeof store === "object" ? store : undefined;
+}
+
+function memoFor(create: boolean): Map<string, Promise<unknown>> | undefined {
+	const store = requestStore();
+	if (!store) return undefined;
+	let memo = memos.get(store);
+	if (!memo && create) {
+		memo = new Map();
+		memos.set(store, memo);
+	}
+	return memo;
+}
+
+/** `read()` once per request for `key`; later callers in the same request get the same promise. */
+export function requestMemo<T>(key: string, read: () => Promise<T>): Promise<T> {
+	const memo = memoFor(true);
+	if (!memo) return read();
+	const hit = memo.get(key);
+	if (hit) return hit as Promise<T>;
+	const promise = read().catch((error) => {
+		if (memo.get(key) === promise) memo.delete(key);
+		throw error;
+	});
+	memo.set(key, promise);
+	return promise;
+}
+
+/** The value already read (or being read) for `key` in this request, if any. */
+export function peekRequestMemo<T>(key: string): Promise<T> | undefined {
+	return memoFor(false)?.get(key) as Promise<T> | undefined;
+}
+
+/** Share a read that's already under way (e.g. one batched read for many keys) with later callers in this request. */
+export function seedRequestMemo<T>(key: string, value: Promise<T>): void {
+	const memo = memoFor(true);
+	if (!memo || memo.has(key)) return;
+	const promise = value.catch((error) => {
+		if (memo.get(key) === promise) memo.delete(key);
+		throw error;
+	});
+	// The caller handles `value`'s failure; a seeded copy nobody reads must not be an unhandled rejection.
+	promise.catch(() => {});
+	memo.set(key, promise);
+}
+
+/** Forget `key` in this request (after a write that changes it). */
+export function forgetRequestMemo(key: string): void {
+	memoFor(false)?.delete(key);
+}

package/src/core/secrets.ts

@@ -0,0 +1,83 @@
+/**
+ * The plugin's EmDash `admin.settingsSchema`: API keys and tokens only.
+ *
+ * EmDash renders this schema as the plugin's generic Settings page and uses
+ * the same schema to decide which settings are encrypted: a key declared
+ * `type: "secret"` is encrypted on write and decrypted on read, and reading
+ * an encrypted value whose key isn't declared secret throws. So every secret
+ * stays declared here permanently, whatever the feature switches or module
+ * options say, and the keys never change (stored values must keep working).
+ *
+ * Every other setting is plain JSON, edited on its module's own admin page
+ * (ctx.settings.get/set work for keys that aren't in the schema).
+ *
+ * Kept free of imports so tests can load it directly.
+ */
+
+export interface SecretSettingField {
+	type: "secret";
+	label: string;
+	description?: string;
+}
+
+export const SECRET_SETTINGS = {
+	aiApiKey: {
+		type: "secret",
+		label: "AI Enrichment — API key",
+		description:
+			"For Anthropic, OpenAI or Gemini (Workers AI needs no key). To get one: (1) sign in to your provider's developer console: platform.claude.com (Anthropic), platform.openai.com (OpenAI) or aistudio.google.com (Gemini); (2) add billing; (3) create an API key and copy it; (4) paste it here and save. Step-by-step guides for each provider, and the provider and model settings, are on the AI Enrichment page.",
+	},
+	filesR2SecretAccessKey: {
+		type: "secret",
+		label: "File Downloads — R2 secret access key",
+		description:
+			"For large uploads. To get one: (1) Cloudflare dashboard → R2 → Manage API tokens → Create Account API token; (2) choose Object Read & Write on the bucket bound as MEDIA; (3) create it and copy the Secret Access Key (shown once); (4) paste it here and save. The account ID, access key ID and bucket name go on the Files page → Settings, which has the full step-by-step guide.",
+	},
+	videosApiToken: {
+		type: "secret",
+		label: "Videos — Cloudflare Stream API token",
+		description:
+			"To get one: (1) Cloudflare dashboard → My Profile → API Tokens → Create Token → Create Custom Token; (2) add the permission Account → Stream → Edit and include your account; (3) create it and copy the token (shown once); (4) paste it here and save. Or set the CF_STREAM_TOKEN Worker secret. The account ID and the full step-by-step guide are on the Videos page → Settings.",
+	},
+	videosWebhookSecret: {
+		type: "secret",
+		label: "Videos — Stream webhook signing secret",
+		description: "Filled in by Subscribe Stream webhook on the Videos page. Leave as is.",
+	},
+	imagesApiToken: {
+		type: "secret",
+		label: "Clean image URLs — Cloudflare API token",
+		description:
+			"Optional. Only for Set up media host on the Clean Image URLs page, which does the Cloudflare setup for you. To get one: (1) Cloudflare dashboard → My Profile → API Tokens → Create Token → Create Custom Token; (2) add the permissions Zone → Zone → Read, Zone → Zone Settings → Edit, Zone → Transform Rules → Edit, Zone → DNS → Edit, Account → Workers R2 Storage → Edit and Account → Account Rulesets → Read; (3) include your account and the site's zone; (4) create it, copy the token (shown once), paste it here and save. Or set the IMAGES_API_TOKEN Worker secret.",
+	},
+	usageApiToken: {
+		type: "secret",
+		label: "Cloudflare usage — read-only API token",
+		description:
+			"Optional. Shows this site's D1 and Workers usage, the account's against its plan, and the estimated bill on the Performance page and the dashboard. To get one: (1) Cloudflare dashboard → Manage Account → Account API Tokens → Create Token → Create Custom Token; (2) add the permissions Account → Account Analytics → Read, Workers → Metadata Read-Only (All Workers; finds this site's Worker and database and reads Workers Logs for the cache-warming estimate) and Account → Account Settings → Read (to detect the plan); (3) create it, copy the token (shown once), paste it here and save. Or set the USAGE_API_TOKEN Worker secret (one token works for every site in the account).",
+	},
+	robotsRadarToken: {
+		type: "secret",
+		label: "Robots.txt Rules — Cloudflare Radar API token",
+		description:
+			"Optional. Keeps the crawler list current from Cloudflare Radar each week. To get one: (1) Cloudflare dashboard → My Profile → API Tokens → Create Token → Create Custom Token; (2) add the permission Account → Radar → Read and include your account; (3) create it and copy the token (shown once); (4) paste it here and save. Or set the RADAR_API_TOKEN Worker secret. The full step-by-step guide is on the Robots.txt page → Bots.",
+	},
+} as const satisfies Record<string, SecretSettingField>;
+
+export type SecretSettingKey = keyof typeof SECRET_SETTINGS;
+
+/**
+ * The schema EmDash sees: the pack's secrets plus any secret fields a module
+ * declares. Non-secret fields are dropped, so they never appear on the
+ * generic Settings page.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: SettingField shape is EmDash's.
+export function secretSettingsSchema(moduleSchemas: Array<Record<string, any> | undefined> = []): Record<string, SecretSettingField> {
+	const out: Record<string, SecretSettingField> = { ...SECRET_SETTINGS };
+	for (const schema of moduleSchemas) {
+		for (const [key, field] of Object.entries(schema ?? {})) {
+			if (field && field.type === "secret" && !(key in out)) out[key] = field as SecretSettingField;
+		}
+	}
+	return out;
+}

package/src/core/settings-enhance.ts

@@ -0,0 +1,74 @@
+/**
+ * Step-by-step guides on EmDash's generic plugin Settings page
+ * (/_emdash/admin/plugins-manager/coywolf-pack/settings). EmDash renders that
+ * page from the settings schema and shows each field's description as plain
+ * text, so the pack middleware adds this small script to admin pages. On that
+ * page it swaps each secret's plain-text description for a short line plus the
+ * guides in closed <details> (the same ones the module pages show).
+ *
+ * Progressive enhancement: it looks the fields up by their label, and if
+ * EmDash's markup ever changes it does nothing, leaving the plain-text steps
+ * from secrets.ts in place.
+ */
+import { GUIDES, SETTINGS_PAGE_GUIDES, guideHtml } from "./guide-content.js";
+import { SECRET_SETTINGS } from "./secrets.js";
+
+const PAGE = /\/_emdash\/admin\/plugins-manager\/coywolf-pack\/settings\/?$/;
+
+/** Label text → the HTML that replaces that field's description. */
+export function settingsGuideHtml(): Record<string, string> {
+	const out: Record<string, string> = {};
+	for (const [key, entry] of Object.entries(SETTINGS_PAGE_GUIDES)) {
+		const field = (SECRET_SETTINGS as Record<string, { label: string }>)[key];
+		if (!field) continue;
+		const guides = entry.guides.map((id) => guideHtml(GUIDES[id])).join("");
+		out[field.label] = `<p class="text-sm leading-snug text-kumo-subtle" data-cw-intro>${entry.intro}</p><div class="space-y-2">${guides}</div>`;
+	}
+	return out;
+}
+
+/** Built once per isolate: its content only changes with a deploy. */
+let enhanceScript: string | null = null;
+
+/**
+ * The inline script. JSON is escaped so it can't close the <script> element.
+ * It goes on every admin page, not just the Settings page: the admin is a
+ * single-page app, so a visit that starts elsewhere reaches Settings without
+ * a page load (the script checks the path itself).
+ */
+export function settingsEnhanceScript(): string {
+	enhanceScript ??= buildEnhanceScript();
+	return enhanceScript;
+}
+
+function buildEnhanceScript(): string {
+	const data = JSON.stringify(settingsGuideHtml()).replace(/</g, "\\u003c").replace(/[\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16)}`);
+	return `(function(){var D=${data};var P=${PAGE.toString()};var q=0;
+function run(){q=0;if(!P.test(location.pathname))return;var f=document.getElementById("plugin-settings-form");if(!f)return;
+f.querySelectorAll("input[aria-labelledby][aria-describedby]").forEach(function(i){if(i.getAttribute("data-cw-guide"))return;
+var l=document.getElementById(i.getAttribute("aria-labelledby"));var h=l&&D[l.textContent.trim()];if(!h)return;
+var d=document.getElementById(i.getAttribute("aria-describedby"));if(!d||!d.parentNode)return;
+var b=document.createElement("div");b.className="col-span-full space-y-2";b.setAttribute("data-cw-guides","");b.innerHTML=h;
+var p=b.querySelector("[data-cw-intro]");p.id=d.id+"-cw";d.hidden=true;d.parentNode.insertBefore(b,d.nextSibling);
+i.setAttribute("aria-describedby",p.id);i.setAttribute("data-cw-guide","1");});}
+function later(){if(!q)q=requestAnimationFrame(run);}
+new MutationObserver(later).observe(document.documentElement,{childList:true,subtree:true});later();})();`;
+}
+
+/** Add the script to an admin HTML page. Returns the response unchanged when it isn't HTML. */
+export async function injectAdminEnhancements(response: Response): Promise<Response> {
+	if (!(response.headers.get("content-type") ?? "").includes("text/html") || response.status !== 200) return response;
+	const html = await response.text();
+	const at = html.lastIndexOf("</body>");
+	const script = `<script data-coywolf-pack>${settingsEnhanceScript()}</script>`;
+	const body = at === -1 ? html + script : html.slice(0, at) + script + html.slice(at);
+	const headers = new Headers(response.headers);
+	headers.delete("content-length");
+	const out = new Response(body, { status: response.status, statusText: response.statusText, headers });
+	// Astro keeps cookies set during the request on the response under this symbol; a new
+	// Response drops it, which would lose session cookies (EmDash's middleware does the same).
+	const cookies = Symbol.for("astro.cookies");
+	const value = (response as unknown as Record<symbol, unknown>)[cookies];
+	if (value !== undefined) (out as unknown as Record<symbol, unknown>)[cookies] = value;
+	return out;
+}

package/src/core/site.ts

@@ -0,0 +1,36 @@
+/**
+ * The site's name as editors set it (Settings → Site title). EmDash's plugin
+ * context reports the title from initial setup (`emdash:site_title`), which
+ * Settings doesn't change, so prefer the Settings value.
+ */
+import type { PluginContext } from "emdash";
+
+import { noteReadFailure } from "./read-failures.js";
+import { requestStore } from "./request-memo.js";
+
+export async function siteName(ctx: Pick<PluginContext, "site">): Promise<string> {
+	try {
+		const { getSiteSettings } = await import("emdash");
+		const settings = (await getSiteSettings()) as { title?: unknown };
+		if (typeof settings.title === "string" && settings.title.trim()) return settings.title.trim();
+	} catch {
+		// Outside a request context: fall back to the plugin context. Inside one it's a failed read.
+		if (requestStore()) noteReadFailure("site settings (site name)");
+	}
+	return ctx.site?.name ?? "";
+}
+
+/**
+ * Whether the site is in EmDash's staging mode (Settings → General → Site Status, EmDash 1.5+):
+ * hidden from search engines until it goes live. Sites without the setting (all sites before
+ * that release, and sites that went live) are live. A failed read counts as live.
+ */
+export async function siteInStaging(): Promise<boolean> {
+	try {
+		const { getSiteSetting } = await import("emdash");
+		// biome-ignore lint/suspicious/noExplicitAny: "staging" isn't in older EmDash versions' setting keys.
+		return (await (getSiteSetting as (key: any) => Promise<unknown>)("staging")) === true;
+	} catch {
+		return false;
+	}
+}

package/src/core/storage.ts

@@ -0,0 +1,27 @@
+/**
+ * Batched plugin-storage reads and deletes. EmDash's getMany and deleteMany
+ * put every id in one `IN (…)` list next to the plugin id and collection
+ * name, and D1 refuses statements with more than 100 bound values, so a
+ * large list fails with "too many SQL variables". These keep each statement
+ * well under the limit.
+ */
+import type { StorageCollection } from "emdash";
+
+/** Ids per statement: 90 + plugin id + collection stays under D1's 100. */
+export const STORAGE_IN_LIMIT = 90;
+
+export async function getManyBatched<T>(collection: StorageCollection<T>, ids: readonly string[]): Promise<Map<string, T>> {
+	const out = new Map<string, T>();
+	const unique = [...new Set(ids)];
+	for (let i = 0; i < unique.length; i += STORAGE_IN_LIMIT) {
+		for (const [id, data] of await collection.getMany(unique.slice(i, i + STORAGE_IN_LIMIT))) out.set(id, data);
+	}
+	return out;
+}
+
+export async function deleteManyBatched<T>(collection: StorageCollection<T>, ids: readonly string[]): Promise<number> {
+	let deleted = 0;
+	const unique = [...new Set(ids)];
+	for (let i = 0; i < unique.length; i += STORAGE_IN_LIMIT) deleted += await collection.deleteMany(unique.slice(i, i + STORAGE_IN_LIMIT));
+	return deleted;
+}