duckfn-docs-kit 0.1.0

package/src/sql/runtime.ts

@@ -0,0 +1,348 @@
+import type * as DuckdbWasm from '@duckdb/duckdb-wasm';
+import {
+  DFK_SQL_RUNTIME_TAG_ID,
+  EXTENSION_NAME_PATTERN,
+  REPOSITORY_KEYWORDS,
+  REPOSITORY_URL_PATTERN,
+  extensionBaseName,
+  isAbsoluteHttpUrl,
+  normalizePreloadEntry,
+  parseSiteRuntimeConfig,
+  type PreloadEntry,
+  type SiteRuntimeConfig,
+} from './runtimeConfig';
+
+/**
+ * The browser-side DuckDB-Wasm runtime: one instance per docs-site frontend
+ * runtime (module-level singleton), *not* persisted across page loads.
+ *
+ * Design points:
+ *
+ * - `@duckdb/duckdb-wasm` is only ever reached through a dynamic `import()`,
+ *   so Docusaurus' Node prerender pass and the initial page load never touch
+ *   it. The wasm binary and the worker script come from the official jsDelivr
+ *   CDN (`getJsDelivrBundles` + `selectBundle`), which sidesteps any webpack
+ *   `asyncWebAssembly` / worker configuration on the consuming site.
+ *   `selectBundle` falls back to a non-`SharedArrayBuffer` bundle when the
+ *   page is not crossOrigin-isolated (GitHub Pages), so it works everywhere.
+ * - `init()` is idempotent and retryable: a failed init leaves `state` at
+ *   `'error'` and clears the memoised promise, so a later Run click can try
+ *   again.
+ * - `execute()` hands the whole string to DuckDB. Multi-statement queries
+ *   return the result of the **last** statement, which is exactly the
+ *   documented behaviour for runnable blocks.
+ * - Extensions get into the shared instance two ways, both through the same
+ *   memoised loader: the **site preload list** (the ordered `preload` array of
+ *   the JSON `<script>` tag the build-time plugin injects, loaded right after
+ *   `connect()` so a block can rely on the extension without naming it), and
+ *   the **per-block `extensions` config** loaded on demand by
+ *   {@link DuckDBRuntime.loadExtension}. Note that on WebAssembly `INSTALL` is
+ *   a no-op (there is no persistent storage to install *into*): it only
+ *   records where a later `LOAD` fetches a name from. A load by name fetches
+ *   `<repository>/duckdb-wasm/<revision>/<platform>/<name>.duckdb_extension.wasm`
+ *   and verifies the signature; a `{url}` preload fetches exactly that URL
+ *   (which is why the URL must be absolute — the worker runs from a blob URL
+ *   and cannot resolve relative paths). Either way, the text before the first
+ *   dot of the file name is the entry symbol DuckDB looks up, so a release
+ *   asset like `duckfn-wasm_eh.duckdb_extension.wasm` has to be renamed to
+ *   `duckfn.duckdb_extension.wasm` on the way in (enforced by validation).
+ * - Extension names, repositories and URLs are **validated, not escaped** (see
+ *   `sql/runtimeConfig`): `LOAD` cannot take them as parameters.
+ * - `allowUnsignedExtensions` is opt-in and per-instance: it is a database
+ *   setting fixed by `open()`, so it has to be known before the first
+ *   `connect()`. The site-wide value (from the injected config) and the first
+ *   caller's are merged by whichever `init()` actually creates the instance.
+ */
+
+export type RuntimeState = 'idle' | 'loading' | 'ready' | 'error';
+
+/**
+ * Options for {@link DuckDBRuntime.init}. They are merged with the site-wide
+ * injected config, and only read by the caller that actually creates the
+ * instance: `allowUnsignedExtensions` is fixed at `open()` time and later
+ * callers cannot retune a database that already exists.
+ */
+export interface RuntimeOptions {
+  /** Let `LOAD` accept an extension whose signature does not verify. */
+  allowUnsignedExtensions?: boolean;
+}
+
+/** Options for {@link DuckDBRuntime.loadExtension}. */
+export interface LoadExtensionOptions {
+  /** `community`, `core` or a repository URL, instead of the official default. */
+  repository?: string;
+}
+
+/** A normalised query result: column names plus row objects keyed by them. */
+export interface QueryResult {
+  columns: string[];
+  rows: Record<string, unknown>[];
+  /** Set when the statement failed; `columns`/`rows` are then empty. */
+  error?: string;
+}
+
+let instance: DuckDBRuntime | null = null;
+
+export class DuckDBRuntime {
+  /** The per-frontend-runtime singleton; shared by every `<dfk-sql>` block. */
+  static getInstance(): DuckDBRuntime {
+    instance ??= new DuckDBRuntime();
+    return instance;
+  }
+
+  #state: RuntimeState = 'idle';
+  #message = '';
+  #init: Promise<void> | null = null;
+  #db: DuckdbWasm.AsyncDuckDB | null = null;
+  #conn: DuckdbWasm.AsyncDuckDBConnection | null = null;
+  #allowUnsigned = false;
+  /** The injected site config; read (and validated) once on first init. */
+  #site: SiteRuntimeConfig | null = null;
+  /** Loaded / in-flight extensions, keyed by repository + name, or by URL. */
+  #loads = new Map<string, Promise<void>>();
+
+  get state(): RuntimeState {
+    return this.#state;
+  }
+
+  /** The last init failure's message, for the UI to display. */
+  get message(): string {
+    return this.#message;
+  }
+
+  /**
+   * Creates the database in the background (first Run click triggers it; a
+   * consuming site may also call it early to warm the instance). Concurrent
+   * callers share one promise, and it only resolves once the site's preloads
+   * are loaded too.
+   *
+   * Options and the injected site config are only read by the caller that
+   * actually creates the instance: `allowUnsignedExtensions` is fixed at
+   * `open()` time, and later callers cannot retune a database that already
+   * exists. A malformed injected config fails here, before any download.
+   */
+  init(options: RuntimeOptions = {}): Promise<void> {
+    if (options.allowUnsignedExtensions) {
+      this.#allowUnsigned = true;
+    }
+    if (this.#state === 'ready') {
+      return Promise.resolve();
+    }
+    if (this.#init) {
+      return this.#init;
+    }
+    const site = this.#siteConfig();
+    if (site.allowUnsignedExtensions) {
+      this.#allowUnsigned = true;
+    }
+    this.#state = 'loading';
+    this.#init = this.#create(site.preload).catch((error: unknown) => {
+      this.#state = 'error';
+      this.#message = errorMessage(error);
+      // Drop the memoised promise so the next click retries from scratch.
+      this.#init = null;
+      throw error;
+    });
+    return this.#init;
+  }
+
+  /** The injected config, validated once; a missing tag means "no preloads". */
+  #siteConfig(): SiteRuntimeConfig {
+    this.#site ??= readSiteRuntimeConfig();
+    return this.#site;
+  }
+
+  async #create(preload: readonly PreloadEntry[]): Promise<void> {
+    const duckdb = await import('@duckdb/duckdb-wasm');
+    const bundle = await duckdb.selectBundle(duckdb.getJsDelivrBundles());
+    if (!bundle.mainWorker) {
+      throw new Error('The selected DuckDB-Wasm bundle has no worker script');
+    }
+
+    // Wrap the worker script in a same-origin Blob URL: the site itself is
+    // not COOP/COEP-isolated, and this keeps the CDN script same-origin-safe
+    // regardless of CORS headers.
+    const workerUrl = URL.createObjectURL(
+      new Blob([`importScripts("${bundle.mainWorker}");`], {
+        type: 'text/javascript',
+      }),
+    );
+    const worker = new Worker(workerUrl);
+    URL.revokeObjectURL(workerUrl);
+    const logger = new duckdb.ConsoleLogger();
+    this.#db = new duckdb.AsyncDuckDB(logger, worker);
+    await this.#db.instantiate(bundle.mainModule, bundle.pthreadWorker);
+    // `open()` is where database-level settings land, and it has to run before
+    // the first `connect()`. It is called unconditionally so the instance's
+    // configuration has exactly one source of truth.
+    await this.#db.open({allowUnsignedExtensions: this.#allowUnsigned});
+    this.#conn = await this.#db.connect();
+    // Site preloads run before `ready`: every block may rely on them, and the
+    // first Run click pays for all of them at once. Sequential on purpose —
+    // the list is ordered (one extension may build on another) and parallel
+    // loads would race the shared connection.
+    for (const entry of preload) {
+      await this.#loadEntry(entry);
+    }
+    this.#state = 'ready';
+    this.#message = '';
+  }
+
+  /** Runs `sql` and resolves with the (last statement's) result. */
+  async execute(sql: string): Promise<QueryResult> {
+    await this.init();
+    const conn = this.#conn;
+    if (!conn) {
+      return {columns: [], rows: [], error: this.#message || 'DuckDB unavailable'};
+    }
+    try {
+      const table = await conn.query(sql);
+      return {
+        columns: table.schema.fields.map((field) => field.name),
+        rows: table.toArray() as Record<string, unknown>[],
+      };
+    } catch (error) {
+      return {columns: [], rows: [], error: errorMessage(error)};
+    }
+  }
+
+  /**
+   * Loads one extension on demand — what a runnable block's `extensions`
+   * config ends up doing.
+   *
+   * `LOAD` is the whole mechanism on WebAssembly: it fetches the extension's
+   * `.duckdb_extension.wasm` and verifies the signature before loading it.
+   * `INSTALL … FROM` only records *where* a later `LOAD` should fetch from
+   * (there is no persistent storage to install into), which is also why it is
+   * used for a non-default `repository` instead of the global
+   * `SET custom_extension_repository` — the recorded source stays attached to
+   * this one extension.
+   *
+   * The name and repository are validated rather than escaped — `LOAD` takes
+   * an identifier, not a parameter, so anything that could terminate the
+   * statement is rejected outright. Successful loads (and in-flight ones) are
+   * memoised per repository + name; a **failure** is not, so a Run click can
+   * retry.
+   */
+  async loadExtension(name: string, options: LoadExtensionOptions = {}): Promise<void> {
+    await this.init();
+    return this.#loadEntry({name, repository: options.repository});
+  }
+
+  /**
+   * The shared loader behind site preloads and {@link loadExtension}:
+   * validates and normalises the entry, then performs it at most once. It
+   * never calls `init()` itself — preloads run from inside `#create()`, and
+   * awaiting `init()` there would deadlock on its own promise.
+   */
+  #loadEntry(entry: unknown): Promise<void> {
+    const normalized = normalizePreloadEntry(entry);
+    if (typeof normalized === 'string') {
+      return this.#memo(`\u0000${normalized}`, () => this.#loadByName(normalized));
+    }
+    if ('name' in normalized) {
+      const {name, repository} = normalized;
+      return this.#memo(`${repository ?? ''}\u0000${name}`, () =>
+        this.#loadByName(name, repository),
+      );
+    }
+    const {url} = normalized;
+    return this.#memo(`url\u0000${url}`, () => this.#loadFromUrl(url));
+  }
+
+  /** Memoises a load per key; a failure drops the entry so a retry can run. */
+  #memo(key: string, load: () => Promise<void>): Promise<void> {
+    const memoised = this.#loads.get(key);
+    if (memoised) {
+      return memoised;
+    }
+    const loading = load().catch((error: unknown) => {
+      this.#loads.delete(key);
+      throw error;
+    });
+    this.#loads.set(key, loading);
+    return loading;
+  }
+
+  async #loadByName(name: string, repository?: string): Promise<void> {
+    if (!EXTENSION_NAME_PATTERN.test(name)) {
+      throw new Error(`Not a valid extension name: ${name}`);
+    }
+    const conn = this.#requireConnection();
+    if (repository !== undefined) {
+      await conn.query(`INSTALL ${name} FROM ${repositoryClause(repository)}`);
+    }
+    await conn.query(`LOAD ${name}`);
+  }
+
+  /** Loads an extension file from the absolute URL a `{url}` entry names. */
+  async #loadFromUrl(url: string): Promise<void> {
+    const conn = this.#requireConnection();
+    await conn.query(`LOAD '${resolveExtensionUrl(url)}'`);
+  }
+
+  #requireConnection(): DuckdbWasm.AsyncDuckDBConnection {
+    const conn = this.#conn;
+    if (!conn) {
+      throw new Error(this.#message || 'DuckDB unavailable');
+    }
+    return conn;
+  }
+}
+
+/**
+ * The `FROM` clause of `INSTALL`: bare keywords stay bare, URLs are quoted so
+ * the recorded repository is exactly the given one; the URL pattern forbids
+ * quote characters from reaching the SQL literal.
+ */
+function repositoryClause(repository: string): string {
+  const keyword = repository.toLowerCase();
+  if (REPOSITORY_KEYWORDS.has(keyword)) {
+    return keyword;
+  }
+  if (!REPOSITORY_URL_PATTERN.test(repository)) {
+    throw new Error(`Not a valid extension repository: ${repository}`);
+  }
+  return `'${repository}'`;
+}
+
+/**
+ * Turns a preload `url` into the absolute URL the worker will fetch: the
+ * worker runs from a blob URL and cannot resolve relative paths, so
+ * site-relative entries (already prefixed with the site's baseUrl by the
+ * build-time plugin) are resolved against the page origin here, on the main
+ * thread.
+ */
+function resolveExtensionUrl(url: string): string {
+  const absolute = isAbsoluteHttpUrl(url) ? url : new URL(url, window.location.origin).href;
+  if (!EXTENSION_NAME_PATTERN.test(extensionBaseName(absolute))) {
+    throw new Error(
+      `An extension file must be named <extension>.duckdb_extension.wasm — the base name ` +
+        `before the first dot is the entry symbol: ${absolute}`,
+    );
+  }
+  return absolute;
+}
+
+/** Reads the JSON config the build-time plugin injects; missing means defaults. */
+function readSiteRuntimeConfig(): SiteRuntimeConfig {
+  if (typeof document === 'undefined') {
+    return {preload: []};
+  }
+  const text = document.getElementById(DFK_SQL_RUNTIME_TAG_ID)?.textContent?.trim();
+  if (!text) {
+    return {preload: []};
+  }
+  try {
+    return parseSiteRuntimeConfig(JSON.parse(text));
+  } catch (error: unknown) {
+    throw new Error(`Invalid <script id="${DFK_SQL_RUNTIME_TAG_ID}"> config: ${errorMessage(error)}`);
+  }
+}
+
+function errorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}

