handoff-app 2.0.0-8 → 2.0.0

package/src/registry/checkout/index.ts

@@ -6,7 +6,8 @@
  * into the local workspace in standard authoring form. The local **declaration is synthesized
  * locally** in the configured `runtime.workspace.declarationFormat` — declarations are never read
  * from the registry (they are workspace-only). Identity is matched by stable `id`, so a checked-out
- * entity maps to the correct logical component/pattern and can be re-authored and re-published.
+ * entity maps to the correct logical component/pattern and can be re-authored and re-published. A
+ * new entity goes to the directory it was published from (`sourceDir`).
  *
  * Available only from a connected workspace (`runtime.mode: workspace` + a configured
  * `registryConnection`). Overwriting existing local files is explicit: a `--force` flag or an
@@ -30,14 +31,14 @@ import {
   type RendererKind,
   type SourceFormat,
 } from '../../catalog/renderers';
-import { addToCatalog, isIncluded } from '../../config/catalog-include';
 import { isComponentDirectory, resolveComponentDeclaration } from '../../config/runtime';
 import Handoff from '../../index';
 import type { DeclarationFormat } from '../../types/config';
 import { Logger } from '../../utils/logger';
+import { arePathsEqual } from '../../utils/path';
 import { createRegistryClient, type RegistryClient, RegistryClientError } from '../client';
 import { loginCommandHint, resolveAuthenticatedRegistryConnection, unusedLoginNote } from '../connection';
-import { isSafePathSegment, isSafeRelativePath, resolvePathWithin } from '../path';
+import { isSafePathSegment, isSafeRelativePath, isWorkspaceRelativePath, resolvePathWithin } from '../path';
 import { quoteIds, selectIds, splitCatalogIds } from '../selection';
 import type { CheckoutPayload, TransferEntityKind, TransferFile } from '../transfer';
 
@@ -52,12 +53,7 @@ export class CheckoutError extends Error {
 /** Default authoring format synthesized when no existing file or configured preference applies. */
 const DEFAULT_DECLARATION_FORMAT: DeclarationFormat = 'ts';
 
-/** Default workspace subdirectory an entity is written into when none is configured. */
-const DEFAULT_ENTITY_DIR: Record<TransferEntityKind, string> = {
-  component: 'components',
-  pattern: 'patterns',
-  page: 'pages',
-};
+const PAGES_DIR = 'pages';
 
 /** Source-file extensions stripped to form a module specifier for a React component import. */
 const COMPONENT_EXTENSION = /\.(tsx|jsx|ts|js|cjs|mjs)$/i;
@@ -108,88 +104,48 @@ const describeFetchFailure = (error: RegistryClientError, kind: TransferEntityKi
   }
 };
 
