handoff-app 2.0.0-9 → 2.0.0

package/src/index.ts

@@ -12,10 +12,16 @@ import {
   initRuntimeConfig,
   loadProfileEnv,
   resolveProfileSelection,
-  validateConfig,
 } from './config';
 import pipeline, { buildComponents, buildPatterns } from './pipeline';
-import { ALL_KIND_ORDER, ENTITY_WIRE_KIND, isRegistryEntityKind, REGISTRY_ENTITY_KINDS, type RegistryEntityKind } from './registry/content-kinds';
+import { resolveFigmaConnection } from './pipeline/figma';
+import {
+  ALL_KIND_ORDER,
+  ENTITY_WIRE_KIND,
+  isRegistryEntityKind,
+  REGISTRY_ENTITY_KINDS,
+  type RegistryEntityKind,
+} from './registry/content-kinds';
 import type { TransferEntityKind } from './registry/transfer';
 import { createFilesystemStore, type HandoffStore } from './store';
 import processComponents, { ComponentSegment } from './transformers/preview/component/builder';
@@ -231,7 +237,7 @@ class Handoff {
     this.exportsDirectory = config.exportsOutputDirectory ?? this.exportsDirectory;
     this.sitesDirectory = config.sitesOutputDirectory ?? this.exportsDirectory;
     [this.runtimeConfig, this._configFilePaths, this._configFileIndex] = initRuntimeConfig(this);
-    if(this.config.app.base_path && !process.env.HANDOFF_APP_BASE_PATH) {
+    if (this.config.app.base_path && !process.env.HANDOFF_APP_BASE_PATH) {
       process.env.HANDOFF_APP_BASE_PATH = this.config.app.base_path ?? '';
     }
     return this;
@@ -242,13 +248,10 @@ class Handoff {
     return this;
   }
 
-  preRunner(validate?: boolean): Handoff {
+  preRunner(): Handoff {
     if (!this.config) {
       throw Error('Handoff not initialized');
     }
-    if (validate) {
-      this.config = validateConfig(this.config);
-    }
     return this;
   }
 
@@ -523,13 +526,8 @@ class Handoff {
       return this._handoffRunner;
     }
 
-    const apiCredentials = {
-      projectId: this.config.figma_project_id,
-      accessToken: this.config.dev_access_token,
-    };
-
-    // Initialize the provider
-    const provider = Providers.RestApiProvider(apiCredentials);
+    const { projectId, accessToken } = resolveFigmaConnection(this.config);
+    const provider = Providers.RestApiProvider({ projectId, accessToken });
 
     this._handoffRunner = HandoffRunner(
       provider,
@@ -557,15 +555,8 @@ class Handoff {
     return this._handoffRunner;
   }
 
-  /**
-   * Gets the project ID, falling back to filesystem-safe working path if figma_project_id is missing
-   * @returns {string} The project ID to use for path construction
-   */
+  /** Keys `.handoff/<projectId>`, so workspaces that share one installed package stage apart. */
   getProjectId(): string {
-    if (this.config?.figma_project_id) {
-      return this.config.figma_project_id;
-    }
-    // Fallback to filesystem-safe transformation of working path
     return generateFilesystemSafeId(this.workingPath);
   }
 
@@ -574,7 +565,7 @@ class Handoff {
    * @returns {string} The absolute path to the output directory
    */
   getOutputPath(): string {
-    return path.resolve(this.workingPath, this.exportsDirectory, this.getProjectId());
+    return path.resolve(this.workingPath, this.exportsDirectory);
   }
 
   /**
@@ -642,6 +633,13 @@ class Handoff {
     return this._mainConfigFilePath;
   }
 
+  /**
+   * Gets the selected profile config file path if one exists.
+   */
+  getProfileConfigFilePath(): string | undefined {
+    return this._profileConfigFilePath;
+  }
+
   getProfile(): string | undefined {
     return this._profile;
   }
@@ -699,14 +697,20 @@ export type {
   SourceFormat,
   RendererKind,
 } from './catalog';
-export { defineAssetStorage } from './registry/asset-storage/define';
+export { defineStorageProvider } from './registry/asset-storage/define';
 export type {
-  AssetStorage,
-  AssetStorageContext,
-  AssetStorageFactory,
-  AssetStorageInput,
-  AssetStorageReadResult,
+  StorageProvider,
+  StorageProviderContext,
+  StorageProviderFactory,
+  StorageInput,
+  StorageReadResult,
+  AssetUpload,
+  AssetUploadInput,
 } from './registry/asset-storage/types';
+export { defineEmailProvider } from './registry/email/define';
+export type { EmailMessage, EmailProvider, EmailProviderContext, EmailProviderFactory } from './registry/email/types';
+export { defineAiProvider } from './ai/define';
+export type { AiProvider, AiProviderContext, AiProviderFactory } from './ai/types';
 
 // Export transformers and types from handoff-core
 export { Transformers as CoreTransformers, TransformerUtils as CoreTransformerUtils, Types as CoreTypes } from 'handoff-core';

package/src/nav/index.ts

@@ -89,6 +89,6 @@ export interface NavData {
 export { getNavData } from './resolver';
 export type { GetNavDataInput } from './resolver';
 export { getWorkspaceNavData } from './workspace';
-export type { WorkspaceNavAdapterOptions, WorkspaceNavLoaders } from './workspace';
+export type { WorkspaceNavOptions, WorkspaceNavLoaders } from './workspace';
 export { getRegistryNavData } from './registry';
-export type { RegistryNavAdapterOptions, RegistryNavRecords } from './registry';
+export type { RegistryNavOptions, RegistryNavRecords } from './registry';

package/src/nav/registry.ts

@@ -9,7 +9,7 @@ export interface RegistryNavRecords {
   tokenSets: NavTokenSet[];
 }
 
-export interface RegistryNavAdapterOptions {
+export interface RegistryNavOptions {
   shell: SectionLink[];
   load: NavLoad;
   basePath?: string;
@@ -18,8 +18,8 @@ export interface RegistryNavAdapterOptions {
 
 const emptyRecords = (): RegistryNavRecords => ({ components: [], patterns: [], pages: [], tokenSets: [] });
 
-/** Registry adapter: shell-only initial load, or one best-effort runtime-record fetch on refresh. */
-export const getRegistryNavData = async (options: RegistryNavAdapterOptions): Promise<NavData> => {
+/** Registry nav data: shell-only initial load, or one best-effort runtime-record fetch on refresh. */
+export const getRegistryNavData = async (options: RegistryNavOptions): Promise<NavData> => {
   let records = emptyRecords();
   if (options.load === 'refresh') {
     try {

package/src/nav/workspace.ts

@@ -14,7 +14,7 @@ export interface WorkspaceNavLoaders {
   tokenSets: () => Awaitable<NavTokenSet[]>;
 }
 
-export interface WorkspaceNavAdapterOptions {
+export interface WorkspaceNavOptions {
   docRoot: string;
   workingPagesDir?: string;
   basePath?: string;
@@ -43,8 +43,8 @@ const markdownTitle = (id: string, docRoot: string, workingPagesDir?: string): s
   return undefined;
 };
 
-/** Workspace/static adapter: live filesystem shell plus best-effort local snapshot loaders. */
-export const getWorkspaceNavData = async (options: WorkspaceNavAdapterOptions): Promise<NavData> => {
+/** Workspace/static nav data: live filesystem shell plus best-effort local snapshot loaders. */
+export const getWorkspaceNavData = async (options: WorkspaceNavOptions): Promise<NavData> => {
   const [loadedComponents, patterns, pages, loadedTokenSets] = await Promise.all([
     safeLoad(options.loaders.components),
     safeLoad(options.loaders.patterns),

package/src/pipeline/README.md

@@ -7,7 +7,7 @@ Handles the end-to-end Figma data pipeline: authentication, extraction, token ge
 | File | Purpose |
 |------|---------|
 | `index.ts` | Main `pipeline()` orchestrator and barrel re-exports |
-| `figma.ts` | `validateFigmaAuth()` — interactive credential prompting; `figmaExtract()` — Figma data extraction |
+| `figma.ts` | `resolveFigmaConnection()` — Figma values from `integrations.figma` and their variable names; `validateFigmaAuth()` — in a terminal, asks for an empty value and can save it to the profile env file, otherwise throws `HandoffConfigError`; `figmaExtract()` — Figma data extraction |
 | `styles.ts` | `buildStyles()` — design token transformers; `buildCustomFonts()` — font zipping |
 | `components.ts` | `buildComponents()` — component preview generation |
 | `documentation.ts` | `createDocumentationObject()` — Figma data extraction into a documentation object with assets and SVG sprites |

package/src/pipeline/figma.ts

@@ -4,29 +4,74 @@ import { Types as HandoffTypes } from 'handoff-core';
 import * as stream from 'node:stream';
 import path from 'path';
 import Handoff from '..';
+import { HandoffConfigError } from '../config/errors';
+import { configEnvName } from '../config/resolve-env';
+import type { ResolvedConfig } from '../types/config';
 import { Logger } from '../utils/logger';
 import { zipAssets } from './archive';
 import { createDocumentationObject } from './documentation';
 
+/** Figma values resolved at config load, with the variable names they come from. */
+export type FigmaConnection = {
+  projectId: string;
+  accessToken: string;
+  /** Unset when the config gives a literal file ID. */
+  projectIdEnv?: string;
+  accessTokenEnv?: string;
+};
+
+export const resolveFigmaConnection = (config: ResolvedConfig | null | undefined): FigmaConnection => {
+  const figma = config?.integrations?.figma;
+  return {
+    projectId: figma?.projectId?.trim() || '',
+    accessToken: figma?.accessToken?.trim() || '',
+    projectIdEnv: configEnvName(config, 'integrations.figma.projectId'),
+    accessTokenEnv: configEnvName(config, 'integrations.figma.accessToken'),
+  };
+};
+
+const describeSource = (envName: string | undefined, configPath: string): string =>
+  envName ? `${envName} (${configPath})` : configPath;
+
+/** Replaces each variable that the file already sets and appends the others. */
+const saveEnvValues = async (filePath: string, values: Record<string, string>): Promise<void> => {
+  const lines = fs.existsSync(filePath) ? (await fs.readFile(filePath, 'utf8')).split(/\r?\n/) : [];
+  while (lines.length && !lines[lines.length - 1].trim()) lines.pop();
+  for (const [name, value] of Object.entries(values)) {
+    const line = `${name}="${value}"`;
+    const index = lines.findIndex((existing) => new RegExp(`^\\s*(export\\s+)?${name}\\s*=`).test(existing));
+    if (index === -1) lines.push(line);
+    else lines[index] = line;
+  }
+  await fs.writeFile(filePath, `${lines.join('\n')}\n`);
+};
+
 /**
- * Validate the figma auth tokens.
- * Prompts the user interactively if credentials are missing.
+ * Makes sure that `fetch` has a Figma file ID and access token. In a terminal, it asks for an empty
+ * value and can save it to the env file of the selected profile. Without a terminal, it throws
+ * `HandoffConfigError`.
  */
 export const validateFigmaAuth = async (handoff: Handoff): Promise<void> => {
-  let DEV_ACCESS_TOKEN = handoff.config.dev_access_token;
-  let FIGMA_PROJECT_ID = handoff.config.figma_project_id;
+  const connection = resolveFigmaConnection(handoff.config);
+  let { projectId, accessToken } = connection;
 
-  if (DEV_ACCESS_TOKEN && FIGMA_PROJECT_ID) {
+  if (projectId && accessToken) {
     return;
   }
 
-  let missingEnvVars = false;
+  const profile = handoff.getProfile();
+  if (!process.stdin.isTTY) {
+    const missing = [
+      !accessToken && describeSource(connection.accessTokenEnv, 'integrations.figma.accessToken'),
+      !projectId && describeSource(connection.projectIdEnv, 'integrations.figma.projectId'),
+    ].filter(Boolean);
+    throw new HandoffConfigError(`Figma is not configured (profile "${profile ?? 'default'}"). Set ${missing.join(' and ')}.`);
+  }
 
-  if (!DEV_ACCESS_TOKEN) {
-    missingEnvVars = true;
+  if (!accessToken) {
     p.log.warn(
-      `Figma developer access token not found. You can supply it as an environment variable or .env file at HANDOFF_DEV_ACCESS_TOKEN.\n` +
-      `Use these instructions to generate them: https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens`
+      `Figma access token not found. Set ${describeSource(connection.accessTokenEnv, 'integrations.figma.accessToken')}.\n` +
+        `Use these instructions to generate one: https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens`
     );
     const token = await p.password({
       message: 'Figma Developer Key:',
@@ -35,68 +80,55 @@ export const validateFigmaAuth = async (handoff: Handoff): Promise<void> => {
       p.cancel('Authentication cancelled.');
       process.exit(0);
     }
-    DEV_ACCESS_TOKEN = token as string;
+    accessToken = (token as string).trim();
   }
 
-  if (!FIGMA_PROJECT_ID) {
-    missingEnvVars = true;
+  if (!projectId) {
     p.log.warn(
-      `Figma project ID not found. Provide HANDOFF_FIGMA_PROJECT_ID via environment variable or .env file.\n` +
-      `Find it in your Figma file URL (e.g., figma.com/file/{PROJECT_ID}/...).`
+      `Figma project ID not found. Set ${describeSource(connection.projectIdEnv, 'integrations.figma.projectId')}.\n` +
+        `Find it in your Figma file URL (e.g., figma.com/file/{PROJECT_ID}/...).`
     );
-    const projectId = await p.text({
+    const value = await p.text({
       message: 'Figma Project Id:',
       validate: (value) => {
         if (!value.trim()) return 'Project ID is required';
       },
     });
-    if (p.isCancel(projectId)) {
+    if (p.isCancel(value)) {
       p.cancel('Authentication cancelled.');
       process.exit(0);
     }
-    FIGMA_PROJECT_ID = projectId as string;
+    projectId = (value as string).trim();
   }
 
-  if (missingEnvVars) {
-    p.log.info(`To simplify future runs, we can save these variables to a local .env file.`);
+  const values: Record<string, string> = {};
+  if (!connection.accessToken && connection.accessTokenEnv) values[connection.accessTokenEnv] = accessToken;
+  if (!connection.projectId && connection.projectIdEnv) values[connection.projectIdEnv] = projectId;
 
-    const writeEnvFile = await p.confirm({
-      message: 'Write environment variables to .env file?',
+  const envFileName = profile ? `.env.${profile}` : '.env';
+  if (Object.keys(values).length) {
+    const save = await p.confirm({
+      message: `Save ${Object.keys(values).join(' and ')} to ${envFileName} for future runs?`,
       initialValue: true,
     });
 
-    if (p.isCancel(writeEnvFile) || writeEnvFile === false) {
-      p.log.info(`Skipped .env file creation. Please provide these variables manually.`);
+    if (p.isCancel(save) || save === false) {
+      p.log.info(`Skipped saving. Set these variables before the next run.`);
     } else {
-      const envFilePath = path.resolve(handoff.workingPath, '.env');
-      const envFileContent = `
-HANDOFF_DEV_ACCESS_TOKEN="${DEV_ACCESS_TOKEN}"
-HANDOFF_FIGMA_PROJECT_ID="${FIGMA_PROJECT_ID}"
-`;
-
       try {
-        const fileExists = await fs
-          .access(envFilePath)
-          .then(() => true)
-          .catch(() => false);
-
-        if (fileExists) {
-          await fs.appendFile(envFilePath, envFileContent);
-          p.log.success(
-            `The .env file was found and updated with new content. Since these are sensitive variables, please do not commit this file.`
-          );
-        } else {
-          await fs.writeFile(envFilePath, envFileContent.replace(/^\s*[\r\n]/gm, ''));
-          p.log.success(`Created .env file. Do not commit sensitive variables.`);
-        }
+        await saveEnvValues(path.resolve(handoff.workingPath, envFileName), values);
+        const secretNote = connection.accessTokenEnv && values[connection.accessTokenEnv] ? ' It contains a secret, so do not commit it.' : '';
+        p.log.success(`Saved to ${envFileName}.${secretNote}`);
       } catch (error) {
-        Logger.error('Error handling the .env file:', error);
+        Logger.error(`Could not save ${envFileName}:`, error);
       }
     }
   }
 
-  handoff.config.dev_access_token = DEV_ACCESS_TOKEN;
-  handoff.config.figma_project_id = FIGMA_PROJECT_ID;
+  handoff.config.integrations = {
+    ...handoff.config.integrations,
+    figma: { ...handoff.config.integrations?.figma, projectId, accessToken },
+  };
 };
 
 /**
@@ -105,13 +137,26 @@ HANDOFF_FIGMA_PROJECT_ID="${FIGMA_PROJECT_ID}"
 export const figmaExtract = async (handoff: Handoff): Promise<HandoffTypes.IDocumentationObject> => {
   Logger.success(`Starting Figma data extraction.`);
 
-  await fs.emptyDir(handoff.getOutputPath());
+  // The export directory can hold other files, so remove only what fetch writes.
+  const outputPath = handoff.getOutputPath();
+  await Promise.all(
+    [
+      handoff.getTokensFilePath(),
+      handoff.getVariablesFilePath(),
+      handoff.getIconsZipFilePath(),
+      handoff.getLogosZipFilePath(),
+      path.join(outputPath, 'tokens-map.json'),
+      path.join(outputPath, 'fonts'),
+    ].map((entry) => fs.remove(entry))
+  );
+  await fs.ensureDir(outputPath);
 
   const documentationObject = await createDocumentationObject(handoff);
+  const createZipFiles = process.env.HANDOFF_CREATE_ASSETS_ZIP_FILES !== 'false';
 
   await Promise.all([
     fs.writeJSON(handoff.getTokensFilePath(), documentationObject, { spaces: 2 }),
-    ...(!process.env.HANDOFF_CREATE_ASSETS_ZIP_FILES || process.env.HANDOFF_CREATE_ASSETS_ZIP_FILES !== 'false'
+    ...(createZipFiles
       ? [
           zipAssets(documentationObject.assets.icons, fs.createWriteStream(handoff.getIconsZipFilePath())).then((writeStream) =>
             stream.promises.finished(writeStream)
@@ -123,6 +168,10 @@ export const figmaExtract = async (handoff: Handoff): Promise<HandoffTypes.IDocu
       : []),
   ]);
 
+  if (!createZipFiles) {
+    return documentationObject;
+  }
+
   // define the output folder
   const outputFolder = path.resolve(handoff.modulePath, '.handoff', `${handoff.getProjectId()}`, 'public');
 

package/src/pipeline/styles.ts

@@ -29,7 +29,7 @@ export const buildCustomFonts = async (handoff: Handoff, documentationObject: Ha
     if (fs.existsSync(fontDirName)) {
       const stream = fs.createWriteStream(path.join(fontLocation, `${name}.zip`));
       await zip(fontDirName, stream);
-      const fontsFolder = path.resolve(handoff.workingPath, handoff.exportsDirectory, handoff.getProjectId(), 'fonts');
+      const fontsFolder = path.join(handoff.getOutputPath(), 'fonts');
       if (!fs.existsSync(fontsFolder)) {
         fs.mkdirSync(fontsFolder);
       }

package/src/pipeline/validation.ts

@@ -3,13 +3,13 @@ import { Logger } from '../utils/logger';
 /**
  * Validates that the Node.js runtime meets the minimum version requirements.
  *
- * @throws {Error} If Node.js version is below 16.
+ * @throws {Error} If Node.js version is below 22.
  */
 export const validateHandoffRequirements = async () => {
   let requirements = false;
   const result = process.versions;
   if (result && result.node) {
-    if (parseInt(result.node) >= 16) {
+    if (parseInt(result.node) >= 22) {
       requirements = true;
     }
   } else {
@@ -18,7 +18,7 @@ export const validateHandoffRequirements = async () => {
   if (!requirements) {
     Logger.error('Handoff installation failed.');
     Logger.warn(
-      '- Please update node to at least Node 16 https://nodejs.org/en/download. \n- You can read more about installing handoff at https://www.handoff.com/docs/'
+      '- Please update node to at least Node 22 https://nodejs.org/en/download. \n- You can read more about installing handoff at https://www.handoff.com/docs/'
     );
     throw new Error('Could not run handoff');
   }

package/src/providers.ts

@@ -0,0 +1,18 @@
+/**
+ * Define helpers for custom server modules: storage, email and AI providers. This entry point has no
+ * runtime dependencies, so a module that imports it does not pull the CLI into the registry bundle.
+ */
+export { defineAiProvider } from './ai/define';
+export type { AiProvider, AiProviderContext, AiProviderFactory } from './ai/types';
+export { defineStorageProvider } from './registry/asset-storage/define';
+export type {
+  StorageProvider,
+  StorageProviderContext,
+  StorageProviderFactory,
+  StorageInput,
+  StorageReadResult,
+  AssetUpload,
+  AssetUploadInput,
+} from './registry/asset-storage/types';
+export { defineEmailProvider } from './registry/email/define';
+export type { EmailMessage, EmailProvider, EmailProviderContext, EmailProviderFactory } from './registry/email/types';

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

@@ -1,15 +1,15 @@
 /**
- * Typed identity helper for custom asset storage adapters (mirrors `defineCatalogItem`): a consumer
+ * Typed identity helper for custom asset storage providers (mirrors `defineCatalogItem`): a consumer
  * default-exports its result from a **server-only** module and points
  * `runtime.registry.assetStorage.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 adapter object, or a factory `(context) => AssetStorage` when it needs its options/env.
+ * may be the provider object, or a factory `(context) => StorageProvider` when it needs its options/env.
  */
 
-import type { AssetStorage, AssetStorageFactory } from './types';
+import type { StorageProvider, StorageProviderFactory } from './types';
 
-export function defineAssetStorage(adapter: AssetStorage): AssetStorage;
-export function defineAssetStorage(factory: AssetStorageFactory): AssetStorageFactory;
-export function defineAssetStorage(input: AssetStorage | AssetStorageFactory): AssetStorage | AssetStorageFactory {
+export function defineStorageProvider(provider: StorageProvider): StorageProvider;
+export function defineStorageProvider(factory: StorageProviderFactory): StorageProviderFactory;
+export function defineStorageProvider(input: StorageProvider | StorageProviderFactory): StorageProvider | StorageProviderFactory {
   return input;
 }

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

@@ -2,74 +2,75 @@
  * Asset storage settings resolution.
  *
  * `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/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.
+ * `database` inline default or a `custom` module. The build bakes the provider, the module location,
+ * and the options. An option literal is baked as it is. An environment reference stays `{ $env }`
+ * and is resolved at request time, before the custom provider factory runs.
  */
 
+import { HandoffConfigError } from '../../config/errors';
 import type { ResolvedConfig } from '../../types/config';
 import type { AssetStorageProvider } from '../db/schema';
 
-/** Which adapter implementation is active. */
-export type AssetStorageAdapterKind = 'database' | 'vercel-blob' | 'custom';
-
 /** The raw, authored settings block (a structural copy of the config type, resolvable from bake). */
 export interface AssetStorageSettings {
-  adapter?: AssetStorageAdapterKind;
+  provider?: AssetStorageProvider;
   module?: string;
-  tokenEnv?: string;
   maxInlineBytes?: number;
   options?: Record<string, unknown>;
 }
 
-/** Default adapter when none is configured. */
-export const DEFAULT_ASSET_STORAGE_ADAPTER: AssetStorageAdapterKind = 'database';
+const PROVIDERS: readonly AssetStorageProvider[] = ['database', 'custom'];
 
-/** Default env-var name holding the Vercel Blob read/write token. */
-export const DEFAULT_BLOB_TOKEN_ENV = 'BLOB_READ_WRITE_TOKEN';
+export const DEFAULT_ASSET_STORAGE_PROVIDER: AssetStorageProvider = 'database';
 
 /** Default max bytes kept inline in Postgres `bytea` (4 MB, under Vercel's ~4.5 MB function limit). */
 export const DEFAULT_MAX_INLINE_BYTES = 4 * 1024 * 1024;
 
 /** Fully resolved asset storage settings. */
 export interface ResolvedAssetStorage {
-  /** The active adapter implementation. */
-  adapterKind: AssetStorageAdapterKind;
-  /** Provider id recorded on blob rows written by the active adapter (drives read resolution). */
+  /** Recorded on each new blob row as its storage provider. */
   provider: AssetStorageProvider;
-  /** For `custom`: the server-only adapter module path. */
+  /** For `custom`: the server-only provider module path. */
   module?: string;
-  /** For `vercel-blob`: the env-var name holding the token. */
-  tokenEnv: string;
   /** For `database`: the inline-content size ceiling. */
   maxInlineBytes: number;
-  /** Non-secret adapter options. */
+  /** Provider options: literals and `{ $env }` references, never secret values. */
   options: Record<string, unknown>;
 }
 
-/** The stable provider id recorded on blobs for a custom adapter (single custom provider at a time). */
-const customProviderId = (options: Record<string, unknown>): AssetStorageProvider => {
-  const id = typeof options.providerId === 'string' && options.providerId.trim() ? options.providerId.trim() : 'custom';
-  return id;
-};
-
 /** Resolve raw asset storage settings into a fully-defaulted shape. */
 export const resolveAssetStorageSettings = (settings: AssetStorageSettings | null | undefined): ResolvedAssetStorage => {
-  const adapterKind = settings?.adapter ?? DEFAULT_ASSET_STORAGE_ADAPTER;
+  const provider = settings?.provider ?? DEFAULT_ASSET_STORAGE_PROVIDER;
   const options = settings?.options ?? {};
-  const tokenEnv = settings?.tokenEnv?.trim() || DEFAULT_BLOB_TOKEN_ENV;
   const maxInlineBytes =
     typeof settings?.maxInlineBytes === 'number' && settings.maxInlineBytes > 0 ? settings.maxInlineBytes : DEFAULT_MAX_INLINE_BYTES;
 
-  const provider: AssetStorageProvider =
-    adapterKind === 'vercel-blob' ? 'vercel-blob' : adapterKind === 'custom' ? customProviderId(options) : 'database';
-
-  return { adapterKind, provider, module: settings?.module?.trim() || undefined, tokenEnv, maxInlineBytes, options };
+  return { provider, module: settings?.module?.trim() || undefined, maxInlineBytes, options };
 };
 
-/** Resolve the active asset storage settings from a loaded config (CLI/build side). */
-export const resolveAssetStorageFromConfig = (config: ResolvedConfig | null | undefined): ResolvedAssetStorage =>
-  resolveAssetStorageSettings({
-    ...config?.runtime?.registry?.assetStorage,
-    tokenEnv: config?.runtime?.registry?.assetStorage?.token?.$env,
-  });
+/** Resolve and validate the asset storage block from a loaded config (CLI/build side). An unusable block fails the build. */
+export const resolveAssetStorageFromConfig = (config: ResolvedConfig | null | undefined): ResolvedAssetStorage => {
+  const settings = config?.runtime?.registry?.assetStorage as Record<string, unknown> | undefined;
+  const fail = (problem: string): never => {
+    throw new HandoffConfigError(`Config "runtime.registry.assetStorage": ${problem}`);
+  };
+
+  const provider = settings?.provider ?? DEFAULT_ASSET_STORAGE_PROVIDER;
+  if (!PROVIDERS.includes(provider as AssetStorageProvider)) {
+    fail(`unknown provider ${JSON.stringify(provider)}. Use "database" or "custom".`);
+  }
+  const options = settings?.options;
+  if (options !== undefined && (options === null || typeof options !== 'object' || Array.isArray(options))) {
+    fail('"options" must be an object.');
+  }
+  const module = settings?.module;
+  if (provider === 'custom' && (typeof module !== 'string' || !module.trim())) {
+    fail('provider "custom" needs a "module" that default-exports a defineStorageProvider() result.');
+  }
+  const maxInlineBytes = settings?.maxInlineBytes;
+  if (maxInlineBytes !== undefined && (typeof maxInlineBytes !== 'number' || !Number.isInteger(maxInlineBytes) || maxInlineBytes <= 0)) {
+    fail('"maxInlineBytes" must be a positive whole number.');
+  }
+
+  return resolveAssetStorageSettings(settings as AssetStorageSettings | undefined);
+};