handoff-app 1.2.2-6 → 2.0.0-0

package/src/registry/checkout/tokens.ts

@@ -0,0 +1,152 @@
+/**
+ * Connected-workspace token checkout orchestration.
+ *
+ * `checkout tokens [setId]` pulls published token sets from the connected registry into this
+ * workspace: it reconstructs the canonical local `tokens.json` (splicing each set's record into the
+ * document) and restores the generated token files (CSS/SCSS/Style Dictionary/types/custom) to their
+ * standard configured output paths under `getVariablesFilePath()`. Overwriting changed local token
+ * data requires `--force` or an interactive confirmation. Available only from a connected workspace.
+ */
+
+import * as p from '@clack/prompts';
+import fs from 'fs-extra';
+import path from 'path';
+import { Types as CoreTypes } from 'handoff-core';
+import Handoff from '../../index';
+import { Logger } from '../../utils/logger';
+import { createRegistryClient, RegistryClientError } from '../client';
+import { resolvePathWithin } from '../path';
+import { isTokenSetId, mergeTokenSetsIntoDocument, type DerivedTokenSet } from '../tokens/sets';
+import type { TokenSetCheckoutPayload } from '../tokens/transfer';
+import { CheckoutError, resolveConnectionOrThrow } from './index';
+
+/** Map a registry client error to an actionable checkout message. */
+const describeFetchFailure = (error: RegistryClientError, target: string, registryUrl: string): string => {
+  switch (error.code) {
+    case 'not_found':
+      return `No token set "${target}" exists in the registry at ${registryUrl}.`;
+    case 'runtime_mode_conflict':
+      return `The registry at ${registryUrl} is not running in registry mode, so it cannot serve a checkout: ${error.message}`;
+    case 'unauthorized':
+      return `The registry rejected the access token (401). Check the configured access token matches the registry's token.`;
+    default:
+      return error.message;
+  }
+};
+
+/** Read the existing local token document, or `null` when none exists yet. */
+const readExistingDocument = (handoff: Handoff): CoreTypes.IDocumentationObject | null => {
+  const tokensFilePath = handoff.getTokensFilePath();
+  if (!fs.existsSync(tokensFilePath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(tokensFilePath, 'utf8')) as CoreTypes.IDocumentationObject;
+  } catch {
+    return null;
+  }
+};
+
+/** A generated artifact to restore, resolved to its absolute local output path. */
+interface ArtifactWrite {
+  absolutePath: string;
+  content: string;
+}
+
+/** Whether writing `content` to `absolutePath` would change (or create) the file. */
+const wouldChange = (absolutePath: string, content: string): boolean => {
+  if (!fs.existsSync(absolutePath)) {
+    return true;
+  }
+  try {
+    return fs.readFileSync(absolutePath, 'utf8') !== content;
+  } catch {
+    return true;
+  }
+};
+
+/**
+ * Checkout all published token sets, or a single set when `setId` is given. Reconstructs `tokens.json`
+ * and restores generated files; prompts before overwriting changed local files unless `--force`.
+ */
+export const checkoutTokens = async (handoff: Handoff, setId?: string): Promise<void> => {
+  if (setId && !isTokenSetId(setId)) {
+    throw new CheckoutError(`Unknown or unsafe token set id "${setId}".`);
+  }
+  const connection = resolveConnectionOrThrow(handoff);
+  const client = createRegistryClient({ baseUrl: connection.url, accessToken: connection.accessToken });
+
+  let ids: string[];
+  if (setId) {
+    ids = [setId];
+  } else {
+    const summaries = await client.listTokenSets();
+    ids = summaries.map((summary) => summary.id);
+    if (ids.length === 0) {
+      Logger.info('No token sets are published to the registry; nothing to checkout.');
+      return;
+    }
+  }
+
+  const payloads: TokenSetCheckoutPayload[] = [];
+  for (const id of ids) {
+    if (!isTokenSetId(id)) {
+      throw new CheckoutError(`Registry returned an unknown or unsafe token set id "${id}".`);
+    }
+    try {
+      payloads.push(await client.checkoutTokens(id));
+    } catch (error) {
+      if (error instanceof RegistryClientError) {
+        throw new CheckoutError(describeFetchFailure(error, id, connection.url));
+      }
+      throw error;
+    }
+  }
+
+  const existingDoc = readExistingDocument(handoff);
+  const sets: DerivedTokenSet[] = payloads.map((payload) => ({ id: payload.id, kind: payload.kind, record: payload.record }));
+  const mergedDoc = mergeTokenSetsIntoDocument(existingDoc, sets);
+  const mergedDocContent = `${JSON.stringify(mergedDoc, null, 2)}\n`;
+
+  const variablesDir = handoff.getVariablesFilePath();
+  const artifactWrites: ArtifactWrite[] = payloads.flatMap((payload) =>
+    payload.artifacts.map((artifact) => {
+      const absolutePath = resolvePathWithin(variablesDir, artifact.path);
+      if (!absolutePath) {
+        throw new CheckoutError(`Registry returned an unsafe token artifact path "${artifact.path}".`);
+      }
+      return { absolutePath, content: artifact.content };
+    })
+  );
+
+  const tokensFilePath = handoff.getTokensFilePath();
+  const changed: string[] = [];
+  if (wouldChange(tokensFilePath, mergedDocContent)) {
+    changed.push(tokensFilePath);
+  }
+  for (const write of artifactWrites) {
+    if (wouldChange(write.absolutePath, write.content)) {
+      changed.push(write.absolutePath);
+    }
+  }
+
+  const existingChanges = changed.filter((filePath) => fs.existsSync(filePath));
+  if (existingChanges.length > 0 && !handoff.force) {
+    const proceed = await p.confirm({
+      message: `Checkout will overwrite ${existingChanges.length} changed local token file(s). Continue?`,
+    });
+    if (p.isCancel(proceed) || proceed !== true) {
+      Logger.info('Token checkout cancelled; no files were written.');
+      return;
+    }
+  }
+
+  await fs.ensureDir(path.dirname(tokensFilePath));
+  await fs.writeFile(tokensFilePath, mergedDocContent);
+  for (const write of artifactWrites) {
+    await fs.ensureDir(path.dirname(write.absolutePath));
+    await fs.writeFile(write.absolutePath, write.content);
+  }
+
+  Logger.success(`Checked out ${ids.length} token set(s) into ${tokensFilePath} (${artifactWrites.length} generated file(s) restored).`);
+};

