emdash 0.7.0 → 0.9.0

package/src/plugins/types.ts

@@ -20,20 +20,151 @@ import type { FieldType } from "../schema/types.js";
 // =============================================================================
 
 /**
- * Plugin capabilities determine what APIs are available in context
+ * Plugin capabilities determine what APIs are available in context.
+ *
+ * Capabilities follow the formula `<resource>[.<sub-resource>]:<verb>[:<qualifier>]`
+ * — resource first, verb second, matching RBAC. The `unrestricted` qualifier
+ * (used by `network:request:unrestricted`) is intentionally verbose so that
+ * granting it stands out in manifest review.
+ *
+ * Hook-registration capabilities (`hooks.<family>:register`) are a distinct
+ * audit category from data-access capabilities — they gate which hooks a
+ * plugin is allowed to register, not which context APIs it gets.
+ *
+ * @see CAPABILITY_RENAMES for the legacy → current mapping, and
+ *      `normalizeCapability()` for the runtime alias layer.
  */
 export type PluginCapability =
-	| "network:fetch" // ctx.http is available (host-restricted via allowedHosts)
-	| "network:fetch:any" // ctx.http is available (unrestricted outbound — use for user-configured URLs)
-	| "read:content" // ctx.content.get/list available
-	| "write:content" // ctx.content.create/update/delete available
-	| "read:media" // ctx.media.get/list available
-	| "write:media" // ctx.media.getUploadUrl/delete available
-	| "read:users" // ctx.users is available
+	// ── Network ─────────────────────────────────────────────────
+	| "network:request" // ctx.http is available (host-restricted via allowedHosts)
+	| "network:request:unrestricted" // ctx.http is available (unrestricted outbound — use for user-configured URLs)
+	// ── Content ─────────────────────────────────────────────────
+	| "content:read" // ctx.content.get/list available
+	| "content:write" // ctx.content.create/update/delete available
+	// ── Media ───────────────────────────────────────────────────
+	| "media:read" // ctx.media.get/list available
+	| "media:write" // ctx.media.getUploadUrl/delete available
+	// ── Users ───────────────────────────────────────────────────
+	| "users:read" // ctx.users is available
+	// ── Email ───────────────────────────────────────────────────
 	| "email:send" // ctx.email is available (when a provider is configured)
