handoff-app 2.0.0-9 → 2.0.0

package/dist/ai/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Server-only AI provider contract for connections that are not OpenAI-compatible.
+ *
+ * Every built-in connection speaks the OpenAI-compatible `/chat/completions` API and needs no
+ * custom module — Ollama, LiteLLM, OpenRouter, vLLM, LM Studio and Azure OpenAI all serve it, and each of
+ * them fronts Anthropic, Google and xAI models. A provider that fits nothing else names a
+ * {@link defineAiProvider} module instead of a base URL.
+ */
+import type { LanguageModel } from 'ai';
+/** Context passed to a custom provider factory. */
+export interface AiProviderContext {
+    /** The connection's `options`, with each `fromEnv()` reference replaced by its value. */
+    options: Record<string, unknown>;
+    env: NodeJS.ProcessEnv;
+    /**
+     * The resolved key for this request: the deployment's own key for a service connection, or the
+     * reader's saved key for a `credential: 'user'` connection. Undefined when neither applies.
+     */
+    apiKey?: string;
+}
+/** The pluggable provider contract: resolve one of the connection's declared models. */
+export interface AiProvider {
+    languageModel(modelId: string): LanguageModel;
+}
+/** A custom provider may export the provider directly or a factory that builds it from its context. */
+export type AiProviderFactory = (context: AiProviderContext) => AiProvider | Promise<AiProvider>;

package/dist/ai/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Server-only AI provider contract for connections that are not OpenAI-compatible.
+ *
+ * Every built-in connection speaks the OpenAI-compatible `/chat/completions` API and needs no
+ * custom module — Ollama, LiteLLM, OpenRouter, vLLM, LM Studio and Azure OpenAI all serve it, and each of
+ * them fronts Anthropic, Google and xAI models. A provider that fits nothing else names a
+ * {@link defineAiProvider} module instead of a base URL.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/app-builder/build.d.ts

@@ -10,7 +10,7 @@ export declare const DEFAULT_BUILD_TARGET: BuildTarget;
 /**
  * Resolved packaging axis — orthogonal to {@link BuildTarget}. It
  * selects *how* the build is packaged, not *what* is built:
- *   - `standalone` → the existing sites-directory deliverable (`out/<projectId>` for static, the
+ *   - `standalone` → the sites-directory deliverable (`out/static` for static, the
  *     Node standalone bundle `out/registry` for registry).
  *   - `vercel`     → the Vercel Build Output API directory (`.vercel/output`) at the repo root.
  *
@@ -28,14 +28,21 @@ export type BuildPackage = 'standalone' | 'vercel';
 export declare class HandoffBuildError extends Error {
     constructor(message: string);
 }
+/** Fixed names, not project ids, so deploy paths are the same on every machine. */
+export declare const getStaticBuildOutputPath: (handoff: Handoff) => string;
+export declare const getRegistryBuildOutputPath: (handoff: Handoff) => string;
 /**
- * Output directory for the packaged registry app. Lives under the configurable sites output
- * directory (`sitesOutputDirectory`, default `out`) alongside the static target's `out/<projectId>`
- * deliverable — both build targets emit to one discoverable, gitignored output root, keeping the
- * package's `.handoff` for internal build/staging only. The registry artifact is a single
- * deployable, so it is not keyed by project id.
+ * Root for Next's file tracing. Every traced path in the standalone bundle is relative to this root.
+ *
+ * The tracer copies only the files inside this root. It must contain the staged app (see
+ * {@link getAppPath}), or Next emits no standalone bundle. It must also contain every
+ * `node_modules` that the required runtime dependencies resolve from, or the bundle cannot start
+ * (see {@link assertRegistryRuntimeDepsTraced}).
+ *
+ * `workingPath` satisfies both conditions only when handoff-app is installed in the same package as
+ * the config, and nothing is hoisted above it.
  */
-export declare const getRegistryBuildOutputPath: (handoff: Handoff) => string;
+export declare const resolveRegistryTracingRoot: (handoff: Handoff) => string;
 /**
  * Build the Next.js documentation application for the resolved target. The `static` target builds
  * and exports the local workspace (default); the `registry` target packages the deployable dynamic

package/dist/app-builder/build.js

@@ -35,16 +35,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.devApp = exports.watchApp = exports.getRegistryBuildOutputPath = exports.HandoffBuildError = exports.DEFAULT_BUILD_TARGET = void 0;
+exports.devApp = exports.watchApp = exports.resolveRegistryTracingRoot = exports.getRegistryBuildOutputPath = exports.getStaticBuildOutputPath = exports.HandoffBuildError = exports.DEFAULT_BUILD_TARGET = void 0;
 const p = __importStar(require("@clack/prompts"));
+const nft_1 = require("@vercel/nft");
 const cross_spawn_1 = __importDefault(require("cross-spawn"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
+const connections_1 = require("../ai/connections");
 const config_1 = require("../config");
+const from_env_1 = require("../config/from-env");
 const components_1 = require("../pipeline/components");
 const patterns_1 = require("../pipeline/patterns");
 const resolve_1 = require("../registry/asset-storage/resolve");
 const driver_1 = require("../registry/db/driver");
+const resolve_2 = require("../registry/email/resolve");
 const builder_1 = __importDefault(require("../transformers/preview/component/builder"));
 const css_1 = require("../transformers/preview/component/css");
 const javascript_1 = require("../transformers/preview/component/javascript");
@@ -75,7 +79,7 @@ exports.HandoffBuildError = HandoffBuildError;
  * Resolve and validate the effective `(target, package)` pair.
  *
  * `--package` is optional and never implies a target. When omitted the effective package is
- * `standalone` for both targets, preserving today's `out/<projectId>` / `out/registry` deliverables.
+ * `standalone` for both targets (`out/static` / `out/registry`).
  * The one rejected combination is `static + standalone`: a static snapshot has no server to package
  * as a Node standalone bundle.
  */
