handoff-app 2.0.0-8 → 2.0.0

package/src/app-builder/build.ts

@@ -1,13 +1,17 @@
 import * as p from '@clack/prompts';
+import { nodeFileTrace } from '@vercel/nft';
 import spawn from 'cross-spawn';
 import fs from 'fs-extra';
 import path from 'path';
 import Handoff from '..';
+import { resolveAiFromConfig, type AiSettings } from '../ai/connections';
 import { isMcpEnabled } from '../config';
+import { envReferenceNames } from '../config/from-env';
 import { buildComponents } from '../pipeline/components';
 import { buildPatterns } from '../pipeline/patterns';
-import { resolveAssetStorageFromConfig } from '../registry/asset-storage/resolve';
+import { resolveAssetStorageFromConfig, type ResolvedAssetStorage } from '../registry/asset-storage/resolve';
 import { resolveDatabaseUrlEnv, resolveRegistryDriver } from '../registry/db/driver';
+import { resolveEmailFromConfig, type EmailSettings } from '../registry/email/resolve';
 import processComponents from '../transformers/preview/component/builder';
 import { buildMainCss } from '../transformers/preview/component/css';
 import { buildMainJS } from '../transformers/preview/component/javascript';
@@ -44,7 +48,7 @@ export const DEFAULT_BUILD_TARGET: BuildTarget = 'static';
 /**
  * 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.
  *
@@ -71,7 +75,7 @@ export class HandoffBuildError extends Error {
  * 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.
  */
@@ -162,16 +166,51 @@ const runNextBuild = async (appPath: string, target: BuildTarget, errorLabel: st
   });
 };
 
-/**
- * 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. */
+export const getStaticBuildOutputPath = (handoff: Handoff): string => path.resolve(handoff.workingPath, handoff.sitesDirectory, 'static');
+
 export const getRegistryBuildOutputPath = (handoff: Handoff): string =>
   path.resolve(handoff.workingPath, handoff.sitesDirectory, 'registry');
 
+const commonAncestorPath = (paths: string[]): string => {
+  const [first, ...rest] = paths.map((entry) => path.resolve(entry).split(path.sep));
+  let shared = first;
+  for (const candidate of rest) {
+    const next: string[] = [];
+    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.sep) || path.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.
+ */
+export const resolveRegistryTracingRoot = (handoff: Handoff): string => {
+  const anchors = [path.resolve(handoff.workingPath), path.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.realpathSync(path.dirname(resolved)));
+    } catch {
+      // The assertion after assembly reports a module that does not resolve.
+    }
+  }
+  return commonAncestorPath(anchors);
+};
+
 /**
  * Performs cleanup of the application directory by removing the existing app directory if it exists.
  */