-	| "email:provide" // can register email:deliver exclusive hook (transport provider)
-	| "email:intercept" // can register email:beforeSend / email:afterSend hooks
-	| "page:inject"; // can register page:fragments hook (inject scripts/styles into pages)
+	// ── Hook registration ───────────────────────────────────────
+	| "hooks.email-transport:register" // can register email:deliver exclusive hook (transport provider)
+	| "hooks.email-events:register" // can register email:beforeSend / email:afterSend hooks
+	| "hooks.page-fragments:register" // can register page:fragments hook (inject scripts/styles into pages)
+	// ── Deprecated (legacy aliases) ─────────────────────────────
+	// Kept in the union for one minor with @deprecated tags so existing
+	// plugins typecheck during migration. Normalized to current names at
+	// definition time via normalizeCapability(). Will be removed in the
+	// following minor.
+	/** @deprecated Use `network:request` instead. */
+	| "network:fetch"
+	/** @deprecated Use `network:request:unrestricted` instead. */
+	| "network:fetch:any"
+	/** @deprecated Use `content:read` instead. */
+	| "read:content"
+	/** @deprecated Use `content:write` instead. */
+	| "write:content"
+	/** @deprecated Use `media:read` instead. */
+	| "read:media"
+	/** @deprecated Use `media:write` instead. */
+	| "write:media"
+	/** @deprecated Use `users:read` instead. */
+	| "read:users"
+	/** @deprecated Use `hooks.email-transport:register` instead. */
+	| "email:provide"
+	/** @deprecated Use `hooks.email-events:register` instead. */
+	| "email:intercept"
+	/** @deprecated Use `hooks.page-fragments:register` instead. */
+	| "page:inject";
+
+/**
+ * Deprecated capability names that map to current names.
+ *
+ * These are accepted at every external boundary (manifest parse, definePlugin,
+ * adaptSandboxEntry) and silently normalized to the new names before reaching
+ * the runtime. The runtime never sees deprecated names.
+ *
+ * Authors are warned at `bundle` / `validate`, and hard-failed at `publish`.
+ */
+export type DeprecatedPluginCapability =
+	| "network:fetch"
+	| "network:fetch:any"
+	| "read:content"
+	| "write:content"
+	| "read:media"
+	| "write:media"
+	| "read:users"
+	| "email:provide"
+	| "email:intercept"
+	| "page:inject";
+
+/**
+ * Current (non-deprecated) capability names.
+ */
+export type CurrentPluginCapability = Exclude<PluginCapability, DeprecatedPluginCapability>;
+
+/**
+ * Mapping from deprecated capability names to their current replacements.
+ *
+ * Used by `normalizeCapability()` and the marketplace `diffCapabilities`
+ * helper to compare manifests across the rename without flagging spurious
+ * "capability changed" prompts on upgrade.
+ */
+export const CAPABILITY_RENAMES: Readonly<
+	Record<DeprecatedPluginCapability, CurrentPluginCapability>
+> = Object.freeze({
+	"network:fetch": "network:request",
+	"network:fetch:any": "network:request:unrestricted",
+	"read:content": "content:read",
+	"write:content": "content:write",
+	"read:media": "media:read",
+	"write:media": "media:write",
+	"read:users": "users:read",
+	"email:provide": "hooks.email-transport:register",
+	"email:intercept": "hooks.email-events:register",
+	"page:inject": "hooks.page-fragments:register",
+});
+
+/**
+ * Type guard: is this capability one of the deprecated legacy names?
+ *
+ * Uses an own-property check so that prototype keys like "toString" or
+ * "constructor" don't accidentally pass.
+ */
+export function isDeprecatedCapability(cap: string): cap is DeprecatedPluginCapability {
+	return Object.hasOwn(CAPABILITY_RENAMES, cap);
+}
+
+/**
+ * Normalize a capability string — deprecated names map to current names,
+ * current names pass through unchanged. Unknown strings are returned as-is
+ * so that downstream validators can produce a precise error.
+ */
+export function normalizeCapability(cap: string): string {
+	if (isDeprecatedCapability(cap)) {
+		return CAPABILITY_RENAMES[cap];
+	}
+	return cap;
+}
+
+/**
+ * Normalize an array of capabilities. Deduplicates by normalized name so
+ * that a plugin declaring both `read:content` and `content:read` ends up
+ * with a single `content:read` entry.
+ */
+export function normalizeCapabilities(caps: readonly string[]): string[] {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const cap of caps) {
+		const normalized = normalizeCapability(cap);
+		if (!seen.has(normalized)) {
+			seen.add(normalized);
+			out.push(normalized);
+		}
+	}
+	return out;
+}
 
 // =============================================================================
 // Storage Types
