handoff-app 2.0.0-9 → 2.0.0

package/dist/config/resolve-env.js

@@ -8,11 +8,32 @@ const isPlainObject_1 = __importDefault(require("lodash/isPlainObject"));
 const logger_1 = require("../utils/logger");
 const from_env_1 = require("./from-env");
 const errors_1 = require("./errors");
-exports.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) => 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, path, prefix = false) => {
+    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. */
+exports.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) => exports.DEFERRED_PATHS.some((deferred) => pathMatches(deferred, path));
+const isUnderDeferredPrefix = (path) => DEFERRED_PREFIXES.some((prefix) => pathMatches(`${prefix}.*`, path, true));
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const ALIASES = {
     HANDOFF_REGISTRY_URL: 'HANDOFF_CLOUD_URL',
@@ -44,17 +65,12 @@ const resolveConfigEnv = (config, profile, defaults) => {
     };
     const walk = (value, path, seed) => {
         var _a;
-        const deferred = exports.DEFERRED_PATHS.has(path);
+        const deferred = isDeferred(path);
         const secret = SECRET_PATHS.has(path);
         if ((secret || deferred) && value !== undefined && !(0, from_env_1.isEnvReference)(value)) {
             fail(path, 'Expected an environment reference, such as { $env: "VARIABLE_NAME" }. Literal values are not allowed.');
         }
         if ((0, from_env_1.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.');
             }
@@ -63,7 +79,7 @@ const resolveConfigEnv = (config, profile, defaults) => {
             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/dist/config/runtime.js

@@ -50,7 +50,7 @@ const evaluateDeclaration = (filePath, handoffModulePath) => {
         write: false,
         platform: 'node',
         format: 'cjs',
-        target: 'node16',
+        target: 'node22',
         logLevel: 'silent',
         jsx: 'automatic',
         external: ['react', 'react-dom', 'handoff-app'],

package/dist/index.d.ts

@@ -83,7 +83,7 @@ declare class Handoff {
     private profilesWithoutConfig;
     init(configOverride?: Partial<Config>): Handoff;
     reload(): Handoff;
-    preRunner(validate?: boolean): Handoff;
+    preRunner(): Handoff;
     fetch(): Promise<Handoff>;
     component(name: string | null): Promise<Handoff>;
     pattern(): Promise<Handoff>;
@@ -186,10 +186,7 @@ declare class Handoff {
      */
     getDocumentationObject(): Promise<CoreTypes.IDocumentationObject | undefined>;
     getRunner(): Promise<ReturnType<typeof 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;
     /**
      * Gets the output path for the current project
@@ -236,6 +233,10 @@ declare class Handoff {
      * Gets the selected main config file path if one exists.
      */
     getMainConfigFilePath(): string | undefined;
+    /**
+     * Gets the selected profile config file path if one exists.
+     */
+    getProfileConfigFilePath(): string | undefined;
     getProfile(): string | undefined;
     /**
      * True for the base config file and for the profile file merged onto it. Both carry project-wide
@@ -260,7 +261,11 @@ export { defineConfig } from './config';
 export { fromEnv } from './config/from-env';
 export type { EnvValue, EnvSecret, RuntimeEnvReference } from './config/from-env';
 export type { CatalogItem, CatalogItemEntries, CatalogItemInput, CatalogItemMeta, CatalogPreview, CompositionRef, Preview, SourceDescriptor, SourceFormat, RendererKind, } from './catalog';
-export { defineAssetStorage } from './registry/asset-storage/define';
-export type { AssetStorage, AssetStorageContext, AssetStorageFactory, AssetStorageInput, AssetStorageReadResult, } from './registry/asset-storage/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';
+export { defineAiProvider } from './ai/define';
+export type { AiProvider, AiProviderContext, AiProviderFactory } from './ai/types';
 export { Transformers as CoreTransformers, TransformerUtils as CoreTransformerUtils, Types as CoreTypes } from 'handoff-core';
 export default Handoff;

package/dist/index.js

@@ -35,7 +35,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CoreTypes = exports.CoreTransformerUtils = exports.CoreTransformers = exports.defineAssetStorage = exports.fromEnv = exports.defineConfig = void 0;
+exports.CoreTypes = exports.CoreTransformerUtils = exports.CoreTransformers = exports.defineAiProvider = exports.defineEmailProvider = exports.defineStorageProvider = exports.fromEnv = exports.defineConfig = void 0;
 require("./config/env");
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const handoff_core_1 = require("handoff-core");
@@ -46,6 +46,7 @@ const make_1 = require("./cli/make");
 const store_1 = require("./cli/auth/store");
 const config_1 = require("./config");
 const pipeline_1 = __importStar(require("./pipeline"));
+const figma_1 = require("./pipeline/figma");
 const content_kinds_1 = require("./registry/content-kinds");
 const store_2 = require("./store");
 const builder_1 = __importStar(require("./transformers/preview/component/builder"));
@@ -193,13 +194,10 @@ class Handoff {
         this.construct(this._options);
         return this;
     }
-    preRunner(validate) {
+    preRunner() {
         if (!this.config) {
             throw Error('Handoff not initialized');
         }
-        if (validate) {
-            this.config = (0, config_1.validateConfig)(this.config);
-        }
         return this;
     }
     fetch() {
@@ -504,12 +502,8 @@ class Handoff {
             if (!!this._handoffRunner) {
                 return this._handoffRunner;
             }
-            const apiCredentials = {
-                projectId: this.config.figma_project_id,
-                accessToken: this.config.dev_access_token,
-            };
-            // Initialize the provider
-            const provider = handoff_core_1.Providers.RestApiProvider(apiCredentials);
+            const { projectId, accessToken } = (0, figma_1.resolveFigmaConnection)(this.config);
+            const provider = handoff_core_1.Providers.RestApiProvider({ projectId, accessToken });
             this._handoffRunner = (0, handoff_core_1.Handoff)(provider, {
                 options: {
                     transformer: this.runtimeConfig.options,
@@ -531,16 +525,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() {
-        var _a;
-        if ((_a = this.config) === null || _a === void 0 ? void 0 : _a.figma_project_id) {
-            return this.config.figma_project_id;
-        }
-        // Fallback to filesystem-safe transformation of working path
         return (0, path_3.generateFilesystemSafeId)(this.workingPath);
     }
     /**
@@ -548,7 +534,7 @@ class Handoff {
      * @returns {string} The absolute path to the output directory
      */
     getOutputPath() {
-        return path_1.default.resolve(this.workingPath, this.exportsDirectory, this.getProjectId());
+        return path_1.default.resolve(this.workingPath, this.exportsDirectory);
     }
     /**
      * Gets the path to the tokens.json file
@@ -607,6 +593,12 @@ class Handoff {
     getMainConfigFilePath() {
         return this._mainConfigFilePath;
     }
+    /**
+     * Gets the selected profile config file path if one exists.
+     */
+    getProfileConfigFilePath() {
+        return this._profileConfigFilePath;
+    }
     getProfile() {
         return this._profile;
     }
@@ -651,7 +643,11 @@ Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function
 var from_env_1 = require("./config/from-env");
 Object.defineProperty(exports, "fromEnv", { enumerable: true, get: function () { return from_env_1.fromEnv; } });
 var define_1 = require("./registry/asset-storage/define");
-Object.defineProperty(exports, "defineAssetStorage", { enumerable: true, get: function () { return define_1.defineAssetStorage; } });
+Object.defineProperty(exports, "defineStorageProvider", { enumerable: true, get: function () { return define_1.defineStorageProvider; } });
+var define_2 = require("./registry/email/define");
+Object.defineProperty(exports, "defineEmailProvider", { enumerable: true, get: function () { return define_2.defineEmailProvider; } });
+var define_3 = require("./ai/define");
+Object.defineProperty(exports, "defineAiProvider", { enumerable: true, get: function () { return define_3.defineAiProvider; } });
 // Export transformers and types from handoff-core
 var handoff_core_2 = require("handoff-core");
 Object.defineProperty(exports, "CoreTransformers", { enumerable: true, get: function () { return handoff_core_2.Transformers; } });

package/dist/nav/index.d.ts

@@ -78,6 +78,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/dist/nav/registry.d.ts

@@ -5,11 +5,11 @@ export interface RegistryNavRecords {
     pages: NavPageRecord[];
     tokenSets: NavTokenSet[];
 }
-export interface RegistryNavAdapterOptions {
+export interface RegistryNavOptions {
     shell: SectionLink[];
     load: NavLoad;
     basePath?: string;
     fetchRecords: () => Promise<RegistryNavRecords>;
 }
-/** Registry adapter: shell-only initial load, or one best-effort runtime-record fetch on refresh. */
-export declare const getRegistryNavData: (options: RegistryNavAdapterOptions) => Promise<NavData>;
+/** Registry nav data: shell-only initial load, or one best-effort runtime-record fetch on refresh. */
+export declare const getRegistryNavData: (options: RegistryNavOptions) => Promise<NavData>;

package/dist/nav/registry.js

@@ -13,7 +13,7 @@ exports.getRegistryNavData = void 0;
 const menu_shell_1 = require("../utils/menu-shell");
 const resolver_1 = require("./resolver");
 const emptyRecords = () => ({ components: [], patterns: [], pages: [], tokenSets: [] });
-/** Registry adapter: shell-only initial load, or one best-effort runtime-record fetch on refresh. */
+/** Registry nav data: shell-only initial load, or one best-effort runtime-record fetch on refresh. */
 const getRegistryNavData = (options) => __awaiter(void 0, void 0, void 0, function* () {
     var _a;
     let records = emptyRecords();

package/dist/nav/workspace.d.ts

@@ -6,13 +6,13 @@ export interface WorkspaceNavLoaders {
     pages: () => Awaitable<NavPageRecord[]>;
     tokenSets: () => Awaitable<NavTokenSet[]>;
 }
-export interface WorkspaceNavAdapterOptions {
+export interface WorkspaceNavOptions {
     docRoot: string;
     workingPagesDir?: string;
     basePath?: string;
     load?: NavLoad;
     loaders: WorkspaceNavLoaders;
 }
-/** Workspace/static adapter: live filesystem shell plus best-effort local snapshot loaders. */
-export declare const getWorkspaceNavData: (options: WorkspaceNavAdapterOptions) => Promise<NavData>;
+/** Workspace/static nav data: live filesystem shell plus best-effort local snapshot loaders. */
+export declare const getWorkspaceNavData: (options: WorkspaceNavOptions) => Promise<NavData>;
 export {};

package/dist/nav/workspace.js

@@ -64,7 +64,7 @@ const markdownTitle = (id, docRoot, workingPagesDir) => {
     }
     return undefined;
 };
-/** Workspace/static adapter: live filesystem shell plus best-effort local snapshot loaders. */
+/** Workspace/static nav data: live filesystem shell plus best-effort local snapshot loaders. */
 const getWorkspaceNavData = (options) => __awaiter(void 0, void 0, void 0, function* () {
     var _a;
     const [loadedComponents, patterns, pages, loadedTokenSets] = yield Promise.all([

package/dist/pipeline/figma.d.ts

@@ -1,8 +1,19 @@
 import { Types as HandoffTypes } from 'handoff-core';
 import Handoff from '..';
+import type { ResolvedConfig } from '../types/config';
+/** 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 declare const resolveFigmaConnection: (config: ResolvedConfig | null | undefined) => FigmaConnection;
 /**
- * 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 declare const validateFigmaAuth: (handoff: Handoff) => Promise<void>;
 /**

package/dist/pipeline/figma.js

@@ -35,29 +35,66 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.figmaExtract = exports.validateFigmaAuth = void 0;
+exports.figmaExtract = exports.validateFigmaAuth = exports.resolveFigmaConnection = void 0;
 const p = __importStar(require("@clack/prompts"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const stream = __importStar(require("node:stream"));
 const path_1 = __importDefault(require("path"));
+const errors_1 = require("../config/errors");
+const resolve_env_1 = require("../config/resolve-env");
 const logger_1 = require("../utils/logger");
 const archive_1 = require("./archive");
 const documentation_1 = require("./documentation");
+const resolveFigmaConnection = (config) => {
+    var _a, _b, _c;
+    const figma = (_a = config === null || config === void 0 ? void 0 : config.integrations) === null || _a === void 0 ? void 0 : _a.figma;
+    return {
+        projectId: ((_b = figma === null || figma === void 0 ? void 0 : figma.projectId) === null || _b === void 0 ? void 0 : _b.trim()) || '',
+        accessToken: ((_c = figma === null || figma === void 0 ? void 0 : figma.accessToken) === null || _c === void 0 ? void 0 : _c.trim()) || '',
+        projectIdEnv: (0, resolve_env_1.configEnvName)(config, 'integrations.figma.projectId'),
+        accessTokenEnv: (0, resolve_env_1.configEnvName)(config, 'integrations.figma.accessToken'),
+    };
+};
+exports.resolveFigmaConnection = resolveFigmaConnection;
+const describeSource = (envName, configPath) => envName ? `${envName} (${configPath})` : configPath;
+/** Replaces each variable that the file already sets and appends the others. */
+const saveEnvValues = (filePath, values) => __awaiter(void 0, void 0, void 0, function* () {
+    const lines = fs_extra_1.default.existsSync(filePath) ? (yield fs_extra_1.default.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;
+    }
+    yield fs_extra_1.default.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`.
  */
 const validateFigmaAuth = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
-    let DEV_ACCESS_TOKEN = handoff.config.dev_access_token;
-    let FIGMA_PROJECT_ID = handoff.config.figma_project_id;
-    if (DEV_ACCESS_TOKEN && FIGMA_PROJECT_ID) {
+    var _a;
+    const connection = (0, exports.resolveFigmaConnection)(handoff.config);
+    let { projectId, accessToken } = connection;
+    if (projectId && accessToken) {
         return;
     }
-    let missingEnvVars = false;
-    if (!DEV_ACCESS_TOKEN) {
-        missingEnvVars = true;
-        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`);
+    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 errors_1.HandoffConfigError(`Figma is not configured (profile "${profile !== null && profile !== void 0 ? profile : 'default'}"). Set ${missing.join(' and ')}.`);
+    }
+    if (!accessToken) {
+        p.log.warn(`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 = yield p.password({
             message: 'Figma Developer Key:',
         });
@@ -65,61 +102,50 @@ const validateFigmaAuth = (handoff) => __awaiter(void 0, void 0, void 0, functio
             p.cancel('Authentication cancelled.');
             process.exit(0);
         }
-        DEV_ACCESS_TOKEN = token;
+        accessToken = token.trim();
     }
-    if (!FIGMA_PROJECT_ID) {
-        missingEnvVars = true;
-        p.log.warn(`Figma project ID not found. Provide HANDOFF_FIGMA_PROJECT_ID via environment variable or .env file.\n` +
+    if (!projectId) {
+        p.log.warn(`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 = yield p.text({
+        const value = yield 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;
+        projectId = value.trim();
     }
-    if (missingEnvVars) {
-        p.log.info(`To simplify future runs, we can save these variables to a local .env file.`);
-        const writeEnvFile = yield p.confirm({
-            message: 'Write environment variables to .env file?',
+    const values = {};
+    if (!connection.accessToken && connection.accessTokenEnv)
+        values[connection.accessTokenEnv] = accessToken;
+    if (!connection.projectId && connection.projectIdEnv)
+        values[connection.projectIdEnv] = projectId;
+    const envFileName = profile ? `.env.${profile}` : '.env';
+    if (Object.keys(values).length) {
+        const save = yield 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_1.default.resolve(handoff.workingPath, '.env');
-            const envFileContent = `
-HANDOFF_DEV_ACCESS_TOKEN="${DEV_ACCESS_TOKEN}"
-HANDOFF_FIGMA_PROJECT_ID="${FIGMA_PROJECT_ID}"
-`;
             try {
-                const fileExists = yield fs_extra_1.default
-                    .access(envFilePath)
-                    .then(() => true)
-                    .catch(() => false);
-                if (fileExists) {
-                    yield fs_extra_1.default.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 {
-                    yield fs_extra_1.default.writeFile(envFilePath, envFileContent.replace(/^\s*[\r\n]/gm, ''));
-                    p.log.success(`Created .env file. Do not commit sensitive variables.`);
-                }
+                yield saveEnvValues(path_1.default.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_1.Logger.error('Error handling the .env file:', error);
+                logger_1.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 = Object.assign(Object.assign({}, handoff.config.integrations), { figma: Object.assign(Object.assign({}, (_a = handoff.config.integrations) === null || _a === void 0 ? void 0 : _a.figma), { projectId, accessToken }) });
 });
 exports.validateFigmaAuth = validateFigmaAuth;
 /**
@@ -127,17 +153,31 @@ exports.validateFigmaAuth = validateFigmaAuth;
  */
 const figmaExtract = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
     logger_1.Logger.success(`Starting Figma data extraction.`);
-    yield fs_extra_1.default.emptyDir(handoff.getOutputPath());
+    // The export directory can hold other files, so remove only what fetch writes.
+    const outputPath = handoff.getOutputPath();
+    yield Promise.all([
+        handoff.getTokensFilePath(),
+        handoff.getVariablesFilePath(),
+        handoff.getIconsZipFilePath(),
+        handoff.getLogosZipFilePath(),
+        path_1.default.join(outputPath, 'tokens-map.json'),
+        path_1.default.join(outputPath, 'fonts'),
+    ].map((entry) => fs_extra_1.default.remove(entry)));
+    yield fs_extra_1.default.ensureDir(outputPath);
     const documentationObject = yield (0, documentation_1.createDocumentationObject)(handoff);
+    const createZipFiles = process.env.HANDOFF_CREATE_ASSETS_ZIP_FILES !== 'false';
     yield Promise.all([
         fs_extra_1.default.writeJSON(handoff.getTokensFilePath(), documentationObject, { spaces: 2 }),
-        ...(!process.env.HANDOFF_CREATE_ASSETS_ZIP_FILES || process.env.HANDOFF_CREATE_ASSETS_ZIP_FILES !== 'false'
+        ...(createZipFiles
             ? [
                 (0, archive_1.zipAssets)(documentationObject.assets.icons, fs_extra_1.default.createWriteStream(handoff.getIconsZipFilePath())).then((writeStream) => stream.promises.finished(writeStream)),
                 (0, archive_1.zipAssets)(documentationObject.assets.logos, fs_extra_1.default.createWriteStream(handoff.getLogosZipFilePath())).then((writeStream) => stream.promises.finished(writeStream)),
             ]
             : []),
     ]);
+    if (!createZipFiles) {
+        return documentationObject;
+    }
     // define the output folder
     const outputFolder = path_1.default.resolve(handoff.modulePath, '.handoff', `${handoff.getProjectId()}`, 'public');
     // ensure output folder exists

package/dist/pipeline/styles.js

@@ -37,7 +37,7 @@ const buildCustomFonts = (handoff, documentationObject) => __awaiter(void 0, voi
         if (fs_extra_1.default.existsSync(fontDirName)) {
             const stream = fs_extra_1.default.createWriteStream(path_1.default.join(fontLocation, `${name}.zip`));
             yield (0, archive_1.zip)(fontDirName, stream);
-            const fontsFolder = path_1.default.resolve(handoff.workingPath, handoff.exportsDirectory, handoff.getProjectId(), 'fonts');
+            const fontsFolder = path_1.default.join(handoff.getOutputPath(), 'fonts');
             if (!fs_extra_1.default.existsSync(fontsFolder)) {
                 fs_extra_1.default.mkdirSync(fontsFolder);
             }

package/dist/pipeline/validation.d.ts

@@ -1,6 +1,6 @@
 /**
  * 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 declare const validateHandoffRequirements: () => Promise<void>;

package/dist/pipeline/validation.js

@@ -14,13 +14,13 @@ const logger_1 = require("../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.
  */
 const validateHandoffRequirements = () => __awaiter(void 0, void 0, void 0, function* () {
     let requirements = false;
     const result = process.versions;
     if (result && result.node) {
-        if (parseInt(result.node) >= 16) {
+        if (parseInt(result.node) >= 22) {
             requirements = true;
         }
     }
@@ -29,7 +29,7 @@ const validateHandoffRequirements = () => __awaiter(void 0, void 0, void 0, func
     }
     if (!requirements) {
         logger_1.Logger.error('Handoff installation failed.');
-        logger_1.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/');
+        logger_1.Logger.warn('- 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/dist/providers.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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/dist/providers.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineEmailProvider = exports.defineStorageProvider = exports.defineAiProvider = void 0;
+/**
+ * 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.
+ */
+var define_1 = require("./ai/define");
+Object.defineProperty(exports, "defineAiProvider", { enumerable: true, get: function () { return define_1.defineAiProvider; } });
+var define_2 = require("./registry/asset-storage/define");
+Object.defineProperty(exports, "defineStorageProvider", { enumerable: true, get: function () { return define_2.defineStorageProvider; } });
+var define_3 = require("./registry/email/define");
+Object.defineProperty(exports, "defineEmailProvider", { enumerable: true, get: function () { return define_3.defineEmailProvider; } });

package/dist/registry/asset-storage/define.d.ts

@@ -1,10 +1,10 @@
 /**
- * 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';
-export declare function defineAssetStorage(adapter: AssetStorage): AssetStorage;
-export declare function defineAssetStorage(factory: AssetStorageFactory): AssetStorageFactory;
+import type { StorageProvider, StorageProviderFactory } from './types';
+export declare function defineStorageProvider(provider: StorageProvider): StorageProvider;
+export declare function defineStorageProvider(factory: StorageProviderFactory): StorageProviderFactory;

package/dist/registry/asset-storage/define.js

@@ -1,13 +1,13 @@
 "use strict";
 /**
- * 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defineAssetStorage = defineAssetStorage;
-function defineAssetStorage(input) {
+exports.defineStorageProvider = defineStorageProvider;
+function defineStorageProvider(input) {
     return input;
 }