handoff-app 2.0.0-8 → 2.0.0

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

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

@@ -2,44 +2,34 @@
  * 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 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 declare const DEFAULT_ASSET_STORAGE_ADAPTER: AssetStorageAdapterKind;
-/** Default env-var name holding the Vercel Blob read/write token. */
-export declare const DEFAULT_BLOB_TOKEN_ENV = "BLOB_READ_WRITE_TOKEN";
+export declare const DEFAULT_ASSET_STORAGE_PROVIDER: AssetStorageProvider;
 /** Default max bytes kept inline in Postgres `bytea` (4 MB, under Vercel's ~4.5 MB function limit). */
 export declare const DEFAULT_MAX_INLINE_BYTES: number;
 /** 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>;
 }
 /** Resolve raw asset storage settings into a fully-defaulted shape. */
 export declare const resolveAssetStorageSettings: (settings: AssetStorageSettings | null | undefined) => ResolvedAssetStorage;
-/** Resolve the active asset storage settings from a loaded config (CLI/build side). */
+/** Resolve and validate the asset storage block from a loaded config (CLI/build side). An unusable block fails the build. */
 export declare const resolveAssetStorageFromConfig: (config: ResolvedConfig | null | undefined) => ResolvedAssetStorage;

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

@@ -3,37 +3,49 @@
  * 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveAssetStorageFromConfig = exports.resolveAssetStorageSettings = exports.DEFAULT_MAX_INLINE_BYTES = exports.DEFAULT_BLOB_TOKEN_ENV = exports.DEFAULT_ASSET_STORAGE_ADAPTER = void 0;
-/** Default adapter when none is configured. */
-exports.DEFAULT_ASSET_STORAGE_ADAPTER = 'database';
-/** Default env-var name holding the Vercel Blob read/write token. */
-exports.DEFAULT_BLOB_TOKEN_ENV = 'BLOB_READ_WRITE_TOKEN';
+exports.resolveAssetStorageFromConfig = exports.resolveAssetStorageSettings = exports.DEFAULT_MAX_INLINE_BYTES = exports.DEFAULT_ASSET_STORAGE_PROVIDER = void 0;
+const errors_1 = require("../../config/errors");
+const PROVIDERS = ['database', 'custom'];
+exports.DEFAULT_ASSET_STORAGE_PROVIDER = 'database';
 /** Default max bytes kept inline in Postgres `bytea` (4 MB, under Vercel's ~4.5 MB function limit). */
 exports.DEFAULT_MAX_INLINE_BYTES = 4 * 1024 * 1024;