@@ -1114,7 +1245,14 @@ export interface PluginDashboardWidget {
 /**
  * Settings field types (for admin UI generation)
  */
-export type SettingFieldType = "string" | "number" | "boolean" | "select" | "secret";
+export type SettingFieldType =
+	| "string"
+	| "number"
+	| "boolean"
+	| "select"
+	| "secret"
+	| "url"
+	| "email";
 
 export interface BaseSettingField {
 	type: SettingFieldType;
@@ -1150,12 +1288,26 @@ export interface SecretSettingField extends BaseSettingField {
 	type: "secret";
 }
 
+export interface UrlSettingField extends BaseSettingField {
+	type: "url";
+	default?: string;
+	placeholder?: string;
+}
+
+export interface EmailSettingField extends BaseSettingField {
+	type: "email";
+	default?: string;
+	placeholder?: string;
+}
+
 export type SettingField =
 	| StringSettingField
 	| NumberSettingField
 	| BooleanSettingField
 	| SelectSettingField
-	| SecretSettingField;
+	| SecretSettingField
+	| UrlSettingField
+	| EmailSettingField;
 
 /**
  * Block Kit element for block editing fields.
@@ -1180,6 +1332,15 @@ export interface PortableTextBlockConfig {
 	placeholder?: string;
 	/** Block Kit form fields for the editing UI. If declared, replaces the simple URL input. */
 	fields?: PortableTextBlockField[];
+	/**
+	 * Optional. Display category in the slash menu. Defaults to "Embeds".
+	 *
+	 * Plugin authors should pick a meaningful category that reflects what the
+	 * block actually is — e.g. "Sections", "Marketing", "Media", "Embeds",
+	 * "Layout". Blocks with the same category are grouped together in the
+	 * editor's slash menu.
+	 */
+	category?: string;
 }
 
 /**

package/src/preview/urls.ts

@@ -6,6 +6,8 @@
 
 import { generatePreviewToken } from "./tokens.js";
 
+const REPEATED_SLASHES = /\/{2,}/g;
+
 /**
  * Options for generating a preview URL
  */
@@ -20,8 +22,18 @@ export interface GetPreviewUrlOptions {
 	expiresIn?: string | number;
 	/** Base URL of the site. If not provided, returns a relative URL. */
 	baseUrl?: string;
-	/** Custom path pattern. Use {collection} and {id} as placeholders. Default: "/{collection}/{id}" */
+	/**
+	 * Custom path pattern. Supports `{collection}`, `{id}` and `{locale}`
+	 * placeholders. Default: `"/{collection}/{id}"`.
+	 */
 	pathPattern?: string;
+	/**
+	 * Locale segment substituted for the `{locale}` placeholder in `pathPattern`.
+	 * Pass an empty string to omit the locale prefix (e.g. for the default locale
+	 * when `prefixDefaultLocale` is `false`); adjacent slashes left by an empty
+	 * value are collapsed and any trailing slash is trimmed.
+	 */
+	locale?: string;
 }
 
 /**
@@ -65,6 +77,7 @@ export async function getPreviewUrl(options: GetPreviewUrlOptions): Promise<stri
 		expiresIn = "1h",
 		baseUrl,
 		pathPattern = "/{collection}/{id}",
+		locale = "",
 	} = options;
 
 	// Generate the signed token
@@ -74,8 +87,15 @@ export async function getPreviewUrl(options: GetPreviewUrlOptions): Promise<stri
 		secret,
 	});
 
-	// Build the path
-	const path = pathPattern.replace("{collection}", collection).replace("{id}", id);
+	// Build the path. `{locale}` may resolve to an empty string (default locale
+	// without a prefix); collapse the resulting double slashes and trim a
+	// trailing slash so the URL stays clean.
+	let path = pathPattern
+		.replace("{collection}", collection)
+		.replace("{id}", id)
+		.replace("{locale}", locale);
+	path = path.replace(REPEATED_SLASHES, "/");
+	if (path.length > 1 && path.endsWith("/")) path = path.slice(0, -1);
 
 	// Add token as query parameter
 	const url = new URL(path, baseUrl || "http://placeholder");

package/src/query.ts

@@ -12,7 +12,9 @@
  * and sets the context; query functions read it automatically.
  */
 
+import { encodeCursor } from "./database/repositories/types.js";
 import { getFallbackChain, getI18nConfig, isI18nEnabled } from "./i18n/config.js";
+import { CURSOR_RAW_VALUES } from "./loader.js";
 import { requestCached } from "./request-cache.js";
 import { getRequestContext } from "./request-context.js";
 import { isMissingTableError } from "./utils/db-errors.js";
@@ -279,9 +281,144 @@ export async function getEmDashCollection<T extends string, D = InferCollectionD
 	// appears on the home page AND in the sidebar) — caching collapses
 	// those duplicate queries, along with the bylines and taxonomy-term
 	// hydration each call would otherwise re-do.
-	return requestCached(collectionCacheKey(type, filter), () =>
-		getEmDashCollectionUncached<T, D>(type, filter),
+	//
+	// Bucket small limits to a shared minimum so a page with several
+	// "recent N posts" widgets at slightly different limits (e.g. a
+	// post-detail page asking for 4 in the body and 5 in the sidebar)
+	// shares one fetch + hydration round-trip rather than running two.
+	// Cursor-paginated calls are exempt: their limit is part of the
+	// pagination contract.
+	const bucketed = bucketFilter(filter);
+	const cached = await requestCached(collectionCacheKey(type, bucketed.fetchFilter), () =>
+		getEmDashCollectionUncached<T, D>(type, bucketed.fetchFilter),
 	);
+	return bucketed.requestedLimit === undefined
+		? cached
+		: sliceCollectionResult(cached, bucketed.requestedLimit, filter?.orderBy);
+}
+
+/**
+ * Threshold for limit bucketing. Page templates routinely render small
+ * "recent posts" widgets at limits 3-8; rounding those up to a single
+ * shared bucket lets one fetch satisfy several widgets within a request.
+ * Above this, the requested limit is honoured exactly — bucketing limit:50
+ * to limit:64 would waste hydration work for callers fetching real pages.
+ */
+const BUCKET_LIMIT_THRESHOLD = 10;
+
+interface BucketedFilter {
+	/** Filter to pass to the loader (with limit possibly raised). */
+	fetchFilter: CollectionFilter | undefined;
+	/** Original limit; defined only when bucketing was applied. */
+	requestedLimit: number | undefined;
+}
+
+/** @internal exported for unit tests; not part of the public API. */
+export function bucketFilter(filter: CollectionFilter | undefined): BucketedFilter {
+	const limit = filter?.limit;
+	if (
+		limit === undefined ||
+		limit >= BUCKET_LIMIT_THRESHOLD ||
+		limit <= 0 ||
+		filter?.cursor !== undefined
+	) {
+		return { fetchFilter: filter, requestedLimit: undefined };
+	}
+	return {
+		fetchFilter: { ...filter, limit: BUCKET_LIMIT_THRESHOLD },
+		requestedLimit: limit,
+	};
+}
+
+/**
+ * Slice a cached bucketed result down to the originally-requested limit
+ * and recompute `nextCursor` from the row that would have been the
+ * over-fetch detector for that limit. When truncation is needed, returns
+ * a shallow-copied result with a new `entries` array; otherwise returns
+ * the cached result unchanged (including error results and results
+ * already within the requested limit).
+ */
+/** @internal exported for unit tests; not part of the public API. */
+export function sliceCollectionResult<D>(
+	cached: CollectionResult<D>,
+	limit: number,
+	orderBy: OrderBySpec | undefined,
+): CollectionResult<D> {
+	if (cached.error) return cached;
+	if (cached.entries.length <= limit) return cached;
+	const sliced = cached.entries.slice(0, limit);
+	// Mirror the loader's encoding: cursor points at the last returned row,
+	// so "next page" picks up at the row immediately after it. See
+	// buildCursorCondition in loader.ts — it filters strictly past this row.
+	const lastEntry = sliced.at(-1);
+	const nextCursor = lastEntry ? encodeEntryCursor(lastEntry, orderBy) : undefined;
+	return { ...cached, entries: sliced, nextCursor };
+}
+
+/** Map of database column names to camelCase keys present on entry.data. */
+const ENTRY_DATA_KEY_MAP: Record<string, string> = {
+	created_at: "createdAt",
+	updated_at: "updatedAt",
+	published_at: "publishedAt",
+	scheduled_at: "scheduledAt",
+	author_id: "authorId",
+	primary_byline_id: "primaryBylineId",
+};
+
+// Mirror loader.ts FIELD_NAME_PATTERN. Kept in sync intentionally — diverging
+// would let the encoder accept a field name the loader's getPrimarySort then
+// rejected, producing a cursor that paginates against a different column.
+const FIELD_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+/**
+ * Encode a `nextCursor` from a content entry, mirroring the loader's
+ * encoding scheme: `(orderValue, id)` where `orderValue` is the primary
+ * sort field's stringified value. For date columns, reads the raw DB
+ * string the loader stashed via CURSOR_RAW_VALUES — round-tripping the
+ * parsed Date through `toISOString()` would lose precision for stored
+ * values that aren't already ISO-with-milliseconds.
+ */
+function encodeEntryCursor<D>(
+	entry: ContentEntry<D>,
+	orderBy: OrderBySpec | undefined,
+): string | undefined {
+	const data = entryData(entry);
+	const id = dataStr(data, "id");
+	if (!id) return undefined;
+
+	// Match loader.ts getPrimarySort: take the first valid field, default to created_at.
+	let dbField = "created_at";
+	if (orderBy) {
+		for (const field of Object.keys(orderBy)) {
+			if (FIELD_NAME_PATTERN.test(field)) {
+				dbField = field;
+				break;
+			}
+		}
+	}
+
+	// Date columns: prefer the raw stored string captured by the loader so
+	// the cursor matches what a direct loader fetch would emit, regardless
+	// of how the DB stored the timestamp.
+	const rawDateValuesRaw = Reflect.get(data, CURSOR_RAW_VALUES);
+	if (rawDateValuesRaw !== null && typeof rawDateValuesRaw === "object") {
+		const raw = Reflect.get(rawDateValuesRaw, dbField);
+		if (typeof raw === "string") return encodeCursor(raw, id);
+	}
+
+	const dataKey = ENTRY_DATA_KEY_MAP[dbField] ?? dbField;
+	const value = data[dataKey];
+	let orderValue: string;
+	if (value instanceof Date) {
+		orderValue = value.toISOString();
+	} else if (typeof value === "string" || typeof value === "number") {
+		orderValue = String(value);
+	} else {
+		// Match the loader's empty-string fallback for null/undefined order
+		// values so cursor decoding stays valid even at the boundary.
+		orderValue = "";
+	}
+	return encodeCursor(orderValue, id);
 }
 
 /**
@@ -478,7 +615,7 @@ export async function getEmDashEntry<T extends string, D = InferCollectionData<T
 			// Edit mode (authenticated editors) has collection-wide draft access.
 			if (isPreviewMode && !isEditMode) {
 				const dbId = entryDatabaseId(baseEntry);
-				if (preview!.id !== dbId && preview!.id !== id) {
+				if (preview.id !== dbId && preview.id !== id) {
 					// Token doesn't match — serve only if publicly visible, without draft access
 					if (isVisible(baseEntry)) {
 						return successResult(wrapEntry(baseEntry), {
@@ -562,10 +699,16 @@ async function hydrateEntryBylines<D>(type: string, entries: ContentEntry<D>[]):
 	try {
 		const { getBylinesForEntries } = await import("./bylines/index.js");
 
-		const ids = entries.map((e) => dataStr(entryData(e), "id")).filter(Boolean);
-		if (ids.length === 0) return;
+		const refs = entries
+			.map((e) => {
+				const data = entryData(e);
+				const id = dataStr(data, "id");
+				return id ? { id, authorId: dataStr(data, "authorId") || null } : null;
+			})
+			.filter((r): r is { id: string; authorId: string | null } => r !== null);
+		if (refs.length === 0) return;
 
-		const bylinesMap = await getBylinesForEntries(type, ids);
+		const bylinesMap = await getBylinesForEntries(type, refs);
 
 		for (const entry of entries) {
 			const data = entryData(entry);

package/src/redirects/cache.ts

@@ -1,8 +1,13 @@
 /**
- * Redirect pattern cache.
+ * Redirect rule cache.
  *
- * Module-level cache for compiled redirect pattern rules. The middleware
- * populates this on first request; route handlers invalidate it on writes.
+ * Module-level cache for enabled redirect rules. The middleware populates this
+ * on first request; route handlers invalidate it on writes.
+ *
+ * Both exact-match and pattern rules are loaded from one query and cached
+ * together: exact rules indexed by source path in a Map, pattern rules
+ * pre-compiled into an array. A single warm request issues zero database
+ * queries; a cold isolate issues one.
  *
  * This module deliberately has NO Astro imports so it can be safely imported
  * from handlers, seed, CLI, and tests without dragging in `astro:middleware`.
@@ -17,36 +22,51 @@ export interface CachedRedirectRule {
 	compiled: CompiledPattern;
 }
 
+export interface CachedRedirects {
+	/** Exact-match rules indexed by source path (`source` -> `Redirect`). */
+	exact: Map<string, Redirect>;
+	/** Pattern rules with their compiled regexes, preserving insertion order. */
+	patterns: CachedRedirectRule[];
+}
+
 /**
- * Cached pattern rules with compiled regexes.
- * null = not yet populated, array = cached.
+ * Cached enabled redirects.
+ * null = not yet populated, object = cached.
  */
