handoff-app 2.0.0-0 → 2.0.0-10

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

@@ -36,6 +36,18 @@ export declare class HandoffBuildError extends Error {
  * deployable, so it is not keyed by project id.
  */
 export declare const getRegistryBuildOutputPath: (handoff: Handoff) => string;
+/**
+ * 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 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

@@ -1,4 +1,27 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -12,17 +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.HandoffBuildError = exports.DEFAULT_BUILD_TARGET = void 0;
+const p = __importStar(require("@clack/prompts"));
 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 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 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");
@@ -78,6 +104,51 @@ const assertStaticBuildAllowed = (handoff) => {
             'or package the registry app with `handoff-app build --target registry`.');
     }
 };
+/**
+ * Run the Next.js production build while keeping its delayed output out of the successful CLI flow.
+ * Captured output is replayed only when the child fails so compiler diagnostics remain available.
+ */
+const runNextBuild = (appPath, target, errorLabel) => __awaiter(void 0, void 0, void 0, function* () {
+    const spinner = p.spinner();
+    spinner.start('Building Next.js app...');
+    const stdout = [];
+    const stderr = [];
+    yield new Promise((resolve, reject) => {
+        var _a, _b;
+        const buildProcess = (0, cross_spawn_1.default)('npx', ['next', 'build'], {
+            cwd: appPath,
+            stdio: ['inherit', 'pipe', 'pipe'],
+            env: Object.assign(Object.assign({}, process.env), { NODE_ENV: 'production', HANDOFF_BUILD_TARGET: target }),
+        });
+        (_a = buildProcess.stdout) === null || _a === void 0 ? void 0 : _a.on('data', (chunk) => stdout.push(Buffer.from(chunk)));
+        (_b = buildProcess.stderr) === null || _b === void 0 ? void 0 : _b.on('data', (chunk) => stderr.push(Buffer.from(chunk)));
+        let settled = false;
+        const fail = (message) => {
+            if (settled)
+                return;
+            settled = true;
+            spinner.stop('Next.js app build failed');
+            logger_1.Logger.childProcessBuffer(Buffer.concat(stdout));
+            logger_1.Logger.childProcessBuffer(Buffer.concat(stderr));
+            reject(new Error(message));
+        };
+        buildProcess.once('error', (error) => {
+            fail(`${errorLabel} failed to start\nSpawn error: ${error.message}`);
+        });
+        buildProcess.once('close', (code, signal) => {
+            if (settled)
+                return;
+            if (code === 0) {
+                settled = true;
+                spinner.stop('Next.js app built successfully');
+                resolve();
+                return;
+            }
+            const reason = signal ? ` because it was terminated by signal ${signal}` : ` with exit code ${code}`;
+            fail(`${errorLabel} failed${reason}`);
+        });
+    });
+});
 /**
  * Output directory for the packaged registry app. Lives under the configurable sites output
  * directory (`sitesOutputDirectory`, default `out`) alongside the static target's `out/<projectId>`
@@ -87,6 +158,45 @@ const assertStaticBuildAllowed = (handoff) => {
  */
 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.
  */
@@ -103,7 +213,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;
     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');
@@ -142,14 +252,16 @@ 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
     // 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));
+    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).
     const assetStorage = (0, resolve_1.resolveAssetStorageFromConfig)(handoff.config);
     const escapedAssetStorageAdapter = escapeForSingleQuotedJsString(assetStorage.adapterKind);