@@ -148,15 +152,50 @@ const runNextBuild = (appPath, target, errorLabel) => __awaiter(void 0, void 0,
         });
     });
 });
-/**
- * Output directory for the packaged registry app. Lives under the configurable sites output
- * directory (`sitesOutputDirectory`, default `out`) alongside the static target's `out/<projectId>`
- * deliverable — both build targets emit to one discoverable, gitignored output root, keeping the
- * package's `.handoff` for internal build/staging only. The registry artifact is a single
- * deployable, so it is not keyed by project id.
- */
+/** Fixed names, not project ids, so deploy paths are the same on every machine. */
+const getStaticBuildOutputPath = (handoff) => path_1.default.resolve(handoff.workingPath, handoff.sitesDirectory, 'static');
+exports.getStaticBuildOutputPath = getStaticBuildOutputPath;
 const getRegistryBuildOutputPath = (handoff) => path_1.default.resolve(handoff.workingPath, handoff.sitesDirectory, 'registry');
 exports.getRegistryBuildOutputPath = getRegistryBuildOutputPath;
+const commonAncestorPath = (paths) => {
+    const [first, ...rest] = paths.map((entry) => path_1.default.resolve(entry).split(path_1.default.sep));
+    let shared = first;
+    for (const candidate of rest) {
+        const next = [];
+        for (let index = 0; index < Math.min(shared.length, candidate.length) && shared[index] === candidate[index]; index += 1) {
+            next.push(shared[index]);
+        }
+        shared = next;
+    }
+    return shared.join(path_1.default.sep) || path_1.default.sep;
+};
+/**
+ * Root for Next's file tracing. Every traced path in the standalone bundle is relative to this root.
+ *
+ * The tracer copies only the files inside this root. It must contain the staged app (see
+ * {@link getAppPath}), or Next emits no standalone bundle. It must also contain every
+ * `node_modules` that the required runtime dependencies resolve from, or the bundle cannot start
+ * (see {@link assertRegistryRuntimeDepsTraced}).
+ *
+ * `workingPath` satisfies both conditions only when handoff-app is installed in the same package as
+ * the config, and nothing is hoisted above it.
+ */
+const resolveRegistryTracingRoot = (handoff) => {
+    const anchors = [path_1.default.resolve(handoff.workingPath), path_1.default.resolve(handoff.modulePath)];
+    // Resolve each module instead of assuming its location. A hoisted or linked dependency otherwise
+    // drops out of the trace.
+    for (const moduleName of getRequiredRegistryRuntimeModules(handoff)) {
+        try {
+            const resolved = require.resolve(`${moduleName}/package.json`, { paths: [handoff.modulePath, handoff.workingPath] });
+            anchors.push(fs_extra_1.default.realpathSync(path_1.default.dirname(resolved)));
+        }
+        catch (_a) {
+            // The assertion after assembly reports a module that does not resolve.
+        }
+    }
+    return commonAncestorPath(anchors);
+};
+exports.resolveRegistryTracingRoot = resolveRegistryTracingRoot;
 /**
  * Performs cleanup of the application directory by removing the existing app directory if it exists.
  */
