emdash 0.0.0-b → 0.0.2

package/src/taxonomies/index.ts

@@ -0,0 +1,309 @@
+/**
+ * Runtime API for taxonomies
+ *
+ * Provides functions to query taxonomy definitions and terms.
+ */
+
+import { getDb } from "../loader.js";
+import type { TaxonomyDef, TaxonomyTerm, TaxonomyTermRow } from "./types.js";
+
+/**
+ * Get all taxonomy definitions
+ */
+export async function getTaxonomyDefs(): Promise<TaxonomyDef[]> {
+	const db = await getDb();
+
+	const rows = await db.selectFrom("_emdash_taxonomy_defs").selectAll().execute();
+
+	return rows.map((row) => ({
+		id: row.id,
+		name: row.name,
+		label: row.label,
+		labelSingular: row.label_singular ?? undefined,
+		hierarchical: row.hierarchical === 1,
+		collections: row.collections ? JSON.parse(row.collections) : [],
+	}));
+}
+
+/**
+ * Get a single taxonomy definition by name
+ */
+export async function getTaxonomyDef(name: string): Promise<TaxonomyDef | null> {
+	const db = await getDb();
+
+	const row = await db
+		.selectFrom("_emdash_taxonomy_defs")
+		.selectAll()
+		.where("name", "=", name)
+		.executeTakeFirst();
+
+	if (!row) return null;
+
+	return {
+		id: row.id,
+		name: row.name,
+		label: row.label,
+		labelSingular: row.label_singular ?? undefined,
+		hierarchical: row.hierarchical === 1,
+		collections: row.collections ? JSON.parse(row.collections) : [],
+	};
+}
+
+/**
+ * Get all terms for a taxonomy (as tree for hierarchical, flat for tags)
+ */
+export async function getTaxonomyTerms(taxonomyName: string): Promise<TaxonomyTerm[]> {
+	const db = await getDb();
+
+	// Get taxonomy definition to check if hierarchical
+	const def = await getTaxonomyDef(taxonomyName);
+	if (!def) return [];
+
+	// Get all terms for this taxonomy
+	const rows = await db
+		.selectFrom("taxonomies")
+		.selectAll()
+		.where("name", "=", taxonomyName)
+		.orderBy("label", "asc")
+		.execute();
+
+	// Count entries for each term
+	const countsResult = await db
+		.selectFrom("content_taxonomies")
+		.select(["taxonomy_id"])
+		.select((eb) => eb.fn.count<number>("entry_id").as("count"))
+		.groupBy("taxonomy_id")
+		.execute();
+
+	const counts = new Map<string, number>();
+	for (const row of countsResult) {
+		counts.set(row.taxonomy_id, row.count);
+	}
+
+	const flatTerms: TaxonomyTermRow[] = rows.map((row) => ({
+		id: row.id,
+		name: row.name,
+		slug: row.slug,
+		label: row.label,
+		parent_id: row.parent_id,
+		data: row.data,
+	}));
+
+	// If hierarchical, build tree. Otherwise return flat
+	if (def.hierarchical) {
+		return buildTree(flatTerms, counts);
+	}
+
+	return flatTerms.map((term) => ({
+		id: term.id,
+		name: term.name,
+		slug: term.slug,
+		label: term.label,
+		children: [],
+		count: counts.get(term.id) ?? 0,
+	}));
+}
+
+/**
+ * Get a single term by taxonomy and slug
+ */
+export async function getTerm(taxonomyName: string, slug: string): Promise<TaxonomyTerm | null> {
+	const db = await getDb();
+
+	const row = await db
+		.selectFrom("taxonomies")
+		.selectAll()
+		.where("name", "=", taxonomyName)
+		.where("slug", "=", slug)
+		.executeTakeFirst();
+
+	if (!row) return null;
+
+	// Get entry count
+	const countResult = await db
+		.selectFrom("content_taxonomies")
+		.select((eb) => eb.fn.count<number>("entry_id").as("count"))
+		.where("taxonomy_id", "=", row.id)
+		.executeTakeFirst();
+
+	const count = countResult?.count ?? 0;
+
+	// Get children if hierarchical
+	const childRows = await db
+		.selectFrom("taxonomies")
+		.selectAll()
+		.where("parent_id", "=", row.id)
+		.orderBy("label", "asc")
+		.execute();
+
+	const children = childRows.map((child) => ({
+		id: child.id,
+		name: child.name,
+		slug: child.slug,
+		label: child.label,
+		parentId: child.parent_id ?? undefined,
+		children: [],
+	}));
+
+	return {
+		id: row.id,
+		name: row.name,
+		slug: row.slug,
+		label: row.label,
+		parentId: row.parent_id ?? undefined,
+		description: row.data ? JSON.parse(row.data).description : undefined,
+		children,
+		count,
+	};
+}
+
+/**
+ * Get terms assigned to an entry
+ */
+export async function getEntryTerms(
+	collection: string,
+	entryId: string,
+	taxonomyName?: string,
+): Promise<TaxonomyTerm[]> {
+	const db = await getDb();
+
+	let query = db
+		.selectFrom("content_taxonomies")
+		.innerJoin("taxonomies", "taxonomies.id", "content_taxonomies.taxonomy_id")
+		.selectAll("taxonomies")
+		.where("content_taxonomies.collection", "=", collection)
+		.where("content_taxonomies.entry_id", "=", entryId);
+
+	if (taxonomyName) {
+		query = query.where("taxonomies.name", "=", taxonomyName);
+	}
+
+	const rows = await query.execute();
+
+	return rows.map((row) => ({
+		id: row.id,
+		name: row.name,
+		slug: row.slug,
+		label: row.label,
+		parentId: row.parent_id ?? undefined,
+		children: [],
+	}));
+}
+
+/**
+ * Get terms for multiple entries in a single query (batched API)
+ *
+ * This is more efficient than calling getEntryTerms for each entry
+ * when you need terms for a list of entries.
+ *
+ * @param collection - The collection type (e.g., "posts")
+ * @param entryIds - Array of entry IDs
+ * @param taxonomyName - The taxonomy name (e.g., "categories")
+ * @returns Map from entry ID to array of terms
+ */
+export async function getTermsForEntries(
+	collection: string,
+	entryIds: string[],
+	taxonomyName: string,
+): Promise<Map<string, TaxonomyTerm[]>> {
+	const result = new Map<string, TaxonomyTerm[]>();
+
+	// Initialize all entry IDs with empty arrays
+	for (const id of entryIds) {
+		result.set(id, []);
+	}
+
+	if (entryIds.length === 0) {
+		return result;
+	}
+
+	const db = await getDb();
+
+	const rows = await db
+		.selectFrom("content_taxonomies")
+		.innerJoin("taxonomies", "taxonomies.id", "content_taxonomies.taxonomy_id")
+		.select([
+			"content_taxonomies.entry_id",
+			"taxonomies.id",
+			"taxonomies.name",
+			"taxonomies.slug",
+			"taxonomies.label",
+			"taxonomies.parent_id",
+		])
+		.where("content_taxonomies.collection", "=", collection)
+		.where("content_taxonomies.entry_id", "in", entryIds)
+		.where("taxonomies.name", "=", taxonomyName)
+		.execute();
+
+	for (const row of rows) {
+		const entryId = row.entry_id;
+		const term: TaxonomyTerm = {
+			id: row.id,
+			name: row.name,
+			slug: row.slug,
+			label: row.label,
+			parentId: row.parent_id ?? undefined,
+			children: [],
+		};
+
+		const terms = result.get(entryId);
+		if (terms) {
+			terms.push(term);
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Get entries by term (wraps getEmDashCollection)
+ */
+export async function getEntriesByTerm(
+	collection: string,
+	taxonomyName: string,
+	termSlug: string,
+): Promise<Array<{ id: string; data: Record<string, unknown> }>> {
+	const { getEmDashCollection } = await import("../query.js");
+
+	// Build options as the expected type — getEmDashCollection accepts
+	// a generic options object with `where` for filtering by taxonomy
+	const options: Record<string, unknown> = {
+		where: { [taxonomyName]: termSlug },
+	};
+	const { entries } = await getEmDashCollection(collection, options);
+
+	return entries;
+}
+
+/**
+ * Build tree structure from flat terms
+ */
+function buildTree(flatTerms: TaxonomyTermRow[], counts: Map<string, number>): TaxonomyTerm[] {
+	const map = new Map<string, TaxonomyTerm>();
+	const roots: TaxonomyTerm[] = [];
+
+	// First pass: create nodes
+	for (const term of flatTerms) {
+		map.set(term.id, {
+			id: term.id,
+			name: term.name,
+			slug: term.slug,
+			label: term.label,
+			parentId: term.parent_id ?? undefined,
+			description: term.data ? JSON.parse(term.data).description : undefined,
+			children: [],
+			count: counts.get(term.id) ?? 0,
+		});
+	}
+
+	// Second pass: build tree
+	for (const term of map.values()) {
+		if (term.parentId && map.has(term.parentId)) {
+			map.get(term.parentId)!.children.push(term);
+		} else {
+			roots.push(term);
+		}
+	}
+
+	return roots;
+}

package/src/taxonomies/types.ts

@@ -0,0 +1,61 @@
+/**
+ * Taxonomy types for EmDash CMS
+ */
+
+/**
+ * Taxonomy definition - describes a taxonomy like "category" or "tag"
+ */
+export interface TaxonomyDef {
+	id: string;
+	name: string; // 'category', 'tag', 'genre'
+	label: string; // 'Categories', 'Tags'
+	labelSingular?: string; // 'Category', 'Tag'
+	hierarchical: boolean;
+	collections: string[]; // ['posts', 'pages']
+}
+
+/**
+ * Taxonomy term - a specific term within a taxonomy (e.g., "News" in "category")
+ */
+export interface TaxonomyTerm {
+	id: string;
+	name: string; // Taxonomy name ('category')
+	slug: string; // Term slug ('news')
+	label: string; // Display label ('News')
+	parentId?: string;
+	description?: string;
+	children: TaxonomyTerm[]; // For tree structure
+	count?: number; // Entry count
+}
+
+/**
+ * Flat version for DB row
+ */
+export interface TaxonomyTermRow {
+	id: string;
+	name: string;
+	slug: string;
+	label: string;
+	parent_id: string | null;
+	data: string | null; // JSON
+}
+
+/**
+ * Input for creating a term
+ */
+export interface CreateTermInput {
+	slug: string;
+	label: string;
+	parentId?: string;
+	description?: string;
+}
+
+/**
+ * Input for updating a term
+ */
+export interface UpdateTermInput {
+	slug?: string;
+	label?: string;
+	parentId?: string | null;
+	description?: string;
+}

package/src/ui.ts

@@ -0,0 +1,75 @@
+/**
+ * EmDash UI Components
+ *
+ * Image component for rendering optimized images:
+ *
+ * ```astro
+ * ---
+ * import { Image } from "emdash/ui";
+ * ---
+ * <Image image={post.data.featured_image} />
+ * ```
+ *
+ * Portable Text component for rich content:
+ *
+ * ```astro
+ * ---
+ * import { PortableText } from "emdash/ui";
+ * ---
+ * <PortableText value={post.data.content} />
+ * ```
+ *
+ * Override specific Portable Text components:
+ *
+ * ```astro
+ * <PortableText value={content} components={{ type: { image: MyImage } }} />
+ * ```
+ */
+
+// Re-export types and utilities from astro-portabletext
+export {
+	type PortableTextProps,
+	type TypedObject,
+	type SomePortableTextComponents,
+	type Block,
+	type ArbitraryTypedObject,
+	type PortableTextBlock,
+	type PortableTextMarkDefinition,
+	type PortableTextSpan,
+	type PortableTextListItemBlock,
+	usePortableText,
+	mergeComponents,
+} from "astro-portabletext";
+
+// EmDash PortableText wrapper and components
+export {
+	// Main Image component for EmDash media
+	EmDashImage as Image,
+	// Main component (wrapper with EmDash defaults)
+	PortableText,
+	// Comment components
+	Comments,
+	CommentForm,
+	// Widget components
+	WidgetArea,
+	// Components object for manual use
+	emdashComponents,
+	// Portable Text block types (prefixed to avoid collision with Image)
+	Image as PTImage,
+	Code,
+	Embed,
+	Gallery,
+	Columns,
+	Break,
+	HtmlBlock,
+	// Marks
+	Superscript,
+	Subscript,
+	Underline,
+	StrikeThrough,
+	Link,
+	// Public page contribution components
+	EmDashHead,
+	EmDashBodyStart,
+	EmDashBodyEnd,
+} from "./components/index.js";

package/src/utils/base64.ts

@@ -0,0 +1,73 @@
+/**
+ * Base64 encoding/decoding utilities.
+ *
+ * Uses native Uint8Array.prototype.toBase64 / Uint8Array.fromBase64 when
+ * available (workerd, Node 26+, modern browsers), falls back to btoa/atob.
+ *
+ * All base64url encoding uses the { alphabet: "base64url" } option natively
+ * or manual character replacement as fallback.
+ *
+ * Delete the fallback paths when the minimum Node version supports these
+ * methods natively.
+ */
+
+const hasNative =
+	typeof Uint8Array.prototype.toBase64 === "function" &&
+	typeof Uint8Array.fromBase64 === "function";
+
+// Regex patterns for base64url character replacement
+const BASE64_PLUS_PATTERN = /\+/g;
+const BASE64_SLASH_PATTERN = /\//g;
+const BASE64_PADDING_PATTERN = /=+$/;
+const BASE64URL_DASH_PATTERN = /-/g;
+const BASE64URL_UNDERSCORE_PATTERN = /_/g;
+
+// ---------------------------------------------------------------------------
+// Standard base64 (for opaque tokens, cursors, Basic Auth, etc.)
+// ---------------------------------------------------------------------------
+
+/** Encode a UTF-8 string as standard base64. */
+export function encodeBase64(str: string): string {
+	const bytes = new TextEncoder().encode(str);
+	if (hasNative) return bytes.toBase64();
+	let binary = "";
+	for (const b of bytes) binary += String.fromCharCode(b);
+	return btoa(binary);
+}
+
+/** Decode a standard base64 string to a UTF-8 string. */
+export function decodeBase64(base64: string): string {
+	if (hasNative) return new TextDecoder().decode(Uint8Array.fromBase64(base64));
+	const binary = atob(base64);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+	return new TextDecoder().decode(bytes);
+}
+
+// ---------------------------------------------------------------------------
+// Base64url (for tokens, HMAC signatures, PKCE, etc.)
+// ---------------------------------------------------------------------------
+
+/** Encode bytes as base64url without padding. */
+export function encodeBase64url(bytes: Uint8Array): string {
+	if (hasNative) return bytes.toBase64({ alphabet: "base64url", omitPadding: true });
+	let binary = "";
+	for (const b of bytes) binary += String.fromCharCode(b);
+	return btoa(binary)
+		.replace(BASE64_PLUS_PATTERN, "-")
+		.replace(BASE64_SLASH_PATTERN, "_")
+		.replace(BASE64_PADDING_PATTERN, "");
+}
+
+/** Decode a base64url string (with or without padding) to bytes. */
+export function decodeBase64url(encoded: string): Uint8Array {
+	if (hasNative) return Uint8Array.fromBase64(encoded, { alphabet: "base64url" });
+	const base64 = encoded
+		.replace(BASE64URL_DASH_PATTERN, "+")
+		.replace(BASE64URL_UNDERSCORE_PATTERN, "/");
+	const padded = base64 + "=".repeat((4 - (base64.length % 4)) % 4);
+	const binary = atob(padded);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+}

package/src/utils/hash.ts

@@ -0,0 +1,36 @@
+/**
+ * SHA-256 hash of a string, truncated to 16 hex chars (64 bits).
+ * For cache invalidation / ETags — not for security.
+ */
+export async function hashString(content: string): Promise<string> {
+	const buf = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(content));
+	return Array.from(new Uint8Array(buf).slice(0, 8), (b) => b.toString(16).padStart(2, "0")).join(
+		"",
+	);
+}
+
+/**
+ * Compute content hash using Web Crypto API
+ *
+ * Uses SHA-1 which is the fastest option in SubtleCrypto.
+ * SHA-1 is cryptographically weak but fine for content deduplication
+ * where we only need to detect identical files, not resist attacks.
+ *
+ * Returns hex string prefixed with "sha1:" for future-proofing
+ */
+export async function computeContentHash(content: Uint8Array | ArrayBuffer): Promise<string> {
+	// SubtleCrypto.digest() requires BufferSource (ArrayBuffer | ArrayBufferView<ArrayBuffer>).
+	// Uint8Array.buffer is ArrayBufferLike which may include SharedArrayBuffer in the type system,
+	// so we ensure we have a plain ArrayBuffer.
+	let buf: ArrayBuffer;
+	if (content instanceof ArrayBuffer) {
+		buf = content;
+	} else {
+		buf = new ArrayBuffer(content.byteLength);
+		new Uint8Array(buf).set(content);
+	}
+	const hashBuffer = await crypto.subtle.digest("SHA-1", buf);
+	const hashArray = new Uint8Array(hashBuffer);
+	const hashHex = Array.from(hashArray, (b) => b.toString(16).padStart(2, "0")).join("");
+	return `sha1:${hashHex}`;
+}

package/src/utils/sanitize.ts

@@ -0,0 +1,20 @@
+import sanitizeHtml from "sanitize-html";
+
+/**
+ * Sanitize HTML content to prevent XSS attacks.
+ *
+ * Allows standard formatting tags, images, iframes (from specific providers),
+ * and basic attributes.
+ */
+export function sanitizeContent(html: string): string {
+	return sanitizeHtml(html, {
+		allowedTags: [...sanitizeHtml.defaults.allowedTags, "img", "span", "iframe"],
+		allowedAttributes: {
+			...sanitizeHtml.defaults.allowedAttributes,
+			"*": ["class", "id", "data-*"],
+			iframe: ["src", "width", "height", "frameborder", "allow", "allowfullscreen"],
+			img: ["src", "srcset", "alt", "title", "width", "height", "loading"],
+		},
+		allowedIframeHostnames: ["www.youtube.com", "player.vimeo.com"],
+	});
+}

package/src/utils/slugify.ts

@@ -0,0 +1,29 @@
+// Regex patterns for slug normalization
+const DIACRITICS_PATTERN = /[\u0300-\u036f]/g;
+const WHITESPACE_UNDERSCORE_PATTERN = /[\s_]+/g;
+const NON_ALPHANUMERIC_HYPHEN_PATTERN = /[^a-z0-9-]/g;
+const MULTIPLE_HYPHENS_PATTERN = /-+/g;
+const LEADING_TRAILING_HYPHEN_PATTERN = /^-|-$/g;
+const TRAILING_HYPHEN_PATTERN = /-$/;
+
+/**
+ * Convert a string to a URL-friendly slug.
+ *
+ * Handles unicode by normalizing to NFD and stripping diacritics,
+ * so "café" becomes "cafe", "naïve" becomes "naive", etc.
+ */
+export function slugify(text: string, maxLength: number = 80): string {
+	return (
+		text
+			.toLowerCase()
+			.normalize("NFD")
+			.replace(DIACRITICS_PATTERN, "")
+			.replace(WHITESPACE_UNDERSCORE_PATTERN, "-")
+			.replace(NON_ALPHANUMERIC_HYPHEN_PATTERN, "")
+			.replace(MULTIPLE_HYPHENS_PATTERN, "-")
+			.replace(LEADING_TRAILING_HYPHEN_PATTERN, "")
+			.slice(0, maxLength)
+			// Clean trailing hyphen from truncation
+			.replace(TRAILING_HYPHEN_PATTERN, "")
+	);
+}

package/src/utils/url.ts

@@ -0,0 +1,48 @@
+/**
+ * URL scheme validation utilities
+ *
+ * Prevents XSS via dangerous URL schemes (javascript:, data:, vbscript:, etc.)
+ * by allowlisting known-safe schemes before rendering into href attributes.
+ */
+
+/**
+ * Matches URLs that are safe to render in href attributes.
+ *
+ * Allowed:
+ * - http:// and https://
+ * - mailto: and tel:
+ * - Relative paths (starting with /)
+ * - Fragment links (starting with #)
+ * - Protocol-relative URLs are NOT allowed (starting with //) as they can
+ *   redirect to attacker-controlled hosts.
+ */
+const SAFE_URL_SCHEME_RE = /^(https?:|mailto:|tel:|\/(?!\/)|#)/i;
+
+/**
+ * Returns the URL unchanged if it uses a safe scheme, otherwise returns "#".
+ *
+ * Use this at the render layer as the primary defense against XSS via
+ * dangerous URL schemes like `javascript:`, `data:`, or `vbscript:`.
+ *
+ * @example
+ * ```ts
+ * sanitizeHref("https://example.com")        // "https://example.com"
+ * sanitizeHref("/about")                      // "/about"
+ * sanitizeHref("#section")                    // "#section"
+ * sanitizeHref("mailto:a@b.com")              // "mailto:a@b.com"
+ * sanitizeHref("javascript:alert(1)")         // "#"
+ * sanitizeHref("data:text/html,<script>")     // "#"
+ * sanitizeHref("")                            // "#"
+ * ```
+ */
+export function sanitizeHref(url: string | undefined | null): string {
+	if (!url) return "#";
+	return SAFE_URL_SCHEME_RE.test(url) ? url : "#";
+}
+
+/**
+ * Returns true if the URL uses a safe scheme for rendering in href attributes.
+ */
+export function isSafeHref(url: string): boolean {
+	return SAFE_URL_SCHEME_RE.test(url);
+}