package/src/registry/client.ts

@@ -0,0 +1,234 @@
+/**
+ * Shared registry HTTP client.
+ *
+ * One client both the CLI and the app use to talk to a remote registry over its HTTP API. It owns
+ * the transfer endpoint URL shape, bearer-token auth, and the `{ data | error, meta }` envelope
+ * decoding, mapping registry error responses to an actionable {@link RegistryClientError} so callers
+ * surface a clear message instead of a raw fetch failure. Transport is the global `fetch` (Node 18+
+ * and the browser both provide it), so this module stays runtime-agnostic.
+ */
+
+import type { CheckoutPayload, TransferEntityKind, TransferPackage } from './transfer';
+import type { TokenSetCheckoutPayload, TokenSetSummary, TokenSetTransferPackage } from './tokens/transfer';
+import type { AssetCollectionCheckoutPayload, AssetCollectionSummary, AssetCollectionTransferPackage } from './assets/transfer';
+
+/** Encode a token set id for the catch-all transfer route, preserving `/` between segments. */
+const encodeSetIdPath = (id: string): string =>
+  id
+    .split('/')
+    .map((segment) => encodeURIComponent(segment))
+    .join('/');
+
+/** Standard registry response envelope. */
+export interface RegistryEnvelope<T = unknown> {
+  data?: T;
+  error?: { code: string; message: string; details?: Record<string, unknown> };
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * A failed registry request. Carries the HTTP status and (when the server returned the registry
+ * error envelope) the registry error `code`/`details`, so callers can tailor messaging.
+ */
+export class RegistryClientError extends Error {
+  status?: number;
+  code?: string;
+  details?: Record<string, unknown>;
+
+  constructor(message: string, options: { status?: number; code?: string; details?: Record<string, unknown> } = {}) {
+    super(message);
+    this.name = 'RegistryClientError';
+    this.status = options.status;
+    this.code = options.code;
+    this.details = options.details;
+  }
+}
+
+export interface RegistryClientOptions {
+  /** Remote registry base URL (may include a configured basePath). */
+  baseUrl: string;
+  /** Bearer token sent on mutating requests. */
+  accessToken: string;
+}
+
+/** HTTP operations used by connected workspace publish and checkout workflows. */
+export interface RegistryClient {
+  publish(kind: TransferEntityKind, id: string, pkg: TransferPackage): Promise<RegistryEnvelope>;
+  checkout(kind: TransferEntityKind, id: string): Promise<CheckoutPayload>;
+  listTokenSets(): Promise<TokenSetSummary[]>;
+  publishTokens(pkg: TokenSetTransferPackage): Promise<RegistryEnvelope>;
+  checkoutTokens(id: string): Promise<TokenSetCheckoutPayload>;
+  listAssetCollections(): Promise<AssetCollectionSummary[]>;
+  assetBlobHaveCheck(hashes: string[]): Promise<string[]>;
+  uploadAssetBlob(hash: string, contentType: string, bytes: Buffer): Promise<void>;
+  downloadAssetBlob(hash: string): Promise<Buffer>;
+  publishAssetManifest(pkg: AssetCollectionTransferPackage): Promise<RegistryEnvelope>;
+  checkoutAssetCollection(collection: string): Promise<AssetCollectionCheckoutPayload>;
+}
+
+/** Strip a single trailing slash so URL joining never doubles separators. */
+const trimTrailingSlash = (value: string): string => value.replace(/\/+$/, '');
+
+/**
+ * Describe a transport-level fetch failure. `fetch` reports a generic "fetch failed"; the actionable
+ * detail (ECONNREFUSED / ECONNRESET / socket closed) lives on `error.cause`, so surface it.
+ */
+const describeNetworkError = (url: string, error: unknown): string => {
+  const message = error instanceof Error ? error.message : 'network error';
+  const cause = (error as { cause?: { code?: string; message?: string } } | undefined)?.cause;
+  const detail = cause?.code || cause?.message;
+  return `Could not reach the registry at ${url}: ${message}${detail ? ` (${detail})` : ''}.`;
+};
+
+const fetchRegistry = async (url: string, init: RequestInit): Promise<Response> => {
+  try {
+    return await fetch(url, init);
+  } catch (error) {
+    throw new RegistryClientError(describeNetworkError(url, error));
+  }
+};
+
+const readEnvelope = async <T>(response: Response): Promise<RegistryEnvelope<T>> => {
+  const text = await response.text();
+  if (!text) {
+    return {};
+  }
+  try {
+    return JSON.parse(text) as RegistryEnvelope<T>;
+  } catch {
+    return {};
+  }
+};
+
+const readErrorEnvelope = async (response: Response): Promise<RegistryEnvelope> => {
+  try {
+    return await readEnvelope(response);
+  } catch {
+    return {};
+  }
+};
+
+/**
+ * Build a registry HTTP client bound to one connection. Methods reject with a
+ * {@link RegistryClientError} on transport failure, non-2xx responses, or an error envelope.
+ */
+export const createRegistryClient = ({ baseUrl, accessToken }: RegistryClientOptions): RegistryClient => {
+  const root = trimTrailingSlash(baseUrl);
+
+  const request = async <T>(method: string, path: string, body?: unknown): Promise<RegistryEnvelope<T>> => {
+    const url = `${root}${path}`;
+    const response = await fetchRegistry(url, {
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        ...(accessToken ? { Authorization: `Bearer ${accessToken}` } : {}),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const envelope = await readEnvelope<T>(response);
+
+    if (!response.ok || envelope.error) {
+      const code = envelope.error?.code;
+      const message =
+        envelope.error?.message || `Registry request failed (${response.status} ${response.statusText}).`;
+      throw new RegistryClientError(message, { status: response.status, code, details: envelope.error?.details });
+    }
+
+    return envelope;
+  };
+
+  return {
+    /** Publish (`PUT`) an entity's package to the registry transfer endpoint. */
+    publish(kind: TransferEntityKind, id: string, pkg: TransferPackage): Promise<RegistryEnvelope> {
+      return request('PUT', `/api/registry/transfer/${kind}/${encodeURIComponent(id)}`, pkg);
+    },
+    /** Checkout (`GET`) an entity's normalized record + registry-safe source files. */
+    async checkout(kind: TransferEntityKind, id: string): Promise<CheckoutPayload> {
+      const envelope = await request<CheckoutPayload>(
+        'GET',
+        `/api/registry/transfer/${kind}/${encodeURIComponent(id)}`
+      );
+      if (!envelope.data) {
+        throw new RegistryClientError(`The registry returned no data for ${kind} "${id}".`);
+      }
+      return envelope.data;
+    },
+    /** List the registry's token sets (id + kind + source hash) for skip-unchanged / bulk checkout. */
+    async listTokenSets(): Promise<TokenSetSummary[]> {
+      const envelope = await request<{ sets: TokenSetSummary[] }>('GET', '/api/registry/transfer/tokens');
+      return envelope.data?.sets ?? [];
+    },
+    /** Publish (`PUT`) one token set's package (record + generated artifacts). */
+    publishTokens(pkg: TokenSetTransferPackage): Promise<RegistryEnvelope> {
+      return request('PUT', `/api/registry/transfer/tokens/${encodeSetIdPath(pkg.id)}`, pkg);
+    },
+    /** Checkout (`GET`) one token set's record + generated artifacts. */
+    async checkoutTokens(id: string): Promise<TokenSetCheckoutPayload> {
+      const envelope = await request<TokenSetCheckoutPayload>('GET', `/api/registry/transfer/tokens/${encodeSetIdPath(id)}`);
+      if (!envelope.data) {
+        throw new RegistryClientError(`The registry returned no data for token set "${id}".`);
+      }
+      return envelope.data;
+    },
+    /** List the registry's asset collections (collection + source hash) for skip-unchanged / bulk checkout. */
+    async listAssetCollections(): Promise<AssetCollectionSummary[]> {
+      const envelope = await request<{ collections: AssetCollectionSummary[] }>('GET', '/api/registry/transfer/assets');
+      return envelope.data?.collections ?? [];
+    },
+    /** Ask which of the given content hashes the registry does not yet have (the blobs to upload). */
+    async assetBlobHaveCheck(hashes: string[]): Promise<string[]> {
+      const envelope = await request<{ missing: string[] }>('POST', '/api/registry/transfer/assets/blobs/have', { hashes });
+      return envelope.data?.missing ?? [];
+    },
+    /** Upload one content-addressed blob (binary-safe body). Idempotent: re-uploading an existing hash no-ops. */
+    async uploadAssetBlob(hash: string, contentType: string, bytes: Buffer): Promise<void> {
+      const url = `${root}/api/registry/transfer/assets/blobs/${encodeURIComponent(hash)}`;
+      // Send a Blob, not a Buffer/Uint8Array: under Next `trailingSlash: true` this PUT is
+      // 308-redirected and undici must re-send the body; a typed-array body's ArrayBuffer is detached
+      // after the first send ("slice on a detached ArrayBuffer"), but a Blob is re-readable.
+      const body = new Blob([new Uint8Array(bytes)] as unknown as BlobPart[]);
+      const response = await fetchRegistry(url, {
+        method: 'PUT',
+        headers: {
+          'Content-Type': contentType || 'application/octet-stream',
+          ...(accessToken ? { Authorization: `Bearer ${accessToken}` } : {}),
+        },
+        body,
+      });
+      if (!response.ok) {
+        let code: string | undefined;
+        let message = `Blob upload failed (${response.status} ${response.statusText}).`;
+        const envelope = await readErrorEnvelope(response);
+        code = envelope?.error?.code;
+        message = envelope?.error?.message || message;
+        throw new RegistryClientError(message, { status: response.status, code });
+      }
+    },
+    /** Download one blob's raw bytes by hash (follows any provider redirect). */
+    async downloadAssetBlob(hash: string): Promise<Buffer> {
+      const url = `${root}/api/registry/transfer/assets/blobs/${encodeURIComponent(hash)}`;
+      const response = await fetchRegistry(url, {
+        headers: { ...(accessToken ? { Authorization: `Bearer ${accessToken}` } : {}) },
+      });
+      if (!response.ok) {
+        throw new RegistryClientError(`Blob download failed for "${hash}" (${response.status} ${response.statusText}).`, {
+          status: response.status,
+        });
+      }
+      return Buffer.from(await response.arrayBuffer());
+    },
+    /** Publish (`PUT`) one asset collection's manifest (blobs must already be uploaded). */
+    publishAssetManifest(pkg: AssetCollectionTransferPackage): Promise<RegistryEnvelope> {
+      return request('PUT', `/api/registry/transfer/assets/${encodeURIComponent(pkg.collection)}`, pkg);
+    },
+    /** Checkout (`GET`) one asset collection's manifest. */
+    async checkoutAssetCollection(collection: string): Promise<AssetCollectionCheckoutPayload> {
+      const envelope = await request<AssetCollectionCheckoutPayload>('GET', `/api/registry/transfer/assets/${encodeURIComponent(collection)}`);
+      if (!envelope.data) {
+        throw new RegistryClientError(`The registry returned no data for asset collection "${collection}".`);
+      }
+      return envelope.data;
+    },
+  };
+};

package/src/registry/connection.ts

@@ -0,0 +1,50 @@
+/**
+ * Connected-workspace registry connection resolution.
+ *
+ * A connected workspace is `runtime.mode: 'workspace'` plus a `runtime.registryConnection` block
+ * pointing at a remote registry — it is not a third runtime mode. The connection is resolved from
+ * config + environment: the registry URL may be given inline or via an env-var *name*, and the
+ * access token is always read from an env-var name (never persisted as a value). This is the single
+ * source the publish (and later checkout) client reads its target + credentials from.
+ */
+
+import type { Config } from '../types/config';
+
+/** Default env-var name holding the remote registry base URL. */
+export const DEFAULT_REGISTRY_URL_ENV = 'HANDOFF_REGISTRY_URL';
+
+/** Default env-var name holding the connected-workspace access token. */
+export const DEFAULT_REGISTRY_ACCESS_TOKEN_ENV = 'HANDOFF_REGISTRY_ACCESS_TOKEN';
+
+/** Fully resolved connected-workspace registry connection. */
+export interface ResolvedRegistryConnection {
+  /** Resolved registry base URL (inline config value wins, else the named env var), or `''`. */
+  url: string;
+  /** Resolved access token value (from the named env var), or `''`. */
+  accessToken: string;
+  /** Name of the env var the URL falls back to. */
+  urlEnv: string;
+  /** Name of the env var the access token is read from. */
+  accessTokenEnv: string;
+}
+
+/**
+ * Resolve the connected-workspace registry connection from config + environment. Never throws —
+ * Callers inspect the resolved URL and access token to surface specific configuration errors.
+ */
+export const resolveRegistryConnection = (config: Config | null | undefined): ResolvedRegistryConnection => {
+  const connection = config?.runtime?.registryConnection;
+  const urlEnv = connection?.urlEnv?.trim() || DEFAULT_REGISTRY_URL_ENV;
+  const accessTokenEnv = connection?.accessTokenEnv?.trim() || DEFAULT_REGISTRY_ACCESS_TOKEN_ENV;
+
+  const inlineUrl = connection?.url?.trim();
+  const url = (inlineUrl || process.env[urlEnv]?.trim()) ?? '';
+  const accessToken = process.env[accessTokenEnv]?.trim() ?? '';
+
+  return {
+    url,
+    accessToken,
+    urlEnv,
+    accessTokenEnv,
+  };
+};

package/src/registry/db/adapter.ts

@@ -0,0 +1,74 @@
+/**
+ * Registry database adapter resolution.
+ *
+ * `runtime.registry.database.adapter` selects one of two built-in adapters shipped with the
+ * `handoff-app` package — `pg` (default) and `neon` — both targeting the Postgres dialect.
+ * `build --target registry` and `db:migrate` resolve the **same** adapter so build and migration
+ * never diverge. Connection credentials are referenced by environment-variable name only and
+ * resolved to a value at runtime; the value is never stored in config.
+ */
+
+import type { Config } from '../../types/config';
+
+/** Built-in registry database adapter. Both ship with the package and target Postgres. */
+export type RegistryDatabaseAdapter = 'pg' | 'neon';
+
+/** Default env-var name holding the database connection string. */
+export const DEFAULT_DATABASE_URL_ENV = 'DATABASE_URL';
+
+/** Default env-var name holding the registry management API bearer token. */
+export const DEFAULT_REGISTRY_API_TOKEN_ENV = 'HANDOFF_REGISTRY_API_TOKEN';
+
+/** Default registry database adapter when none is configured. */
+export const DEFAULT_REGISTRY_ADAPTER: RegistryDatabaseAdapter = 'pg';
+
+/** Fully resolved registry database connection inputs. */
+export interface ResolvedRegistryDatabase {
+  /** Selected built-in adapter. */
+  adapter: RegistryDatabaseAdapter;
+  /** Name of the env var the connection string was read from. */
+  databaseUrlEnv: string;
+  /** Resolved connection string (never persisted in config). */
+  connectionString: string;
+}
+
+/** Resolve the env-var name holding the database URL (defaults to `DATABASE_URL`). */
+export const resolveDatabaseUrlEnv = (config: Config | null | undefined): string => {
+  const configured = config?.runtime?.registry?.databaseUrlEnv?.trim();
+  return configured || DEFAULT_DATABASE_URL_ENV;
+};
+
+/**
+ * Resolve the env-var *name* holding the registry management API bearer token (defaults to
+ * `HANDOFF_REGISTRY_API_TOKEN`). Like the database URL, only the name is ever persisted — the token
+ * value is resolved from the environment at request time and never written to config.
+ */
+export const resolveApiTokenEnv = (config: Config | null | undefined): string => {
+  const configured = config?.runtime?.registry?.apiTokenEnv?.trim();
+  return configured || DEFAULT_REGISTRY_API_TOKEN_ENV;
+};
+
+/** Resolve the configured registry adapter (defaults to `pg`). */
+export const resolveRegistryAdapter = (config: Config | null | undefined): RegistryDatabaseAdapter => {
+  return config?.runtime?.registry?.database?.adapter ?? DEFAULT_REGISTRY_ADAPTER;
+};
+
+/**
+ * Resolve the registry database connection from config + environment. Throws an actionable error
+ * when the configured env var is unset so the CLI can surface a clear "missing database URL"
+ * message instead of failing deep inside the driver.
+ */
+export const resolveRegistryDatabase = (config: Config | null | undefined): ResolvedRegistryDatabase => {
+  const adapter = resolveRegistryAdapter(config);
+  const databaseUrlEnv = resolveDatabaseUrlEnv(config);
+  const connectionString = process.env[databaseUrlEnv]?.trim();
+
+  if (!connectionString) {
+    throw new Error(
+      `Registry database URL is not configured. Set the "${databaseUrlEnv}" environment variable to a ` +
+        `PostgreSQL connection string (or change "runtime.registry.databaseUrlEnv" to point at the env var you use).`
+    );
+  }
+
+  return { adapter, databaseUrlEnv, connectionString };
+};

package/src/registry/db/client.ts

@@ -0,0 +1,88 @@
+/**
+ * Bundled Drizzle client + migrator for the registry database.
+ *
+ * The package ships both built-in adapters (`pg` and `neon`) and the Drizzle client/migrator, so a
+ * consuming project needs no global Drizzle install or separate CLI. Driver modules are loaded
+ * lazily (dynamic import) for the selected adapter only, so workspace dev/build never pulls the
+ * Postgres/Neon drivers into memory when the registry is not in use.
+ */
+
+import type { NeonDatabase } from 'drizzle-orm/neon-serverless';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type { RegistryDatabaseAdapter } from './adapter';
+import * as schema from './schema';
+
+/** Typed Drizzle database over the registry schema, regardless of which adapter backs it. */
+export type RegistryDatabase = NodePgDatabase<typeof schema> | NeonDatabase<typeof schema>;
+
+/** A live registry database connection plus its lifecycle operations. */
+export interface RegistryDbConnection {
+  /** Selected adapter that produced this connection. */
+  adapter: RegistryDatabaseAdapter;
+  /** Typed Drizzle database. */
+  db: RegistryDatabase;
+  /** Apply the package-owned migrations found in `migrationsFolder`. */
+  migrate(migrationsFolder: string): Promise<void>;
+  /** Close the underlying connection pool. */
+  close(): Promise<void>;
+}
+
+export interface CreateRegistryDbConnectionParams {
+  adapter: RegistryDatabaseAdapter;
+  connectionString: string;
+}
+
+/**
+ * Create a registry database connection for the resolved adapter. Both adapters target the
+ * Postgres dialect and share the same schema, so the returned connection is interchangeable for
+ * migration and (later) the registry store.
+ */
+export const createRegistryDbConnection = async ({
+  adapter,
+  connectionString,
+}: CreateRegistryDbConnectionParams): Promise<RegistryDbConnection> => {
+  if (adapter === 'neon') {
+    const { Pool, neonConfig } = await import('@neondatabase/serverless');
+    // Neon's serverless driver needs a WebSocket constructor in Node; reuse the bundled `ws`.
+    const ws = await import('ws');
+    neonConfig.webSocketConstructor = (ws as any).default ?? ws;
+    const { drizzle } = await import('drizzle-orm/neon-serverless');
+    const { migrate } = await import('drizzle-orm/neon-serverless/migrator');
+
+    const pool = new Pool({ connectionString });
+    try {
+      await pool.query('select 1');
+    } catch (error) {
+      await pool.end().catch(() => undefined);
+      throw error;
+    }
+    const db = drizzle(pool, { schema });
+
+    return {
+      adapter,
+      db,
+      migrate: (migrationsFolder: string) => migrate(db, { migrationsFolder }),
+      close: () => pool.end(),
+    };
+  }
+
+  const { Pool } = await import('pg');
+  const { drizzle } = await import('drizzle-orm/node-postgres');
+  const { migrate } = await import('drizzle-orm/node-postgres/migrator');
+
+  const pool = new Pool({ connectionString });
+  try {
+    await pool.query('select 1');
+  } catch (error) {
+    await pool.end().catch(() => undefined);
+    throw error;
+  }
+  const db = drizzle(pool, { schema });
+
+  return {
+    adapter,
+    db,
+    migrate: (migrationsFolder: string) => migrate(db, { migrationsFolder }),
+    close: () => pool.end(),
+  };
+};

package/src/registry/db/index.ts

@@ -0,0 +1,35 @@
+export {
+  buildMetadata,
+  componentFiles,
+  components,
+  docsArtifacts,
+  patternFiles,
+  patterns,
+  registrySchema,
+  type BuildMetadataEntityKind,
+  type DocsArtifactEntityKind,
+  type RegistryReviewMetadata,
+} from './schema';
+
+export type { ArtifactBuildStatus as RegistryBuildStatus } from '../../artifacts/types';
+
+export {
+  DEFAULT_DATABASE_URL_ENV,
+  DEFAULT_REGISTRY_ADAPTER,
+  DEFAULT_REGISTRY_API_TOKEN_ENV,
+  resolveApiTokenEnv,
+  resolveDatabaseUrlEnv,
+  resolveRegistryAdapter,
+  resolveRegistryDatabase,
+  type RegistryDatabaseAdapter,
+  type ResolvedRegistryDatabase,
+} from './adapter';
+
+export {
+  createRegistryDbConnection,
+  type CreateRegistryDbConnectionParams,
+  type RegistryDatabase,
+  type RegistryDbConnection,
+} from './client';
+
+export { getMigrationsFolder, runRegistryMigrations } from './migrate';