-let cachedPatternRules: CachedRedirectRule[] | null = null;
+let cachedRedirects: CachedRedirects | null = null;
 
 /**
- * Invalidate the cached redirect pattern rules.
+ * Invalidate the cached redirects (both exact and pattern).
  * Call when redirects are created, updated, or deleted.
  */
 export function invalidateRedirectCache(): void {
-	cachedPatternRules = null;
+	cachedRedirects = null;
 }
 
 /**
- * Get the cached compiled pattern rules, or null if the cache is cold.
+ * Get the cached redirects, or null if the cache is cold.
  */
-export function getCachedPatternRules(): CachedRedirectRule[] | null {
-	return cachedPatternRules;
+export function getCachedRedirects(): CachedRedirects | null {
+	return cachedRedirects;
 }
 
 /**
- * Populate the pattern rules cache from a list of enabled pattern redirects.
+ * Populate the cache from a list of enabled redirects (both exact and
+ * pattern). The caller is responsible for passing only enabled rows — the
+ * cache stores them as-is.
  */
-export function setCachedPatternRules(redirects: Redirect[]): CachedRedirectRule[] {
-	cachedPatternRules = redirects.map((r) => ({
-		redirect: r,
-		compiled: compilePattern(r.source),
-	}));
-	return cachedPatternRules;
+export function setCachedRedirects(redirects: Redirect[]): CachedRedirects {
+	const exact = new Map<string, Redirect>();
+	const patterns: CachedRedirectRule[] = [];
+	for (const r of redirects) {
+		if (r.isPattern) {
+			patterns.push({ redirect: r, compiled: compilePattern(r.source) });
+		} else {
+			exact.set(r.source, r);
+		}
+	}
+	cachedRedirects = { exact, patterns };
+	return cachedRedirects;
 }
 
 /**

package/src/request-cache.ts

@@ -22,6 +22,7 @@ type CacheStore = WeakMap<EmDashRequestContext, Map<string, Promise<unknown>>>;
 const STORE_KEY = Symbol.for("emdash:request-cache");
 const g = globalThis as Record<symbol, unknown>;
 const store: CacheStore =
+	// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- globalThis singleton pattern (see request-context.ts)
 	(g[STORE_KEY] as CacheStore | undefined) ??
 	(() => {
 		const wm: CacheStore = new WeakMap();
@@ -47,6 +48,7 @@ export function requestCached<T>(key: string, fn: () => Promise<T>): Promise<T>
 	}
 
 	const existing = cache.get(key);
+	// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- heterogeneous cache; key namespacing guarantees the stored promise resolves to T
 	if (existing) return existing as Promise<T>;
 
 	const promise = Promise.resolve()
@@ -74,6 +76,7 @@ export function peekRequestCache<T>(key: string): Promise<T> | undefined {
 	const ctx = getRequestContext();
 	if (!ctx) return undefined;
 	const cache = store.get(ctx);
+	// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- heterogeneous cache; caller is responsible for using a T-compatible key
 	return cache?.get(key) as Promise<T> | undefined;
 }