@@ -243,7 +282,7 @@ const initializeProjectApp = async (handoff: Handoff, options: InitializeProject
   const handoffAppBasePath = handoff.config.app.base_path ?? '';
   const handoffWorkingPath = path.resolve(handoff.workingPath);
   const handoffModulePath = path.resolve(handoff.modulePath);
-  const handoffExportPath = path.resolve(handoff.workingPath, handoff.exportsDirectory, handoff.getProjectId());
+  const handoffExportPath = handoff.getOutputPath();
   const nextConfigPath = path.resolve(srcPath, 'next.config.mjs');
   const targetPath = path.resolve(appPath, 'next.config.mjs');
   const handoffWebsocketPort = handoff.config.app.ports?.websocket ?? 3001;
@@ -251,6 +290,8 @@ const initializeProjectApp = async (handoff: Handoff, options: InitializeProject
   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(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
@@ -259,29 +300,47 @@ const initializeProjectApp = async (handoff: Handoff, options: InitializeProject
   const escapedMcpEnabled = escapeForSingleQuotedJsString(String(isMcpEnabled(handoff.config)));
   const escapedRegistryDriver = escapeForSingleQuotedJsString(resolveRegistryDriver(handoff.config));
   const escapedDatabaseUrlEnv = escapeForSingleQuotedJsString(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 = resolveAssetStorageFromConfig(handoff.config);
-  const escapedAssetStorageAdapter = escapeForSingleQuotedJsString(assetStorage.adapterKind);
+  const escapedAssetStorageProvider = escapeForSingleQuotedJsString(assetStorage.provider);
   const escapedAssetStorageModule = escapeForSingleQuotedJsString(assetStorage.module ?? '');
-  const escapedAssetStorageTokenEnv = escapeForSingleQuotedJsString(assetStorage.tokenEnv);
   const escapedAssetStorageMaxInline = escapeForSingleQuotedJsString(String(assetStorage.maxInlineBytes));
   const escapedAssetStorageOptions = escapeForSingleQuotedJsString(JSON.stringify(assetStorage.options ?? {}));
+  const email = resolveEmailFromConfig(handoff.config);
+  const escapedEmailProvider = escapeForSingleQuotedJsString(email.provider ?? '');
+  const escapedEmailFrom = escapeForSingleQuotedJsString(email.from ?? '');
+  const escapedEmailModule = escapeForSingleQuotedJsString(email.module ?? '');
+  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 = resolveAiFromConfig(handoff.config);
+  const escapedAiEnabled = escapeForSingleQuotedJsString(String(ai.enabled));
+  const escapedAiConnections = escapeForSingleQuotedJsString(JSON.stringify(ai.connections));
+  const escapedAiDefaultModel = escapeForSingleQuotedJsString(ai.defaultModel ?? '');
   const placeholderValues: Record<string, string> = {
     '%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 = await fs.readFile(nextConfigPath, 'utf-8');
   for (const [placeholder, value] of Object.entries(placeholderValues)) {
@@ -350,23 +409,14 @@ const buildApp = async (
 
   // 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') {
     await writeStaticVercelOutput(handoff, exportDir);
     return;
   }
 
-  // Ensure output root directory exists
-  const outputRoot = path.resolve(handoff.workingPath, handoff.sitesDirectory);
-  await fs.ensureDir(outputRoot);
-
-  // Clean the project output directory (if exists)
-  const output = path.resolve(outputRoot, handoff.getProjectId());
-  if (fs.existsSync(output)) {
-    await fs.remove(output);
-  }
-
-  // Copy the build files into the project output directory
+  const output = getStaticBuildOutputPath(handoff);
+  await fs.remove(output);
   await fs.copy(exportDir, output);
 };
 
@@ -402,8 +452,36 @@ const findStandaloneServerDir = (root: string): string | null => {
 const writeRegistryDeploymentReadme = async (
   outputRoot: string,
   entryRelativePath: string,
-  databaseUrlEnv: string
+  databaseUrlEnv: string,
+  ai: AiSettings,
+  email: EmailSettings,
+  assetStorage: ResolvedAssetStorage
 ): Promise<void> => {
+  const serviceKeyEnvs = [...new Set(ai.connections.map((connection) => connection.apiKeyEnv).filter(Boolean))];
+  const aiOptionEnvs = [...new Set(ai.connections.flatMap((connection) => envReferenceNames(connection.options ?? {})))];
+  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' ? envReferenceNames(assetStorage.options) : [];
+  const emailEnvs = 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
@@ -420,10 +498,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
@@ -492,8 +569,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.
@@ -505,29 +582,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: Handoff): string[] => {
   const base = ['next', 'next-auth', 'react', 'react-dom', 'drizzle-orm'];
-  if (isMcpEnabled(handoff.config)) {
-    base.push('@modelcontextprotocol/sdk', 'zod');
+  const ai = 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 (isMcpEnabled(handoff.config) || ai.enabled) {
+    base.push('@modelcontextprotocol/sdk');
+  }
+  if (ai.enabled) {
+    base.push('ai', '@ai-sdk/openai-compatible');
   }
   const driver = 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 = resolveAssetStorageFromConfig(handoff.config);
-  const storage: string[] = [];
-  if (assetStorage.adapterKind === 'vercel-blob') {
-    storage.push('@vercel/blob');
-  }
-  const sdkModules = assetStorage.options?.sdkModules;
-  if (Array.isArray(sdkModules)) {
-    storage.push(...sdkModules.filter((mod): mod is string => typeof mod === 'string'));
-  }
-  return [...base, ...driverModules, ...storage];
+  const email = resolveEmailFromConfig(handoff.config).provider === 'smtp' ? ['nodemailer'] : [];
+  return [...base, ...driverModules, ...email];
 };
 
 /**
@@ -558,6 +631,64 @@ const assertRegistryRuntimeDepsTraced = (handoff: Handoff, entryDir: string): vo
   );
 };
 
+const getCustomServerModules = (handoff: Handoff): string[] => {
+  const assetStorage = resolveAssetStorageFromConfig(handoff.config);
+  const email = resolveEmailFromConfig(handoff.config);
+  const modules = [
+    assetStorage.provider === 'custom' ? assetStorage.module : undefined,
+    email.provider === 'custom' ? email.module : undefined,
+    ...resolveAiFromConfig(handoff.config).connections.map((connection) => connection.module),
+  ];
+  return [...new Set(modules.filter((module): module is string => 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 = async (handoff: Handoff, tracingRoot: string, entryDir: string): Promise<void> => {
+  const modules = getCustomServerModules(handoff);
+  if (modules.length === 0) return;
+
+  const missing = modules.filter((module) => !fs.existsSync(path.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<string>();
+  for (const module of modules) {
+    const { fileList } = await nodeFileTrace([path.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.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.join(tracingRoot, file);
+    const target = path.join(entryDir, file);
+    if (await fs.lstat(target).then(() => true, () => false)) continue;
+    const stat = await fs.lstat(source);
+    await fs.ensureDir(path.dirname(target));
+    if (stat.isSymbolicLink()) {
+      // Point the link at the bundle copy of its target, not at the build machine.
+      const linked = path.join(entryDir, path.relative(tracingRoot, await fs.realpath(source)));
+      await fs.symlink(path.relative(path.dirname(target), linked), target);
+    } else if (stat.isFile()) {
+      await fs.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
@@ -567,22 +698,14 @@ const assertRegistryRuntimeDepsTraced = (handoff: Handoff, entryDir: string): vo
  *
  * @returns the absolute path of the server entry (`<entryDir>/server.js`).
  */
-const assembleRegistryStandalone = async (
-  handoff: Handoff,
-  appPath: string,
-  standaloneRoot: string,
-  entryDir: string
-): Promise<string> => {
+const assembleRegistryStandalone = async (handoff: Handoff, appPath: string, standaloneRoot: string, entryDir: string): Promise<string> => {
   await fs.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.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 = resolveRegistryTracingRoot(handoff);
+  const relAppDir = path.relative(tracingRoot, appPath);
   let serverDir = path.resolve(entryDir, relAppDir);
   if (!fs.existsSync(path.join(serverDir, 'server.js'))) {
     const located = findStandaloneServerDir(entryDir);
@@ -605,7 +728,7 @@ const assembleRegistryStandalone = async (
     // 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.resolve(entryDir, path.relative(handoff.workingPath, path.dirname(appPath)));
+    const stagingContainer = path.resolve(entryDir, path.relative(tracingRoot, path.dirname(appPath)));
     if (path.basename(stagingContainer) === '.handoff' && fs.existsSync(stagingContainer)) {
       await fs.remove(stagingContainer);
     }
@@ -631,6 +754,19 @@ const assembleRegistryStandalone = async (
     }
   }
 
+  // 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.join(entryDir, 'package.json');
+  const inheritedManifest: Record<string, unknown> = (await fs.pathExists(manifestPath))
+    ? await fs.readJson(manifestPath).catch(() => ({}))
+    : {};
+  delete inheritedManifest.scripts;
+  delete inheritedManifest.devDependencies;
+  await fs.writeJson(manifestPath, { ...inheritedManifest, type: 'commonjs' }, { spaces: 2 });
+
+  await 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`).
@@ -710,8 +846,10 @@ const buildRegistryApp = async (handoff: Handoff, buildPackage: BuildPackage = '
   const standaloneRoot = path.resolve(appPath, '.next', 'standalone');
   if (!fs.existsSync(standaloneRoot)) {
     throw new Error(
-      `Registry build did not produce a standalone bundle at "${standaloneRoot}". Ensure the registry ` +
-        'build target sets Next `output: "standalone"`.'
+      `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 ` +
+        `"${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"`.'
     );
   }
 
@@ -733,7 +871,14 @@ const buildRegistryApp = async (handoff: Handoff, buildPackage: BuildPackage = '
   // never from the deployed bundle. See the generated README for the migrate-then-deploy flow.
 
   const entryRelativePath = path.relative(output, serverEntry).split(path.sep).join('/');
-  await writeRegistryDeploymentReadme(output, entryRelativePath, resolveDatabaseUrlEnv(handoff.config));
+  await writeRegistryDeploymentReadme(
+    output,
+    entryRelativePath,
+    resolveDatabaseUrlEnv(handoff.config),
+    resolveAiFromConfig(handoff.config),
+    resolveEmailFromConfig(handoff.config),
+    resolveAssetStorageFromConfig(handoff.config)
+  );
 
   Logger.success(`Packaged registry app at ${output} (start: \`node ${entryRelativePath}\`, migrate: \`handoff-app db:migrate\`).`);
 };
@@ -744,11 +889,11 @@ const buildRegistryApp = async (handoff: Handoff, buildPackage: BuildPackage = '
  */
 export const watchApp = async (handoff: Handoff): Promise<void> => {
   // 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.
   await buildMainJS(handoff);
   await buildMainCss(handoff);
-  await processComponents(handoff, undefined, undefined, { useCache: true });
+  await processComponents(handoff);
 
   // Build patterns after components are ready
   await buildPatterns(handoff);

package/src/app-builder/client-config.ts

@@ -5,6 +5,7 @@ import { getClientConfig, isMcpEnabled } from '../config';
 import { resolveAssetStorageFromConfig } from '../registry/asset-storage/resolve';
 import { resolveAuthenticatedRegistryConnection } from '../registry/connection';
 import { resolveDatabaseUrlEnv, resolveRegistryDriver } from '../registry/db/driver';
+import { resolveEmailFromConfig } from '../registry/email/resolve';
 import type { ResolvedConfig, RuntimeMode } from '../types/config';
 import { getAppPath } from './paths';
 
@@ -63,12 +64,12 @@ const buildServerRuntimeConfig = (config: ResolvedConfig, modeOverride?: Runtime
       databaseUrlEnv: resolveDatabaseUrlEnv(config),
     },
     assetStorage: {
-      adapter: assetStorage.adapterKind,
+      provider: assetStorage.provider,
       module: assetStorage.module,
-      tokenEnv: assetStorage.tokenEnv,
       maxInlineBytes: assetStorage.maxInlineBytes,
       options: assetStorage.options,
     },
+    email: resolveEmailFromConfig(config),
   };
 };
 

package/src/app-builder/paths.ts

@@ -2,30 +2,11 @@ import fs from 'fs-extra';
 import path from 'path';
 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 const getWorkingPublicPath = (handoff: Handoff): string | null => {
-  const paths = [path.resolve(handoff.workingPath, `public-${handoff.getProjectId()}`), path.resolve(handoff.workingPath, `public`)];
-
-  for (const p of paths) {
-    if (fs.existsSync(p)) {
-      return p;
-    }
-  }
-
-  return null;
+  const publicPath = path.resolve(handoff.workingPath, 'public');
+  return fs.existsSync(publicPath) ? publicPath : 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 const getAppPath = (handoff: Handoff): string => {
   return path.resolve(handoff.modulePath, '.handoff', `${handoff.getProjectId()}`);
 };
@@ -42,7 +23,7 @@ const mirrorDirectory = async (sourcePath: string, destinationPath: string): Pro
 };
 
 /**
- * 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/src/app-builder/static-export.ts

@@ -220,7 +220,7 @@ export const materializeDocsReadModel = async (handoff: Handoff, outDir: string)
  * 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/src/app-builder/vercel-output.ts

@@ -40,7 +40,7 @@ const resolveBasePath = (rawBasePath: string | undefined): 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 const writeStaticVercelOutput = async (handoff: Handoff, exportDir: string): Promise<void> => {
   const outputPath = getVercelOutputPath(handoff);
@@ -69,10 +69,11 @@ export const writeStaticVercelOutput = async (handoff: Handoff, exportDir: strin
 /**
  * Node.js runtime identifier baked into the registry function's `.vc-config.json`. The `pg` driver
  * (and the Neon serverless driver in its Node fallback) need the Node.js runtime, not the edge
- * runtime — this is the required baseline. Vercel resolves the patch
- * version within this major; pinning the major keeps the artifact stable.
+ * runtime. The major matches the package `engines` minimum, and the Vercel project's Node.js setting
+ * does not override it. Vercel resolves the patch version within this major; pinning the major keeps
+ * the artifact stable.
  */
-const VERCEL_NODE_RUNTIME = 'nodejs20.x';
+const VERCEL_NODE_RUNTIME = 'nodejs22.x';
 
 /** Name (sans `.func`) of the single registry function. Served at `/` and the catch-all route. */
 const REGISTRY_FUNCTION_NAME = 'index';

package/src/cache/README.md

@@ -2,10 +2,13 @@
 
 Incremental build cache for component previews. Tracks file states to skip rebuilding unchanged components.
 
+Every full component build uses the cache (`start`, `build`, `build:components` without an id, and bulk `publish`), unless `--force` is set. The cache file is `<workingPath>/.handoff/.cache/build-cache.json`. A component entry holds its declared files and every file that its last build read: Rollup watch files from the Vite builds (Sass partials included) and the esbuild graph of each script entry. The lockfile state in the global dependencies covers the files under `node_modules`.
+
 ## Files
 
 | File | Purpose |
 |------|---------|
 | `file-state.ts` | `computeFileState()`, `computeDirectoryState()`, `statesMatch()`, `directoryStatesMatch()` — file-level change detection |
-| `build-cache.ts` | `loadBuildCache()`, `saveBuildCache()`, `hasComponentChanged()`, `computeGlobalDepsState()`, `haveGlobalDepsChanged()`, `computeComponentFileStates()` — component-level and global dependency cache management |
+| `build-cache.ts` | `loadBuildCache()`, `saveBuildCache()`, `hasComponentChanged()`, `computeGlobalDepsState()`, `haveGlobalDepsChanged()`, `computeComponentFileStates()`, `computeBuildInputStates()` — component-level and global dependency cache management |
+| `build-inputs.ts` | `createBuildInputs()`, `withBuildInputs()` — collects the files that the Vite builds of a component read |
 | `index.ts` | Barrel re-exports |