-/**
- * Ask the user which collection directory a new entity should land in when the config is ambiguous.
- * Under `--force` (or any non-interactive run) there's no one to ask, so we fail with an actionable
- * message rather than guessing a root.
- */
-const promptForCollectionRoot = async (handoff: Handoff, kind: TransferEntityKind, roots: string[]): Promise<string> => {
-  const relative = (root: string) => path.relative(handoff.workingPath, root) || '.';
-  if (handoff.force) {
-    throw new CheckoutError(
-      `Cannot determine where to checkout the ${kind}: catalog.include declares directories under different ` +
-        `parents (${roots.map(relative).join(', ')}), and none is named "${DEFAULT_ENTITY_DIR[kind]}". Declare a single ` +
-        `collection directory in handoff.config, or run checkout without --force to choose interactively.`
-    );
-  }
-  const choice = await p.select({
-    message: `Where should the new ${kind} be checked out?`,
-    options: roots.map((root) => ({ value: root, label: relative(root) })),
-    initialValue: roots[0],
+/** `dir` is a `catalog.include` entry, or a direct child of a collection entry. */
+const isInCatalog = (handoff: Handoff, dir: string): boolean =>
+  (handoff.config?.catalog?.include ?? []).some((entry) => {
+    const included = path.resolve(handoff.workingPath, entry);
+    return arePathsEqual(included, dir) || (!isComponentDirectory(included) && arePathsEqual(included, path.dirname(dir)));
   });
-  if (p.isCancel(choice)) {
-    throw new CheckoutError('Checkout cancelled; no target directory chosen.');
-  }
-  return choice as string;
-};
-
-/**
- * Resolve the collection directory a new entity is cloned into from the configured
- * `catalog.include`. Each entry is either a collection directory (used as-is) or a
- * single declared entity directory, in which case its parent is the collection root so the new
- * entity lands as a sibling rather than nested inside. Different parents are settled by the
- * conventional directory name for the kind, and only then by asking the user. With nothing
- * configured we fall back to the default subdir.
- */
-const resolveCollectionRoot = async (handoff: Handoff, kind: TransferEntityKind): Promise<string> => {
-  const configuredRoots = handoff.config?.catalog?.include;
-  if (!configuredRoots?.length) {
-    return path.resolve(handoff.workingPath, DEFAULT_ENTITY_DIR[kind]);
-  }
-
-  const roots = [
-    ...new Set(
-      configuredRoots.map((entry) => {
-        const resolved = path.resolve(handoff.workingPath, entry);
-        return isComponentDirectory(resolved) ? path.dirname(resolved) : resolved;
-      })
-    ),
-  ];
-
-  if (roots.length === 1) {
-    return roots[0];
-  }
 
-  // `catalog.include` is one list for both lanes, so a project that registers `components` and
-  // `patterns` offers two roots for every checkout. Without this, every such project prompts, and a
-  // non-interactive `--force` run fails.
-  const conventional = roots.filter((root) => path.basename(root) === DEFAULT_ENTITY_DIR[kind]);
-  if (conventional.length === 1) {
-    return conventional[0];
-  }
-
-  return promptForCollectionRoot(handoff, kind, roots);
-};
-
-/**
- * Resolve the local directory the entity is written into. An already-checked-out or locally-declared
- * entity keeps its existing source directory (matched by stable `id`); otherwise it lands as a
- * sibling under its configured collection root (see {@link resolveCollectionRoot}).
- */
-const resolveTargetDir = async (handoff: Handoff, kind: TransferEntityKind, id: string): Promise<string> => {
+/** A locally declared entity keeps its directory. A new one goes to the directory it was published from. */
+const resolveTargetDir = async (
+  handoff: Handoff,
+  kind: TransferEntityKind,
+  id: string,
+  sourceDir: string | undefined
+): Promise<{ dir: string; isInCatalog: boolean }> => {
   const store = kind === 'component' ? handoff.store.components : handoff.store.patterns;
   const existing = await store.get(id);
   const existingDir = (existing as { path?: string } | null)?.path;
   if (existingDir) {
-    return existingDir;
+    return { dir: existingDir, isInCatalog: true };
   }
 
-  const root = await resolveCollectionRoot(handoff, kind);
-  const targetDir = resolvePathWithin(root, id);
-  if (!targetDir) {
-    throw new CheckoutError(`Cannot checkout ${kind} with unsafe id "${id}".`);
+  if (!isWorkspaceRelativePath(sourceDir)) {
+    throw new CheckoutError(`The registry has no valid source directory for ${kind} "${id}". Republish it, then checkout again.`);
+  }
+  const dir = path.resolve(handoff.workingPath, sourceDir);
+  return { dir, isInCatalog: isInCatalog(handoff, dir) };
+};
+
+/** `--force` fails here: it skips overwrite prompts, not approval of a location the registry chose. */
+const confirmLocation = async (handoff: Handoff, kind: TransferEntityKind, id: string, dir: string): Promise<boolean> => {
+  const relative = path.relative(handoff.workingPath, dir) || '.';
+  if (handoff.force) {
+    throw new CheckoutError(
+      `The registry places ${kind} "${id}" at ${relative}, which is outside catalog.include. ` +
+        `Add "${relative}" or its parent directory to catalog.include, or run checkout without --force to accept the location.`
+    );
   }
-  return targetDir;
+  const proceed = await p.confirm({
+    message: `The registry places ${kind} "${id}" at ${relative}, which is outside catalog.include. Write it there?`,
+    initialValue: false,
+  });
+  return !p.isCancel(proceed) && proceed === true;
 };
 
 /** Read the extension of an existing local declaration in `dir`, if any maps to a known format. */
@@ -761,7 +717,7 @@ export const reportPlannedWrites = (handoff: Handoff, label: string, targets: st
  * markdown file is itself the authored source — so the page round-trips byte-for-byte.
  */
 const checkoutPage = async (handoff: Handoff, id: string, payload: CheckoutPayload): Promise<void> => {
-  const pagesRoot = path.resolve(handoff.workingPath, DEFAULT_ENTITY_DIR.page);
+  const pagesRoot = path.resolve(handoff.workingPath, PAGES_DIR);
   const targets = payload.files.map((file) => {
     const target = resolvePathWithin(pagesRoot, file.path);
     if (!target) {
@@ -799,7 +755,7 @@ const checkoutSingle = async (
   id: string,
   client: RegistryClient,
   registryUrl: string
-): Promise<string | null> => {
+): Promise<void> => {
   const validId = kind === 'page' ? isSafeRelativePath(id) : isSafePathSegment(id);
   if (!validId) {
     throw new CheckoutError(`Cannot checkout ${kind} with unsafe id "${id}".`);
@@ -816,14 +772,15 @@ const checkoutSingle = async (
     throw error;
   }
 
-  // Pages round-trip as a single verbatim `.md` with no declaration synthesis, and aren't
-  // listed in `catalog.include`, so there's nothing to register.
   if (kind === 'page') {
     await checkoutPage(handoff, id, payload);
-    return null;
+    return;
   }
 
-  const targetDir = await resolveTargetDir(handoff, kind, id);
+  const target = await resolveTargetDir(handoff, kind, id, payload.sourceDir);
+  const targetDir = target.dir;
+  const relativeDir = path.relative(handoff.workingPath, targetDir) || '.';
+  const outsideCatalogWarning = `Add "${relativeDir}" to catalog.include, or the build will not load ${kind} "${id}".`;
   const format = resolveDeclarationFormat(handoff, targetDir);
   const declarationFileName = resolveDeclarationFileName(targetDir, id, format);
   const declarationPath = path.join(targetDir, declarationFileName);
@@ -840,13 +797,19 @@ const checkoutSingle = async (
   const plannedWrites = [...sourceTargets.map((entry) => entry.absolutePath), declarationPath];
   const conflicts = plannedWrites.filter((file) => fs.existsSync(file));
   if (handoff.dryRun) {
-    // Returning null also skips `registerCheckedOut`, so a dry run never edits handoff.config either.
     reportPlannedWrites(handoff, `${kind} "${id}"`, plannedWrites, conflicts);
-    return null;
+    if (!target.isInCatalog) {
+      Logger.warn(`${relativeDir} is outside catalog.include. ${outsideCatalogWarning}`);
+    }
+    return;
+  }
+  if (!target.isInCatalog && !(await confirmLocation(handoff, kind, id, targetDir))) {
+    Logger.warn(`Checkout of ${kind} "${id}" cancelled; no files were written.`);
+    return;
   }
   if (!(await confirmOverwrite(handoff, conflicts))) {
     Logger.warn(`Checkout of ${kind} "${id}" cancelled; no files were written.`);
-    return null;
+    return;
   }
 
   await fs.ensureDir(targetDir);
@@ -858,41 +821,10 @@ const checkoutSingle = async (
   await fs.writeFile(declarationPath, declaration, 'utf8');
   written.push(declarationPath);
 
-  Logger.success(
-    `Checked out ${kind} "${id}" into ${path.relative(handoff.workingPath, targetDir) || '.'} ` +
-      `(${payload.files.length} source file(s) + ${declarationFileName}).`
-  );
-  return targetDir;
-};
-
-/**
- * Declare freshly checked-out entities in `catalog.include` so the workspace build
- * picks them up. Ones already covered by a collection directory load on their own and are left
- * alone; the rest are added to the config automatically. If the config can't be edited (a computed
- * or unusual `include` array), we print the paths for the user to add so nothing is silently orphaned.
- */
-const registerCheckedOut = async (handoff: Handoff, kind: TransferEntityKind, targetDirs: string[]): Promise<void> => {
-  if (kind === 'page') {
-    return;
-  }
-  const kindLabel = kind === 'component' ? 'components' : 'patterns';
-  const unlisted = targetDirs.filter((dir) => !isIncluded(handoff, dir));
-  if (unlisted.length === 0) {
-    return;
-  }
-
-  const result = await addToCatalog(handoff, unlisted);
-  if (result.status === 'added') {
-    const where = result.configPath
-      ? path.relative(handoff.workingPath, result.configPath) || path.basename(result.configPath)
-      : 'handoff.config';
-    Logger.success(`Updated ${where} with ${result.added.length} ${kindLabel} path(s).`);
-    return;
+  Logger.success(`Checked out ${kind} "${id}" into ${relativeDir} (${payload.files.length} source file(s) + ${declarationFileName}).`);
+  if (!target.isInCatalog) {
+    Logger.warn(outsideCatalogWarning);
   }
-
-  const where = result.configPath ? path.relative(handoff.workingPath, result.configPath) : 'handoff.config';
-  Logger.warn(`Could not update ${where} automatically. Add these to catalog.include manually:`);
-  result.pending.forEach((rel) => Logger.warn(`  - ${rel}`));
 };
 
 /**
@@ -902,10 +834,7 @@ const registerCheckedOut = async (handoff: Handoff, kind: TransferEntityKind, ta
 export const checkoutEntity = async (handoff: Handoff, kind: TransferEntityKind, id: string): Promise<void> => {
   const connection = await resolveConnectionOrThrow(handoff);
   const client = createRegistryClient({ baseUrl: connection.url, accessToken: connection.accessToken });
-  const targetDir = await checkoutSingle(handoff, kind, id, client, connection.url);
-  if (targetDir) {
-    await registerCheckedOut(handoff, kind, [targetDir]);
-  }
+  await checkoutSingle(handoff, kind, id, client, connection.url);
 };
 
 /** List the ids the registry publishes for one kind, naming the registry in a listing failure. */
@@ -922,7 +851,7 @@ const listPublishedIds = async (kind: TransferEntityKind, client: RegistryClient
 };
 
 /**
- * Check out the given ids of one kind and register what landed. The caller selects the ids, because a
+ * Check out the given ids of one kind. The caller selects the ids, because a
  * catalog run resolves them across both entity lanes before any of them is written.
  *
  * A per-entity failure is collected and never aborts the rest. Failures are reported here, and the
@@ -937,22 +866,15 @@ const checkoutSelected = async (
 ): Promise<number> => {
   let checkedOut = 0;
   const failed: { id: string; message: string }[] = [];
-  const targetDirs: string[] = [];
   for (const id of targets) {
     try {
-      const targetDir = await checkoutSingle(handoff, kind, id, client, registryUrl);
-      if (targetDir) {
-        targetDirs.push(targetDir);
-      }
+      await checkoutSingle(handoff, kind, id, client, registryUrl);
       checkedOut += 1;
     } catch (error) {
       failed.push({ id, message: error instanceof Error ? error.message : String(error) });
     }
   }
 
-  // Register everything checked out in one pass, so the config is edited (and confirmed) once.
-  await registerCheckedOut(handoff, kind, targetDirs);
-
   Logger.success(
     `${kind[0].toUpperCase()}${kind.slice(1)}s checkout complete — ${checkedOut} ${handoff.dryRun ? 'would be checked out' : 'checked out'}` +
       `${failed.length ? `, ${failed.length} failed` : ''}.`

package/src/registry/client.ts

@@ -11,6 +11,7 @@
 import type { CheckoutPayload, EntitySummary, TransferEntityKind, TransferPackage } from './transfer';
 import type { TokenSetCheckoutPayload, TokenSetSummary, TokenSetTransferPackage } from './tokens/transfer';
 import type { AssetCollectionCheckoutPayload, AssetCollectionSummary, AssetCollectionTransferPackage } from './assets/transfer';
+import type { AssetUpload } from './asset-storage/types';
 
 /** Encode a token set id for the catch-all transfer route, preserving `/` between segments. */
 const encodeSetIdPath = (id: string): string =>
@@ -139,6 +140,30 @@ export const createRegistryClient = ({ baseUrl, accessToken }: RegistryClientOpt
     return envelope;
   };
 
+  const uploadAssetBlobThroughRegistry = async (blobPath: string, contentType: string, bytes: Buffer): Promise<void> => {
+    const url = `${root}${blobPath}`;
+    // 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 });
+    }
+  };
+
   return {
     /** Publish (`PUT`) an entity's package to the registry transfer endpoint. */
     publish(kind: TransferEntityKind, id: string, pkg: TransferPackage): Promise<RegistryEnvelope> {
@@ -187,29 +212,44 @@ export const createRegistryClient = ({ baseUrl, accessToken }: RegistryClientOpt
       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. */
+    /**
+     * Upload one content-addressed blob. Sends it directly to storage when the registry returns a
+     * signed URL, otherwise through the registry. 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,
-      });
+      const blobPath = `/api/registry/transfer/assets/blobs/${encodeURIComponent(hash)}`;
+      const size = bytes.length;
+      const envelope = await request<{ upload: AssetUpload | null; stored?: boolean }>('POST', `${blobPath}/upload`, { size, contentType });
+      if (envelope.data?.stored) {
+        return;
+      }
+      const upload = envelope.data?.upload;
+      if (!upload) {
+        await uploadAssetBlobThroughRegistry(blobPath, contentType, bytes);
+        return;
+      }
+
+      // Name only the origin in errors: the signed query string must not reach logs.
+      const storage = new URL(upload.url).origin;
+      let response: Response;
+      try {
+        response = await fetch(upload.url, {
+          method: 'PUT',
+          headers: upload.headers,
+          body: new Blob([new Uint8Array(bytes)] as unknown as BlobPart[]),
+        });
+      } catch (error) {
+        const cause = (error as { cause?: { code?: string; message?: string } } | undefined)?.cause;
+        throw new RegistryClientError(`Could not reach asset storage at ${storage}: ${cause?.code || cause?.message || 'network error'}.`);
+      }
       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 });
+        const detail = (await response.text().catch(() => '')).slice(0, 300);
+        throw new RegistryClientError(
+          `Asset storage at ${storage} rejected the upload of blob "${hash}" (${response.status} ${response.statusText})${detail ? `: ${detail}` : ''}.`,
+          { status: response.status }
+        );
       }
+      await request('POST', `${blobPath}/complete`, { storageRef: upload.storageRef, size, contentType });
     },
     /** Download one blob's raw bytes by hash (follows any provider redirect). */
     async downloadAssetBlob(hash: string): Promise<Buffer> {

package/src/registry/db/driver.ts

@@ -36,7 +36,7 @@ export interface ResolvedRegistryDatabase {
 
 /** Resolve the env-var name holding the database URL (defaults to `DATABASE_URL`). */
 export const resolveDatabaseUrlEnv = (config: ResolvedConfig | null | undefined): string => {
-  const configured = config?.runtime?.registry?.databaseUrl?.$env?.trim();
+  const configured = config?.runtime?.registry?.database?.url?.$env?.trim();
   return configured || DEFAULT_DATABASE_URL_ENV;
 };
 
@@ -58,7 +58,7 @@ export const resolveRegistryDatabase = (config: ResolvedConfig | null | undefine
   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.databaseUrl" to point at the env var you use).`
+        `PostgreSQL connection string (or change "runtime.registry.database.url" to point at the env var you use).`
     );
   }
 

package/src/registry/db/schema.ts

@@ -30,7 +30,7 @@ import type { TokenSetKind } from '../tokens/sets';
 
 /**
  * PostgreSQL `bytea` column. Drizzle pg-core has no built-in binary type, so declare it once here.
- * Reads/writes are Node `Buffer`s. The default asset storage adapter keeps small/ordinary asset
+ * Reads/writes are Node `Buffer`s. The default asset storage provider keeps small/ordinary asset
  * bytes inline in this column; larger assets are offloaded to an object-storage `storageRef` instead.
  */
 const bytea = customType<{ data: Buffer; driverData: Buffer }>({
@@ -39,8 +39,8 @@ const bytea = customType<{ data: Buffer; driverData: Buffer }>({
   },
 });
 
-/** Where an asset blob's bytes physically live: the default DB adapter, Vercel Blob, or a custom id. */
-export type AssetStorageProvider = 'database' | 'vercel-blob' | (string & {});
+/** Where an asset blob's bytes live: inline in the database (`database`) or in a custom provider (`custom`). */
+export type AssetStorageProvider = 'database' | 'custom';
 import type { ComponentListObject, PageListObject, PatternComponentEntry, PatternListObject } from '../../transformers/preview/types';
 
 /** Registry account role. Administrators may issue write-scoped credentials. */
@@ -112,6 +112,8 @@ export const components = pgTable(
     sourceFormat: text('source_format'),
     tags: jsonb('tags').$type<string[]>(),
     categories: jsonb('categories').$type<string[]>(),
+    /** Workspace-relative directory the component was published from. */
+    sourceDir: text('source_dir'),
     /** Full normalized component record. */
     record: jsonb('record').$type<ComponentListObject>().notNull(),
     /** Registry-only review/catalog metadata (management-API allowlist; never a render input). */
@@ -165,6 +167,8 @@ export const patterns = pgTable(
     tags: jsonb('tags').$type<string[]>(),
     /** Pattern component references. */
     components: jsonb('components').$type<PatternComponentEntry[]>(),
+    /** Workspace-relative directory the pattern was published from. */
+    sourceDir: text('source_dir'),
     /** Full normalized pattern record. */
     record: jsonb('record').$type<PatternListObject>().notNull(),
     /** Registry-only review/catalog metadata (management-API allowlist; never a render input). */
@@ -378,23 +382,20 @@ export const tokenArtifacts = pgTable(
  * collection is its current manifest. Publish replaces those rows atomically, so readers always see a
  * complete manifest.
  */
-export const assetCollections = pgTable(
-  'asset_collections',
-  {
-    /** Stable collection id (`icons`|`logos`|`fonts`). Join key across stores. */
-    collection: text('collection').primaryKey(),
-    /** Deterministic content hash over the collection's `(path, contentHash)` manifest (skip-unchanged). */
-    sourceHash: text('source_hash'),
-    /** Build/publish status for the collection. */
-    status: text('status').$type<RegistryBuildStatus>(),
-    builtAt: timestamp('built_at', { withTimezone: true }),
-    builderVersion: text('builder_version'),
-    /** Registry-only review/catalog metadata (parity with other entities; management-API only). */
-    metadata: jsonb('metadata').$type<RegistryReviewMetadata>(),
-    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
-    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
-  }
-);
+export const assetCollections = pgTable('asset_collections', {
+  /** Stable collection id (`icons`|`logos`|`fonts`). Join key across stores. */
+  collection: text('collection').primaryKey(),
+  /** Deterministic content hash over the collection's `(path, contentHash)` manifest (skip-unchanged). */
+  sourceHash: text('source_hash'),
+  /** Build/publish status for the collection. */
+  status: text('status').$type<RegistryBuildStatus>(),
+  builtAt: timestamp('built_at', { withTimezone: true }),
+  builderVersion: text('builder_version'),
+  /** Registry-only review/catalog metadata (parity with other entities; management-API only). */
+  metadata: jsonb('metadata').$type<RegistryReviewMetadata>(),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+});
 
 /**
  * Logical asset metadata - the collection manifest. One row per asset (icon/logo SVG, sprite,
@@ -431,13 +432,13 @@ export const assets = pgTable(
 /**
  * Content-addressed binary blob store, shared across assets/collections (the `hash` is the blob
  * identity, so an unchanged file re-references the same row). Exactly one location is active per row:
- * inline `content` (bytea, default DB adapter) or an external `storageRef` resolved through the
+ * inline `content` (bytea, default `database` provider) or an external `storageRef` resolved through the
  * recorded `storageProvider`. Both nullable so DB- and object-backed blobs coexist.
  */
 export const assetBlobs = pgTable('asset_blobs', {
   /** SHA-256 of the blob bytes (hex). */
   hash: text('hash').primaryKey(),
-  /** Which storage backed this blob when it was written (`database`|`vercel-blob`|custom id). */
+  /** Which storage backed this blob when it was written (`database`|custom id). */
   storageProvider: text('storage_provider').$type<AssetStorageProvider>().notNull(),
   /** Inline bytes; null when stored externally via `storageRef`. */
   content: bytea('content'),
@@ -575,6 +576,31 @@ export const registryDeviceAuthorizations = pgTable(
   ]
 );
 
+/**
+ * One reader's key for one declared AI connection. Unlike every other credential here the value
+ * must be recoverable, because it is sent to the provider on that reader's behalf, so it is
+ * encrypted rather than hashed (see `../auth/crypto`). A row whose `connectionId` no longer appears
+ * in the config is ignored, not deleted: the connection may come back on the next deploy.
+ */
+export const registryAiKeys = pgTable(
+  'registry_ai_keys',
+  {
+    userId: text('user_id')
+      .notNull()
+      .references(() => registryUsers.id, { onDelete: 'cascade' }),
+    /** Id of the connection the config declares. Never a reader-supplied endpoint. */
+    connectionId: text('connection_id').notNull(),
+    /** Self-describing AES-256-GCM payload; the deployment secret it is keyed from is never stored. */
+    encryptedKey: text('encrypted_key').notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    primaryKey({ columns: [table.userId, table.connectionId] }),
+    check('registry_ai_keys_connection_not_blank', sql`length(btrim(${table.connectionId})) > 0`),
+  ]
+);
+
 /**
  * Fixed-window throttling counters. Callers pass a hash of the identifying value so raw emails and
  * IP addresses are not retained.
@@ -616,6 +642,7 @@ export const registrySchema = {
   registryInstallations,
   registryAuthActionTokens,
   registryAccessTokens,
+  registryAiKeys,
   registryDeviceAuthorizations,
   registryAuthRateLimits,
 };

package/src/registry/email/define.ts

@@ -0,0 +1,15 @@
+/**
+ * Typed identity helper for custom email providers (mirrors `defineStorageProvider`): a consumer
+ * default-exports its result from a **server-only** module and points `runtime.registry.email.module`
+ * at it. It must be its own module (not an inline `defineConfig` function) so the build can trace it
+ * into the deployed registry. The default export may be the provider object, or a factory
+ * `(context) => EmailProvider` when it needs its options or env.
+ */
+
+import type { EmailProvider, EmailProviderFactory } from './types';
+
+export function defineEmailProvider(provider: EmailProvider): EmailProvider;
+export function defineEmailProvider(factory: EmailProviderFactory): EmailProviderFactory;
+export function defineEmailProvider(input: EmailProvider | EmailProviderFactory): EmailProvider | EmailProviderFactory {
+  return input;
+}

package/src/registry/email/providers/smtp.ts

@@ -0,0 +1,39 @@
+/**
+ * Built-in SMTP provider, selected with `runtime.registry.email.provider: "smtp"`.
+ *
+ * `nodemailer` is loaded lazily so it is only pulled into memory (and traced into the registry
+ * bundle) when this provider is selected. Options may come from environment variables, so numbers
+ * and booleans can arrive as strings.
+ */
+
+import type { EmailProvider } from '../types';
+
+const toNumber = (value: unknown): number | undefined => {
+  const number = typeof value === 'number' ? value : typeof value === 'string' && value.trim() ? Number(value) : NaN;
+  return Number.isFinite(number) ? number : undefined;
+};
+
+const toBoolean = (value: unknown): boolean | undefined =>
+  typeof value === 'boolean' ? value : typeof value === 'string' && value.trim() ? value.trim() === 'true' : undefined;
+
+/** Build an SMTP provider from options whose references are already resolved. */
+export const createSmtpProvider = (options: Record<string, unknown>): EmailProvider => {
+  const host = typeof options.host === 'string' ? options.host : '';
+  const configuredPort = toNumber(options.port);
+  const secure = toBoolean(options.secure) ?? (configuredPort === undefined || configuredPort === 465);
+  const port = configuredPort ?? (secure ? 465 : 587);
+  const user = typeof options.user === 'string' ? options.user : undefined;
+  const password = typeof options.password === 'string' ? options.password : undefined;
+
+  return {
+    async send({ from, to, subject, html, text }) {
+      if (!host) throw new Error('The SMTP host is not set.');
+      const { createTransport } = await import('nodemailer');
+      const transport = createTransport({ host, port, secure, auth: user ? { user, pass: password } : undefined });
+      const info = await transport.sendMail({ from, to, subject, html, text });
+      if (info.rejected?.length) {
+        throw new Error(`The SMTP server rejected the recipient: ${info.response}`);
+      }
+    },
+  };
+};