@@ -173,7 +212,7 @@ const cleanupAppDirectory = (handoff) => __awaiter(void 0, void 0, void 0, funct
  * @returns The path to the prepared application directory
  */
 const initializeProjectApp = (handoff_1, ...args_1) => __awaiter(void 0, [handoff_1, ...args_1], void 0, function* (handoff, options = {}) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
     const includeWorkspaceArtifacts = (_a = options.includeWorkspaceArtifacts) !== null && _a !== void 0 ? _a : true;
     const runtimeMode = (_e = (_b = options.runtimeModeOverride) !== null && _b !== void 0 ? _b : (_d = (_c = handoff.config) === null || _c === void 0 ? void 0 : _c.runtime) === null || _d === void 0 ? void 0 : _d.mode) !== null && _e !== void 0 ? _e : 'workspace';
     const srcPath = path_1.default.resolve(handoff.modulePath, 'src', 'app');
@@ -204,7 +243,7 @@ const initializeProjectApp = (handoff_1, ...args_1) => __awaiter(void 0, [handof
     const handoffAppBasePath = (_f = handoff.config.app.base_path) !== null && _f !== void 0 ? _f : '';
     const handoffWorkingPath = path_1.default.resolve(handoff.workingPath);
     const handoffModulePath = path_1.default.resolve(handoff.modulePath);
-    const handoffExportPath = path_1.default.resolve(handoff.workingPath, handoff.exportsDirectory, handoff.getProjectId());
+    const handoffExportPath = handoff.getOutputPath();
     const nextConfigPath = path_1.default.resolve(srcPath, 'next.config.mjs');
     const targetPath = path_1.default.resolve(appPath, 'next.config.mjs');
     const handoffWebsocketPort = (_h = (_g = handoff.config.app.ports) === null || _g === void 0 ? void 0 : _g.websocket) !== null && _h !== void 0 ? _h : 3001;
@@ -212,6 +251,8 @@ const initializeProjectApp = (handoff_1, ...args_1) => __awaiter(void 0, [handof
     const escapedProjectId = escapeForSingleQuotedJsString(handoffProjectId);
     const escapedWorkingPath = escapeForSingleQuotedJsString(handoffWorkingPath);
     const escapedModulePath = escapeForSingleQuotedJsString(handoffModulePath);
+    // Baked here so the template and the assembly step use the same root.
+    const escapedTracingRoot = escapeForSingleQuotedJsString((0, exports.resolveRegistryTracingRoot)(handoff));
     const escapedExportPath = escapeForSingleQuotedJsString(handoffExportPath);
     const escapedWebsocketPort = escapeForSingleQuotedJsString(String(handoffWebsocketPort));
     // Resolved runtime mode + registry connection inputs (names only) baked into the Next bundle so the
@@ -220,29 +261,47 @@ const initializeProjectApp = (handoff_1, ...args_1) => __awaiter(void 0, [handof
     const escapedMcpEnabled = escapeForSingleQuotedJsString(String((0, config_1.isMcpEnabled)(handoff.config)));
     const escapedRegistryDriver = escapeForSingleQuotedJsString((0, driver_1.resolveRegistryDriver)(handoff.config));
     const escapedDatabaseUrlEnv = escapeForSingleQuotedJsString((0, driver_1.resolveDatabaseUrlEnv)(handoff.config));
-    // Asset storage selection baked (provider + module + env-var names + non-secret options JSON).
+    // Asset storage selection baked (provider + module + options JSON with `{ $env }` references).
     const assetStorage = (0, resolve_1.resolveAssetStorageFromConfig)(handoff.config);
-    const escapedAssetStorageAdapter = escapeForSingleQuotedJsString(assetStorage.adapterKind);
+    const escapedAssetStorageProvider = escapeForSingleQuotedJsString(assetStorage.provider);
     const escapedAssetStorageModule = escapeForSingleQuotedJsString((_j = assetStorage.module) !== null && _j !== void 0 ? _j : '');
-    const escapedAssetStorageTokenEnv = escapeForSingleQuotedJsString(assetStorage.tokenEnv);
     const escapedAssetStorageMaxInline = escapeForSingleQuotedJsString(String(assetStorage.maxInlineBytes));
     const escapedAssetStorageOptions = escapeForSingleQuotedJsString(JSON.stringify((_k = assetStorage.options) !== null && _k !== void 0 ? _k : {}));
+    const email = (0, resolve_2.resolveEmailFromConfig)(handoff.config);
+    const escapedEmailProvider = escapeForSingleQuotedJsString((_l = email.provider) !== null && _l !== void 0 ? _l : '');
+    const escapedEmailFrom = escapeForSingleQuotedJsString((_m = email.from) !== null && _m !== void 0 ? _m : '');
+    const escapedEmailModule = escapeForSingleQuotedJsString((_o = email.module) !== null && _o !== void 0 ? _o : '');
+    const escapedEmailOptions = escapeForSingleQuotedJsString(JSON.stringify(email.options));
+    // AI assistant selection baked (enabled flag + declared connections + default model). Connections
+    // carry env-var names and non-secret options only; keys are read from their named env var at
+    // request time, and a deployment can extend or replace the list through HANDOFF_AI_CONNECTIONS.
+    const ai = (0, connections_1.resolveAiFromConfig)(handoff.config);
+    const escapedAiEnabled = escapeForSingleQuotedJsString(String(ai.enabled));
+    const escapedAiConnections = escapeForSingleQuotedJsString(JSON.stringify(ai.connections));
+    const escapedAiDefaultModel = escapeForSingleQuotedJsString((_p = ai.defaultModel) !== null && _p !== void 0 ? _p : '');
     const placeholderValues = {
         '%HANDOFF_PROJECT_ID%': escapedProjectId,
         '%HANDOFF_APP_BASE_PATH%': escapedAppBasePath,
         '%HANDOFF_WORKING_PATH%': escapedWorkingPath,
         '%HANDOFF_MODULE_PATH%': escapedModulePath,
+        '%HANDOFF_TRACING_ROOT%': escapedTracingRoot,
         '%HANDOFF_EXPORT_PATH%': escapedExportPath,
         '%HANDOFF_WEBSOCKET_PORT%': escapedWebsocketPort,
         '%HANDOFF_RUNTIME_MODE%': escapedRuntimeMode,
         '%HANDOFF_MCP_ENABLED%': escapedMcpEnabled,
         '%HANDOFF_REGISTRY_DRIVER%': escapedRegistryDriver,
         '%HANDOFF_REGISTRY_DATABASE_URL_ENV%': escapedDatabaseUrlEnv,
-        '%HANDOFF_ASSET_STORAGE_ADAPTER%': escapedAssetStorageAdapter,
+        '%HANDOFF_ASSET_STORAGE_PROVIDER%': escapedAssetStorageProvider,
         '%HANDOFF_ASSET_STORAGE_MODULE%': escapedAssetStorageModule,
-        '%HANDOFF_ASSET_STORAGE_TOKEN_ENV%': escapedAssetStorageTokenEnv,
         '%HANDOFF_ASSET_STORAGE_MAX_INLINE_BYTES%': escapedAssetStorageMaxInline,
         '%HANDOFF_ASSET_STORAGE_OPTIONS%': escapedAssetStorageOptions,
+        '%HANDOFF_EMAIL_PROVIDER%': escapedEmailProvider,
+        '%HANDOFF_EMAIL_FROM%': escapedEmailFrom,
+        '%HANDOFF_EMAIL_MODULE%': escapedEmailModule,
+        '%HANDOFF_EMAIL_OPTIONS%': escapedEmailOptions,
+        '%HANDOFF_AI_ENABLED%': escapedAiEnabled,
+        '%HANDOFF_AI_BAKED_CONNECTIONS%': escapedAiConnections,
+        '%HANDOFF_AI_DEFAULT_MODEL%': escapedAiDefaultModel,
     };
     let nextConfigContent = yield fs_extra_1.default.readFile(nextConfigPath, 'utf-8');
     for (const [placeholder, value] of Object.entries(placeholderValues)) {
@@ -293,20 +352,13 @@ const buildApp = (handoff_1, ...args_1) => __awaiter(void 0, [handoff_1, ...args
     yield (0, static_export_1.materializeDocsReadModel)(handoff, exportDir);
     // Final assembly branches on the resolved package. `vercel` lays the materialized export
     // under `.vercel/output/static/` at the repo root (not the sites directory) — a hard Vercel
-    // constraint; `standalone` keeps writing the `out/<projectId>` export.
+    // constraint; `standalone` keeps writing the `out/static` export.
     if (resolvedPackage === 'vercel') {
         yield (0, vercel_output_1.writeStaticVercelOutput)(handoff, exportDir);
         return;
     }
-    // Ensure output root directory exists
-    const outputRoot = path_1.default.resolve(handoff.workingPath, handoff.sitesDirectory);
-    yield fs_extra_1.default.ensureDir(outputRoot);
-    // Clean the project output directory (if exists)
-    const output = path_1.default.resolve(outputRoot, handoff.getProjectId());
-    if (fs_extra_1.default.existsSync(output)) {
-        yield fs_extra_1.default.remove(output);
-    }
-    // Copy the build files into the project output directory
+    const output = (0, exports.getStaticBuildOutputPath)(handoff);
+    yield fs_extra_1.default.remove(output);
     yield fs_extra_1.default.copy(exportDir, output);
 });
 /**
@@ -337,7 +389,28 @@ const findStandaloneServerDir = (root) => {
  * Write a deployment guide next to the packaged registry app describing how to run it on Vercel,
  * a custom Node server, or in a container, and which env vars it requires at deploy time.
  */
-const writeRegistryDeploymentReadme = (outputRoot, entryRelativePath, databaseUrlEnv) => __awaiter(void 0, void 0, void 0, function* () {
+const writeRegistryDeploymentReadme = (outputRoot, entryRelativePath, databaseUrlEnv, ai, email, assetStorage) => __awaiter(void 0, void 0, void 0, function* () {
+    const serviceKeyEnvs = [...new Set(ai.connections.map((connection) => connection.apiKeyEnv).filter(Boolean))];
+    const aiOptionEnvs = [...new Set(ai.connections.flatMap((connection) => { var _a; return (0, from_env_1.envReferenceNames)((_a = connection.options) !== null && _a !== void 0 ? _a : {}); }))];
+    const needsKeySecret = ai.connections.some((connection) => connection.credential === 'user');
+    const aiSection = !ai.enabled
+        ? ''
+        : `
+## AI assistant
+
+This build serves the docs assistant at \`/api/ai/*\`.
+
+${serviceKeyEnvs.map((name) => `- \`${name}\` — API key for a declared AI connection, read at request time.`).join('\n') || '- No service-key connection is declared, so no provider key is required here.'}
+${aiOptionEnvs.map((name) => `- \`${name}\` — read by a custom AI provider at request time.\n`).join('')}${needsKeySecret ? '- `HANDOFF_AI_KEY_SECRET` — a long, random secret that encrypts the API keys readers save for themselves. Readers cannot save a key without it.\n' : ''}
+\`HANDOFF_AI_CONNECTIONS\` optionally carries a JSON array of connections, read at request time and
+merged over the list this build baked in, keyed by \`id\`. Use it to add or repoint a provider
+without rebuilding.
+`;
+    const assetStorageEnvs = assetStorage.provider === 'custom' ? (0, from_env_1.envReferenceNames)(assetStorage.options) : [];
+    const emailEnvs = (0, from_env_1.envReferenceNames)(email.options);
+    const emailSection = !email.from
+        ? 'Email delivery is off because `runtime.registry.email.from` is not set. Invitation links are shown once to an administrator for manual delivery.'
+        : `Invitation and password-reset emails are sent from \`${email.from}\` through the \`${email.provider}\` provider.${emailEnvs.length ? ` The provider reads ${emailEnvs.map((name) => `\`${name}\``).join(', ')} at request time.` : ''} Until the provider's settings have values, invitation links are shown once to an administrator for manual delivery.`;
     const readme = `# Handoff Registry App
 
 A self-contained, deployable Next.js **standalone** build produced by
@@ -354,10 +427,9 @@ and \`.next/static/\` already copied alongside so the server serves them.
 - \`${databaseUrlEnv}\` — PostgreSQL/Neon connection string, read at request time.
 - \`AUTH_SECRET\` — a long, random secret used to sign browser sessions.
 - \`AUTH_URL\` — the canonical public registry URL, including the configured base path.
-
-Optional email delivery uses \`RESEND_API_KEY\` and \`AUTH_FROM_EMAIL\`. Without them, invitation
-links are shown once to an administrator for manual delivery.
-
+${assetStorageEnvs.map((name) => `- \`${name}\` — read by the custom asset storage provider at request time.\n`).join('')}
+${emailSection}
+${aiSection}
 ## Database migrations
 
 Apply migrations from the \`handoff-app\` CLI as a controlled release step (e.g. in your CI/CD
@@ -426,8 +498,8 @@ For multi-instance self-hosting, front \`/_next/static\` with a CDN and configur
 
 ## Deploying to Vercel
 
-Vercel does **not** use \`output: 'standalone'\` — it ignores that setting and builds with its own
-adapter, so this pre-built bundle is **not** the artifact you deploy there. For Vercel, deploy the
+Vercel does **not** use \`output: 'standalone'\` — it ignores that setting and runs its
+own build, so this pre-built bundle is **not** the artifact you deploy there. For Vercel, deploy the
 registry app via Vercel's Git/CLI source build (it produces and serves the dynamic app itself) and
 supply the same environment variables above as project env vars. Use this standalone bundle for
 containers, custom Node servers, and other non-Vercel hosts.
@@ -438,30 +510,25 @@ containers, custom Node servers, and other non-Vercel hosts.
  * Resolve the set of npm packages the packaged registry app must be able to `require`/`import` at
  * runtime, given the configured database driver. `next`/`react`/`react-dom` run the server and React
  * runtime; `drizzle-orm` backs both the request-time DB client and the migration runner; the MCP SDK
- * (and its `zod` peer) is only needed when `/api/mcp/` is enabled; the driver package is
- * driver-specific (the Neon serverless driver also needs `ws` for its Node WebSocket transport).
+ * is only needed when `/api/mcp/` is enabled; the driver package is
+ * driver-specific (the Neon serverless driver also needs `ws` for its Node WebSocket transport); the
+ * SMTP email provider needs `nodemailer`.
  */
 const getRequiredRegistryRuntimeModules = (handoff) => {
-    var _a;
     const base = ['next', 'next-auth', 'react', 'react-dom', 'drizzle-orm'];
-    if ((0, config_1.isMcpEnabled)(handoff.config)) {
-        base.push('@modelcontextprotocol/sdk', 'zod');
+    const ai = (0, connections_1.resolveAiFromConfig)(handoff.config);
+    // The assistant runs the MCP tools in-process, so it needs the MCP SDK whether or not the HTTP
+    // endpoint is served.
+    if ((0, config_1.isMcpEnabled)(handoff.config) || ai.enabled) {
+        base.push('@modelcontextprotocol/sdk');
+    }
+    if (ai.enabled) {
+        base.push('ai', '@ai-sdk/openai-compatible');
     }
     const driver = (0, driver_1.resolveRegistryDriver)(handoff.config);
     const driverModules = driver === 'neon' ? ['@neondatabase/serverless', 'ws'] : ['pg'];
-    // Asset-storage SDKs the deployed registry must be able to load at request time. The pre-packaged
-    // Vercel Blob adapter needs `@vercel/blob`; a custom adapter may declare its installed SDK
-    // package(s) via `assetStorage.options.sdkModules` so the trace/assertion covers them.
-    const assetStorage = (0, resolve_1.resolveAssetStorageFromConfig)(handoff.config);
-    const storage = [];
-    if (assetStorage.adapterKind === 'vercel-blob') {
-        storage.push('@vercel/blob');
-    }
-    const sdkModules = (_a = assetStorage.options) === null || _a === void 0 ? void 0 : _a.sdkModules;
-    if (Array.isArray(sdkModules)) {
-        storage.push(...sdkModules.filter((mod) => typeof mod === 'string'));
-    }
-    return [...base, ...driverModules, ...storage];
+    const email = (0, resolve_2.resolveEmailFromConfig)(handoff.config).provider === 'smtp' ? ['nodemailer'] : [];
+    return [...base, ...driverModules, ...email];
 };
 /**
  * Build-time guard against the empty-`node_modules` regression (the artifact would otherwise boot-fail
@@ -488,6 +555,58 @@ const assertRegistryRuntimeDepsTraced = (handoff, entryDir) => {
         `must be the nearest ancestor of *both* the staged app and the resolved node_modules. Ensure ` +
         `${missing.join(', ')} are installed and resolvable from "${handoff.workingPath}".`);
 };
+const getCustomServerModules = (handoff) => {
+    const assetStorage = (0, resolve_1.resolveAssetStorageFromConfig)(handoff.config);
+    const email = (0, resolve_2.resolveEmailFromConfig)(handoff.config);
+    const modules = [
+        assetStorage.provider === 'custom' ? assetStorage.module : undefined,
+        email.provider === 'custom' ? email.module : undefined,
+        ...(0, connections_1.resolveAiFromConfig)(handoff.config).connections.map((connection) => connection.module),
+    ];
+    return [...new Set(modules.filter((module) => Boolean(module)))];
+};
+/**
+ * Copy the custom server modules and every file they import into the bundle. The Next trace cannot
+ * follow their variable dynamic import.
+ */
+const copyCustomServerModules = (handoff, tracingRoot, entryDir) => __awaiter(void 0, void 0, void 0, function* () {
+    const modules = getCustomServerModules(handoff);
+    if (modules.length === 0)
+        return;
+    const missing = modules.filter((module) => !fs_extra_1.default.existsSync(path_1.default.resolve(handoff.workingPath, module)));
+    if (missing.length > 0) {
+        throw new HandoffBuildError(`A custom server module does not exist: ${missing.map((module) => `"${module}"`).join(', ')}.`);
+    }
+    const files = new Set();
+    for (const module of modules) {
+        const { fileList } = yield (0, nft_1.nodeFileTrace)([path_1.default.resolve(handoff.workingPath, module)], { base: tracingRoot });
+        const outside = [...fileList].filter((file) => file.startsWith('..'));
+        if (outside.length > 0) {
+            throw new HandoffBuildError(`The custom server module "${module}" imports files outside the build's tracing root "${tracingRoot}": ${outside.join(', ')}. ` +
+                `Install the packages it imports so that they resolve from "${handoff.workingPath}".`);
+        }
+        if ([...fileList].some((file) => file.split(path_1.default.sep).join('/').endsWith('node_modules/handoff-app/dist/index.js'))) {
+            throw new HandoffBuildError(`The custom server module "${module}" imports "handoff-app", which loads the whole CLI. Import the define helpers from "handoff-app/providers".`);
+        }
+        fileList.forEach((file) => files.add(file));
+    }
+    for (const file of files) {
+        const source = path_1.default.join(tracingRoot, file);
+        const target = path_1.default.join(entryDir, file);
+        if (yield fs_extra_1.default.lstat(target).then(() => true, () => false))
+            continue;
+        const stat = yield fs_extra_1.default.lstat(source);
+        yield fs_extra_1.default.ensureDir(path_1.default.dirname(target));
+        if (stat.isSymbolicLink()) {
+            // Point the link at the bundle copy of its target, not at the build machine.
+            const linked = path_1.default.join(entryDir, path_1.default.relative(tracingRoot, yield fs_extra_1.default.realpath(source)));
+            yield fs_extra_1.default.symlink(path_1.default.relative(path_1.default.dirname(target), linked), target);
+        }
+        else if (stat.isFile()) {
+            yield fs_extra_1.default.copy(source, target);
+        }
+    }
+});
 /**
  * Lay the Next `standalone` build out as the documented standalone layout under `entryDir`: copy the
  * traced bundle, flatten the package-rooted server entry up to `entryDir`, and copy the untraced
@@ -499,14 +618,11 @@ const assertRegistryRuntimeDepsTraced = (handoff, entryDir) => {
  */
 const assembleRegistryStandalone = (handoff, appPath, standaloneRoot, entryDir) => __awaiter(void 0, void 0, void 0, function* () {
     yield fs_extra_1.default.copy(standaloneRoot, entryDir, { overwrite: true });
-    // Locate the server entry within the assembled package. Standalone tracing is rooted at the
-    // consumer project root (`workingPath`, see next.config.mjs), so every traced file is laid out at
-    // its path *relative to `workingPath`*. The staged app lives at `<workingPath>/node_modules/
-    // handoff-app/.handoff/<projectId>`, so the server entry lands nested at that same relative path
-    // *underneath* the traced `node_modules`. Resolve it deterministically; the recursive fallback
-    // skips `node_modules` (so it cannot find this nested entry) and only covers a hypothetical
-    // non-nested layout.
-    const relAppDir = path_1.default.relative(handoff.workingPath, appPath);
+    // Locate the server entry in the assembled package. Traced files keep their path relative to the
+    // tracing root, so the server entry nests under the traced `node_modules`. The recursive fallback
+    // skips `node_modules`, so it covers only a non-nested layout.
+    const tracingRoot = (0, exports.resolveRegistryTracingRoot)(handoff);
+    const relAppDir = path_1.default.relative(tracingRoot, appPath);
     let serverDir = path_1.default.resolve(entryDir, relAppDir);
     if (!fs_extra_1.default.existsSync(path_1.default.join(serverDir, 'server.js'))) {
         const located = findStandaloneServerDir(entryDir);
@@ -526,7 +642,7 @@ const assembleRegistryStandalone = (handoff, appPath, standaloneRoot, entryDir)
         // so we must NOT remove the first path segment (`node_modules`) — that would delete every traced
         // dependency. Remove only the `.handoff` staging container (the parent of the staged app dir),
         // leaving `node_modules/` and the real `node_modules/handoff-app/` package intact.
-        const stagingContainer = path_1.default.resolve(entryDir, path_1.default.relative(handoff.workingPath, path_1.default.dirname(appPath)));
+        const stagingContainer = path_1.default.resolve(entryDir, path_1.default.relative(tracingRoot, path_1.default.dirname(appPath)));
         if (path_1.default.basename(stagingContainer) === '.handoff' && fs_extra_1.default.existsSync(stagingContainer)) {
             yield fs_extra_1.default.remove(stagingContainer);
         }
@@ -549,6 +665,17 @@ const assembleRegistryStandalone = (handoff, appPath, standaloneRoot, entryDir)
             yield fs_extra_1.default.copy(src, path_1.default.join(entryDir, configFile), { overwrite: true });
         }
     }
+    // Next copies the `package.json` of the tracing root into the bundle without change. The generated
+    // `server.js` is CommonJS, so an ESM manifest stops the bundle from starting. That manifest also
+    // names scripts and dev dependencies that the bundle does not ship.
+    const manifestPath = path_1.default.join(entryDir, 'package.json');
+    const inheritedManifest = (yield fs_extra_1.default.pathExists(manifestPath))
+        ? yield fs_extra_1.default.readJson(manifestPath).catch(() => ({}))
+        : {};
+    delete inheritedManifest.scripts;
+    delete inheritedManifest.devDependencies;
+    yield fs_extra_1.default.writeJson(manifestPath, Object.assign(Object.assign({}, inheritedManifest), { type: 'commonjs' }), { spaces: 2 });
+    yield copyCustomServerModules(handoff, tracingRoot, entryDir);
     // Fail loudly at build time if the trace did not capture the runtime deps, rather than shipping a
     // broken artifact that only crashes on an isolated deploy. Covers both deliverables (this is the
     // shared assembly step for `standalone` and `vercel`).
@@ -618,8 +745,10 @@ const buildRegistryApp = (handoff_1, ...args_1) => __awaiter(void 0, [handoff_1,
     // files are not traced and must be copied alongside the server entry.
     const standaloneRoot = path_1.default.resolve(appPath, '.next', 'standalone');
     if (!fs_extra_1.default.existsSync(standaloneRoot)) {
-        throw new Error(`Registry build did not produce a standalone bundle at "${standaloneRoot}". Ensure the registry ` +
-            'build target sets Next `output: "standalone"`.');
+        throw new Error(`Registry build did not produce a standalone bundle at "${standaloneRoot}". Next emits one only ` +
+            `when the app being built sits inside \`outputFileTracingRoot\` (resolved here to ` +
+            `"${(0, exports.resolveRegistryTracingRoot)(handoff)}"), so check that the staged app at "${appPath}" is ` +
+            'inside that root, and that the registry build target still sets Next `output: "standalone"`.');
     }
     // Final assembly branches on the resolved package. Both lay out
     // the same traced standalone bundle; they differ only in where it lands and how it is wrapped.
@@ -636,7 +765,7 @@ const buildRegistryApp = (handoff_1, ...args_1) => __awaiter(void 0, [handoff_1,
     // `handoff-app` source/CLI (`handoff-app db:migrate`) as a controlled release step (e.g. CI/CD),
     // never from the deployed bundle. See the generated README for the migrate-then-deploy flow.
     const entryRelativePath = path_1.default.relative(output, serverEntry).split(path_1.default.sep).join('/');
-    yield writeRegistryDeploymentReadme(output, entryRelativePath, (0, driver_1.resolveDatabaseUrlEnv)(handoff.config));
+    yield writeRegistryDeploymentReadme(output, entryRelativePath, (0, driver_1.resolveDatabaseUrlEnv)(handoff.config), (0, connections_1.resolveAiFromConfig)(handoff.config), (0, resolve_2.resolveEmailFromConfig)(handoff.config), (0, resolve_1.resolveAssetStorageFromConfig)(handoff.config));
     logger_1.Logger.success(`Packaged registry app at ${output} (start: \`node ${entryRelativePath}\`, migrate: \`handoff-app db:migrate\`).`);
 });
 /**
@@ -646,11 +775,11 @@ const buildRegistryApp = (handoff_1, ...args_1) => __awaiter(void 0, [handoff_1,
 const watchApp = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
     var _a, _b, _c, _d;
     // Build the shared/global artifacts first so component/pattern preview HTML references them only
-    // when present, then process components with caching enabled (which skips
-    // rebuilding components whose source files haven't changed).
+    // when present, then process components. The build cache skips the components whose files did not
+    // change.
     yield (0, javascript_1.buildMainJS)(handoff);
     yield (0, css_1.buildMainCss)(handoff);
-    yield (0, builder_1.default)(handoff, undefined, undefined, { useCache: true });
+    yield (0, builder_1.default)(handoff);
     // Build patterns after components are ready
     yield (0, patterns_1.buildPatterns)(handoff);
     const appPath = yield initializeProjectApp(handoff);

package/dist/app-builder/client-config.js

@@ -19,6 +19,7 @@ const config_1 = require("../config");
 const resolve_1 = require("../registry/asset-storage/resolve");
 const connection_1 = require("../registry/connection");
 const driver_1 = require("../registry/db/driver");
+const resolve_2 = require("../registry/email/resolve");
 const paths_1 = require("./paths");
 /**
  * Publishes the tokens API files to the public directory.
@@ -71,12 +72,12 @@ const buildServerRuntimeConfig = (config, modeOverride) => {
             databaseUrlEnv: (0, driver_1.resolveDatabaseUrlEnv)(config),
         },
         assetStorage: {
-            adapter: assetStorage.adapterKind,
+            provider: assetStorage.provider,
             module: assetStorage.module,
-            tokenEnv: assetStorage.tokenEnv,
             maxInlineBytes: assetStorage.maxInlineBytes,
             options: assetStorage.options,
         },
+        email: (0, resolve_2.resolveEmailFromConfig)(config),
     };
 };
 /**

package/dist/app-builder/paths.d.ts

@@ -1,17 +1,5 @@
 import Handoff from '..';
-/**
- * Gets the working public directory path for a given handoff instance.
- * Checks for both project-specific and default public directories.
- *
- * @param handoff - The handoff instance containing working path and figma project configuration
- * @returns The resolved path to the public directory if it exists, null otherwise
- */
 export declare const getWorkingPublicPath: (handoff: Handoff) => string | null;
-/**
- * Gets the application path for a given handoff instance.
- * @param handoff - The handoff instance containing module path and figma project configuration
- * @returns The resolved path to the application directory
- */
 export declare const getAppPath: (handoff: Handoff) => string;
 /**
  * Copy the public dir from the working dir to the module dir.

package/dist/app-builder/paths.js

@@ -15,28 +15,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.syncPublicFiles = exports.getAppPath = exports.getWorkingPublicPath = void 0;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
-/**
- * Gets the working public directory path for a given handoff instance.
- * Checks for both project-specific and default public directories.
- *
- * @param handoff - The handoff instance containing working path and figma project configuration
- * @returns The resolved path to the public directory if it exists, null otherwise
- */
 const getWorkingPublicPath = (handoff) => {
-    const paths = [path_1.default.resolve(handoff.workingPath, `public-${handoff.getProjectId()}`), path_1.default.resolve(handoff.workingPath, `public`)];
-    for (const p of paths) {
-        if (fs_extra_1.default.existsSync(p)) {
-            return p;
-        }
-    }
-    return null;
+    const publicPath = path_1.default.resolve(handoff.workingPath, 'public');
+    return fs_extra_1.default.existsSync(publicPath) ? publicPath : null;
 };
 exports.getWorkingPublicPath = getWorkingPublicPath;
-/**
- * Gets the application path for a given handoff instance.
- * @param handoff - The handoff instance containing module path and figma project configuration
- * @returns The resolved path to the application directory
- */
 const getAppPath = (handoff) => {
     return path_1.default.resolve(handoff.modulePath, '.handoff', `${handoff.getProjectId()}`);
 };
@@ -51,7 +34,7 @@ const mirrorDirectory = (sourcePath, destinationPath) => __awaiter(void 0, void
     yield fs_extra_1.default.copy(sourcePath, destinationPath, { overwrite: true });
 });
 /**
- * Copy the fetch-produced asset bundles (`exported/<id>/{collection}.zip`) into the app's public
+ * Copy the fetch-produced asset bundles (`exported/{collection}.zip`) into the app's public
  * root, where the docs read API serves them at `/api/docs/assets/{collection}/{collection}.zip`.
  * `fetch` writes these bundles, but `build`/`start` cleans and re-stages `.handoff` without them, so
  * the download links 404 until the next fetch. Copying them here keeps the route working in workspace

package/dist/app-builder/static-export.js

@@ -184,7 +184,7 @@ exports.materializeDocsReadModel = materializeDocsReadModel;
  * Write the whole-collection asset bundles to the asset route
  * (`api/docs/assets/{collection}/{collection}.zip`), the same URL the docs read API serves in
  * registry mode, so the "Download" links work identically on a static host. The bundles come from the
- * fetch output (`exported/<id>/{collection}.zip`); `next build` never re-creates them and the
+ * fetch output (`exported/{collection}.zip`); `next build` never re-creates them and the
  * fetch-time copy into `public/` is wiped by the build's clean+restage, so we copy them here again.
  * Projects with no logos/icons have no bundles, so those are skipped rather than treated as an error.
  */

package/dist/app-builder/vercel-output.d.ts

@@ -7,7 +7,7 @@ export declare const getVercelOutputPath: (handoff: Handoff) => string;
  * no functions, no database.
  *
  * @param exportDir Absolute path of the materialized static export (the same content the static
- *   target writes to `out/<projectId>`).
+ *   target writes to `out/static`).
  */
 export declare const writeStaticVercelOutput: (handoff: Handoff, exportDir: string) => Promise<void>;
 /**