@q32/core 0.1.4 → 0.1.6

package/src/http.ts

@@ -0,0 +1,78 @@
+export type JsonResponseInit = ResponseInit & {
+  pretty?: boolean;
+};
+
+export type FetchLike = typeof fetch;
+
+export const defaultFetch: FetchLike = (input, init) => fetch(input, init);
+
+export class HttpError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+    public readonly code = "http_error",
+  ) {
+    super(message);
+    this.name = "HttpError";
+  }
+}
+
+export function jsonResponse(value: unknown, init: JsonResponseInit = {}): Response {
+  const headers = new Headers(init.headers);
+  if (!headers.has("content-type")) headers.set("content-type", "application/json; charset=utf-8");
+  return new Response(JSON.stringify(value, null, init.pretty ? 2 : 0), {
+    ...init,
+    headers,
+  });
+}
+
+export function errorResponse(error: unknown, fallbackStatus = 500): Response {
+  if (error instanceof HttpError) {
+    return jsonResponse({ error: { code: error.code, message: error.message } }, { status: error.status });
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return jsonResponse({ error: { code: "internal_error", message } }, { status: fallbackStatus });
+}
+
+export async function readJson<T = unknown>(request: Request): Promise<T> {
+  const contentType = request.headers.get("content-type") ?? "";
+  if (!contentType.toLowerCase().includes("application/json")) {
+    throw new HttpError(415, "Expected application/json request body.", "unsupported_media_type");
+  }
+  try {
+    return (await request.json()) as T;
+  } catch {
+    throw new HttpError(400, "Invalid JSON request body.", "invalid_json");
+  }
+}
+
+export function requireBearerToken(request: Request): string {
+  const value = request.headers.get("authorization") ?? "";
+  const match = value.match(/^Bearer\s+(.+)$/i);
+  if (!match) throw new HttpError(401, "Missing bearer token.", "missing_bearer_token");
+  return match[1];
+}
+
+export function requireAdminToken(request: Request, expected: string | undefined): void {
+  if (!expected) throw new HttpError(500, "Admin token is not configured.", "admin_token_not_configured");
+  const provided = request.headers.get("x-admin-token") ?? requireBearerToken(request);
+  if (provided !== expected) throw new HttpError(403, "Invalid admin token.", "invalid_admin_token");
+}
+
+export function absoluteUrl(appUrl: string, path: string): string {
+  return `${appUrl.replace(/\/$/, "")}${path.startsWith("/") ? path : `/${path}`}`;
+}
+
+export function escapeHtml(value: string | null | undefined): string {
+  return String(value ?? "")
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#039;");
+}
+
+export async function readResponseExcerpt(response: Response, maxLength = 800): Promise<string> {
+  const text = await response.text().catch(() => "");
+  return text.slice(0, maxLength);
+}

package/src/ids.ts

@@ -0,0 +1,55 @@
+const DEFAULT_TOKEN_BYTES = 32;
+const BASE36_ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz";
+
+export function createId(prefix: string, bytes = 12): string {
+  const cleanPrefix = prefix.trim().replace(/[^a-zA-Z0-9_-]/g, "_");
+  if (!cleanPrefix) throw new Error("ID prefix is required.");
+  return `${cleanPrefix}_${randomBase64Url(bytes)}`;
+}
+
+export function createToken(prefix = "tok", bytes = DEFAULT_TOKEN_BYTES): string {
+  return createId(prefix, bytes);
+}
+
+export function randomBase36(length: number): string {
+  const safeLength = Math.max(1, Math.floor(length));
+  const bytes = new Uint8Array(safeLength);
+  crypto.getRandomValues(bytes);
+  let value = "";
+  for (const byte of bytes) value += BASE36_ALPHABET[byte % BASE36_ALPHABET.length];
+  return value;
+}
+
+export function createBase36Id(prefix: string, length = 20): string {
+  return `${prefix}_${randomBase36(length)}`;
+}
+
+export function createBase36Token(prefix: string, length = 40): string {
+  return `${prefix}_${randomBase36(length)}`;
+}
+
+export function randomBase64Url(bytes = DEFAULT_TOKEN_BYTES): string {
+  const data = new Uint8Array(Math.max(1, Math.floor(bytes)));
+  crypto.getRandomValues(data);
+  return toBase64Url(data);
+}
+
+export function toBase64Url(input: string | Uint8Array): string {
+  const bytes = typeof input === "string" ? new TextEncoder().encode(input) : input;
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+
+export function fromBase64Url(value: string): Uint8Array {
+  const padded = value.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(value.length / 4) * 4, "=");
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+export async function sha256Hex(input: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+export * from "./api.js";
+export * from "./ai.js";
+export * from "./billing.js";
+export * from "./cloudflare.js";
+export * from "./crypto.js";
+export * from "./d1.js";
+export * from "./encoding.js";
+export * from "./email.js";
+export * from "./env.js";
+export * from "./http.js";
+export * from "./ids.js";
+export * from "./jobs.js";
+export * from "./mcp.js";
+export * from "./oauth.js";
+export * from "./ops-events.js";
+export * from "./pg.js";
+export * from "./r2-json.js";
+export * from "./rate-limit.js";
+export * from "./seo.js";
+export * from "./session.js";
+export * from "./testing.js";
+export * from "./time.js";

package/src/jobs.ts

@@ -0,0 +1,276 @@
+import type { D1DatabaseLike } from "./d1.js";
+import { parseJsonColumn, stringifyJsonColumn } from "./d1.js";
+import { createId } from "./ids.js";
+import { isFutureIso, nowIso } from "./time.js";
+
+export type JobStatus = "queued" | "running" | "succeeded" | "failed";
+
+export type JobHandlerResult<TResult = unknown> =
+  | { kind: "done"; result?: TResult | null }
+  | { kind: "requeue"; result?: TResult | null; availableAt?: string | null };
+
+export type JobRecord<TPayload = unknown, TResult = unknown> = {
+  jobId: string;
+  jobType: string;
+  status: JobStatus;
+  payload: TPayload;
+  result: TResult | null;
+  lockKey: string | null;
+  attemptCount: number;
+  maxAttempts: number;
+  availableAt: string | null;
+  startedAt: string | null;
+  completedAt: string | null;
+  lastError: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type EnqueueJobInput<TPayload = unknown> = {
+  jobType: string;
+  payload?: TPayload;
+  lockKey?: string | null;
+  maxAttempts?: number;
+  availableAt?: string | null;
+};
+
+export class D1JobStore {
+  constructor(
+    private readonly db: D1DatabaseLike,
+    private readonly options: { tableName?: string; idPrefix?: string } = {},
+  ) {}
+
+  get tableName(): string {
+    return this.options.tableName ?? "jobs";
+  }
+
+  async enqueue<TPayload = unknown>(input: EnqueueJobInput<TPayload>): Promise<JobRecord<TPayload>> {
+    const jobId = createId(this.options.idPrefix ?? "job");
+    const now = nowIso();
+    await this.db
+      .prepare(
+        `INSERT INTO ${this.tableName} (
+          job_id, job_type, status, payload_json, result_json, lock_key,
+          attempt_count, max_attempts, available_at, created_at, updated_at
+        ) VALUES (?, ?, 'queued', ?, NULL, ?, 0, ?, ?, ?, ?)`,
+      )
+      .bind(
+        jobId,
+        input.jobType,
+        stringifyJsonColumn(input.payload ?? {}),
+        input.lockKey ?? null,
+        Math.max(1, Math.floor(input.maxAttempts ?? 3)),
+        input.availableAt ?? null,
+        now,
+        now,
+      )
+      .run();
+
+    const job = await this.get<TPayload>(jobId);
+    if (!job) throw new Error(`Failed to load enqueued job: ${jobId}`);
+    return job;
+  }
+
+  async get<TPayload = unknown, TResult = unknown>(jobId: string): Promise<JobRecord<TPayload, TResult> | null> {
+    const row = await this.db
+      .prepare(
+        `SELECT
+          job_id AS jobId,
+          job_type AS jobType,
+          status,
+          payload_json AS payloadJson,
+          result_json AS resultJson,
+          lock_key AS lockKey,
+          attempt_count AS attemptCount,
+          max_attempts AS maxAttempts,
+          available_at AS availableAt,
+          started_at AS startedAt,
+          completed_at AS completedAt,
+          last_error AS lastError,
+          created_at AS createdAt,
+          updated_at AS updatedAt
+        FROM ${this.tableName}
+        WHERE job_id = ?
+        LIMIT 1`,
+      )
+      .bind(jobId)
+      .first<JobRow>();
+    return row ? rowToJob<TPayload, TResult>(row) : null;
+  }
+
+  async listQueued(limit = 25): Promise<JobRecord[]> {
+    const now = nowIso();
+    const rows = await this.db
+      .prepare(
+        `SELECT
+          job_id AS jobId, job_type AS jobType, status, payload_json AS payloadJson,
+          result_json AS resultJson, lock_key AS lockKey, attempt_count AS attemptCount,
+          max_attempts AS maxAttempts, available_at AS availableAt, started_at AS startedAt,
+          completed_at AS completedAt, last_error AS lastError, created_at AS createdAt, updated_at AS updatedAt
+        FROM ${this.tableName}
+        WHERE status = 'queued' AND (available_at IS NULL OR available_at <= ?)
+        ORDER BY created_at ASC
+        LIMIT ?`,
+      )
+      .bind(now, Math.max(1, Math.min(100, Math.floor(limit))))
+      .all<JobRow>();
+    return (rows.results ?? []).map(rowToJob);
+  }
+
+  async claim<TPayload = unknown>(jobId: string): Promise<JobRecord<TPayload> | null> {
+    const current = await this.get<TPayload>(jobId);
+    if (!current || current.status === "succeeded" || current.status === "failed") return null;
+    if (current.status === "queued" && isFutureIso(current.availableAt)) return null;
+    if (current.attemptCount >= current.maxAttempts) {
+      await this.fail(jobId, "Job exhausted all attempts.");
+      return null;
+    }
+
+    const now = nowIso();
+    const result = await this.db
+      .prepare(
+        `UPDATE ${this.tableName}
+         SET status = 'running',
+             attempt_count = attempt_count + 1,
+             started_at = COALESCE(started_at, ?),
+             updated_at = ?,
+             last_error = NULL
+         WHERE job_id = ?
+           AND status IN ('queued', 'running')
+           AND (available_at IS NULL OR available_at <= ?)`,
+      )
+      .bind(now, now, jobId, now)
+      .run();
+
+    if (!Number(result.meta.changes ?? 0)) return null;
+    return this.get<TPayload>(jobId);
+  }
+
+  async succeed<TResult = unknown>(jobId: string, result: TResult | null = null): Promise<void> {
+    const now = nowIso();
+    await this.db
+      .prepare(
+        `UPDATE ${this.tableName}
+         SET status = 'succeeded', result_json = ?, completed_at = ?, updated_at = ?
+         WHERE job_id = ?`,
+      )
+      .bind(stringifyJsonColumn(result), now, now, jobId)
+      .run();
+  }
+
+  async requeue<TResult = unknown>(jobId: string, result: TResult | null = null, availableAt: string | null = null): Promise<void> {
+    const now = nowIso();
+    await this.db
+      .prepare(
+        `UPDATE ${this.tableName}
+         SET status = 'queued', result_json = ?, available_at = ?, updated_at = ?
+         WHERE job_id = ?`,
+      )
+      .bind(stringifyJsonColumn(result), availableAt, now, jobId)
+      .run();
+  }
+
+  async fail(jobId: string, error: unknown): Promise<void> {
+    const now = nowIso();
+    const message = error instanceof Error ? error.message : String(error);
+    await this.db
+      .prepare(
+        `UPDATE ${this.tableName}
+         SET status = 'failed', last_error = ?, completed_at = ?, updated_at = ?
+         WHERE job_id = ?`,
+      )
+      .bind(message, now, now, jobId)
+      .run();
+  }
+
+  async run<TPayload = unknown, TResult = unknown>(
+    jobId: string,
+    handler: (job: JobRecord<TPayload, TResult>) => Promise<JobHandlerResult<TResult> | TResult | void>,
+  ): Promise<JobHandlerResult<TResult>> {
+    const job = await this.claim<TPayload>(jobId);
+    if (!job) return { kind: "done", result: null };
+
+    try {
+      const output = await handler(job as JobRecord<TPayload, TResult>);
+      const normalized = normalizeJobResult<TResult>(output);
+      if (normalized.kind === "requeue") {
+        await this.requeue(jobId, normalized.result ?? null, normalized.availableAt ?? null);
+      } else {
+        await this.succeed(jobId, normalized.result ?? null);
+      }
+      return normalized;
+    } catch (error) {
+      const latest = await this.get(jobId);
+      if (latest && latest.attemptCount < latest.maxAttempts) {
+        await this.requeue(jobId, { retryError: error instanceof Error ? error.message : String(error) });
+        return { kind: "requeue", result: null };
+      }
+      await this.fail(jobId, error);
+      throw error;
+    }
+  }
+}
+
+export const D1_JOBS_SCHEMA = `
+CREATE TABLE IF NOT EXISTS jobs (
+  job_id TEXT PRIMARY KEY,
+  job_type TEXT NOT NULL,
+  status TEXT NOT NULL,
+  payload_json TEXT NOT NULL DEFAULT '{}',
+  result_json TEXT,
+  lock_key TEXT,
+  attempt_count INTEGER NOT NULL DEFAULT 0,
+  max_attempts INTEGER NOT NULL DEFAULT 3,
+  available_at TEXT,
+  started_at TEXT,
+  completed_at TEXT,
+  last_error TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS jobs_status_available_idx ON jobs(status, available_at, created_at);
+CREATE INDEX IF NOT EXISTS jobs_type_status_idx ON jobs(job_type, status, created_at);
+CREATE UNIQUE INDEX IF NOT EXISTS jobs_active_lock_key_idx ON jobs(lock_key)
+  WHERE lock_key IS NOT NULL AND status IN ('queued', 'running');
+`;
+
+type JobRow = {
+  jobId: string;
+  jobType: string;
+  status: JobStatus;
+  payloadJson: string;
+  resultJson: string | null;
+  lockKey: string | null;
+  attemptCount: number;
+  maxAttempts: number;
+  availableAt: string | null;
+  startedAt: string | null;
+  completedAt: string | null;
+  lastError: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+function rowToJob<TPayload = unknown, TResult = unknown>(row: JobRow): JobRecord<TPayload, TResult> {
+  return {
+    jobId: row.jobId,
+    jobType: row.jobType,
+    status: row.status,
+    payload: parseJsonColumn<TPayload>(row.payloadJson, {} as TPayload),
+    result: parseJsonColumn<TResult | null>(row.resultJson, null),
+    lockKey: row.lockKey,
+    attemptCount: Number(row.attemptCount),
+    maxAttempts: Number(row.maxAttempts),
+    availableAt: row.availableAt,
+    startedAt: row.startedAt,
+    completedAt: row.completedAt,
+    lastError: row.lastError,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+function normalizeJobResult<TResult>(output: JobHandlerResult<TResult> | TResult | void): JobHandlerResult<TResult> {
+  if (output && typeof output === "object" && "kind" in output) return output as JobHandlerResult<TResult>;
+  return { kind: "done", result: (output ?? null) as TResult | null };
+}

package/src/mcp.ts

@@ -0,0 +1,52 @@
+import type { ApiOperationRegistry } from "./api.js";
+
+export type McpToolDescriptor = {
+  name: string;
+  title?: string;
+  description?: string;
+  inputSchema: Record<string, unknown>;
+  annotations?: Record<string, unknown>;
+};
+
+export function mcpToolsFromApiRegistry<TContext>(
+  registry: ApiOperationRegistry<TContext>,
+  options: { includeScopes?: boolean } = {},
+): McpToolDescriptor[] {
+  return Object.values(registry).map((operation) => ({
+    name: operation.name,
+    title: operation.title,
+    description: operation.description,
+    inputSchema: jsonSchemaPlaceholder(operation.path),
+    annotations: options.includeScopes && operation.scope ? { scope: operation.scope } : undefined,
+  }));
+}
+
+export function mcpWellKnownServerMetadata(options: {
+  name: string;
+  url: string;
+  description?: string;
+  authorizationServers?: string[];
+}): Record<string, unknown> {
+  return {
+    name: options.name,
+    description: options.description,
+    transport: "http",
+    url: options.url,
+    authorization_servers: options.authorizationServers,
+  };
+}
+
+function jsonSchemaPlaceholder(path: string): Record<string, unknown> {
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+  for (const match of path.matchAll(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g)) {
+    properties[match[1]] = { type: "string" };
+    required.push(match[1]);
+  }
+  return {
+    type: "object",
+    properties,
+    required,
+    additionalProperties: true,
+  };
+}

package/src/oauth.ts

@@ -0,0 +1,44 @@
+export type OAuthMetadataOptions = {
+  issuer: string;
+  authorizationPath?: string;
+  tokenPath?: string;
+  registrationPath?: string;
+  revocationPath?: string;
+  scopes?: string[];
+  resourceDocumentation?: string;
+};
+
+export function oauthAuthorizationServerMetadata(options: OAuthMetadataOptions): Record<string, unknown> {
+  const issuer = options.issuer.replace(/\/$/, "");
+  return {
+    issuer,
+    authorization_endpoint: `${issuer}${options.authorizationPath ?? "/authorize"}`,
+    token_endpoint: `${issuer}${options.tokenPath ?? "/token"}`,
+    registration_endpoint: `${issuer}${options.registrationPath ?? "/register"}`,
+    revocation_endpoint: `${issuer}${options.revocationPath ?? "/revoke"}`,
+    response_types_supported: ["code"],
+    grant_types_supported: ["authorization_code", "refresh_token"],
+    token_endpoint_auth_methods_supported: ["client_secret_post", "none"],
+    code_challenge_methods_supported: ["S256"],
+    scopes_supported: options.scopes ?? ["mcp:read", "mcp:write"],
+    resource_documentation: options.resourceDocumentation ?? `${issuer}/mcp`,
+  };
+}
+
+export function oauthProtectedResourceMetadata(resource: string, authorizationServer: string, scopes?: string[]): Record<string, unknown> {
+  return {
+    resource,
+    authorization_servers: [authorizationServer.replace(/\/$/, "")],
+    scopes_supported: scopes ?? ["mcp:read", "mcp:write"],
+    bearer_methods_supported: ["header"],
+  };
+}
+
+export function mcpServerCard(options: { name: string; description?: string; url: string }): Record<string, unknown> {
+  return {
+    name: options.name,
+    description: options.description,
+    url: options.url,
+    transport: "http",
+  };
+}

package/src/ops-events.ts

@@ -0,0 +1,75 @@
+import type { D1DatabaseLike } from "./d1.js";
+import { stringifyJsonColumn } from "./d1.js";
+
+export type OpsSeverity = "debug" | "info" | "warn" | "error";
+
+export type OpsEventInput = {
+  eventType: string;
+  severity?: OpsSeverity;
+  source: string;
+  fingerprint?: string | null;
+  payload?: unknown;
+};
+
+export type OpsEventRow = {
+  id: number;
+  event_type: string;
+  severity: OpsSeverity;
+  source: string;
+  fingerprint: string | null;
+  payload_json: string;
+  created_at: string;
+};
+
+export async function recordOpsEvent(db: D1DatabaseLike, input: OpsEventInput): Promise<void> {
+  await db
+    .prepare(
+      `INSERT INTO ops_events (event_type, severity, source, fingerprint, payload_json)
+       VALUES (?, ?, ?, ?, ?)`,
+    )
+    .bind(input.eventType, input.severity ?? "info", input.source, input.fingerprint ?? null, stringifyJsonColumn(input.payload ?? {}))
+    .run();
+}
+
+export async function listRecentOpsEvents(
+  db: D1DatabaseLike,
+  options: { limit?: number; eventType?: string | null } = {},
+): Promise<OpsEventRow[]> {
+  const limit = Math.max(1, Math.min(200, Math.floor(options.limit ?? 25)));
+  const eventType = options.eventType?.trim();
+  const statement = eventType
+    ? db
+        .prepare(
+          `SELECT id, event_type, severity, source, fingerprint, payload_json, created_at
+           FROM ops_events
+           WHERE event_type = ?
+           ORDER BY created_at DESC, id DESC
+           LIMIT ?`,
+        )
+        .bind(eventType, limit)
+    : db
+        .prepare(
+          `SELECT id, event_type, severity, source, fingerprint, payload_json, created_at
+           FROM ops_events
+           ORDER BY created_at DESC, id DESC
+           LIMIT ?`,
+        )
+        .bind(limit);
+  const rows = await statement.all<OpsEventRow>();
+  return rows.results ?? [];
+}
+
+export const D1_OPS_EVENTS_SCHEMA = `
+CREATE TABLE IF NOT EXISTS ops_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  event_type TEXT NOT NULL,
+  severity TEXT NOT NULL DEFAULT 'info',
+  source TEXT NOT NULL,
+  fingerprint TEXT,
+  payload_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX IF NOT EXISTS ops_events_created_at_idx ON ops_events(created_at DESC);
+CREATE INDEX IF NOT EXISTS ops_events_type_created_idx ON ops_events(event_type, created_at DESC);
+CREATE INDEX IF NOT EXISTS ops_events_severity_created_idx ON ops_events(severity, created_at DESC);
+`;

package/src/pg.ts

@@ -0,0 +1,81 @@
+export interface PgQueryResult<Row = unknown> {
+  rows: Row[];
+  rowCount: number | null;
+}
+
+export interface PgClientLike {
+  query<Row = unknown>(text: string, values?: readonly unknown[]): Promise<PgQueryResult<Row>>;
+}
+
+export interface PgPoolLike extends PgClientLike {
+  connect(): Promise<PgClientLike & { release(): void }>;
+}
+
+export type PgMigration = {
+  id: string;
+  sql: string;
+};
+
+export type PgMigrationResult = {
+  applied: string[];
+  skipped: string[];
+};
+
+export async function ensurePgMigrationsTable(client: PgClientLike, tableName = "schema_migrations"): Promise<void> {
+  assertSafeIdentifier(tableName);
+  await client.query(`
+    CREATE TABLE IF NOT EXISTS ${tableName} (
+      id TEXT PRIMARY KEY,
+      applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+    )
+  `);
+}
+
+export async function applyPgMigrations(
+  pool: PgPoolLike,
+  migrations: PgMigration[],
+  options: { tableName?: string; lockKey?: number } = {},
+): Promise<PgMigrationResult> {
+  const tableName = options.tableName ?? "schema_migrations";
+  assertSafeIdentifier(tableName);
+  const client = await pool.connect();
+  const applied: string[] = [];
+  const skipped: string[] = [];
+
+  try {
+    await client.query("BEGIN");
+    if (options.lockKey !== undefined) {
+      await client.query("SELECT pg_advisory_xact_lock($1)", [options.lockKey]);
+    }
+    await ensurePgMigrationsTable(client, tableName);
+
+    for (const migration of migrations) {
+      const existing = await client.query<{ id: string }>(`SELECT id FROM ${tableName} WHERE id = $1 LIMIT 1`, [migration.id]);
+      if (existing.rows[0]) {
+        skipped.push(migration.id);
+        continue;
+      }
+      await client.query(migration.sql);
+      await client.query(`INSERT INTO ${tableName} (id) VALUES ($1)`, [migration.id]);
+      applied.push(migration.id);
+    }
+
+    await client.query("COMMIT");
+    return { applied, skipped };
+  } catch (error) {
+    await client.query("ROLLBACK");
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+
+export function pgJson<T>(value: T): string {
+  return JSON.stringify(value ?? null);
+}
+
+function assertSafeIdentifier(value: string): void {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+    throw new Error(`Unsafe SQL identifier: ${value}`);
+  }
+}