package/src/sql/runtimeConfig.ts

@@ -0,0 +1,249 @@
+/**
+ * The contract between the build-time plugin (`sql/extensions`) and the
+ * browser runtime (`sql/runtime`).
+ *
+ * The plugin writes one JSON `<script>` tag into every page carrying the
+ * site's runtime configuration; the runtime reads it once, when the shared
+ * DuckDB instance is first created. Tag id, entry shapes and the validators
+ * live together in this dependency-free module so the two sides cannot drift —
+ * and so the browser bundle never drags in Node code (or the Node plugin the
+ * DOM).
+ *
+ * This module must not import anything: it is bundled into both the browser
+ * and the Node entry points.
+ */
+
+/** Id of the JSON config `<script>` the build-time plugin injects per page. */
+export const DFK_SQL_RUNTIME_TAG_ID = 'dfk-sql-runtime';
+
+/** A bare SQL identifier: `LOAD` / `INSTALL` cannot be parameterised, so this is the guard. */
+export const EXTENSION_NAME_PATTERN = /^[a-z][a-z0-9_]*$/i;
+
+/** A repository URL with no character that could escape the SQL string literal. */
+export const REPOSITORY_URL_PATTERN = /^https?:\/\/[^\s'";`<>\\]+$/i;
+
+/** Bare `FROM` keywords `INSTALL` accepts instead of a repository URL. */
+export const REPOSITORY_KEYWORDS = new Set(['community', 'core']);
+
+/** An extension preloaded by name, from the official repository or another one. */
+export interface NamedPreloadEntry {
+  /** The extension name, e.g. `duckfn`. */
+  name: string;
+  /** `community`, `core` or a repository URL; omitted = the official repository. */
+  repository?: string;
+}
+
+/** A GitHub release asset the build-time plugin copies to `url` at build time. */
+export interface PreloadReleaseSource {
+  /** The GitHub repository, `owner/name`. */
+  repository: string;
+  /** The asset name on that repository's latest release, e.g. `duckfn-wasm_eh.duckdb_extension.wasm`. */
+  asset: string;
+}
+
+/** An extension preloaded from a file, served by the site itself or remotely. */
+export interface UrlPreloadEntry {
+  /**
+   * A site-relative path (`duckdb-extensions/duckfn.duckdb_extension.wasm`),
+   * resolved against the site's baseUrl and served from `static/`; or an
+   * absolute `http(s)://` URL.
+   *
+   * The base name of the last path segment — the text before its first dot —
+   * must be the extension name: on WebAssembly that text is what DuckDB turns
+   * into the `<name>_init_c_api` entry symbol, which is exactly why a release
+   * asset like `duckfn-wasm_eh.duckdb_extension.wasm` has to be renamed to
+   * `duckfn.duckdb_extension.wasm` on the way in.
+   */
+  url: string;
+  /** Fetch the file from the repository's latest GitHub release at build time. */
+  release?: PreloadReleaseSource;
+}
+
+/** One entry of the ordered site-level preload list. */
+export type PreloadEntry = string | NamedPreloadEntry | UrlPreloadEntry;
+
+/** The config the build-time plugin injects and the browser runtime reads. */
+export interface SiteRuntimeConfig {
+  /** Let `LOAD` accept extensions without a valid signature; a site-wide opt-in. */
+  allowUnsignedExtensions?: boolean;
+  /** Ordered: every entry loads, one after another, before the instance is `ready`. */
+  preload: PreloadEntry[];
+}
+
+/** `owner/name`. */
+const GITHUB_REPOSITORY_PATTERN = /^[\w.-]+\/[\w.-]+$/;
+
+/** A file name / URL safe for the injected JSON, the SQL literal and a static path. */
+const SAFE_URL_TEXT_PATTERN = /^[^\s'";`<>\\?#]+$/;
+
+/** Anything that starts like a URL scheme; only `http(s):` may follow it. */
+const URL_SCHEME_PATTERN = /^[a-z][a-z0-9+.-]*:/i;
+
+/** True for the only absolute URL form a preload may carry. */
+export function isAbsoluteHttpUrl(value: string): boolean {
+  return /^https?:\/\//i.test(value);
+}
+
+/**
+ * The entry-symbol base name of a served extension file: the text before the
+ * first dot in its last path segment. DuckDB loads a direct file by that name
+ * (`duckfn.duckdb_extension.wasm` -> `duckfn` -> `duckfn_init_c_api`), so a
+ * file still carrying a platform suffix cannot be loaded as-is.
+ */
+export function extensionBaseName(url: string): string {
+  const withoutQuery = url.split(/[?#]/, 1)[0];
+  const segment = withoutQuery.slice(withoutQuery.lastIndexOf('/') + 1);
+  const dot = segment.indexOf('.');
+  return dot === -1 ? segment : segment.slice(0, dot);
+}
+
+/**
+ * Validates and normalises one preload entry, dropping unknown keys and
+ * lower-casing repository keywords; throws with a readable message on
+ * anything that could not be turned into a safe `LOAD` / `INSTALL` statement
+ * or a static file path.
+ */
+export function normalizePreloadEntry(entry: unknown): PreloadEntry {
+  if (typeof entry === 'string') {
+    return requireExtensionName(entry, 'A preload entry');
+  }
+  if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+    throw new Error(`A preload entry must be a string, {name, repository?} or {url, release?}: ${describe(entry)}`);
+  }
+  const record = entry as Record<string, unknown>;
+  const hasName = record.name !== undefined;
+  const hasUrl = record.url !== undefined;
+  if (hasName === hasUrl) {
+    throw new Error(
+      `A preload entry needs exactly one of \`name\` (load by name) or \`url\` (load a file): ${describe(entry)}`,
+    );
+  }
+  return hasName ? normalizeNamedEntry(record) : normalizeUrlEntry(record);
+}
+
+/** Validates the injected config envelope and normalises every preload entry. */
+export function parseSiteRuntimeConfig(value: unknown): SiteRuntimeConfig {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`Expected an object: ${describe(value)}`);
+  }
+  const record = value as Record<string, unknown>;
+  requireOnlyKeys(record, ['allowUnsignedExtensions', 'preload'], 'The config');
+  const {allowUnsignedExtensions} = record;
+  if (allowUnsignedExtensions !== undefined && typeof allowUnsignedExtensions !== 'boolean') {
+    throw new Error(`\`allowUnsignedExtensions\` must be a boolean: ${describe(allowUnsignedExtensions)}`);
+  }
+  const raw = record.preload ?? [];
+  if (!Array.isArray(raw)) {
+    throw new Error(`\`preload\` must be an array: ${describe(raw)}`);
+  }
+  const preload = raw.map((entry, index) => {
+    try {
+      return normalizePreloadEntry(entry);
+    } catch (error) {
+      throw new Error(`preload[${index}]: ${errorMessage(error)}`);
+    }
+  });
+  return allowUnsignedExtensions === undefined ? {preload} : {allowUnsignedExtensions, preload};
+}
+
+function normalizeNamedEntry(record: Record<string, unknown>): NamedPreloadEntry {
+  requireOnlyKeys(record, ['name', 'repository'], 'A name preload entry');
+  const name = requireExtensionName(record.name, '`name`');
+  const {repository} = record;
+  if (repository === undefined) {
+    return {name};
+  }
+  if (typeof repository === 'string') {
+    const keyword = repository.toLowerCase();
+    if (REPOSITORY_KEYWORDS.has(keyword)) {
+      return {name, repository: keyword};
+    }
+    if (REPOSITORY_URL_PATTERN.test(repository)) {
+      return {name, repository};
+    }
+  }
+  throw new Error(`\`repository\` must be 'community', 'core' or an http(s) URL without quotes: ${describe(repository)}`);
+}
+
+function normalizeUrlEntry(record: Record<string, unknown>): UrlPreloadEntry {
+  requireOnlyKeys(record, ['url', 'release'], 'A url preload entry');
+  const rawUrl = record.url;
+  if (typeof rawUrl !== 'string' || !SAFE_URL_TEXT_PATTERN.test(rawUrl)) {
+    throw new Error(`\`url\` must be a file path or http(s) URL without quotes, whitespace or backslashes: ${describe(rawUrl)}`);
+  }
+  const absolute = isAbsoluteHttpUrl(rawUrl);
+  if (!absolute && URL_SCHEME_PATTERN.test(rawUrl)) {
+    throw new Error(`\`url\` must be a site-relative path or an http(s) URL: ${describe(rawUrl)}`);
+  }
+  const url = absolute ? rawUrl : normalizeSitePath(rawUrl);
+  if (!EXTENSION_NAME_PATTERN.test(extensionBaseName(url))) {
+    throw new Error(
+      `The last path segment of \`url\` must start with the extension name before its first dot ` +
+        `(that base names the entry symbol, e.g. duckfn.duckdb_extension.wasm): ${url}`,
+    );
+  }
+  const {release} = record;
+  if (release === undefined) {
+    return {url};
+  }
+  if (absolute) {
+    throw new Error(`\`release\` copies the asset into the site's static directory, so \`url\` has to be site-relative: ${url}`);
+  }
+  return {url, release: normalizeReleaseSource(release)};
+}
+
+/** Strips the leading slash and rejects anything that cannot join a baseUrl safely. */
+function normalizeSitePath(value: string): string {
+  if (value.startsWith('//')) {
+    throw new Error(`Protocol-relative URLs are not supported: ${value}`);
+  }
+  const path = value.replace(/^\/+/, '');
+  const segments = path.split('/');
+  if (path === '' || segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+    throw new Error(`\`url\` must be a plain site-relative file path: ${value}`);
+  }
+  return path;
+}
+
+function normalizeReleaseSource(value: unknown): PreloadReleaseSource {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`\`release\` must be {repository, asset}: ${describe(value)}`);
+  }
+  const record = value as Record<string, unknown>;
+  requireOnlyKeys(record, ['repository', 'asset'], '`release`');
+  const {repository, asset} = record;
+  if (typeof repository !== 'string' || !GITHUB_REPOSITORY_PATTERN.test(repository)) {
+    throw new Error(`\`release.repository\` must look like 'owner/name': ${describe(repository)}`);
+  }
+  if (typeof asset !== 'string' || !SAFE_URL_TEXT_PATTERN.test(asset) || asset.includes('/')) {
+    throw new Error(`\`release.asset\` is the release asset's file name (no slashes): ${describe(asset)}`);
+  }
+  return {repository, asset};
+}
+
+function requireExtensionName(value: unknown, label: string): string {
+  if (typeof value !== 'string' || !EXTENSION_NAME_PATTERN.test(value)) {
+    throw new Error(`${label} must be a bare SQL identifier ([a-z][a-z0-9_]*): ${describe(value)}`);
+  }
+  return value;
+}
+
+function requireOnlyKeys(record: Record<string, unknown>, allowed: string[], label: string): void {
+  for (const key of Object.keys(record)) {
+    if (!allowed.includes(key)) {
+      throw new Error(`${label} has an unknown key \`${key}\` (expected: ${allowed.join(' / ')})`);
+    }
+  }
+}
+
+function describe(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}