@@ -157,22 +269,35 @@ const initializeProjectApp = (handoff_1, ...args_1) => __awaiter(void 0, [handof
     const escapedAssetStorageTokenEnv = escapeForSingleQuotedJsString(assetStorage.tokenEnv);
     const escapedAssetStorageMaxInline = escapeForSingleQuotedJsString(String(assetStorage.maxInlineBytes));
     const escapedAssetStorageOptions = escapeForSingleQuotedJsString(JSON.stringify((_k = assetStorage.options) !== null && _k !== void 0 ? _k : {}));
+    // 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((_l = ai.defaultModel) !== null && _l !== void 0 ? _l : '');
+    const escapedAiProviderModules = escapeForSingleQuotedJsString(JSON.stringify(ai.connections.map((connection) => connection.module).filter((module) => Boolean(module))));
     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_REGISTRY_ADAPTER%': escapedRegistryAdapter,
+        '%HANDOFF_MCP_ENABLED%': escapedMcpEnabled,
+        '%HANDOFF_REGISTRY_DRIVER%': escapedRegistryDriver,
         '%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,
+        '%HANDOFF_AI_ENABLED%': escapedAiEnabled,
+        '%HANDOFF_AI_BAKED_CONNECTIONS%': escapedAiConnections,
+        '%HANDOFF_AI_DEFAULT_MODEL%': escapedAiDefaultModel,
+        '%HANDOFF_AI_PROVIDER_MODULES%': escapedAiProviderModules,
     };
     let nextConfigContent = yield fs_extra_1.default.readFile(nextConfigPath, 'utf-8');
     for (const [placeholder, value] of Object.entries(placeholderValues)) {
@@ -216,20 +341,7 @@ const buildApp = (handoff_1, ...args_1) => __awaiter(void 0, [handoff_1, ...args
     (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', HANDOFF_BUILD_TARGET: target }),
-    });
-    logger_1.Logger.childProcessBuffer(buildResult.stdout);
-    logger_1.Logger.childProcessBuffer(buildResult.stderr);
-    if (buildResult.status !== 0) {
-        let errorMsg = `Next.js build failed with exit code ${buildResult.status}`;
-        if (buildResult.error) {
-            errorMsg += `\nSpawn error: ${buildResult.error.message}`;
-        }
-        throw new Error(errorMsg);
-    }
+    yield runNextBuild(appPath, target, 'Next.js build');
     // 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');
@@ -280,7 +392,22 @@ 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) => __awaiter(void 0, void 0, void 0, function* () {
+    const serviceKeyEnvs = [...new Set(ai.connections.map((connection) => connection.apiKeyEnv).filter(Boolean))];
+    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.'}
+${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 readme = `# Handoff Registry App
 
 A self-contained, deployable Next.js **standalone** build produced by
@@ -295,8 +422,12 @@ 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).
+- \`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.
+${aiSection}
 ## Database migrations
 
 Apply migrations from the \`handoff-app\` CLI as a controlled release step (e.g. in your CI/CD
@@ -306,10 +437,33 @@ pipeline) before deploying new code:
 ${databaseUrlEnv}="postgres://…" handoff-app db:migrate
 \`\`\`
 
-\`db:migrate\` reads your project config + DB env vars, resolves the same database adapter the app was
+\`db:migrate\` reads your project config + DB env vars, resolves the same database driver 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.
 
+## Complete the one-time installation
+
+After migrations and deployment, open \`/install\` immediately and create the initial administrator.
+The installer verifies the deployment but never changes the schema. An exposed, uninstalled registry
+can be claimed by its first visitor, so do not leave this step unattended.
+
+Once installation completes, sign in and authorize a workspace. Either approve the CLI in the
+browser:
+
+\`\`\`bash
+handoff-app login --url https://registry.example.com
+\`\`\`
+
+or create a token under Account > Access tokens and set it in the workspace environment:
+
+\`\`\`bash
+HANDOFF_REGISTRY_URL=https://registry.example.com
+HANDOFF_REGISTRY_ACCESS_TOKEN=hnd_…
+\`\`\`
+
+Both produce the same revocable, user-owned credential. The former
+\`HANDOFF_REGISTRY_API_TOKEN\` fixed server secret is no longer accepted.
+
 ## Run it (self-hosting)
 
 Standalone is the documented artifact for self-hosting on a Node.js server, VPS, Docker, or
@@ -352,15 +506,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 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).
+ * 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).
  */
 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'];
+    const base = ['next', 'next-auth', 'react', 'react-dom', 'drizzle-orm'];
+    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', 'zod');
+    }
+    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.
@@ -373,7 +537,7 @@ const getRequiredRegistryRuntimeModules = (handoff) => {
     if (Array.isArray(sdkModules)) {
         storage.push(...sdkModules.filter((mod) => typeof mod === 'string'));
     }
-    return [...base, ...driver, ...storage];
+    return [...base, ...driverModules, ...storage];
 };
 /**
  * Build-time guard against the empty-`node_modules` regression (the artifact would otherwise boot-fail
@@ -411,14 +575,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);
@@ -438,7 +599,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);
         }
@@ -461,6 +622,16 @@ 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 });
     // 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`).
@@ -482,7 +653,7 @@ const assembleRegistryStandalone = (handoff, appPath, standaloneRoot, entryDir)
  *   - `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
+ * Mode is forced to `registry`; the database driver 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') {
@@ -495,15 +666,15 @@ const buildRegistryApp = (handoff_1, ...args_1) => __awaiter(void 0, [handoff_1,
     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
+    // The driver 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
+    // the Neon driver. 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 ' +
+    if (buildPackage === 'vercel' && (0, driver_1.resolveRegistryDriver)(handoff.config) === 'pg') {
+        logger_1.Logger.warn('Registry Vercel build uses the "pg" driver (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 ' +
+            '(PgBouncer / transaction pooling), or set runtime.registry.database.driver: "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.
@@ -524,27 +695,16 @@ const buildRegistryApp = (handoff_1, ...args_1) => __awaiter(void 0, [handoff_1,
     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);
-    }
+    yield runNextBuild(appPath, 'registry', 'Registry app build');
     // 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"`.');
+        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.
@@ -561,7 +721,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, adapter_1.resolveDatabaseUrlEnv)(handoff.config));
+    yield writeRegistryDeploymentReadme(output, entryRelativePath, (0, driver_1.resolveDatabaseUrlEnv)(handoff.config), (0, connections_1.resolveAiFromConfig)(handoff.config));
     logger_1.Logger.success(`Packaged registry app at ${output} (start: \`node ${entryRelativePath}\`, migrate: \`handoff-app db:migrate\`).`);
 });
 /**
@@ -628,14 +788,12 @@ const watchApp = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
         pendingHandlers: new Map(),
         runtimeComponentsWatcher: null,
         runtimeConfigurationWatcher: null,
-        componentDirectoriesWatcher: null,
-        patternDirectoriesWatcher: null,
+        catalogDirectoriesWatcher: 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.watchCatalogDirectories)(handoff, state, chokidarConfig);
     (0, watchers_1.watchGlobalEntries)(handoff, state, chokidarConfig);
     (0, watchers_1.watchPages)(handoff, chokidarConfig);
 });

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

@@ -17,7 +17,8 @@ const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const config_1 = require("../config");
 const resolve_1 = require("../registry/asset-storage/resolve");
-const adapter_1 = require("../registry/db/adapter");
+const connection_1 = require("../registry/connection");
+const driver_1 = require("../registry/db/driver");
 const paths_1 = require("./paths");
 /**
  * Publishes the tokens API files to the public directory.
@@ -55,7 +56,7 @@ exports.generateTokensApi = generateTokensApi;
  * Build the server-only runtime config consumed by the docs read API.
  *
  * The browser-facing `client.config.json` carries only the resolved mode; the server additionally
- * needs the registry connection *inputs* (selected adapter + the *name* of the database-URL env
+ * needs the registry connection *inputs* (selected driver + the *name* of the database-URL env
  * var) to back the registry-mode docs read API. These are non-secret — the connection-string value
  * itself is never persisted, only resolved from the env var at request time.
  */
