handoff-app 2.0.0-8 → 2.0.0

package/UPGRADE.md

@@ -18,29 +18,54 @@ Each feature section identifies the affected projects and the required changes.
 
 | Change | Affected projects |
 | --- | --- |
-| [Figma token environment references](#figma-token-environment-references) | Projects that put a Figma token directly in config |
+| [Node.js 22](#nodejs-22) | All projects |
+| [Figma settings](#figma-settings) | Projects that set Figma values in config |
 | [Catalog items](#catalog-items) | Projects with component or pattern declarations |
+| [Output directories](#output-directories) | Projects that deploy the static build, commit `exported/`, or use a `public-<projectId>` directory |
 
 <!-- Add future breaking changes as feature sections before "Verify the upgrade". Add each section to this table. -->
 
-### Figma token environment references
+### Node.js 22
 
-`devAccessToken` and its legacy spelling `dev_access_token` now accept only an environment reference.
+Handoff 2.x.x requires Node.js 22 or newer and npm 10 or newer. Version 1.x.x supported Node.js 16.
+Update Node.js, CI images, and hosting runtimes before you install the new package.
+
+Projects created by `handoff-app init` in version 1.x.x declare the old minimum in `package.json`.
+Change it to:
+
+```json
+"engines": {
+  "node": ">=22",
+  "npm": ">=10"
+}
+```
+
+### Figma settings
+
+The Figma file ID and access token moved to `integrations.figma`.
+The top-level `figmaProjectId`, `figma_project_id`, `devAccessToken`, and `dev_access_token` were removed, and Handoff ignores them.
+If you use `HANDOFF_FIGMA_PROJECT_ID` and `HANDOFF_DEV_ACCESS_TOKEN` and do not set Figma values in config, no change is required.
+
+The access token accepts only an environment reference.
 A literal token throws `HandoffConfigError`, including in JavaScript and JSON configs.
-Move the token to the environment and replace the literal:
+Replace the old keys. Move a literal token to the environment:
 
 ```ts
 import { defineConfig, fromEnv } from 'handoff-app';
 
 export default defineConfig({
-  devAccessToken: fromEnv('HANDOFF_DEV_ACCESS_TOKEN'),
+  integrations: {
+    figma: {
+      projectId: 'your-figma-file-id',
+      accessToken: fromEnv('HANDOFF_DEV_ACCESS_TOKEN'),
+    },
+  },
 });
 ```
 
-For JSON, use `"devAccessToken": { "$env": "HANDOFF_DEV_ACCESS_TOKEN" }`.
-If you already use `HANDOFF_DEV_ACCESS_TOKEN` and omit the config property, no change is required.
-Environment references resolve after profile merging. Higher-layer literals still override default
-environment seeds for properties that allow literals, such as output directories.
+For JSON, use `"accessToken": { "$env": "HANDOFF_DEV_ACCESS_TOKEN" }`.
+Environment references resolve after profile merging. A profile can change one value, such as `integrations.figma.projectId`, and keep the other.
+A literal in a higher layer, such as `projectId: 'your-figma-file-id'`, overrides the default environment variable.
 
 ### Catalog items
 
@@ -201,6 +226,29 @@ CSF uses `renderer: 'react'` with `format: 'csf'` inside `implementation`.
 Checkout writes only catalog declarations.
 Registry records require explicit renderer and source-format metadata where applicable.
 
+### Output directories
+
+Version 1.x.x put the static site and the fetched tokens in a directory named after `<projectId>`.
+`<projectId>` was the Figma file ID, or a name made from the project path when no Figma file was set.
+Version 2.x.x uses fixed directory names:
+
+| Content | 1.x.x | 2.x.x |
+| --- | --- | --- |
+| Static site from `handoff-app build` | `out/<projectId>` | `out/static` |
+| Tokens and assets from `fetch` and `checkout` | `exported/<projectId>` | `exported` |
+| Project-specific public files | `public-<projectId>` | Removed. Use `public` |
+
+Do these steps:
+
+1. Update deploy scripts and CI steps that read `out/<projectId>`.
+   If you set `sitesOutputDirectory` or `HANDOFF_SITES_DIR`, the site is in `static` below that directory.
+2. Move the contents of `exported/<projectId>` up to `exported`, or run `npm run fetch` again.
+   Then remove `exported/<projectId>` and commit the result.
+3. Merge the files from `public-<projectId>` into `public`, then remove `public-<projectId>`.
+
+A repository that builds more than one Figma file gets one `out/static` and one `exported` directory.
+Set `HANDOFF_SITES_DIR` and `HANDOFF_OUTPUT_DIR`, or the matching config values in a profile, to a different directory for each build.
+
 ### Verify the upgrade
 
 After you apply the required migrations, verify the project:

package/components.json

@@ -1,21 +1,21 @@
 {
-    "$schema": "https://ui.shadcn.com/schema.json",
-    "style": "new-york",
-    "rsc": false,
-    "tsx": true,
-    "tailwind": {
-      "config": "tailwind.config.ts",
-      "css": "src/app/css/index.css",
-      "baseColor": "zinc",
-      "cssVariables": true,
-      "prefix": ""
-    },
-    "aliases": {
-      "components": "src/app/components",
-      "utils": "src/app/lib/utils",
-      "ui": "src/app/components/ui",
-      "lib": "src/app/lib",
-      "hooks": "src/app/hooks"
-    },
-    "iconLibrary": "lucide"
-  }
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "tailwind.config.ts",
+    "css": "src/app/css/index.css",
+    "baseColor": "zinc",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "src/app/components",
+    "utils": "src/app/lib/utils",
+    "ui": "src/app/components/ui",
+    "lib": "src/app/lib",
+    "hooks": "src/app/hooks"
+  },
+  "iconLibrary": "lucide"
+}

package/config/docs/foundations/colors/guidelines.md

@@ -1,7 +1,6 @@
 ---
 title: Color Guidelines
 description: How to apply the color palette consistently and accessibly across products.
-metaTitle: 'Color Guidelines | Handoff Design System'
 metaDescription: 'How to apply the color palette consistently and accessibly across products.'
 ---
 

package/config/docs/foundations/colors.md

@@ -2,6 +2,5 @@
 title: Colors
 description: Color system built out of main brand colors and adjusted for variety of interfaces.
 image: hero-colors
-metaTitle: 'Colors | Handoff Design System'
 metaDescription: 'Color system built out of main brand colors and adjusted for variety of interfaces.'
 ---

package/config/docs/foundations/effects/guidelines.md

@@ -1,7 +1,6 @@
 ---
 title: Effects Guidelines
 description: When and how to apply shadows, blurs, and elevation across the interface.
-metaTitle: 'Effects Guidelines | Handoff Design System'
 metaDescription: 'When and how to apply shadows, blurs, and elevation across the interface.'
 ---
 

package/config/docs/foundations/effects/resources.md

@@ -1,7 +1,6 @@
 ---
 title: Effects Resources
 description: Reference values and assets for reproducing the brand's effects in any tool.
-metaTitle: 'Effects Resources | Handoff Design System'
 metaDescription: 'Reference values and assets for reproducing effects in any tool.'
 ---
 

package/config/docs/foundations/effects.md

@@ -2,7 +2,6 @@
 title: Effects
 description: Effects are Drop Shadows, Inner Shadows and Blur Effects. 
 image: hero-effects
-metaTitle: 'Effects | Handoff Design System'
 metaDescription: 'Effects are Drop Shadows, Inner Shadows and Blur Effects.'
 ---
 

package/config/docs/foundations/fonts.md

@@ -1,7 +1,6 @@
 ---
 title: Fonts
 description: Approved library of font families that are approved and licensed for use across the organization.
-metaTitle: Fonts | Handoff Design System
 metaDescription: Font families are packaged as assets that can be used across platforms.
 ---
 

package/config/docs/foundations/grid.md

@@ -2,7 +2,6 @@
 title: Grid
 description: Layout grid and spacing system that keeps compositions aligned and balanced.
 image: hero-design
-metaTitle: 'Grid | Handoff Design System'
 metaDescription: 'Layout grid and spacing system that keeps compositions aligned and balanced.'
 ---
 

package/config/docs/foundations/icon.md

@@ -1,6 +1,5 @@
 ---
 title: Icon Library
 description: Set of icons used to provide users with a way to process information faster and instinctively recognize actions signified by the icon.
-metaTitle: 'Icon Library | Handoff Design System'
 metaDescription: 'Set of icons used to provide users with a way to process information faster and instinctively recognize actions signified by the icon.'
 ---

package/config/docs/foundations/icons/guidelines.md

@@ -1,7 +1,6 @@
 ---
 title: Icon Guidelines
 description: Sizing, spacing, and usage rules that keep the icon set consistent.
-metaTitle: 'Icon Guidelines | Handoff Design System'
 metaDescription: 'Sizing, spacing, and usage rules that keep the icon set consistent.'
 ---
 

package/config/docs/foundations/icons.md

@@ -1,6 +1,5 @@
 ---
 title: Icon Library
 description: Set of icons used to provide users with a way to process information faster and instinctively recognize actions signified by the icon.
-metaTitle: 'Icon Library | Handoff Design System'
 metaDescription: 'Set of icons used to provide users with a way to process information faster and instinctively recognize actions signified by the icon.'
 ---

package/config/docs/foundations/images/guidelines.md

@@ -1,7 +1,6 @@
 ---
 title: Image Guidelines
 description: How to select, crop, and treat imagery so it stays on brand.
-metaTitle: 'Image Guidelines | Handoff Design System'
 metaDescription: 'How to select, crop, and treat imagery so it stays on brand.'
 ---
 

package/config/docs/foundations/images/resources.md

@@ -1,7 +1,6 @@
 ---
 title: Image Resources
 description: Source files and downloads for approved photography and illustration.
-metaTitle: 'Image Resources | Handoff Design System'
 metaDescription: 'Source files and downloads for approved photography and illustration.'
 ---
 

package/config/docs/foundations/images.md

@@ -2,7 +2,6 @@
 title: Images
 description: Photography and illustration style that shapes how the brand looks and feels.
 image: hero-design
-metaTitle: 'Images | Handoff Design System'
 metaDescription: 'Photography and illustration style that shapes how the brand looks and feels.'
 ---
 

package/config/docs/foundations/logo/resources.md

@@ -1,7 +1,6 @@
 ---
 title: Logo Resources
 description: Downloadable logo files and everything teams need to represent the brand correctly.
-metaTitle: 'Logo Resources | Handoff Design System'
 metaDescription: 'Downloadable logo files and everything teams need to represent the brand correctly.'
 ---
 

package/config/docs/foundations/logo.md

@@ -2,6 +2,5 @@
 title: Logos
 description: Show the logos used for promoting public identification and recognition.
 image: react
-metaTitle: 'Logos | Handoff Design System'
 metaDescription: 'Show the logos used for promoting public identification and recognition.'
 ---

package/config/docs/foundations/typography/guidelines.md

@@ -1,7 +1,6 @@
 ---
 title: Typography Guidelines
 description: Best practices for type scale, hierarchy, and readability across the system.
-metaTitle: 'Typography Guidelines | Handoff Design System'
 metaDescription: 'Best practices for type scale, hierarchy, and readability across the system.'
 ---
 

package/config/docs/foundations/typography/resources.md

@@ -1,7 +1,6 @@
 ---
 title: Typography Resources
 description: Font files, licenses, and assets needed to work with the brand typography.
-metaTitle: 'Typography Resources | Handoff Design System'
 metaDescription: 'Font files, licenses, and assets needed to work with the brand typography.'
 ---
 

package/config/docs/foundations/typography.md

@@ -2,7 +2,6 @@
 title: Typography
 description: Typographic system establishes scale, sizes and weight of text.
 image: hero-design
-metaTitle: 'Typography | Handoff Design System'
 metaDescription: 'Typographic system establishes scale, sizes and weight of text.'
 ---
 

package/config/docs/foundations.md

@@ -4,7 +4,6 @@ description: Set of design principles and visual guidelines that define the bran
 weight: 0
 image: hero-design
 menuTitle: 'Foundations'
-metaTitle: 'Design Foundations | Handoff Design System'
 metaDescription: 'Set of design principles and visual guidelines that define the brand across every experience'
 enabled: true
 menu:

package/config/docs/guidelines.md

@@ -4,7 +4,6 @@ description: How to build out a robust project built on the designs, tokens, and
 weight: 10
 image: hero-components
 menuTitle: 'Guidelines'
-metaTitle: 'Guidelines | Handoff Design System'
 metaDescription: 'How to build out a robust project built on the designs, tokens, and components documented here.'
 enabled: true
 menu:

package/config/docs/index.md

@@ -3,7 +3,6 @@ title: 'Handoff Design System for building better user experiences.'
 description: This is a sample page where you could insert a style guide.
 weight: -5
 menuTitle: 'Handoff'
-metaTitle: 'Style Guide | Handoff Design System'
 metaDescription: 'A sample page in the handoff design system, in markdown'
 enabled: true
 ---

package/config/docs/system/tokens/foundations/colors.md

@@ -7,10 +7,6 @@ description: |
 weight: 5
 image: hero-components
 menuTitle: 'Colors'
-metaTitle: 'Colors | Handoff Design System'
-metaDescription: |
-  Element that represents a control that provides a menu of options, collection 
-  of UI components used.'
 enabled: true
 menu:
   - title: Design System

package/config/docs/system/tokens/foundations/effects.md

@@ -4,10 +4,6 @@ description: Effects are the shadows and insets pulled automatically from Figma
 weight: 5
 image: hero-components
 menuTitle: 'Effects'
-metaTitle: 'Effects | Handoff Design System'
-metaDescription: |
-  Element that represents a control that provides a menu of options, collection 
-  of UI components used.
 enabled: true
 menu:
   - title: Design System

package/config/docs/system/tokens/foundations/typography.md

@@ -9,8 +9,6 @@ description: |
 weight: 5
 image: hero-components
 menuTitle: 'Typography'
-metaTitle: 'Typography | Handoff Design System'
-metaDescription: 'Element that represents a control that provides a menu of options, collection of UI components used.'
 enabled: true
 menu:
   - title: Design System

package/config/docs/system.md

@@ -4,8 +4,6 @@ description: Library of production-ready UI components built to deliver consiste
 weight: 5
 image: hero-components
 menuTitle: 'Design System'
-metaTitle: 'Design System | Handoff Design System'
-metaDescription: 'Element that represents a control that provides a menu of options, collection of UI components used.'
 enabled: true
 menu:
   - title: Design System

package/config/templates/page.md

@@ -3,7 +3,8 @@ title: 'The visible title of the page.'
 description: A description of the page.
 weight: 0
 menuTitle: 'Menu Title'
-metaTitle: 'Meta Title'
+# metaTitle replaces the whole browser title. Without it, the title is "<title> | <app.title>".
+# metaTitle: 'Meta Title'
 metaDescription: 'Insert a meta description'
 enabled: true
 ---

package/config/templates/page.mdx

@@ -3,7 +3,8 @@ title: 'The visible title of the page.'
 description: A description of the page.
 weight: 0
 menuTitle: 'Menu Title'
-metaTitle: 'Meta Title'
+# metaTitle replaces the whole browser title. Without it, the title is "<title> | <app.title>".
+# metaTitle: 'Meta Title'
 metaDescription: 'Insert a meta description'
 enabled: true
 ---

package/dist/ai/connections.d.ts

@@ -0,0 +1,66 @@
+/**
+ * AI connection resolution.
+ *
+ * `runtime.ai.connections` declares the whole surface a reader can reach. Mirrors
+ * {@link import('../registry/asset-storage/resolve')}: only provider selection, module location,
+ * non-secret options, and env-var *names* are ever persisted; secret *values* are read from
+ * `process.env` at request time.
+ *
+ * The list is deployment data rather than build shape, so `HANDOFF_AI_CONNECTIONS` can extend or
+ * replace the baked list at request time. A registry is built once and redeployed many times, and a
+ * new gateway should not need a rebuild.
+ */
+import type { AiCredentialKind, ResolvedConfig } from '../types/config';
+/** A connection as it is baked and read back: env-var names, never secret values. */
+export interface AiConnectionSettings {
+    id: string;
+    label: string;
+    baseUrl?: string;
+    module?: string;
+    /** Name of the env var holding the deployment's own key. Its presence marks a service connection. */
+    apiKeyEnv?: string;
+    credential?: 'user';
+    models?: string[];
+    options?: Record<string, unknown>;
+}
+/** The resolved AI block: whether this build serves the assistant, and what it can reach. */
+export interface AiSettings {
+    enabled: boolean;
+    connections: AiConnectionSettings[];
+    defaultModel?: string;
+}
+/**
+ * Which of the three credential states a connection declares. Derived from the declaration, never
+ * from a missing key: without the explicit `user` state, a connection that needs a reader's key
+ * would be indistinguishable from one that needs none.
+ */
+export declare const aiCredentialKind: (connection: AiConnectionSettings) => AiCredentialKind;
+/** Split `<connectionId>/<model>`. Only the first slash separates them, since model ids carry slashes. */
+export declare const parseAiModelId: (value: string) => {
+    connectionId: string;
+    model: string;
+} | null;
+/** Join a connection id and a model into the address the client sends back. */
+export declare const formatAiModelId: (connectionId: string, model: string) => string;
+/**
+ * Merge a deployment-supplied list over the baked one by `id`: a matching id replaces the baked
+ * connection outright, and a new id is appended. Replacement rather than a field-wise merge, so a
+ * deployment that repoints a gateway cannot leave a stale model list or key name behind.
+ *
+ * A deployment-supplied connection can use only a `module` that the build includes.
+ */
+export declare const mergeAiConnections: (baked: readonly AiConnectionSettings[], overrides: readonly AiConnectionSettings[]) => AiConnectionSettings[];
+/** Parse the `HANDOFF_AI_CONNECTIONS` JSON array. A malformed value is ignored rather than fatal. */
+export declare const parseAiConnections: (raw: string | undefined) => AiConnectionSettings[];
+/**
+ * Whether this build serves the assistant. The `ai` block is the opt-in; `enabled: false` turns it
+ * back off. Config-only and baked, like `runtime.mcp`.
+ */
+export declare const isAiEnabled: (config: Pick<ResolvedConfig, "runtime"> | null | undefined) => boolean;
+/**
+ * Resolve the AI settings from a loaded config (CLI/build side).
+ *
+ * An authored connection that cannot be used fails the build rather than disappearing. A deployment
+ * list stays lenient by contrast: a bad `HANDOFF_AI_CONNECTIONS` entry must not take the server down.
+ */
+export declare const resolveAiFromConfig: (config: ResolvedConfig | null | undefined) => AiSettings;

package/dist/ai/connections.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * AI connection resolution.
+ *
+ * `runtime.ai.connections` declares the whole surface a reader can reach. Mirrors
+ * {@link import('../registry/asset-storage/resolve')}: only provider selection, module location,
+ * non-secret options, and env-var *names* are ever persisted; secret *values* are read from
+ * `process.env` at request time.
+ *
+ * The list is deployment data rather than build shape, so `HANDOFF_AI_CONNECTIONS` can extend or
+ * replace the baked list at request time. A registry is built once and redeployed many times, and a
+ * new gateway should not need a rebuild.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAiFromConfig = exports.isAiEnabled = exports.parseAiConnections = exports.mergeAiConnections = exports.formatAiModelId = exports.parseAiModelId = exports.aiCredentialKind = void 0;
+const errors_1 = require("../config/errors");
+/** A connection id addresses a model as `<id>/<model>`, so it cannot itself contain a slash. */
+const isUsableId = (id) => typeof id === 'string' && id.trim().length > 0 && !id.includes('/');
+/**
+ * Which of the three credential states a connection declares. Derived from the declaration, never
+ * from a missing key: without the explicit `user` state, a connection that needs a reader's key
+ * would be indistinguishable from one that needs none.
+ */
+const aiCredentialKind = (connection) => {
+    if (connection.credential === 'user')
+        return 'user';
+    return connection.apiKeyEnv ? 'service' : 'none';
+};
+exports.aiCredentialKind = aiCredentialKind;
+/** Split `<connectionId>/<model>`. Only the first slash separates them, since model ids carry slashes. */
+const parseAiModelId = (value) => {
+    const separator = value.indexOf('/');
+    if (separator <= 0 || separator === value.length - 1)
+        return null;
+    return { connectionId: value.slice(0, separator), model: value.slice(separator + 1) };
+};
+exports.parseAiModelId = parseAiModelId;
+/** Join a connection id and a model into the address the client sends back. */
+const formatAiModelId = (connectionId, model) => `${connectionId}/${model}`;
+exports.formatAiModelId = formatAiModelId;
+/** Normalize one authored or deployment-supplied connection, dropping anything unusable. */
+const toConnectionSettings = (input) => {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        return null;
+    const raw = input;
+    if (!isUsableId(raw.id))
+        return null;
+    const baseUrl = typeof raw.baseUrl === 'string' ? raw.baseUrl.trim() : undefined;
+    const module = typeof raw.module === 'string' ? raw.module.trim() : undefined;
+    if (!baseUrl && !module)
+        return null;
+    // An authored config carries `apiKey` as a deferred `{ $env }` reference; a baked or
+    // deployment-supplied list carries the name it resolved to.
+    const reference = raw.apiKey;
+    const apiKeyEnv = typeof raw.apiKeyEnv === 'string' && raw.apiKeyEnv.trim()
+        ? raw.apiKeyEnv.trim()
+        : typeof (reference === null || reference === void 0 ? void 0 : reference.$env) === 'string'
+            ? reference.$env
+            : undefined;
+    // A repeated model would be two picker entries for one choice, so the first occurrence wins.
+    const models = Array.isArray(raw.models)
+        ? [...new Set(raw.models.filter((model) => typeof model === 'string' && !!model.trim()).map((model) => model.trim()))]
+        : [];
+    const options = raw.options && typeof raw.options === 'object' && !Array.isArray(raw.options) ? raw.options : undefined;
+    return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ id: raw.id.trim(), label: typeof raw.label === 'string' && raw.label.trim() ? raw.label.trim() : raw.id.trim() }, (baseUrl ? { baseUrl } : {})), (module ? { module } : {})), (apiKeyEnv ? { apiKeyEnv } : {})), (raw.credential === 'user' ? { credential: 'user' } : {})), (models.length ? { models } : {})), (options ? { options } : {}));
+};
+/** Normalize a declared list, keeping the first entry for any repeated id. */
+const toConnectionList = (input) => {
+    const byId = new Map();
+    for (const entry of input !== null && input !== void 0 ? input : []) {
+        const connection = toConnectionSettings(entry);
+        if (connection && !byId.has(connection.id))
+            byId.set(connection.id, connection);
+    }
+    return [...byId.values()];
+};
+const ignoredOverrides = new Set();
+/**
+ * Merge a deployment-supplied list over the baked one by `id`: a matching id replaces the baked
+ * connection outright, and a new id is appended. Replacement rather than a field-wise merge, so a
+ * deployment that repoints a gateway cannot leave a stale model list or key name behind.
+ *
+ * A deployment-supplied connection can use only a `module` that the build includes.
+ */
+const mergeAiConnections = (baked, overrides) => {
+    const byId = new Map(baked.map((connection) => [connection.id, connection]));
+    const bakedModules = new Set(baked.map((connection) => connection.module).filter(Boolean));
+    for (const connection of overrides) {
+        if (connection.module && !bakedModules.has(connection.module)) {
+            if (!ignoredOverrides.has(connection.id)) {
+                ignoredOverrides.add(connection.id);
+                console.warn(`HANDOFF_AI_CONNECTIONS: connection "${connection.id}" is ignored, because the build does not include its module ` +
+                    `"${connection.module}". Declare the connection in runtime.ai.connections.`);
+            }
+            continue;
+        }
+        byId.set(connection.id, connection);
+    }
+    return [...byId.values()];
+};
+exports.mergeAiConnections = mergeAiConnections;
+/** Parse the `HANDOFF_AI_CONNECTIONS` JSON array. A malformed value is ignored rather than fatal. */
+const parseAiConnections = (raw) => {
+    if (!(raw === null || raw === void 0 ? void 0 : raw.trim()))
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? toConnectionList(parsed) : [];
+    }
+    catch (_a) {
+        return [];
+    }
+};
+exports.parseAiConnections = parseAiConnections;
+/**
+ * Whether this build serves the assistant. The `ai` block is the opt-in; `enabled: false` turns it
+ * back off. Config-only and baked, like `runtime.mcp`.
+ */
+const isAiEnabled = (config) => { var _a, _b, _c; return Boolean((_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.ai) && ((_c = (_b = config === null || config === void 0 ? void 0 : config.runtime) === null || _b === void 0 ? void 0 : _b.ai) === null || _c === void 0 ? void 0 : _c.enabled) !== false; };
+exports.isAiEnabled = isAiEnabled;
+/**
+ * Resolve the AI settings from a loaded config (CLI/build side).
+ *
+ * An authored connection that cannot be used fails the build rather than disappearing. A deployment
+ * list stays lenient by contrast: a bad `HANDOFF_AI_CONNECTIONS` entry must not take the server down.
+ */
+const resolveAiFromConfig = (config) => {
+    var _a, _b, _c, _d, _e, _f;
+    const authored = ((_c = (_b = (_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.ai) === null || _b === void 0 ? void 0 : _b.connections) !== null && _c !== void 0 ? _c : []);
+    const fail = (problem, ids) => {
+        throw new errors_1.HandoffConfigError(`Config "runtime.ai.connections": ${problem} (${ids.map((id) => JSON.stringify(id !== null && id !== void 0 ? id : null)).join(', ')}).`);
+    };
+    const normalized = authored.map((connection) => ({ authored: connection, settings: toConnectionSettings(connection) }));
+    const unusable = normalized.filter((entry) => !entry.settings);
+    if (unusable.length > 0) {
+        fail('every connection needs an "id" without a slash, and either a "baseUrl" or a "module"', unusable.map((entry) => { var _a; return (_a = entry.authored) === null || _a === void 0 ? void 0 : _a.id; }));
+    }
+    const ids = normalized.map((entry) => entry.settings.id);
+    const duplicates = ids.filter((id, index) => ids.indexOf(id) !== index);
+    if (duplicates.length > 0) {
+        fail('a connection id must be unique, because it is half of every model address', duplicates);
+    }
+    return {
+        enabled: (0, exports.isAiEnabled)(config),
+        connections: normalized.map((entry) => entry.settings),
+        defaultModel: ((_f = (_e = (_d = config === null || config === void 0 ? void 0 : config.runtime) === null || _d === void 0 ? void 0 : _d.ai) === null || _e === void 0 ? void 0 : _e.defaultModel) === null || _f === void 0 ? void 0 : _f.trim()) || undefined,
+    };
+};
+exports.resolveAiFromConfig = resolveAiFromConfig;

package/dist/ai/define.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Typed identity helper for custom AI providers (mirrors `defineStorageProvider`): a consumer
+ * default-exports its result from a **server-only** module and points a connection's `module` at
+ * it. It must be its own module (not an inline `defineConfig` function) so the build can trace it
+ * into the deployed registry. The default export may be the provider object, or a factory
+ * `(context) => AiProvider` when it needs its options, env or the resolved key.
+ */
+import type { AiProvider, AiProviderFactory } from './types';
+export declare function defineAiProvider(provider: AiProvider): AiProvider;
+export declare function defineAiProvider(factory: AiProviderFactory): AiProviderFactory;

package/dist/ai/define.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Typed identity helper for custom AI providers (mirrors `defineStorageProvider`): a consumer
+ * default-exports its result from a **server-only** module and points a connection's `module` at
+ * it. It must be its own module (not an inline `defineConfig` function) so the build can trace it
+ * into the deployed registry. The default export may be the provider object, or a factory
+ * `(context) => AiProvider` when it needs its options, env or the resolved key.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineAiProvider = defineAiProvider;
+function defineAiProvider(input) {
+    return input;
+}