-/** The stable provider id recorded on blobs for a custom adapter (single custom provider at a time). */
-const customProviderId = (options) => {
-    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. */
 const resolveAssetStorageSettings = (settings) => {
-    var _a, _b, _c, _d;
-    const adapterKind = (_a = settings === null || settings === void 0 ? void 0 : settings.adapter) !== null && _a !== void 0 ? _a : exports.DEFAULT_ASSET_STORAGE_ADAPTER;
+    var _a, _b, _c;
+    const provider = (_a = settings === null || settings === void 0 ? void 0 : settings.provider) !== null && _a !== void 0 ? _a : exports.DEFAULT_ASSET_STORAGE_PROVIDER;
     const options = (_b = settings === null || settings === void 0 ? void 0 : settings.options) !== null && _b !== void 0 ? _b : {};
-    const tokenEnv = ((_c = settings === null || settings === void 0 ? void 0 : settings.tokenEnv) === null || _c === void 0 ? void 0 : _c.trim()) || exports.DEFAULT_BLOB_TOKEN_ENV;
     const maxInlineBytes = typeof (settings === null || settings === void 0 ? void 0 : settings.maxInlineBytes) === 'number' && settings.maxInlineBytes > 0 ? settings.maxInlineBytes : exports.DEFAULT_MAX_INLINE_BYTES;
-    const provider = adapterKind === 'vercel-blob' ? 'vercel-blob' : adapterKind === 'custom' ? customProviderId(options) : 'database';
-    return { adapterKind, provider, module: ((_d = settings === null || settings === void 0 ? void 0 : settings.module) === null || _d === void 0 ? void 0 : _d.trim()) || undefined, tokenEnv, maxInlineBytes, options };
+    return { provider, module: ((_c = settings === null || settings === void 0 ? void 0 : settings.module) === null || _c === void 0 ? void 0 : _c.trim()) || undefined, maxInlineBytes, options };
 };
 exports.resolveAssetStorageSettings = resolveAssetStorageSettings;
-/** Resolve the active asset storage settings from a loaded config (CLI/build side). */
+/** Resolve and validate the asset storage block from a loaded config (CLI/build side). An unusable block fails the build. */
 const resolveAssetStorageFromConfig = (config) => {
-    var _a, _b, _c, _d, _e, _f;
-    return (0, exports.resolveAssetStorageSettings)(Object.assign(Object.assign({}, (_b = (_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.registry) === null || _b === void 0 ? void 0 : _b.assetStorage), { tokenEnv: (_f = (_e = (_d = (_c = config === null || config === void 0 ? void 0 : config.runtime) === null || _c === void 0 ? void 0 : _c.registry) === null || _d === void 0 ? void 0 : _d.assetStorage) === null || _e === void 0 ? void 0 : _e.token) === null || _f === void 0 ? void 0 : _f.$env }));
+    var _a, _b, _c;
+    const settings = (_b = (_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.registry) === null || _b === void 0 ? void 0 : _b.assetStorage;
+    const fail = (problem) => {
+        throw new errors_1.HandoffConfigError(`Config "runtime.registry.assetStorage": ${problem}`);
+    };
+    const provider = (_c = settings === null || settings === void 0 ? void 0 : settings.provider) !== null && _c !== void 0 ? _c : exports.DEFAULT_ASSET_STORAGE_PROVIDER;
+    if (!PROVIDERS.includes(provider)) {
+        fail(`unknown provider ${JSON.stringify(provider)}. Use "database" or "custom".`);
+    }
+    const options = settings === null || settings === void 0 ? void 0 : settings.options;
+    if (options !== undefined && (options === null || typeof options !== 'object' || Array.isArray(options))) {
+        fail('"options" must be an object.');
+    }
+    const module = settings === null || settings === void 0 ? void 0 : 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 === null || settings === void 0 ? void 0 : settings.maxInlineBytes;
+    if (maxInlineBytes !== undefined && (typeof maxInlineBytes !== 'number' || !Number.isInteger(maxInlineBytes) || maxInlineBytes <= 0)) {
+        fail('"maxInlineBytes" must be a positive whole number.');
+    }
+    return (0, exports.resolveAssetStorageSettings)(settings);
 };
 exports.resolveAssetStorageFromConfig = resolveAssetStorageFromConfig;

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

@@ -1,12 +1,12 @@
 /**
- * Server-only asset storage contract for object-backed providers (Vercel Blob + custom
- * {@link defineAssetStorage} modules), so callers need no provider-specific logic. The built-in
- * `database` provider is the inline default: bytes live in the `asset_blobs.content` bytea column,
- * read/written directly by the registry, so it needs no adapter. Object providers record a
- * `storageRef` + provider id so reads resolve back through whichever provider stored the blob.
+ * Server-only asset storage contract for custom {@link defineStorageProvider} object storage modules.
+ * The built-in `database` provider is the inline default: bytes live in the `asset_blobs.content`
+ * bytea column, read/written directly by the registry, so it needs no module. Object providers
+ * record a `storageRef` + provider id so reads resolve back through whichever provider stored the
+ * blob.
  */
 /** Input for storing one content-addressed blob. */
-export interface AssetStorageInput {
+export interface StorageInput {
     /** SHA-256 of the bytes (hex), the content identity, usable as a stable object key. */
     hash: string;
     bytes: Buffer;
@@ -17,7 +17,7 @@ export interface AssetStorageInput {
  * How a provider returns stored content: raw bytes, a readable stream, or a signed/redirect URL the
  * client can fetch directly (used to avoid routing large payloads through the serverless function).
  */
-export type AssetStorageReadResult = {
+export type StorageReadResult = {
     kind: 'bytes';
     bytes: Buffer;
     contentType?: string;
@@ -29,23 +29,43 @@ export type AssetStorageReadResult = {
     kind: 'redirect';
     url: string;
 };
-/** The pluggable storage adapter contract for object-backed asset providers. */
-export interface AssetStorage {
+/** Input for a direct upload of one blob from the CLI to storage. */
+export interface AssetUploadInput {
+    /** SHA-256 of the bytes (hex). */
+    hash: string;
+    size: number;
+    contentType: string;
+}
+/** A signed URL the CLI sends the blob to with `PUT` and the given headers. */
+export interface AssetUpload {
+    url: string;
+    headers?: Record<string, string>;
+    /** The reference to persist on the blob's `asset_blobs` row after the upload. */
+    storageRef: string;
+}
+/** The pluggable storage contract for object-backed asset providers. */
+export interface StorageProvider {
     /** Store one blob and return the reference to persist on its `asset_blobs` row. */
-    put(input: AssetStorageInput): Promise<{
+    put(input: StorageInput): Promise<{
         storageRef: string;
     }>;
+    /**
+     * Return a signed URL so the CLI uploads the blob directly to storage instead of through the
+     * registry, which avoids serverless request size limits. The URL must make storage reject bytes
+     * that do not match `hash`, for example with a signed SHA-256 checksum header.
+     */
+    createUpload?(input: AssetUploadInput): Promise<AssetUpload>;
     /** Resolve stored content by its `storageRef`. */
-    get(storageRef: string): Promise<AssetStorageReadResult>;
+    get(storageRef: string): Promise<StorageReadResult>;
     /** Delete stored content by its `storageRef`. Should be retryable/idempotent. */
     delete(storageRef: string): Promise<void>;
 }
-/** Context passed to a custom adapter factory: its non-secret config options + the process env. */
-export interface AssetStorageContext {
-    /** Non-secret options from `runtime.registry.assetStorage.options` (bucket env-var names, region, …). */
+/** Context passed to a custom provider factory: its config options and the process env. */
+export interface StorageProviderContext {
+    /** `runtime.registry.assetStorage.options`, with each `fromEnv()` reference replaced by its value. */
     options: Record<string, unknown>;
-    /** The process environment. Read secret *values* here by the env-var *names* carried in options. */
+    /** The process environment. */
     env: NodeJS.ProcessEnv;
 }
-/** A custom adapter may export the adapter directly or a factory that builds it from its context. */
-export type AssetStorageFactory = (context: AssetStorageContext) => AssetStorage | Promise<AssetStorage>;
+/** A custom provider module may export the provider directly or a factory that builds it from its context. */
+export type StorageProviderFactory = (context: StorageProviderContext) => StorageProvider | Promise<StorageProvider>;

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

@@ -1,9 +1,9 @@
 "use strict";
 /**
- * Server-only asset storage contract for object-backed providers (Vercel Blob + custom
- * {@link defineAssetStorage} modules), so callers need no provider-specific logic. The built-in
- * `database` provider is the inline default: bytes live in the `asset_blobs.content` bytea column,
- * read/written directly by the registry, so it needs no adapter. Object providers record a
- * `storageRef` + provider id so reads resolve back through whichever provider stored the blob.
+ * Server-only asset storage contract for custom {@link defineStorageProvider} object storage modules.
+ * The built-in `database` provider is the inline default: bytes live in the `asset_blobs.content`
+ * bytea column, read/written directly by the registry, so it needs no module. Object providers
+ * record a `storageRef` + provider id so reads resolve back through whichever provider stored the
+ * blob.
  */
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/registry/auth/ai-keys.d.ts

@@ -0,0 +1,32 @@
+import type { RegistryDatabase } from '../db/client';
+/**
+ * Reader-supplied keys for connections the config declares with `credential: 'user'`.
+ *
+ * The key is write-only across the API boundary: once saved, a read reports only that a key exists.
+ * Only the chat route ever decrypts one, and only to send it to the connection's own endpoint.
+ */
+/**
+ * Ids of the connections this reader has a *usable* key for. A row that no longer decrypts — written
+ * under a rotated `HANDOFF_AI_KEY_SECRET` — is left out, so the account page and the assistant agree
+ * that no key is in place instead of offering a key the provider would never receive.
+ */
+export declare const listRegistryAiKeyConnections: (db: RegistryDatabase, userId: string) => Promise<string[]>;
+/** Save or replace this reader's key for one connection. */
+export declare const saveRegistryAiKey: (db: RegistryDatabase, input: {
+    userId: string;
+    connectionId: string;
+    key: string;
+}) => Promise<void>;
+/** Remove this reader's key for one connection. Returns whether a row was there to remove. */
+export declare const deleteRegistryAiKey: (db: RegistryDatabase, input: {
+    userId: string;
+    connectionId: string;
+}) => Promise<boolean>;
+/**
+ * Read back one reader's key. A row that no longer decrypts reads as absent, so the reader is told
+ * to add a key rather than shown a provider error.
+ */
+export declare const readRegistryAiKey: (db: RegistryDatabase, input: {
+    userId: string;
+    connectionId: string;
+}) => Promise<string | null>;