emdash 0.34.0 → 0.36.0

package/src/database/repositories/media.ts

@@ -1,6 +1,13 @@
-import { sql, type ExpressionBuilder, type Kysely, type SqlBool } from "kysely";
+import {
+	sql,
+	type ExpressionBuilder,
+	type Kysely,
+	type SelectQueryBuilder,
+	type SqlBool,
+} from "kysely";
 import { ulid } from "ulidx";
 
+import { normalizeFocalPoint, type FocalPointUpdate } from "../../media/focal-point.js";
 import type { Database, MediaRow } from "../types.js";
 import type { FindManyResult } from "./types.js";
 import { encodeCursor, decodeCursor } from "./types.js";
@@ -48,6 +55,8 @@ export interface MediaItem {
 	size: number | null;
 	width: number | null;
 	height: number | null;
+	focalX: number | null;
+	focalY: number | null;
 	alt: string | null;
 	caption: string | null;
 	storageKey: string;
@@ -57,6 +66,7 @@ export interface MediaItem {
 	dominantColor: string | null;
 	createdAt: string;
 	authorId: string | null;
+	folderId?: string | null;
 }
 
 export interface CreateMediaInput {
@@ -83,6 +93,25 @@ export interface FindManyMediaOptions {
 	status?: MediaStatus | "all"; // Filter by status, defaults to "ready"
 	/** Case-insensitive substring matched against the filename (covers filename and extension). */
 	q?: string;
+	/** Omit for all media, pass null for the Main library, or pass a folder ID. */
+	folderId?: string | null;
+}
+
+export interface UpdateMediaInput extends FocalPointUpdate {
+	alt?: string;
+	caption?: string;
+	width?: number;
+	height?: number;
+	folderId?: string | null;
+}
+
+export interface FindMediaPageOptions extends Omit<FindManyMediaOptions, "cursor"> {
+	page: number;
+}
+
+export interface MediaPageResult {
+	items: MediaItem[];
+	totalCount: number;
 }
 
 const UPLOAD_ATTEMPT_CLEANUP_AGE_MS = 60 * 60 * 1000;
@@ -108,6 +137,8 @@ export class MediaRepository {
 			size: input.size ?? null,
 			width: input.width ?? null,
 			height: input.height ?? null,
+			focal_x: null,
+			focal_y: null,
 			alt: input.alt ?? null,
 			caption: input.caption ?? null,
 			storage_key: input.storageKey,
@@ -117,6 +148,7 @@ export class MediaRepository {
 			status: input.status ?? "ready",
 			created_at: now,
 			author_id: input.authorId ?? null,
+			folder_id: null,
 		};
 
 		await this.db.insertInto("media").values(row).execute();
@@ -367,8 +399,7 @@ export class MediaRepository {
 	async findMany(options: FindManyMediaOptions = {}): Promise<FindManyResult<MediaItem>> {
 		const limit = Math.min(options.limit || 50, 100);
 
-		let query = this.db
-			.selectFrom("media")
+		let query = this.applyListFilters(this.db.selectFrom("media"), options)
 			.selectAll()
 			.orderBy("created_at", "desc")
 			.orderBy("id", "desc")
@@ -387,28 +418,6 @@ export class MediaRepository {
 			);
 		}
 
-		const mimeFilters = normalizeMimeFilter(options.mimeType);
-		if (mimeFilters.length > 0) {
-			query = query.where((eb) => mimeMatchExpr(eb, mimeFilters));
-		}
-
-		// Case-insensitive filename substring search (also matches extensions).
-		// LIKE wildcards in the term are escaped so they're treated literally.
-		const term = options.q?.trim();
-		if (term) {
-			const pattern = `%${escapeLike(term)}%`;
-			query = query.where(
-				sql<string>`lower(filename)`,
-				"like",
-				sql<string>`lower(${pattern}) escape '\\'`,
-			);
-		}
-
-		// Default to only showing ready items
-		if (options.status !== "all") {
-			query = query.where("status", "=", options.status ?? "ready");
-		}
-
 		const rows = await query.execute();
 
 		const hasMore = rows.length > limit;
@@ -423,13 +432,31 @@ export class MediaRepository {
 		return { items, nextCursor };
 	}
 
+	async findPage(options: FindMediaPageOptions): Promise<MediaPageResult> {
+		const limit = Math.min(options.limit || 50, 100);
+		const offset = (options.page - 1) * limit;
+		const filtered = this.applyListFilters(this.db.selectFrom("media"), options);
+		const rows = await filtered
+			.selectAll()
+			.orderBy("created_at", "desc")
+			.orderBy("id", "desc")
+			.limit(limit)
+			.offset(offset)
+			.execute();
+		const count = await filtered
+			.select((eb) => eb.fn.count<number>("id").as("count"))
+			.executeTakeFirst();
+
+		return {
+			items: rows.map((row) => this.rowToItem(row)),
+			totalCount: Number(count?.count ?? 0),
+		};
+	}
+
 	/**
 	 * Update media metadata
 	 */
-	async update(
-		id: string,
-		input: Partial<Pick<CreateMediaInput, "alt" | "caption" | "width" | "height">>,
-	): Promise<MediaItem | null> {
+	async update(id: string, input: UpdateMediaInput): Promise<MediaItem | null> {
 		const existing = await this.findById(id);
 		if (!existing) {
 			return null;
@@ -440,6 +467,11 @@ export class MediaRepository {
 		if (input.caption !== undefined) updates.caption = input.caption;
 		if (input.width !== undefined) updates.width = input.width;
 		if (input.height !== undefined) updates.height = input.height;
+		if (input.folderId !== undefined) updates.folder_id = input.folderId;
+		if (input.focalX !== undefined && input.focalY !== undefined) {
+			updates.focal_x = input.focalX;
+			updates.focal_y = input.focalY;
+		}
 
 		if (Object.keys(updates).length > 0) {
 			await this.db.updateTable("media").set(updates).where("id", "=", id).execute();
@@ -480,6 +512,38 @@ export class MediaRepository {
 		return Number(result?.count || 0);
 	}
 
+	private applyListFilters<O>(
+		query: SelectQueryBuilder<Database, "media", O>,
+		options: Omit<FindManyMediaOptions, "cursor" | "limit">,
+	): SelectQueryBuilder<Database, "media", O> {
+		const mimeFilters = normalizeMimeFilter(options.mimeType);
+		if (mimeFilters.length > 0) {
+			query = query.where((eb) => mimeMatchExpr(eb, mimeFilters));
+		}
+
+		const term = options.q?.trim();
+		if (term) {
+			const pattern = `%${escapeLike(term)}%`;
+			query = query.where(
+				sql<string>`lower(filename)`,
+				"like",
+				sql<string>`lower(${pattern}) escape '\\'`,
+			);
+		}
+
+		if (options.status !== "all") {
+			query = query.where("status", "=", options.status ?? "ready");
+		}
+
+		if (options.folderId === null) {
+			query = query.where("folder_id", "is", null);
+		} else if (options.folderId !== undefined) {
+			query = query.where("folder_id", "=", options.folderId);
+		}
+
+		return query;
+	}
+
 	/**
 	 * Delete pending uploads older than the given age.
 	 * Pending uploads that were never confirmed indicate abandoned upload flows.
@@ -504,6 +568,7 @@ export class MediaRepository {
 	 * Convert database row to MediaItem
 	 */
 	private rowToItem(row: MediaRow): MediaItem {
+		const focalPoint = normalizeFocalPoint(row.focal_x, row.focal_y);
 		return {
 			id: row.id,
 			filename: row.filename,
@@ -511,6 +576,8 @@ export class MediaRepository {
 			size: row.size,
 			width: row.width,
 			height: row.height,
+			focalX: focalPoint?.focalX ?? null,
+			focalY: focalPoint?.focalY ?? null,
 			alt: row.alt,
 			caption: row.caption,
 			storageKey: row.storage_key,
@@ -521,6 +588,7 @@ export class MediaRepository {
 			status: row.status as MediaStatus,
 			createdAt: row.created_at,
 			authorId: row.author_id,
+			folderId: row.folder_id,
 		};
 	}
 }

package/src/database/transaction.ts

@@ -29,6 +29,7 @@ export async function withTransaction<DB, T>(
 	db: Kysely<DB>,
 	fn: (trx: Kysely<DB> | Transaction<DB>) => Promise<T>,
 ): Promise<T> {
+	if (db.isTransaction) return fn(db);
 	// Fast path: we already know transactions work
 	if (transactionsSupported === true) {
 		return db.transaction().execute(fn);

package/src/database/types.ts

@@ -67,6 +67,8 @@ export interface MediaTable {
 	size: number | null;
 	width: number | null;
 	height: number | null;
+	focal_x: number | null;
+	focal_y: number | null;
 	alt: string | null;
 	caption: string | null;
 	storage_key: string;
@@ -76,6 +78,13 @@ export interface MediaTable {
 	dominant_color: string | null;
 	created_at: Generated<string>;
 	author_id: string | null;
+	folder_id: Generated<string | null>;
+}
+
+export interface MediaFolderTable {
+	id: string;
+	name: string;
+	name_key: string;
 }
 
 export interface MediaUploadAttemptTable {
@@ -627,6 +636,7 @@ export interface Database {
 	content_taxonomies: ContentTaxonomyTable;
 	_emdash_taxonomy_defs: TaxonomyDefTable;
 	media: MediaTable;
+	media_folders: MediaFolderTable;
 	_emdash_media_upload_attempts: MediaUploadAttemptTable;
 	_emdash_media_usage_sources: MediaUsageSourceTable;
 	_emdash_media_usage: MediaUsageTable;
@@ -685,6 +695,8 @@ export type MediaRow = {
 	size: number | null;
 	width: number | null;
 	height: number | null;
+	focal_x: number | null;
+	focal_y: number | null;
 	alt: string | null;
 	caption: string | null;
 	storage_key: string;
@@ -694,6 +706,7 @@ export type MediaRow = {
 	dominant_color: string | null;
 	created_at: string;
 	author_id: string | null;
+	folder_id: string | null;
 };
 
 export interface RedirectTable {

package/src/db/adapters.ts

@@ -52,6 +52,20 @@ export type ExecuteCollectionDeletionGuard = (
 	input: CollectionDeletionGuardInput,
 ) => Promise<CollectionDeletionGuardResult>;
 
+const ENVIRONMENT_VARIABLE_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function migrationEnvironmentVariable(
+	value: string | undefined,
+	fallback: string,
+	optionName: string,
+): string {
+	const name = value ?? fallback;
+	if (!ENVIRONMENT_VARIABLE_PATTERN.test(name)) {
+		throw new Error(`${optionName} must be a valid environment variable name.`);
+	}
+	return name;
+}
+
 /**
  * Database descriptor - serializable config for virtual modules
  */
@@ -59,6 +73,11 @@ export interface DatabaseDescriptor {
 	entrypoint: string;
 	config: unknown;
 	type: DatabaseDialectType;
+	/** Deployment migration capability with configuration safe for a build artifact. */
+	migrations?: {
+		entrypoint: string;
+		manifestConfig: unknown;
+	};
 	/**
 	 * When true, the adapter's runtime entrypoint MUST export a named
 	 * `createRequestScopedDb` function matching the signature declared in
@@ -111,12 +130,13 @@ export interface LibsqlConfig {
 	 * Auth token for remote libSQL
 	 */
 	authToken?: string;
+	migrationAuthTokenEnv?: string;
 }
 
 /**
- * SQLite database adapter (better-sqlite3)
+ * SQLite database adapter (node:sqlite)
  *
- * For local development and Node.js deployments.
+ * For local development and Node.js deployments. Requires Node.js 22.16 or later.
  *
  * @example
  * ```ts
@@ -128,6 +148,10 @@ export function sqlite(config: SqliteConfig): DatabaseDescriptor {
 		entrypoint: "emdash/db/sqlite",
 		config,
 		type: "sqlite",
+		migrations: {
+			entrypoint: "emdash/db/sqlite-migrations",
+			manifestConfig: { url: config.url },
+		},
 	};
 }
 
@@ -145,10 +169,22 @@ export function sqlite(config: SqliteConfig): DatabaseDescriptor {
  * ```
  */
 export function libsql(config: LibsqlConfig): DatabaseDescriptor {
+	const { migrationAuthTokenEnv, ...runtimeConfig } = config;
 	return {
 		entrypoint: "emdash/db/libsql",
-		config,
+		config: runtimeConfig,
 		type: "sqlite",
+		migrations: {
+			entrypoint: "emdash/db/libsql-migrations",
+			manifestConfig: {
+				url: config.url,
+				authTokenEnv: migrationEnvironmentVariable(
+					migrationAuthTokenEnv,
+					"TURSO_AUTH_TOKEN",
+					"migrationAuthTokenEnv",
+				),
+			},
+		},
 	};
 }
 
@@ -164,6 +200,7 @@ export interface PostgresConfig {
 	password?: string;
 	ssl?: boolean;
 	pool?: { min?: number; max?: number };
+	migrationConnectionStringEnv?: string;
 }
 
 /**
@@ -177,9 +214,20 @@ export interface PostgresConfig {
  * ```
  */
 export function postgres(config: PostgresConfig): DatabaseDescriptor {
+	const { migrationConnectionStringEnv, ...runtimeConfig } = config;
 	return {
 		entrypoint: "emdash/db/postgres",
-		config,
+		config: runtimeConfig,
 		type: "postgres",
+		migrations: {
+			entrypoint: "emdash/db/postgres-migrations",
+			manifestConfig: {
+				connectionStringEnv: migrationEnvironmentVariable(
+					migrationConnectionStringEnv,
+					"DATABASE_URL",
+					"migrationConnectionStringEnv",
+				),
+			},
+		},
 	};
 }

package/src/db/index.ts

@@ -35,6 +35,8 @@ export type {
 export {
 	runMigrations,
 	getMigrationStatus,
+	getExactMigrationStatus,
 	rollbackMigration,
+	MIGRATION_NAMES,
 } from "../database/migrations/runner.js";
-export type { MigrationStatus } from "../database/migrations/runner.js";
+export type { MigrationStatus, ExactMigrationStatus } from "../database/migrations/runner.js";

package/src/db/libsql-migrations.ts

@@ -0,0 +1,72 @@
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { createDirectMigrationExecutor } from "../migrations/direct-executor.js";
+import type { MigrationExecutor, MigrationExecutorFactoryContext } from "../migrations/protocol.js";
+import { createMigrationTarget, requireMigrationEnvironment } from "../migrations/target.js";
+import { createDialect } from "./libsql.js";
+
+export interface LibsqlMigrationManifestConfig {
+	url: string;
+	authTokenEnv: string;
+}
+
+interface ResolvedLibsqlUrl {
+	connectionUrl: string;
+	label: string;
+	identity: string[];
+	requiresAuthToken: boolean;
+}
+
+function resolveLibsqlUrl(url: unknown, projectRoot: string): ResolvedLibsqlUrl {
+	if (typeof url !== "string" || url.length === 0) {
+		throw new Error("libSQL migration URL is missing.");
+	}
+	if (url.startsWith("file:")) {
+		const configuredPath = url.slice(5);
+		if (configuredPath.length === 0) throw new Error("libSQL migration URL is invalid.");
+		const fileUrl = pathToFileURL(resolve(projectRoot, configuredPath));
+		return {
+			connectionUrl: fileUrl.href,
+			label: fileUrl.href,
+			identity: [fileUrl.protocol, fileUrl.pathname],
+			requiresAuthToken: false,
+		};
+	}
+
+	let parsed: URL;
+	try {
+		parsed = new URL(url);
+	} catch {
+		throw new Error("libSQL migration URL is invalid.");
+	}
+	if (parsed.username || parsed.password) {
+		throw new Error("libSQL migration URL must not contain credentials.");
+	}
+	const label = `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+	return {
+		connectionUrl: url,
+		label,
+		identity: [parsed.protocol, parsed.host, parsed.pathname],
+		requiresAuthToken: true,
+	};
+}
+
+export async function createMigrationExecutor(
+	manifestConfig: LibsqlMigrationManifestConfig,
+	context: MigrationExecutorFactoryContext,
+): Promise<MigrationExecutor> {
+	const resolvedUrl = resolveLibsqlUrl(manifestConfig.url, context.projectRoot);
+	const authToken = resolvedUrl.requiresAuthToken
+		? requireMigrationEnvironment(manifestConfig.authTokenEnv, context.env)
+		: undefined;
+	const target = await createMigrationTarget("libsql", resolvedUrl.label, resolvedUrl.identity);
+	return createDirectMigrationExecutor({
+		target,
+		createDialect: () =>
+			createDialect({
+				url: resolvedUrl.connectionUrl,
+				authToken,
+			}),
+	});
+}

package/src/db/node-sqlite-compat.ts

@@ -0,0 +1,78 @@
+import { DatabaseSync } from "node:sqlite";
+
+export interface NodeSqliteCompatDatabase {
+	close(): void;
+	prepare(sql: string): NodeSqliteCompatStatement;
+}
+
+export interface NodeSqliteCompatStatement {
+	readonly reader: boolean;
+	all(parameters: ReadonlyArray<unknown>): unknown[];
+	run(parameters: ReadonlyArray<unknown>): {
+		changes: number | bigint;
+		lastInsertRowid: number | bigint;
+	};
+	iterate(parameters: ReadonlyArray<unknown>): IterableIterator<unknown>;
+}
+
+export interface NodeSqliteOpenOptions {
+	journalMode?: "wal";
+}
+
+type SqliteBinding = null | number | bigint | string | Uint8Array;
+
+export function openNodeSqliteDatabase(
+	path: string,
+	options: NodeSqliteOpenOptions = {},
+): NodeSqliteCompatDatabase {
+	const database = new DatabaseSync(path);
+
+	try {
+		database.exec("PRAGMA busy_timeout = 5000");
+		database.exec("PRAGMA foreign_keys = ON");
+		// Negative cache_size values are kibibytes.
+		database.exec("PRAGMA cache_size = -16000");
+		if (options.journalMode === "wal") {
+			database.exec("PRAGMA journal_mode = WAL");
+		}
+		const journalMode = database.prepare("PRAGMA journal_mode").get()?.["journal_mode"];
+		if (journalMode === "wal") {
+			database.exec("PRAGMA synchronous = NORMAL");
+		}
+	} catch (error) {
+		try {
+			database.close();
+		} catch {
+			throw new Error("SQLite setup failed and the connection could not be closed", {
+				cause: error,
+			});
+		}
+		throw error;
+	}
+
+	return {
+		close: () => database.close(),
+		prepare(sql) {
+			const statement = database.prepare(sql);
+			return {
+				reader: statement.columns().length > 0,
+				all: (parameters) => statement.all(...toBindings(parameters)),
+				run: (parameters) => statement.run(...toBindings(parameters)),
+				iterate: (parameters) => statement.iterate(...toBindings(parameters)),
+			};
+		},
+	};
+}
+
+function toBindings(parameters: ReadonlyArray<unknown>): SqliteBinding[] {
+	return parameters.map((value) => {
+		if (value === null || typeof value === "string" || typeof value === "number") {
+			return value;
+		}
+		if (typeof value === "bigint") return value;
+		if (typeof value === "boolean") return value ? 1 : 0;
+		if (value === undefined) return null;
+		if (value instanceof Uint8Array) return value;
+		throw new TypeError(`Cannot bind ${Object.prototype.toString.call(value)} to SQLite`);
+	});
+}

package/src/db/postgres-migrations.ts

@@ -0,0 +1,59 @@
+import { createDirectMigrationExecutor } from "../migrations/direct-executor.js";
+import type { MigrationExecutor, MigrationExecutorFactoryContext } from "../migrations/protocol.js";
+import { createMigrationTarget, requireMigrationEnvironment } from "../migrations/target.js";
+import { createDialect } from "./postgres.js";
+
+export interface PostgresMigrationManifestConfig {
+	connectionStringEnv: string;
+}
+
+interface PostgresTargetIdentity {
+	host: string;
+	port: string;
+	database: string;
+}
+
+function parseTargetIdentity(connectionString: string): PostgresTargetIdentity {
+	let parsed: URL;
+	try {
+		parsed = new URL(connectionString);
+	} catch {
+		throw new Error("PostgreSQL migration connection string is invalid.");
+	}
+	if (parsed.protocol !== "postgres:" && parsed.protocol !== "postgresql:") {
+		throw new Error("PostgreSQL migration connection string is invalid.");
+	}
+	const database = parsed.pathname.slice(1);
+	if (!parsed.hostname || !database) {
+		throw new Error("PostgreSQL migration connection string must identify a host and database.");
+	}
+	return {
+		host: parsed.hostname,
+		port: parsed.port || "5432",
+		database,
+	};
+}
+
+export async function createMigrationExecutor(
+	manifestConfig: PostgresMigrationManifestConfig,
+	context: MigrationExecutorFactoryContext,
+): Promise<MigrationExecutor> {
+	const connectionStringEnv =
+		context.overrides?.databaseUrlEnv ?? manifestConfig.connectionStringEnv;
+	const connectionString = requireMigrationEnvironment(connectionStringEnv, context.env);
+	const identity = parseTargetIdentity(connectionString);
+	const label = `${identity.host}:${identity.port}/${identity.database}`;
+	const target = await createMigrationTarget("postgres", label, [
+		identity.host,
+		identity.port,
+		identity.database,
+	]);
+	return createDirectMigrationExecutor({
+		target,
+		createDialect: () =>
+			createDialect({
+				connectionString,
+				pool: { min: 0, max: 1 },
+			}),
+	});
+}

package/src/db/sqlite-migrations.ts

@@ -0,0 +1,37 @@
+import { isAbsolute, resolve } from "node:path";
+
+import { createDirectMigrationExecutor } from "../migrations/direct-executor.js";
+import type { MigrationExecutor, MigrationExecutorFactoryContext } from "../migrations/protocol.js";
+import { createMigrationTarget } from "../migrations/target.js";
+import { createDialect } from "./sqlite.js";
+
+export interface SqliteMigrationManifestConfig {
+	url: string;
+}
+
+function resolveDatabasePath(
+	manifestConfig: SqliteMigrationManifestConfig,
+	context: MigrationExecutorFactoryContext,
+): string {
+	const configuredUrl = context.overrides?.database ?? manifestConfig.url;
+	if (typeof configuredUrl !== "string" || configuredUrl.length === 0) {
+		throw new Error("SQLite migration database path is missing.");
+	}
+	const path = configuredUrl.startsWith("file:") ? configuredUrl.slice(5) : configuredUrl;
+	if (path.length === 0) {
+		throw new Error("SQLite migration database path is missing.");
+	}
+	return isAbsolute(path) ? resolve(path) : resolve(context.projectRoot, path);
+}
+
+export async function createMigrationExecutor(
+	manifestConfig: SqliteMigrationManifestConfig,
+	context: MigrationExecutorFactoryContext,
+): Promise<MigrationExecutor> {
+	const databasePath = resolveDatabasePath(manifestConfig, context);
+	const target = await createMigrationTarget("sqlite", databasePath, [databasePath]);
+	return createDirectMigrationExecutor({
+		target,
+		createDialect: () => createDialect({ url: databasePath }),
+	});
+}

package/src/db/sqlite.ts

@@ -1,14 +1,14 @@
 /**
  * SQLite runtime adapter
  *
- * Creates a Kysely dialect for better-sqlite3.
+ * Creates a Kysely dialect for Node's built-in SQLite driver.
  * Loaded at runtime via virtual module.
  */
 
-import BetterSqlite3 from "better-sqlite3";
 import { type Dialect, SqliteDialect } from "kysely";
 
 import type { SqliteConfig } from "./adapters.js";
+import { openNodeSqliteDatabase } from "./node-sqlite-compat.js";
 
 /**
  * Create a SQLite dialect from config
@@ -18,7 +18,7 @@ export function createDialect(config: SqliteConfig): Dialect {
 	const url = config.url;
 	const filePath = url.startsWith("file:") ? url.slice(5) : url;
 
-	const database = new BetterSqlite3(filePath);
+	const database = openNodeSqliteDatabase(filePath);
 
 	return new SqliteDialect({ database });
 }