handoff-app 2.0.0-8 → 2.0.0

package/src/config/resolve-env.ts

@@ -4,11 +4,32 @@ import { Logger } from '../utils/logger';
 import { isEnvReference } from './from-env';
 import { HandoffConfigError } from './errors';
 
-export const DEFERRED_PATHS = new Set(['runtime.registry.databaseUrl', 'runtime.registry.assetStorage.token']);
-const SECRET_PATHS = new Set(['dev_access_token', 'devAccessToken', 'runtime.registryConnection.accessToken']);
-/** Path prefixes whose resolved contents are JSON-baked into the bundle, so a reference would bake its value. */
-const BAKED_PATHS = ['runtime.registry.assetStorage.options'];
-const isBaked = (path: string): boolean => BAKED_PATHS.some((baked) => path === baked || path.startsWith(`${baked}.`));
+/**
+ * Match a dot path against a pattern. A `*` segment matches exactly one segment, so one pattern
+ * covers every element of a list. With `prefix`, the pattern also matches anything nested under it.
+ */
+const pathMatches = (pattern: string, path: string, prefix = false): boolean => {
+  const expected = pattern.split('.');
+  const actual = path.split('.');
+  if (prefix ? expected.length > actual.length : expected.length !== actual.length) return false;
+  return expected.every((segment, index) => segment === '*' || segment === actual[index]);
+};
+
+/** Paths whose value the deployed app reads at request time, so only the variable name is stored. */
+export const DEFERRED_PATHS = [
+  'runtime.registry.database.url',
+  'runtime.registry.email.options.apiKey',
+  'runtime.registry.email.options.password',
+  'runtime.ai.connections.*.apiKey',
+];
+/**
+ * Path prefixes whose nested references the deployed app reads at request time. Literals below them
+ * are baked. `DEFERRED_PATHS` entries below them still reject literals.
+ */
+const DEFERRED_PREFIXES = ['runtime.registry.email.options', 'runtime.registry.assetStorage.options', 'runtime.ai.connections.*.options'];
+const SECRET_PATHS = new Set(['integrations.figma.accessToken', 'runtime.registryConnection.accessToken']);
+const isDeferred = (path: string): boolean => DEFERRED_PATHS.some((deferred) => pathMatches(deferred, path));
+const isUnderDeferredPrefix = (path: string): boolean => DEFERRED_PREFIXES.some((prefix) => pathMatches(`${prefix}.*`, path, true));
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const ALIASES: Record<string, string> = {
   HANDOFF_REGISTRY_URL: 'HANDOFF_CLOUD_URL',
@@ -40,20 +61,12 @@ export const resolveConfigEnv = (config: Config, profile?: string, defaults?: Co
     throw new HandoffConfigError(`Config "${path}" (profile "${profile ?? 'default'}"): ${message}`);
   };
   const walk = (value: unknown, path: string, seed?: unknown): unknown => {
-    const deferred = DEFERRED_PATHS.has(path);
+    const deferred = isDeferred(path);
     const secret = SECRET_PATHS.has(path);
     if ((secret || deferred) && value !== undefined && !isEnvReference(value)) {
       fail(path, 'Expected an environment reference, such as { $env: "VARIABLE_NAME" }. Literal values are not allowed.');
     }
     if (isEnvReference(value)) {
-      // Checked before the name, so the message names the supported pattern instead of the reference shape.
-      if (isBaked(path)) {
-        fail(
-          path,
-          'Environment references are not allowed here because the resolved value is baked into the build. ' +
-            "Put the variable name in options and read it through the adapter factory's `env` argument."
-        );
-      }
       if (typeof value.$env !== 'string' || !ENV_NAME.test(value.$env)) {
         fail(path, 'Invalid environment variable name. Use letters, digits, and underscores, starting with a letter or underscore.');
       }
@@ -62,7 +75,7 @@ export const resolveConfigEnv = (config: Config, profile?: string, defaults?: Co
       if (Object.keys(value).some((key) => key !== '$env' && key !== 'default')) {
         fail(path, `Environment variable "${name}" has an invalid reference shape.`);
       }
-      if (deferred) {
+      if (deferred || isUnderDeferredPrefix(path)) {
         if ('default' in value) fail(path, `Environment variable "${name}" cannot have a default because it is read by the deployed app.`);
         return { $env: name };
       }

package/src/config/runtime.ts

@@ -1,4 +1,5 @@
 import esbuild from 'esbuild';
+import { STYLE_IMPORT_LOADERS } from '../transformers/utils/build';
 import fs from 'fs-extra';
 import { createRequire } from 'module';
 import path from 'path';
@@ -35,7 +36,8 @@ type DeclarationResolution = {
   fileName: string;
 };
 
-const DECLARATION_EXTENSIONS = ['ts', 'js', 'cjs'] as const;
+/** `.tsx`/`.jsx` are accepted so a preview can write its `render` as JSX. */
+const DECLARATION_EXTENSIONS = ['tsx', 'ts', 'jsx', 'js', 'cjs'] as const;
 
 const getDeclarationFiles = (componentBaseName: string): string[] =>
   DECLARATION_EXTENSIONS.map((ext) => `${componentBaseName}.handoff.${ext}`);
@@ -46,7 +48,7 @@ const findPreferredDeclaration = (componentDir: string, componentBaseName: strin
   if (exactMatch) return exactMatch;
 
   const allFiles = fs.existsSync(componentDir) ? fs.readdirSync(componentDir) : [];
-  const declarationFiles = allFiles.filter((file) => /\.handoff\.(ts|js|cjs)$/.test(file)).sort((a, b) => a.localeCompare(b));
+  const declarationFiles = allFiles.filter((file) => /\.handoff\.(tsx|ts|jsx|js|cjs)$/.test(file)).sort((a, b) => a.localeCompare(b));
 
   if (!declarationFiles.length) return undefined;
 
@@ -70,10 +72,11 @@ const evaluateDeclaration = (filePath: string, handoffModulePath: string): any =
     write: false,
     platform: 'node',
     format: 'cjs',
-    target: 'node16',
+    target: 'node22',
     logLevel: 'silent',
     jsx: 'automatic',
     external: ['react', 'react-dom', 'handoff-app'],
+    loader: STYLE_IMPORT_LOADERS,
   });
 
   const code = buildResult.outputFiles?.[0]?.text;
@@ -219,7 +222,7 @@ export const initRuntimeConfig = (
     if (!declaration) {
       const declarationFiles = getDeclarationFiles(itemBaseName);
       Logger.warn(
-        `Missing catalog declaration (use .handoff.ts, .handoff.js, or .handoff.cjs; see UPGRADE.md#catalog-items): ${path.resolve(itemPath, declarationFiles.join(' or '))}`
+        `Missing catalog declaration (use .handoff.tsx, .handoff.ts, .handoff.jsx, .handoff.js, or .handoff.cjs; see UPGRADE.md#catalog-items): ${path.resolve(itemPath, declarationFiles.join(' or '))}`
       );
       continue;
     }
@@ -433,9 +436,9 @@ const injectPatternPreviews = (result: RuntimeConfig): void => {
 
       // Case 3: args present (with or without preview base) -> create synthetic preview
       let resolvedValues: Record<string, any> = {};
+      const basePreview = ref.preview ? component.previews?.[ref.preview] : undefined;
 
       if (ref.preview) {
-        const basePreview = component.previews?.[ref.preview];
         if (basePreview) {
           resolvedValues = { ...basePreview.values };
         } else {
@@ -454,6 +457,8 @@ const injectPatternPreviews = (result: RuntimeConfig): void => {
         values: resolvedValues,
         url: '',
         sourcePreview: ref.preview,
+        // The ref overrides arguments, not how the preview renders, so a base `render` still applies.
+        ...(basePreview?.render ? { render: basePreview.render } : {}),
       };
 
       ref.resolvedPreview = syntheticKey;

package/src/handlebars.ts

@@ -5,9 +5,15 @@
  * an argument type to check previews: `defineCatalogItem<BadgeArgs>`.
  */
 import { createCatalogItem } from './catalog/define';
-import type { CatalogItem, CatalogItemMeta } from './catalog/types';
+import type { CatalogItem, CatalogItemMeta, CatalogPreview as RendererPreview } from './catalog/types';
 
-export type { CatalogItem, CatalogItemMeta, CatalogPreview, CompositionRef, Preview, SourceDescriptor } from './catalog/types';
+export type { CatalogItem, CatalogItemMeta, CompositionRef, SourceDescriptor } from './catalog/types';
+
+/** A template renderer never calls a preview `render`, so declaring one is an error, not a no-op. */
+export type CatalogPreview<TArgs = Record<string, unknown>> = Omit<RendererPreview<TArgs>, 'render'> & { render?: never };
+
+/** Preview type for a Handlebars catalog item, with its argument type applied. */
+export type Preview<TItem> = TItem extends { readonly __args?: infer TArgs } ? CatalogPreview<Partial<NonNullable<TArgs>>> : never;
 
 /**
  * Declares a Handlebars catalog item. `implementation` is the path to its `.hbs` template. The

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;
 }