handoff-app 2.0.0-0 → 2.0.0-2

package/src/cli/create.ts

@@ -23,6 +23,8 @@ interface CreateOptions {
   figmaAccessToken: string;
   languagePreference: 'typescript' | 'javascript';
   includeExamples: boolean;
+  includeVercel: boolean;
+  vercelBuildCommand: string;
   [key: string]: string | boolean; // Allow dynamic access for template replacement
 }
 
@@ -67,7 +69,8 @@ interface TemplateConfig {
  */
 const getMandatoryTemplates = (
   includeExamples: boolean,
-  languagePreference: 'typescript' | 'javascript'
+  languagePreference: 'typescript' | 'javascript',
+  includeVercel: boolean
 ): TemplateConfig[] => {
   const configFormat = languagePreference;
   const configTemplateBaseName = includeExamples ? 'handoff.config.with-examples' : 'handoff.config';
@@ -89,6 +92,10 @@ const getMandatoryTemplates = (
     templates.push({ source: 'tsconfig.json.tpl', destination: 'tsconfig.json' });
   }
 
+  if (includeVercel) {
+    templates.push({ source: 'vercel.json.tpl', destination: 'vercel.json' });
+  }
+
   return templates;
 };
 
@@ -118,7 +125,8 @@ const renderTemplate = (content: string, data: CreateOptions): string => {
 };
 
 const getDependenciesToInstall = (options: CreateOptions): { dependencies: string[]; devDependencies: string[] } => {
-  const dependencies = ['handoff-app@latest'];
+  // TODO: switch back to `handoff-app@latest` before the 2.0 stable release.
+  const dependencies = ['handoff-app@next'];
   const devDependencies: string[] = [];
 
   if (options.includeExamples) {
@@ -263,6 +271,51 @@ const create = async (): Promise<void> => {
 
     const languagePreference = languagePreferenceSelection as 'typescript' | 'javascript';
 
+    const includeVercelSelection = await p.confirm({
+      message: 'Add a Vercel deployment config (vercel.json)?',
+      initialValue: true,
+    });
+
+    if (p.isCancel(includeVercelSelection)) {
+      p.cancel('Project creation cancelled.');
+      process.exit(0);
+    }
+
+    const includeVercel = includeVercelSelection as boolean;
+
+    // When a Vercel config is scaffolded, choose which deployment its build command produces. Both
+    // package to `.vercel/output`; they differ in what is served. Registry is the recommended,
+    // pre-selected option; static stays available as the simplest deploy.
+    let vercelBuildCommand = 'npm run build -- --target registry --package vercel';
+    if (includeVercel) {
+      const vercelDeploymentSelection = await p.select({
+        message: 'Which deployment should Vercel build?',
+        options: [
+          {
+            value: 'registry',
+            label: 'Registry (dynamic)',
+            hint: 'Live, database-backed app (needs a Postgres DATABASE_URL). The more capable, actively evolving option — recommended for a shared design system.',
+          },
+          {
+            value: 'static',
+            label: 'Static site',
+            hint: 'Prebuilt snapshot served as plain files. The simplest to deploy and run.',
+          },
+        ],
+        initialValue: 'registry',
+      });
+
+      if (p.isCancel(vercelDeploymentSelection)) {
+        p.cancel('Project creation cancelled.');
+        process.exit(0);
+      }
+
+      vercelBuildCommand =
+        vercelDeploymentSelection === 'registry'
+          ? 'npm run build -- --target registry --package vercel'
+          : 'npm run build -- --target static --package vercel';
+    }
+
     // Get Figma project ID
     p.log.step(chalk.blue('Figma Configuration'));
     const figmaProjectId = await p.text({
@@ -295,6 +348,8 @@ const create = async (): Promise<void> => {
       figmaAccessToken: ((figmaAccessToken as string) || '').trim(),
       languagePreference,
       includeExamples,
+      includeVercel,
+      vercelBuildCommand,
     };
 
     // Create files
@@ -309,7 +364,7 @@ const create = async (): Promise<void> => {
 
     // Combine mandatory templates with example templates based on user choice
     const templates = [
-      ...getMandatoryTemplates(includeExamples, languagePreference),
+      ...getMandatoryTemplates(includeExamples, languagePreference, includeVercel),
       ...(includeExamples ? getExampleTemplates(languagePreference) : []),
     ];
 

package/src/commands/checkout/index.ts

@@ -2,20 +2,18 @@ import { CommandModule } from 'yargs';
 import Handoff from '../../';
 import { Logger } from '../../utils/logger';
 import { SharedArgs } from '../types';
-import { getSharedOptions } from '../utils';
-
-/** Entity kinds checkout-able from a connected workspace. */
-const ENTITY_KINDS = ['component', 'pattern', 'page', 'tokens', 'assets'] as const;
+import { ENTITY_WIRE_KIND, getSharedOptions, REGISTRY_ENTITY_KINDS, RegistryEntityKind } from '../utils';
 
 export interface CheckoutArgs extends SharedArgs {
-  type: (typeof ENTITY_KINDS)[number];
+  type: RegistryEntityKind;
   id?: string;
 }
 
 /**
- * `handoff-app checkout <component|pattern|page> <id>` — pull an entity from the connected registry
- * into this workspace: writes its source files in standard authoring form and synthesizes a local
- * declaration.
+ * `handoff-app checkout <components|patterns|pages> [id]` pulls entities from the connected registry
+ * into this workspace, writing their source files in standard authoring form and synthesizing local
+ * declarations. Pass an `id` to pull that one entity, or omit it to pull every published entity of
+ * that kind.
  *
  * `handoff-app checkout tokens [setId]` — pull every published token set (or only the named set) into
  * this workspace: reconstruct `tokens.json` and restore the generated token files.
@@ -28,16 +26,16 @@ export interface CheckoutArgs extends SharedArgs {
  */
 const command: CommandModule<{}, CheckoutArgs> = {
   command: 'checkout <type> [id]',
-  describe: 'Pull a component, pattern, page, design tokens, or assets from the connected registry into this workspace',
+  describe: 'Pull components, patterns, pages, design tokens, or assets from the connected registry into this workspace',
   builder: (yargs) => {
     return getSharedOptions(yargs)
       .positional('type', {
         describe: 'The kind of entity to checkout',
-        choices: ENTITY_KINDS,
+        choices: REGISTRY_ENTITY_KINDS,
         type: 'string',
       })
       .positional('id', {
-        describe: 'The stable id of the entity (component/pattern/page id, token set id, or asset collection); optional for tokens/assets',
+        describe: 'The stable id of the entity (component/pattern/page id, token set id, or asset collection); omit to checkout all of that kind',
         type: 'string',
       });
   },
@@ -52,10 +50,7 @@ const command: CommandModule<{}, CheckoutArgs> = {
         await handoff.checkoutAssets(args.id);
         return;
       }
-      if (!args.id) {
-        throw new Error(`An id is required to checkout a ${args.type} (e.g. "handoff-app checkout ${args.type} <id>").`);
-      }
-      await handoff.checkout(args.type, args.id);
+      await handoff.checkout(ENTITY_WIRE_KIND[args.type], args.id);
     } catch (error) {
       Logger.error(error instanceof Error ? error.message : String(error));
       process.exitCode = 1;

package/src/commands/publish/index.ts

@@ -2,19 +2,18 @@ import { CommandModule } from 'yargs';
 import Handoff from '../../';
 import { Logger } from '../../utils/logger';
 import { SharedArgs } from '../types';
-import { getSharedOptions } from '../utils';
-
-/** Entity kinds publishable from a connected workspace. */
-const ENTITY_KINDS = ['component', 'pattern', 'page', 'tokens', 'assets'] as const;
+import { ENTITY_WIRE_KIND, getSharedOptions, REGISTRY_ENTITY_KINDS, RegistryEntityKind } from '../utils';
 
 export interface PublishArgs extends SharedArgs {
-  type: (typeof ENTITY_KINDS)[number];
+  type: RegistryEntityKind;
   id?: string;
 }
 
 /**
- * `handoff-app publish <component|pattern|page> <id>` — fresh targeted local build + upload of the
- * selected entity to the connected registry.
+ * `handoff-app publish <components|patterns|pages> [id]` runs a fresh local build and uploads to the
+ * connected registry. Pass an `id` to build and upload that one entity, or omit it to build the kind
+ * once and upload every declared entity, skipping any whose content already matches the registry
+ * (pass `--force` to re-upload everything).
  *
  * `handoff-app publish tokens [setId]` — fresh token build + upload of every logical token set, or
  * only the named set (`foundation/colors`, `component/button`).
@@ -25,16 +24,16 @@ export interface PublishArgs extends SharedArgs {
  */
 const command: CommandModule<{}, PublishArgs> = {
   command: 'publish <type> [id]',
-  describe: 'Build and publish a component, pattern, page, design tokens, or assets to the connected registry',
+  describe: 'Build and publish components, patterns, pages, design tokens, or assets to the connected registry',
   builder: (yargs) => {
     return getSharedOptions(yargs)
       .positional('type', {
         describe: 'The kind of entity to publish',
-        choices: ENTITY_KINDS,
+        choices: REGISTRY_ENTITY_KINDS,
         type: 'string',
       })
       .positional('id', {
-        describe: 'The stable id of the entity (component/pattern/page id, token set id, or asset collection); optional for tokens/assets',
+        describe: 'The stable id of the entity (component/pattern/page id, token set id, or asset collection); omit to publish all of that kind',
         type: 'string',
       });
   },
@@ -49,10 +48,7 @@ const command: CommandModule<{}, PublishArgs> = {
         await handoff.publishAssets(args.id);
         return;
       }
-      if (!args.id) {
-        throw new Error(`An id is required to publish a ${args.type} (e.g. "handoff-app publish ${args.type} <id>").`);
-      }
-      await handoff.publish(args.type, args.id);
+      await handoff.publish(ENTITY_WIRE_KIND[args.type], args.id);
     } catch (error) {
       Logger.error(error instanceof Error ? error.message : String(error));
       process.exitCode = 1;

package/src/commands/utils.ts

@@ -1,4 +1,16 @@
 import { Argv } from 'yargs';
+import type { TransferEntityKind } from '../registry/transfer';
+
+/** Plural entity kinds accepted by the `publish`/`checkout` commands. */
+export const REGISTRY_ENTITY_KINDS = ['components', 'patterns', 'pages', 'tokens', 'assets'] as const;
+export type RegistryEntityKind = (typeof REGISTRY_ENTITY_KINDS)[number];
+
+/** Map the plural CLI kind to the singular wire kind used by entity publish/checkout. */
+export const ENTITY_WIRE_KIND: Record<'components' | 'patterns' | 'pages', TransferEntityKind> = {
+  components: 'component',
+  patterns: 'pattern',
+  pages: 'page',
+};
 
 export const getSharedOptions = (yargs: Argv) => {
   return yargs.options({

package/src/index.ts

@@ -138,26 +138,40 @@ class Handoff {
   }
 
   /**
-   * Publish a single component, pattern, or page from this connected workspace to the configured
-   * remote registry. Components and patterns receive a fresh targeted build before upload. Pages
-   * upload their record and markdown source because they render at runtime. The publish module is
-   * loaded lazily so the registry client and build code never enter the docs app bundle.
+   * Publish components, patterns, or pages from this connected workspace to the configured remote
+   * registry. With `id` it publishes that one entity after a targeted build; without `id` it builds
+   * the kind once and publishes every declared entity, skipping ones whose content is unchanged on
+   * the registry (`--force` re-uploads all). Pages upload their record and markdown source because
+   * they render at runtime. The publish module is loaded lazily so the registry client and build code
+   * never enter the docs app bundle.
    */
-  async publish(kind: 'component' | 'pattern' | 'page', id: string): Promise<Handoff> {
+  async publish(kind: 'component' | 'pattern' | 'page', id?: string): Promise<Handoff> {
     this.preRunner();
-    const { publishEntity } = await import('./registry/publish');
-    await publishEntity(this, kind, id);
+    if (id) {
+      const { publishEntity } = await import('./registry/publish');
+      await publishEntity(this, kind, id);
+    } else {
+      const { publishEntities } = await import('./registry/publish');
+      await publishEntities(this, kind);
+    }
     return this;
   }
 
   /**
-   * Checkout a single component, pattern, or page from the connected remote registry. The checkout
-   * module is loaded lazily so the registry client never enters the docs app bundle.
+   * Checkout components, patterns, or pages from the connected remote registry into this workspace.
+   * With `id` it checks out that one entity; without `id` it checks out every published entity of the
+   * kind. Overwriting existing local files requires `--force` or an interactive confirmation. The
+   * checkout module is loaded lazily so the registry client never enters the docs app bundle.
    */
-  async checkout(kind: 'component' | 'pattern' | 'page', id: string): Promise<Handoff> {
+  async checkout(kind: 'component' | 'pattern' | 'page', id?: string): Promise<Handoff> {
     this.preRunner();
-    const { checkoutEntity } = await import('./registry/checkout');
-    await checkoutEntity(this, kind, id);
+    if (id) {
+      const { checkoutEntity } = await import('./registry/checkout');
+      await checkoutEntity(this, kind, id);
+    } else {
+      const { checkoutEntities } = await import('./registry/checkout');
+      await checkoutEntities(this, kind);
+    }
     return this;
   }
 

package/src/registry/asset-storage/resolve.ts

@@ -3,7 +3,7 @@
  *
  * `runtime.registry.assetStorage` selects the active provider for **new** uploads: the built-in
  * `database` inline default, the pre-packaged `vercel-blob` adapter, or a `custom` module. Mirrors
- * {@link import('../db/adapter')}: only provider selection, module location, non-secret options, and
+ * {@link import('../db/driver')}: only provider selection, module location, non-secret options, and
  * env-var *names* are ever persisted; secret *values* are read from `process.env` at request time.
  */
 

package/src/registry/checkout/index.ts

@@ -1,7 +1,7 @@
 /**
  * Connected-workspace checkout orchestration.
  *
- * `checkout <component|pattern> <id>` reads a normalized registry record and its registry-safe
+ * `checkout <components|patterns> <id>` reads a normalized registry record and its registry-safe
  * source files from the connected registry through the shared registry client, then writes them
  * into the local workspace in standard authoring form. The local **declaration is synthesized
  * locally** in the configured `runtime.workspace.declarationFormat` — declarations are never read
@@ -20,7 +20,7 @@ import { resolveComponentDeclaration } from '../../config/runtime';
 import Handoff from '../../index';
 import type { DeclarationFormat } from '../../types/config';
 import { Logger } from '../../utils/logger';
-import { createRegistryClient, RegistryClientError } from '../client';
+import { createRegistryClient, type RegistryClient, RegistryClientError } from '../client';
 import { resolveRegistryConnection } from '../connection';
 import { isSafePathSegment, isSafeRelativePath, resolvePathWithin } from '../path';
 import type { CheckoutPayload, TransferEntityKind, TransferFile } from '../transfer';
@@ -530,26 +530,31 @@ const checkoutPage = async (handoff: Handoff, id: string, payload: CheckoutPaylo
 };
 
 /**
- * Checkout a single component or pattern from a connected workspace: precondition checks → fetch the
- * normalized record + source files → resolve the local target → explicit-overwrite guard → write
- * source files and synthesize the local declaration. Throws {@link CheckoutError} with actionable
- * messaging on any precondition or fetch failure.
+ * Checkout one entity through an already-resolved client: precondition checks → fetch the normalized
+ * record + source files → resolve the local target → explicit-overwrite guard → write source files
+ * and synthesize the local declaration. Shared by the single-id and bulk entry points so both behave
+ * identically. Throws {@link CheckoutError} with actionable messaging on any precondition or fetch
+ * failure.
  */
-export const checkoutEntity = async (handoff: Handoff, kind: TransferEntityKind, id: string): Promise<void> => {
+const checkoutSingle = async (
+  handoff: Handoff,
+  kind: TransferEntityKind,
+  id: string,
+  client: RegistryClient,
+  registryUrl: string
+): Promise<void> => {
   const validId = kind === 'page' ? isSafeRelativePath(id) : isSafePathSegment(id);
   if (!validId) {
     throw new CheckoutError(`Cannot checkout ${kind} with unsafe id "${id}".`);
   }
-  const connection = resolveConnectionOrThrow(handoff);
 
-  Logger.info(`Fetching ${kind} "${id}" from ${connection.url}…`);
-  const client = createRegistryClient({ baseUrl: connection.url, accessToken: connection.accessToken });
+  Logger.info(`Fetching ${kind} "${id}" from ${registryUrl}…`);
   let payload: CheckoutPayload;
   try {
     payload = await client.checkout(kind, id);
   } catch (error) {
     if (error instanceof RegistryClientError) {
-      throw new CheckoutError(describeFetchFailure(error, kind, id, connection.url));
+      throw new CheckoutError(describeFetchFailure(error, kind, id, registryUrl));
     }
     throw error;
   }
@@ -594,3 +599,60 @@ export const checkoutEntity = async (handoff: Handoff, kind: TransferEntityKind,
       `(${payload.files.length} source file(s) + ${declarationFileName}).`
   );
 };
+
+/**
+ * Checkout a single component, pattern, or page from the connected registry into this workspace.
+ * Overwriting existing local files requires `--force` or an interactive confirmation.
+ */
+export const checkoutEntity = async (handoff: Handoff, kind: TransferEntityKind, id: string): Promise<void> => {
+  const connection = resolveConnectionOrThrow(handoff);
+  const client = createRegistryClient({ baseUrl: connection.url, accessToken: connection.accessToken });
+  await checkoutSingle(handoff, kind, id, client, connection.url);
+};
+
+/**
+ * Checkout every published component, pattern, or page of the kind into this workspace. Enumerates
+ * the registry's published ids, then checks each out through the shared client. A per-entity failure
+ * is collected and never aborts the rest; the run throws at the end if any entity failed. Overwrite
+ * prompting is per entity (skipped under `--force`).
+ */
+export const checkoutEntities = async (handoff: Handoff, kind: TransferEntityKind): Promise<void> => {
+  const connection = resolveConnectionOrThrow(handoff);
+  const client = createRegistryClient({ baseUrl: connection.url, accessToken: connection.accessToken });
+
+  let summaries;
+  try {
+    summaries = await client.listEntities(kind);
+  } catch (error) {
+    if (error instanceof RegistryClientError) {
+      throw new CheckoutError(`Could not list ${kind}s from the registry at ${connection.url}: ${error.message}`);
+    }
+    throw error;
+  }
+
+  if (summaries.length === 0) {
+    Logger.success(`No ${kind}s are published in the registry; nothing to checkout.`);
+    return;
+  }
+
+  let checkedOut = 0;
+  const failed: { id: string; message: string }[] = [];
+  for (const { id } of summaries) {
+    try {
+      await checkoutSingle(handoff, kind, id, client, connection.url);
+      checkedOut += 1;
+    } catch (error) {
+      failed.push({ id, message: error instanceof Error ? error.message : String(error) });
+    }
+  }
+
+  Logger.success(
+    `${kind[0].toUpperCase()}${kind.slice(1)}s checkout complete — ${checkedOut} checked out${failed.length ? `, ${failed.length} failed` : ''}.`
+  );
+  if (failed.length > 0) {
+    for (const failure of failed) {
+      Logger.error(`  - ${failure.id}: ${failure.message}`);
+    }
+    throw new CheckoutError(`${failed.length} ${kind}(s) failed to checkout.`);
+  }
+};

package/src/registry/client.ts

@@ -8,7 +8,7 @@
  * and the browser both provide it), so this module stays runtime-agnostic.
  */
 
-import type { CheckoutPayload, TransferEntityKind, TransferPackage } from './transfer';
+import type { CheckoutPayload, EntitySummary, TransferEntityKind, TransferPackage } from './transfer';
 import type { TokenSetCheckoutPayload, TokenSetSummary, TokenSetTransferPackage } from './tokens/transfer';
 import type { AssetCollectionCheckoutPayload, AssetCollectionSummary, AssetCollectionTransferPackage } from './assets/transfer';
 
@@ -55,6 +55,7 @@ export interface RegistryClientOptions {
 export interface RegistryClient {
   publish(kind: TransferEntityKind, id: string, pkg: TransferPackage): Promise<RegistryEnvelope>;
   checkout(kind: TransferEntityKind, id: string): Promise<CheckoutPayload>;
+  listEntities(kind: TransferEntityKind): Promise<EntitySummary[]>;
   listTokenSets(): Promise<TokenSetSummary[]>;
   publishTokens(pkg: TokenSetTransferPackage): Promise<RegistryEnvelope>;
   checkoutTokens(id: string): Promise<TokenSetCheckoutPayload>;
@@ -154,6 +155,11 @@ export const createRegistryClient = ({ baseUrl, accessToken }: RegistryClientOpt
       }
       return envelope.data;
     },
+    /** List the registry's entities of one kind (id + build hashes) for skip-unchanged / bulk checkout. */
+    async listEntities(kind: TransferEntityKind): Promise<EntitySummary[]> {
+      const envelope = await request<{ entities: EntitySummary[] }>('GET', `/api/registry/transfer/${kind}`);
+      return envelope.data?.entities ?? [];
+    },
     /** 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');

package/src/registry/db/client.ts

@@ -1,24 +1,24 @@
 /**
  * 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
+ * The package ships both built-in drivers (`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
+ * lazily (dynamic import) for the selected driver 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 type { RegistryDatabaseDriver } from './driver';
 import * as schema from './schema';
 
-/** Typed Drizzle database over the registry schema, regardless of which adapter backs it. */
+/** Typed Drizzle database over the registry schema, regardless of which driver 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;
+  /** Selected driver that produced this connection. */
+  driver: RegistryDatabaseDriver;
   /** Typed Drizzle database. */
   db: RegistryDatabase;
   /** Apply the package-owned migrations found in `migrationsFolder`. */
@@ -28,20 +28,20 @@ export interface RegistryDbConnection {
 }
 
 export interface CreateRegistryDbConnectionParams {
-  adapter: RegistryDatabaseAdapter;
+  driver: RegistryDatabaseDriver;
   connectionString: string;
 }
 
 /**
- * Create a registry database connection for the resolved adapter. Both adapters target the
+ * Create a registry database connection for the resolved driver. Both drivers 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,
+  driver,
   connectionString,
 }: CreateRegistryDbConnectionParams): Promise<RegistryDbConnection> => {
-  if (adapter === 'neon') {
+  if (driver === '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');
@@ -59,7 +59,7 @@ export const createRegistryDbConnection = async ({
     const db = drizzle(pool, { schema });
 
     return {
-      adapter,
+      driver,
       db,
       migrate: (migrationsFolder: string) => migrate(db, { migrationsFolder }),
       close: () => pool.end(),
@@ -80,7 +80,7 @@ export const createRegistryDbConnection = async ({
   const db = drizzle(pool, { schema });
 
   return {
-    adapter,
+    driver,
     db,
     migrate: (migrationsFolder: string) => migrate(db, { migrationsFolder }),
     close: () => pool.end(),

package/src/registry/db/{adapter.ts → driver.ts}

@@ -1,17 +1,19 @@
 /**
- * Registry database adapter resolution.
+ * Registry database driver 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.
+ * PostgreSQL is the supported database. `runtime.registry.database.driver` selects one of two
+ * built-in connection drivers shipped with the `handoff-app` package — `pg` (default) and `neon` —
+ * both targeting the same Postgres dialect over one package-owned schema and migration set. The
+ * driver picks *how* to connect, not *which* database engine to use. `build --target registry` and
+ * `db:migrate` resolve the **same** driver 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';
+/** Built-in registry database connection driver. Both ship with the package and target Postgres. */
+export type RegistryDatabaseDriver = 'pg' | 'neon';
 
 /** Default env-var name holding the database connection string. */
 export const DEFAULT_DATABASE_URL_ENV = 'DATABASE_URL';
@@ -19,13 +21,13 @@ 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';
+/** Default registry database driver when none is configured. */
+export const DEFAULT_REGISTRY_DRIVER: RegistryDatabaseDriver = 'pg';
 
 /** Fully resolved registry database connection inputs. */
 export interface ResolvedRegistryDatabase {
-  /** Selected built-in adapter. */
-  adapter: RegistryDatabaseAdapter;
+  /** Selected built-in driver. */
+  driver: RegistryDatabaseDriver;
   /** Name of the env var the connection string was read from. */
   databaseUrlEnv: string;
   /** Resolved connection string (never persisted in config). */
@@ -48,9 +50,9 @@ export const resolveApiTokenEnv = (config: Config | null | undefined): string =>
   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 configured registry database driver (defaults to `pg`). */
+export const resolveRegistryDriver = (config: Config | null | undefined): RegistryDatabaseDriver => {
+  return config?.runtime?.registry?.database?.driver ?? DEFAULT_REGISTRY_DRIVER;
 };
 
 /**
@@ -59,7 +61,7 @@ export const resolveRegistryAdapter = (config: Config | null | undefined): Regis
  * message instead of failing deep inside the driver.
  */
 export const resolveRegistryDatabase = (config: Config | null | undefined): ResolvedRegistryDatabase => {
-  const adapter = resolveRegistryAdapter(config);
+  const driver = resolveRegistryDriver(config);
   const databaseUrlEnv = resolveDatabaseUrlEnv(config);
   const connectionString = process.env[databaseUrlEnv]?.trim();
 
@@ -70,5 +72,5 @@ export const resolveRegistryDatabase = (config: Config | null | undefined): Reso
     );
   }
 
-  return { adapter, databaseUrlEnv, connectionString };
+  return { driver, databaseUrlEnv, connectionString };
 };

package/src/registry/db/index.ts

@@ -15,15 +15,15 @@ export type { ArtifactBuildStatus as RegistryBuildStatus } from '../../artifacts
 
 export {
   DEFAULT_DATABASE_URL_ENV,
-  DEFAULT_REGISTRY_ADAPTER,
+  DEFAULT_REGISTRY_DRIVER,
   DEFAULT_REGISTRY_API_TOKEN_ENV,
   resolveApiTokenEnv,
   resolveDatabaseUrlEnv,
-  resolveRegistryAdapter,
+  resolveRegistryDriver,
   resolveRegistryDatabase,
-  type RegistryDatabaseAdapter,
+  type RegistryDatabaseDriver,
   type ResolvedRegistryDatabase,
-} from './adapter';
+} from './driver';
 
 export {
   createRegistryDbConnection,