handoff-app 1.2.2-7 → 2.0.0-0

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

@@ -1,8 +1,47 @@
 import Handoff from '..';
 /**
- * Build the Next.js documentation application.
+ * Resolved build target. Bare `handoff-app build` resolves to `static`. The
+ * target — not `NODE_ENV` — drives whether Next runs a static export, so a future non-static
+ * `next build` path (registry) does not get conflated with static export.
  */
-declare const buildApp: (handoff: Handoff, skipComponents?: boolean) => Promise<void>;
+export type BuildTarget = 'static' | 'registry';
+/** The default build target when none is supplied on the CLI. */
+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
+ *     Node standalone bundle `out/registry` for registry).
+ *   - `vercel`     → the Vercel Build Output API directory (`.vercel/output`) at the repo root.
+ *
+ * `--package` never implies a {@link BuildTarget}; it is optional and additive. When omitted, the
+ * effective package is target-specific (`standalone` for both targets) so existing behavior is
+ * unchanged.
+ */
+export type BuildPackage = 'standalone' | 'vercel';
+/**
+ * An expected build configuration / flow failure surfaced to the CLI — an invalid `(target,
+ * package)` combination, an unsupported runtime mode for the target, or a not-yet-available
+ * deliverable. These are actionable user-facing conditions, not bugs, so the CLI prints the message
+ * on its own (no stack trace). Genuine/unexpected failures stay plain `Error`s and keep their stack.
+ */
+export declare class HandoffBuildError extends Error {
+    constructor(message: 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.
+ */
+export declare const getRegistryBuildOutputPath: (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
+ * registry app via {@link buildRegistryApp}.
+ */
+declare const buildApp: (handoff: Handoff, target?: BuildTarget, skipComponents?: boolean, buildPackage?: BuildPackage) => Promise<void>;
 /**
  * Watch the Next.js application.
  * Starts a custom dev server with Handoff-specific watchers and hot-reloading.

package/dist/app-builder/build.js

@@ -12,7 +12,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.devApp = exports.watchApp = void 0;
+exports.devApp = exports.watchApp = exports.getRegistryBuildOutputPath = exports.HandoffBuildError = exports.DEFAULT_BUILD_TARGET = void 0;
 const cross_spawn_1 = __importDefault(require("cross-spawn"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
@@ -21,12 +21,72 @@ const patterns_1 = require("../pipeline/patterns");
 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");
+const adapter_1 = require("../registry/db/adapter");
+const resolve_1 = require("../registry/asset-storage/resolve");
 const logger_1 = require("../utils/logger");
 const client_config_1 = require("./client-config");
+const nav_shell_1 = require("./nav-shell");
 const paths_1 = require("./paths");
+const static_export_1 = require("./static-export");
+const vercel_output_1 = require("./vercel-output");
 const watchers_1 = require("./watchers");
 const websocket_1 = require("./websocket");
+/** The default build target when none is supplied on the CLI. */
+exports.DEFAULT_BUILD_TARGET = 'static';
+/**
+ * An expected build configuration / flow failure surfaced to the CLI — an invalid `(target,
+ * package)` combination, an unsupported runtime mode for the target, or a not-yet-available
+ * deliverable. These are actionable user-facing conditions, not bugs, so the CLI prints the message
+ * on its own (no stack trace). Genuine/unexpected failures stay plain `Error`s and keep their stack.
+ */
+class HandoffBuildError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HandoffBuildError';
+    }
+}
+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.
+ * The one rejected combination is `static + standalone`: a static snapshot has no server to package
+ * as a Node standalone bundle.
+ */
+const resolveBuildPackage = (target, buildPackage) => {
+    const resolved = buildPackage !== null && buildPackage !== void 0 ? buildPackage : 'standalone';
+    if (target === 'static' && buildPackage === 'standalone') {
+        throw new HandoffBuildError('Cannot package the static target as a Node standalone bundle (`--target static --package standalone`). ' +
+            'A static snapshot has no server to run; omit `--package` for the static export, or use ' +
+            '`--package vercel` for the Vercel Build Output API, or build `--target registry` for the standalone server bundle.');
+    }
+    return resolved;
+};
 const escapeForSingleQuotedJsString = (value) => value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+/**
+ * Guard the static build target against a registry-only runtime configuration. A static export
+ * builds and serves the local workspace; a `runtime.mode: 'registry'` project has no local workspace
+ * to export, so the build fails clearly rather than producing an empty or misleading site.
+ */
+const assertStaticBuildAllowed = (handoff) => {
+    var _a, _b, _c;
+    const mode = (_c = (_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.runtime) === null || _b === void 0 ? void 0 : _b.mode) !== null && _c !== void 0 ? _c : 'workspace';
+    if (mode === 'registry') {
+        throw new HandoffBuildError('Cannot run the static build target with a registry-only runtime (runtime.mode: "registry"). ' +
+            'The static target builds and exports the local workspace; switch runtime.mode to "workspace" ' +
+            'or package the registry app with `handoff-app build --target registry`.');
+    }
+};
+/**
+ * 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.
+ */
+const getRegistryBuildOutputPath = (handoff) => path_1.default.resolve(handoff.workingPath, handoff.sitesDirectory, 'registry');
+exports.getRegistryBuildOutputPath = getRegistryBuildOutputPath;
 /**
  * Performs cleanup of the application directory by removing the existing app directory if it exists.
  */
@@ -42,16 +102,22 @@ const cleanupAppDirectory = (handoff) => __awaiter(void 0, void 0, void 0, funct
  *
  * @returns The path to the prepared application directory
  */
-const initializeProjectApp = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b, _c;
+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;
+    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');
     const appPath = (0, paths_1.getAppPath)(handoff);
-    // Publish tokens API
-    yield (0, client_config_1.generateTokensApi)(handoff);
+    // Publish tokens API (workspace-derived; skipped for the registry target which serves from the DB).
+    if (includeWorkspaceArtifacts) {
+        yield (0, client_config_1.generateTokensApi)(handoff);
+    }
     // Prepare project app dir
     yield fs_extra_1.default.ensureDir(appPath);
     yield fs_extra_1.default.copy(srcPath, appPath, { overwrite: true, filter: (file) => !file.includes('next.config.mjs') });
-    yield (0, paths_1.syncPublicFiles)(handoff);
+    if (includeWorkspaceArtifacts) {
+        yield (0, paths_1.syncPublicFiles)(handoff);
+    }
     // Copy custom theme CSS if it exists in the user's project
     const customThemePath = path_1.default.resolve(handoff.workingPath, 'theme.css');
     const destPath = path_1.default.resolve(appPath, 'css', 'theme.css');
@@ -65,19 +131,32 @@ const initializeProjectApp = (handoff) => __awaiter(void 0, void 0, void 0, func
     }
     // Prepare project app configuration using stable placeholder replacement.
     const handoffProjectId = handoff.getProjectId();
-    const handoffAppBasePath = (_a = handoff.config.app.base_path) !== null && _a !== void 0 ? _a : '';
+    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 nextConfigPath = path_1.default.resolve(srcPath, 'next.config.mjs');
     const targetPath = path_1.default.resolve(appPath, 'next.config.mjs');
-    const handoffWebsocketPort = (_c = (_b = handoff.config.app.ports) === null || _b === void 0 ? void 0 : _b.websocket) !== null && _c !== void 0 ? _c : 3001;
+    const handoffWebsocketPort = (_h = (_g = handoff.config.app.ports) === null || _g === void 0 ? void 0 : _g.websocket) !== null && _h !== void 0 ? _h : 3001;
     const escapedAppBasePath = escapeForSingleQuotedJsString(handoffAppBasePath);
     const escapedProjectId = escapeForSingleQuotedJsString(handoffProjectId);
     const escapedWorkingPath = escapeForSingleQuotedJsString(handoffWorkingPath);
     const escapedModulePath = escapeForSingleQuotedJsString(handoffModulePath);
     const escapedExportPath = escapeForSingleQuotedJsString(handoffExportPath);
     const escapedWebsocketPort = escapeForSingleQuotedJsString(String(handoffWebsocketPort));
+    // Resolved runtime mode + registry connection inputs (names only) baked into the Next bundle so the
+    // deployed registry app resolves its mode/DB env-var name without any build-machine filesystem.
+    const escapedRuntimeMode = escapeForSingleQuotedJsString(runtimeMode);
+    const escapedRegistryAdapter = escapeForSingleQuotedJsString((0, adapter_1.resolveRegistryAdapter)(handoff.config));
+    const escapedDatabaseUrlEnv = escapeForSingleQuotedJsString((0, adapter_1.resolveDatabaseUrlEnv)(handoff.config));
+    const escapedApiTokenEnv = escapeForSingleQuotedJsString((0, adapter_1.resolveApiTokenEnv)(handoff.config));
+    // Asset storage selection baked (provider + module + env-var names + non-secret options JSON).
+    const assetStorage = (0, resolve_1.resolveAssetStorageFromConfig)(handoff.config);
+    const escapedAssetStorageAdapter = escapeForSingleQuotedJsString(assetStorage.adapterKind);
+    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 placeholderValues = {
         '%HANDOFF_PROJECT_ID%': escapedProjectId,
         '%HANDOFF_APP_BASE_PATH%': escapedAppBasePath,
@@ -85,18 +164,43 @@ const initializeProjectApp = (handoff) => __awaiter(void 0, void 0, void 0, func
         '%HANDOFF_MODULE_PATH%': escapedModulePath,
         '%HANDOFF_EXPORT_PATH%': escapedExportPath,
         '%HANDOFF_WEBSOCKET_PORT%': escapedWebsocketPort,
+        '%HANDOFF_RUNTIME_MODE%': escapedRuntimeMode,
+        '%HANDOFF_REGISTRY_ADAPTER%': escapedRegistryAdapter,
+        '%HANDOFF_REGISTRY_DATABASE_URL_ENV%': escapedDatabaseUrlEnv,
+        '%HANDOFF_REGISTRY_API_TOKEN_ENV%': escapedApiTokenEnv,
+        '%HANDOFF_ASSET_STORAGE_ADAPTER%': escapedAssetStorageAdapter,
+        '%HANDOFF_ASSET_STORAGE_MODULE%': escapedAssetStorageModule,
+        '%HANDOFF_ASSET_STORAGE_TOKEN_ENV%': escapedAssetStorageTokenEnv,
+        '%HANDOFF_ASSET_STORAGE_MAX_INLINE_BYTES%': escapedAssetStorageMaxInline,
+        '%HANDOFF_ASSET_STORAGE_OPTIONS%': escapedAssetStorageOptions,
     };
     let nextConfigContent = yield fs_extra_1.default.readFile(nextConfigPath, 'utf-8');
     for (const [placeholder, value] of Object.entries(placeholderValues)) {
         nextConfigContent = nextConfigContent.split(placeholder).join(value);
     }
     yield fs_extra_1.default.writeFile(targetPath, nextConfigContent);
+    // Bake the markdown-driven navigation shell before `next build` so the docs read API can import it
+    // statically (it is unreadable at runtime in the Vercel registry function). Generated for every
+    // target; only registry-mode clients fetch it.
+    // Registry builds must not bake workspace pages into the shell — they come from the DB at runtime.
+    yield (0, nav_shell_1.generateNavShell)(handoff, appPath, runtimeMode !== 'registry');
+    yield (0, nav_shell_1.generateDefaultPages)(handoff, appPath);
     return appPath;
 });
 /**
- * Build the Next.js documentation application.
+ * 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
+ * registry app via {@link buildRegistryApp}.
  */
-const buildApp = (handoff, skipComponents) => __awaiter(void 0, void 0, void 0, function* () {
+const buildApp = (handoff_1, ...args_1) => __awaiter(void 0, [handoff_1, ...args_1], void 0, function* (handoff, target = exports.DEFAULT_BUILD_TARGET, skipComponents, buildPackage) {
+    // Resolve + validate the (target, package) pair once, before any work.
+    const resolvedPackage = resolveBuildPackage(target, buildPackage);
+    if (target === 'registry') {
+        yield buildRegistryApp(handoff, resolvedPackage);
+        return;
+    }
+    // A registry-only runtime has no local workspace to export — fail clearly before any work.
+    assertStaticBuildAllowed(handoff);
     skipComponents = skipComponents !== null && skipComponents !== void 0 ? skipComponents : false;
     // Perform cleanup
     yield cleanupAppDirectory(handoff);
@@ -108,11 +212,14 @@ const buildApp = (handoff, skipComponents) => __awaiter(void 0, void 0, void 0,
     // Prepare app
     const appPath = yield initializeProjectApp(handoff);
     yield (0, client_config_1.persistClientConfig)(handoff);
-    // Build app
+    // Fail before export if generated HTML references a required artifact that cannot be materialized.
+    (0, static_export_1.validateReferencedArtifacts)(handoff);
+    // Build app. The static target drives Next's `output: 'export'` via HANDOFF_BUILD_TARGET so the
+    // export gate is tied to the resolved target, not to NODE_ENV.
     const buildResult = cross_spawn_1.default.sync('npx', ['next', 'build'], {
         cwd: appPath,
         stdio: ['inherit', 'pipe', 'pipe'],
-        env: Object.assign(Object.assign({}, process.env), { NODE_ENV: 'production' }),
+        env: Object.assign(Object.assign({}, process.env), { NODE_ENV: 'production', HANDOFF_BUILD_TARGET: target }),
     });
     logger_1.Logger.childProcessBuffer(buildResult.stdout);
     logger_1.Logger.childProcessBuffer(buildResult.stderr);
@@ -123,6 +230,17 @@ const buildApp = (handoff, skipComponents) => __awaiter(void 0, void 0, void 0,
         }
         throw new Error(errorMsg);
     }
+    // Reproduce the docs read API (`/api/docs/*`) as route-shaped static files in the export output,
+    // since `output: 'export'` disables the live API routes.
+    const exportDir = path_1.default.resolve(appPath, 'out');
+    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.
+    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);
@@ -132,7 +250,319 @@ const buildApp = (handoff, skipComponents) => __awaiter(void 0, void 0, void 0,
         yield fs_extra_1.default.remove(output);
     }
     // Copy the build files into the project output directory
-    yield fs_extra_1.default.copy(path_1.default.resolve(appPath, 'out'), output);
+    yield fs_extra_1.default.copy(exportDir, output);
+});
+/**
+ * Recursively locate the directory containing the standalone `server.js` entry, used as a fallback
+ * when the deterministic (tracing-root-relative) location does not resolve — e.g. if Next changes
+ * the standalone layout. Returns the first match (breadth-first), or `null` when none is found.
+ */
+const findStandaloneServerDir = (root) => {
+    if (!fs_extra_1.default.existsSync(root)) {
+        return null;
+    }
+    const queue = [root];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const entries = fs_extra_1.default.readdirSync(current, { withFileTypes: true });
+        if (entries.some((entry) => entry.isFile() && entry.name === 'server.js')) {
+            return current;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory() && entry.name !== 'node_modules') {
+                queue.push(path_1.default.join(current, entry.name));
+            }
+        }
+    }
+    return null;
+};
+/**
+ * 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 readme = `# Handoff Registry App
+
+A self-contained, deployable Next.js **standalone** build produced by
+\`handoff-app build --target registry\`. It serves the docs read API (\`/api/docs/*\`) and the
+registry API from a PostgreSQL database and the published docs read-model artifacts — it never
+builds or depends on local workspace component/pattern source, and never runs a static export.
+
+This is the [Next.js standalone output](https://nextjs.org/docs/app/api-reference/config/next-config-js/output):
+\`server.js\` and the trimmed \`node_modules\` it needs sit at this directory's root, with \`public/\`
+and \`.next/static/\` already copied alongside so the server serves them.
+
+## Required environment variables (supplied at deploy time, never baked in)
+
+- \`${databaseUrlEnv}\` — PostgreSQL/Neon connection string, read at request time.
+- \`HANDOFF_REGISTRY_API_TOKEN\` — bearer token for registry management mutations (if used).
+
+## Database migrations
+
+Apply migrations from the \`handoff-app\` CLI as a controlled release step (e.g. in your CI/CD
+pipeline) before deploying new code:
+
+\`\`\`bash
+${databaseUrlEnv}="postgres://…" handoff-app db:migrate
+\`\`\`
+
+\`db:migrate\` reads your project config + DB env vars, resolves the same database adapter the app was
+built with, and applies the package-owned migration set. It runs independently of \`build\` and of
+starting the server, so run it as a release/one-shot job.
+
+## Run it (self-hosting)
+
+Standalone is the documented artifact for self-hosting on a Node.js server, VPS, Docker, or
+Kubernetes. Start the bundled server from this directory:
+
+\`\`\`bash
+${databaseUrlEnv}="postgres://…" node ${entryRelativePath}
+\`\`\`
+
+The server listens on \`PORT\` (default \`3000\`) and \`HOSTNAME\` (default \`localhost\`). **In a
+container, set \`HOSTNAME=0.0.0.0\`** so the server is reachable from outside the container:
+
+\`\`\`bash
+PORT=3000 HOSTNAME=0.0.0.0 ${databaseUrlEnv}="postgres://…" node ${entryRelativePath}
+\`\`\`
+
+### Docker (sketch)
+
+\`\`\`dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY . .
+ENV NODE_ENV=production HOSTNAME=0.0.0.0 PORT=3000
+EXPOSE 3000
+CMD ["node", "${entryRelativePath}"]
+\`\`\`
+
+For multi-instance self-hosting, front \`/_next/static\` with a CDN and configure a shared
+\`cacheHandler\` if you rely on ISR.
+
+## 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
+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.
+`;
+    yield fs_extra_1.default.writeFile(path_1.default.join(outputRoot, 'README.md'), readme);
+});
+/**
+ * Resolve the set of npm packages the packaged registry app must be able to `require`/`import` at
+ * runtime, given the configured database adapter. `next`/`react`/`react-dom` run the server and React
+ * runtime; `drizzle-orm` backs both the request-time DB client and the migration runner; the driver
+ * is adapter-specific (the Neon serverless driver also needs `ws` for its Node WebSocket transport).
+ */
+const getRequiredRegistryRuntimeModules = (handoff) => {
+    var _a;
+    const base = ['next', 'react', 'react-dom', 'drizzle-orm'];
+    const adapter = (0, adapter_1.resolveRegistryAdapter)(handoff.config);
+    const driver = adapter === '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, ...driver, ...storage];
+};
+/**
+ * Build-time guard against the empty-`node_modules` regression (the artifact would otherwise boot-fail
+ * with `Cannot find module 'next'` only on a real, isolated deploy). After assembly, assert every
+ * required runtime module resolves under `<entryDir>/node_modules`. `fs.existsSync` follows symlinks,
+ * so this also catches a dangling pnpm symlink (the hoisted link traced without its `.pnpm` target),
+ * not just an absent directory.
+ *
+ * `handoff-app` itself is intentionally not asserted: the app inlines it via the `@handoff` alias and
+ * `transpilePackages`, so it is not required by its bare specifier at runtime and may be absent.
+ */
+const assertRegistryRuntimeDepsTraced = (handoff, entryDir) => {
+    const required = getRequiredRegistryRuntimeModules(handoff);
+    const missing = required.filter((mod) => !fs_extra_1.default.existsSync(path_1.default.join(entryDir, 'node_modules', ...mod.split('/'), 'package.json')));
+    if (missing.length === 0) {
+        return;
+    }
+    throw new HandoffBuildError(`The packaged registry app is missing required runtime dependencies in its bundled node_modules: ` +
+        `${missing.join(', ')}. The Next file trace did not capture them, so the artifact would fail at ` +
+        `startup with "Cannot find module '${missing[0]}'".\n` +
+        `This usually means the runtime dependencies are installed *above* the build's tracing root ` +
+        `(\`outputFileTracingRoot\`, currently the project root "${handoff.workingPath}"). In a ` +
+        `workspace/monorepo the package manager may hoist them to the monorepo root; the tracing root ` +
+        `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}".`);
+};
+/**
+ * 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
+ * static assets + public tree + resolved runtime config beside the server entry. Shared by both
+ * registry deliverables — the `standalone` package emits this as `out/registry`, and the `vercel`
+ * package emits it inside the Build Output API function directory.
+ *
+ * @returns the absolute path of the server entry (`<entryDir>/server.js`).
+ */
+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);
+    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);
+        if (!located) {
+            throw new Error(`Could not locate the standalone "server.js" in the packaged registry app at "${entryDir}". ` +
+                'The Next standalone layout may have changed.');
+        }
+        serverDir = located;
+    }
+    // The project id (and the `.handoff` staging nesting) are irrelevant to the deployable artifact, so
+    // flatten the server entry up to `entryDir` — the traced `node_modules` already live there.
+    if (path_1.default.resolve(serverDir) !== path_1.default.resolve(entryDir)) {
+        for (const entry of fs_extra_1.default.readdirSync(serverDir)) {
+            yield fs_extra_1.default.move(path_1.default.join(serverDir, entry), path_1.default.join(entryDir, entry), { overwrite: true });
+        }
+        // Drop the now-empty staging nesting. The entry nests under `node_modules/handoff-app/.handoff`,
+        // 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)));
+        if (path_1.default.basename(stagingContainer) === '.handoff' && fs_extra_1.default.existsSync(stagingContainer)) {
+            yield fs_extra_1.default.remove(stagingContainer);
+        }
+    }
+    // Static assets and the app's public tree are not traced into standalone — copy them next to the
+    // server entry where the Next standalone server expects them.
+    const staticSrc = path_1.default.resolve(appPath, '.next', 'static');
+    if (fs_extra_1.default.existsSync(staticSrc)) {
+        yield fs_extra_1.default.copy(staticSrc, path_1.default.join(entryDir, '.next', 'static'), { overwrite: true });
+    }
+    const publicSrc = path_1.default.resolve(appPath, 'public');
+    if (fs_extra_1.default.existsSync(publicSrc)) {
+        yield fs_extra_1.default.copy(publicSrc, path_1.default.join(entryDir, 'public'), { overwrite: true });
+    }
+    // Ship the resolved runtime config beside the entry so the deployed server (cwd = entry dir) can
+    // read the full client config; runtime mode + DB env-var name are also baked into the bundle.
+    for (const configFile of ['client.config.json', 'runtime.server.json']) {
+        const src = path_1.default.resolve(appPath, configFile);
+        if (fs_extra_1.default.existsSync(src)) {
+            yield fs_extra_1.default.copy(src, path_1.default.join(entryDir, configFile), { overwrite: true });
+        }
+    }
+    // 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`).
+    assertRegistryRuntimeDepsTraced(handoff, entryDir);
+    return path_1.default.join(entryDir, 'server.js');
+});
+/**
+ * Package the deployable dynamic registry app.
+ *
+ * Unlike the static target this never builds or bundles workspace component/pattern source and the
+ * resulting artifact has no workspace-source runtime dependency — it ships the app/runtime needed to
+ * serve the docs read API and registry API from the database and published docs read-model
+ * artifacts. Next always runs a `standalone` build (no static export); the divergence is the
+ * final-assembly step driven by `buildPackage`:
+ *   - `standalone` (default) → the documented Next.js standalone layout under the sites output
+ *     directory (`<project>/<sitesOutputDirectory>/registry`, default `out/registry`) — a
+ *     self-hosting artifact for containers, custom Node servers, and VPS, started with
+ *     `node server.js`.
+ *   - `vercel` → the Vercel Build Output API directory (`.vercel/output`) at the repo root: the
+ *     traced bundle wrapped as a Node function plus CDN static assets and a route table.
+ *
+ * Mode is forced to `registry`; the database adapter is honored from config (single-sourced so build
+ * and `db:migrate` never diverge). No connection-string value is ever baked — only env-var *names*.
+ */
+const buildRegistryApp = (handoff_1, ...args_1) => __awaiter(void 0, [handoff_1, ...args_1], void 0, function* (handoff, buildPackage = 'standalone') {
+    var _a, _b, _c;
+    // The registry build target *defines* a registry deployment, so the packaged artifact always runs
+    // in registry mode regardless of the source project's `runtime.mode`. Mode stays config-only at
+    // runtime — it is fixed here by the build target, never inferred from the deploy environment — so
+    // a workspace project can produce a registry app without flipping its own runtime mode.
+    const sourceMode = (_c = (_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.runtime) === null || _b === void 0 ? void 0 : _b.mode) !== null && _c !== void 0 ? _c : 'workspace';
+    if (sourceMode !== 'registry') {
+        logger_1.Logger.info(`Source runtime.mode is "${sourceMode}"; forcing "registry" mode in the packaged registry app.`);
+    }
+    // The adapter stays single-sourced from config (never flipped by the package flag), so build and
+    // `db:migrate` always resolve the same one. `pg` uses long-lived TCP connections that pool poorly on
+    // serverless; warn (non-fatally) so the operator points DATABASE_URL at a pooled endpoint or selects
+    // the Neon adapter. The connection-string value is not available at build time, so this cannot be
+    // validated — it is guidance only and never fails the build.
+    if (buildPackage === 'vercel' && (0, adapter_1.resolveRegistryAdapter)(handoff.config) === 'pg') {
+        logger_1.Logger.warn('Registry Vercel build uses the "pg" adapter (standard TCP connections), which pools poorly on ' +
+            'serverless and can exhaust the database connection limit. Point DATABASE_URL at a pooled endpoint ' +
+            '(PgBouncer / transaction pooling), or set runtime.registry.database.adapter: "neon" for a ' +
+            'serverless-native HTTP/WebSocket driver. The build will continue.');
+    }
+    // Stage the app without any workspace-derived artifacts — the registry serves from the database.
+    yield cleanupAppDirectory(handoff);
+    const appPath = yield initializeProjectApp(handoff, {
+        includeWorkspaceArtifacts: false,
+        runtimeModeOverride: 'registry',
+    });
+    // Persist the resolved client/server runtime config so the deployed app reports registry mode and
+    // resolves its DB env-var name (the connection string itself is read from that env var at runtime).
+    yield (0, client_config_1.persistClientConfig)(handoff, { runtimeModeOverride: 'registry' });
+    // Remove prior registry outputs *before* tracing. Both deliverables (`out/registry` and
+    // `.vercel/output`) live inside the trace root (the project root), and after this fix each contains
+    // a full bundled `node_modules`. A stale prior output left in place could be swept into the new
+    // trace (bundle bloat / recursive nesting), so clear both up front. The per-deliverable cleanup in
+    // the assembly step remains.
+    yield fs_extra_1.default.remove((0, exports.getRegistryBuildOutputPath)(handoff));
+    yield fs_extra_1.default.remove((0, vercel_output_1.getVercelOutputPath)(handoff));
+    // Build the dynamic app. `output: 'standalone'` (driven by HANDOFF_BUILD_TARGET) traces the runtime
+    // and the selected Postgres/Neon driver into a self-contained bundle — never a static export.
+    const buildResult = cross_spawn_1.default.sync('npx', ['next', 'build'], {
+        cwd: appPath,
+        stdio: ['inherit', 'pipe', 'pipe'],
+        env: Object.assign(Object.assign({}, process.env), { NODE_ENV: 'production', HANDOFF_BUILD_TARGET: 'registry' }),
+    });
+    logger_1.Logger.childProcessBuffer(buildResult.stdout);
+    logger_1.Logger.childProcessBuffer(buildResult.stderr);
+    if (buildResult.status !== 0) {
+        let errorMsg = `Registry app build failed with exit code ${buildResult.status}`;
+        if (buildResult.error) {
+            errorMsg += `\nSpawn error: ${buildResult.error.message}`;
+        }
+        throw new Error(errorMsg);
+    }
+    // Assemble the deployable package. Standalone tracing is rooted at the package (modulePath), so the
+    // app's traced files land under `<relAppDir>` inside the standalone tree; static assets and public
+    // 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"`.');
+    }
+    // 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.
+    if (buildPackage === 'vercel') {
+        yield (0, vercel_output_1.writeRegistryVercelOutput)(handoff, { appPath, standaloneRoot, assembleStandalone: assembleRegistryStandalone });
+        return;
+    }
+    // Standalone bundle (default): the documented self-hosting layout under the sites output directory.
+    const output = (0, exports.getRegistryBuildOutputPath)(handoff);
+    yield fs_extra_1.default.remove(output);
+    yield fs_extra_1.default.ensureDir(output);
+    const serverEntry = yield assembleRegistryStandalone(handoff, appPath, standaloneRoot, output);
+    // Migrations are intentionally not bundled into the artifact: they are applied from the
+    // `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, adapter_1.resolveDatabaseUrlEnv)(handoff.config));
+    logger_1.Logger.success(`Packaged registry app at ${output} (start: \`node ${entryRelativePath}\`, migrate: \`handoff-app db:migrate\`).`);
 });
 /**
  * Watch the Next.js application.
@@ -140,11 +570,12 @@ const buildApp = (handoff, skipComponents) => __awaiter(void 0, void 0, void 0,
  */
 const watchApp = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
     var _a, _b, _c, _d;