@@ -64,10 +65,10 @@ const buildServerRuntimeConfig = (config, modeOverride) => {
     const assetStorage = (0, resolve_1.resolveAssetStorageFromConfig)(config);
     return {
         mode: (_b = modeOverride !== null && modeOverride !== void 0 ? modeOverride : (_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.mode) !== null && _b !== void 0 ? _b : 'workspace',
+        mcp: (0, config_1.isMcpEnabled)(config),
         registry: {
-            adapter: (0, adapter_1.resolveRegistryAdapter)(config),
-            databaseUrlEnv: (0, adapter_1.resolveDatabaseUrlEnv)(config),
-            apiTokenEnv: (0, adapter_1.resolveApiTokenEnv)(config),
+            driver: (0, driver_1.resolveRegistryDriver)(config),
+            databaseUrlEnv: (0, driver_1.resolveDatabaseUrlEnv)(config),
         },
         assetStorage: {
             adapter: assetStorage.adapterKind,
@@ -84,17 +85,20 @@ const buildServerRuntimeConfig = (config, modeOverride) => {
  * connection inputs from. Both are always written together so they never drift.
  */
 const persistClientConfig = (handoff_1, ...args_1) => __awaiter(void 0, [handoff_1, ...args_1], void 0, function* (handoff, options = {}) {
+    var _a;
     const appPath = (0, paths_1.getAppPath)(handoff);
     // Ensure directory exists
     yield fs_extra_1.default.ensureDir(appPath);
     const clientConfig = (0, config_1.getClientConfig)(handoff.config);
-    if (options.runtimeModeOverride) {
-        // A forced registry mode (the registry build target) is never a connected workspace, so the
-        // baked client config must report `connected: false` even when packaged from a connected
-        // workspace project.
-        const connected = options.runtimeModeOverride === 'registry' ? false : clientConfig.runtime.connected;
-        clientConfig.runtime = Object.assign(Object.assign({}, clientConfig.runtime), { mode: options.runtimeModeOverride, connected });
-    }
+    const mode = (_a = options.runtimeModeOverride) !== null && _a !== void 0 ? _a : clientConfig.runtime.mode;
+    // A registry build target is never a connected workspace, so it must bake `connected: false`
+    // even when packaged from a connected project. Otherwise a workspace is connected whenever a
+    // registry URL resolves — from config/env or a saved device login — so `login` alone surfaces
+    // the publish/checkout UI without also requiring HANDOFF_REGISTRY_URL.
+    const connected = mode === 'registry'
+        ? false
+        : Boolean((yield (0, connection_1.resolveAuthenticatedRegistryConnection)(handoff.config, handoff.workingPath, handoff.getProfile())).url);
+    clientConfig.runtime = Object.assign(Object.assign({}, clientConfig.runtime), { mode, connected });
     yield fs_extra_1.default.writeJson(path_1.default.resolve(appPath, 'client.config.json'), { config: clientConfig }, { spaces: 2 });
     yield fs_extra_1.default.writeJson(path_1.default.resolve(appPath, 'runtime.server.json'), buildServerRuntimeConfig(handoff.config, options.runtimeModeOverride), { spaces: 2 });
 });

package/dist/app-builder/config-diff/strategies/pattern.js

@@ -43,12 +43,12 @@ const snapshot_1 = require("../snapshot");
  * components. Outer key is component id, inner key is synthetic preview key.
  */
 const snapshotPatternSynthetics = (handoff, patternId) => {
-    var _a, _b, _c, _d;
-    const components = (_c = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.components) !== null && _c !== void 0 ? _c : {};
+    var _a, _b, _c;
+    const components = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.components) !== null && _b !== void 0 ? _b : {};
     const prefix = `__pattern_${patternId}_`;
     const result = new Map();
     for (const [componentId, component] of Object.entries(components)) {
-        const previews = (_d = component.internalPatternPreviews) !== null && _d !== void 0 ? _d : {};
+        const previews = (_c = component.internalPatternPreviews) !== null && _c !== void 0 ? _c : {};
         const entries = new Map();
         for (const [key, preview] of Object.entries(previews)) {
             if (key.startsWith(prefix)) {

package/dist/app-builder/nav-shell.js

@@ -14,10 +14,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateNavShell = exports.generateDefaultPages = exports.DEFAULT_PAGES_RELATIVE_PATH = exports.NAV_SHELL_RELATIVE_PATH = void 0;
 const fs_extra_1 = __importDefault(require("fs-extra"));
-const gray_matter_1 = __importDefault(require("gray-matter"));
 const path_1 = __importDefault(require("path"));
+const markdown_1 = require("../utils/markdown");
 const menu_shell_1 = require("../utils/menu-shell");
 const logger_1 = require("../utils/logger");
+const pages_1 = require("../utils/pages");
 /**
  * Relative path (within the staged Next app) of the baked navigation shell. The docs read API
  * (`pages/api/docs/nav.json.ts`) imports this statically so it is bundled into the route chunk and
@@ -27,21 +28,13 @@ const logger_1 = require("../utils/logger");
 exports.NAV_SHELL_RELATIVE_PATH = path_1.default.join('generated', 'nav-shell.json');
 /** Baked package-default markdown used as the registry catch-all's runtime fallback. */
 exports.DEFAULT_PAGES_RELATIVE_PATH = path_1.default.join('generated', 'default-pages.json');
-/** Recursively collect package docs (except dedicated index routes) by their catch-all id. */
-const collectDefaultPages = (root, relativeParts = []) => {
-    if (!fs_extra_1.default.existsSync(root))
-        return {};
+/** Collect package defaults for registry fallbacks, including the dedicated root home page. */
+const collectDefaultPages = (root) => {
     const pages = {};
-    for (const entry of fs_extra_1.default.readdirSync(root)) {
-        const absolutePath = path_1.default.join(root, entry);
-        if (fs_extra_1.default.lstatSync(absolutePath).isDirectory()) {
-            Object.assign(pages, collectDefaultPages(absolutePath, [...relativeParts, entry]));
-        }
-        else if (entry.endsWith('.md') && entry !== 'index.md') {
-            const id = [...relativeParts, entry.replace(/\.md$/, '')].join('/');
-            const { data, content } = (0, gray_matter_1.default)(fs_extra_1.default.readFileSync(absolutePath, 'utf8'));
-            pages[id] = { metadata: data, content };
-        }
+    for (const segments of (0, pages_1.collectPageSlugSegments)(root, { includeRootIndex: true })) {
+        const id = segments.join('/');
+        const { data, content } = (0, markdown_1.parseMarkdown)(fs_extra_1.default.readFileSync(path_1.default.resolve(root, `${id}.md`), 'utf8'));
+        pages[id] = { metadata: data, content };
     }
     return pages;
 };