-    // Initial processing of the components with caching enabled
-    // This will skip rebuilding components whose source files haven't changed
-    yield (0, builder_1.default)(handoff, undefined, undefined, { useCache: true });
+    // 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).
     yield (0, javascript_1.buildMainJS)(handoff);
     yield (0, css_1.buildMainCss)(handoff);
+    yield (0, builder_1.default)(handoff, undefined, undefined, { useCache: true });
     // Build patterns after components are ready
     yield (0, patterns_1.buildPatterns)(handoff);
     const appPath = yield initializeProjectApp(handoff);
@@ -165,7 +596,9 @@ const watchApp = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
     const nextProcess = (0, cross_spawn_1.default)('npx', ['next', 'dev', '--turbopack', '--port', String(port)], {
         cwd: appPath,
         stdio: ['inherit', 'pipe', 'pipe'],
-        env: Object.assign(Object.assign({}, process.env), { NODE_ENV: 'development' }),
+        env: Object.assign(Object.assign({}, process.env), { NODE_ENV: 'development', 
+            // Workspace dev is never a static export, even if a static target leaked into the environment.
+            HANDOFF_BUILD_TARGET: '' }),
     });
     logger_1.Logger.pipeChildStreams(nextProcess.stdout, nextProcess.stderr);
     nextProcess.on('error', (error) => {
@@ -196,11 +629,13 @@ const watchApp = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
         runtimeComponentsWatcher: null,
         runtimeConfigurationWatcher: null,
         componentDirectoriesWatcher: null,
+        patternDirectoriesWatcher: null,
     };
     (0, watchers_1.watchPublicDirectory)(handoff, wss, state, chokidarConfig);
     (0, watchers_1.watchRuntimeComponents)(handoff, state, (0, watchers_1.getRuntimeComponentsPathsToWatch)(handoff));
     (0, watchers_1.watchRuntimeConfiguration)(handoff, state);
     (0, watchers_1.watchComponentDirectories)(handoff, state, chokidarConfig);
+    (0, watchers_1.watchPatternDirectories)(handoff, state, chokidarConfig);
     (0, watchers_1.watchGlobalEntries)(handoff, state, chokidarConfig);
     (0, watchers_1.watchPages)(handoff, chokidarConfig);
 });
@@ -225,7 +660,9 @@ const devApp = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
     const devResult = cross_spawn_1.default.sync('npx', ['next', 'dev', '--turbopack', '--port', String(devPort)], {
         cwd: appPath,
         stdio: ['inherit', 'pipe', 'pipe'],
-        env: Object.assign(Object.assign({}, process.env), { NODE_ENV: 'development' }),
+        env: Object.assign(Object.assign({}, process.env), { NODE_ENV: 'development', 
+            // Workspace dev is never a static export, even if a static target leaked into the environment.
+            HANDOFF_BUILD_TARGET: '' }),
     });
     logger_1.Logger.childProcessBuffer(devResult.stdout);
     logger_1.Logger.childProcessBuffer(devResult.stderr);