handoff-app 2.0.0-7 → 2.0.0-8

package/src/types/config.ts

@@ -1,3 +1,4 @@
+import type { EnvValue, EnvSecret, RuntimeEnvReference } from '../config/from-env';
 import { BuildOptions } from 'esbuild';
 import type Handlebars from 'handlebars';
 import { Types as HandoffTypes } from 'handoff-core';
@@ -58,8 +59,8 @@ export type RegisterHandlebarsHelpersContext = {
 
 export interface NextAppConfig {
   theme?: string;
-  title: string;
-  client: string;
+  title?: string;
+  client?: string;
   google_tag_manager?: string | null | undefined;
   googleTagManager?: string | null | undefined;
   type_copy?: string;
@@ -68,15 +69,17 @@ export interface NextAppConfig {
   typeSort?: string[];
   color_sort?: string[];
   colorSort?: string[];
-  breakpoints: Breakpoints;
+  /** Omit to keep the defaults; a declared block merges onto them rather than replacing them. */
+  breakpoints?: Breakpoints;
   component_sort?: string[];
   componentSort?: string[];
   base_path?: string;
   basePath?: string;
-  attribution: boolean;
+  /** @default true */
+  attribution?: boolean;
   ports?: {
-    app: number;
-    websocket: number;
+    app: EnvValue<number>;
+    websocket: EnvValue<number>;
   };
 }
 
@@ -139,13 +142,8 @@ export interface HandoffRuntimeConfig {
   };
   /** Registry-mode host settings. Env-var values are stored as names, never as secrets. */
   registry?: {
-    /** Name of the env var holding the database URL. @default "DATABASE_URL" */
-    databaseUrlEnv?: string;
-    /**
-     * @deprecated Fixed registry secrets are no longer authorized. This option remains parseable
-     * only so existing configuration files do not break.
-     */
-    apiTokenEnv?: string;
+    /** Environment reference to the database URL. @default fromEnv('DATABASE_URL') */
+    databaseUrl?: RuntimeEnvReference<string>;
     database?: {
       /**
        * PostgreSQL is the supported database. `driver` selects the built-in connection driver — how
@@ -168,11 +166,11 @@ export interface HandoffRuntimeConfig {
       adapter?: 'database' | 'vercel-blob' | 'custom';
       /** For `adapter: "custom"` - server-only module path default-exporting a `defineAssetStorage` adapter. */
       module?: string;
-      /** For `adapter: "vercel-blob"` - env var name holding the Blob read/write token. @default "BLOB_READ_WRITE_TOKEN" */
-      tokenEnv?: string;
+      /** For `adapter: "vercel-blob"` - environment reference to the Blob read/write token. @default fromEnv('BLOB_READ_WRITE_TOKEN') */
+      token?: RuntimeEnvReference<string>;
       /** Max bytes kept inline in the database `bytea` column (larger uploads are rejected). @default 4194304 */
       maxInlineBytes?: number;
-      /** Non-secret adapter options (bucket env-var names, region, a custom `providerId`, …). */
+      /** Non-secret options, JSON-encoded into the bundle. Environment references are rejected. Pass variable names instead. */
       options?: Record<string, unknown>;
     };
   };
@@ -181,22 +179,21 @@ export interface HandoffRuntimeConfig {
    * `mode: 'workspace'` plus this block — it is not a third runtime mode.
    */
   registryConnection?: {
-    url?: string;
-    /** @default "HANDOFF_REGISTRY_URL" */
-    urlEnv?: string;
-    /** @default "HANDOFF_REGISTRY_ACCESS_TOKEN" */
-    accessTokenEnv?: string;
+    /** @default fromEnv('HANDOFF_REGISTRY_URL', { default: '' }) */
+    url?: EnvValue<string>;
+    /** @default fromEnv('HANDOFF_REGISTRY_ACCESS_TOKEN', { default: '' }) */
+    accessToken?: EnvSecret<string>;
   };
 }
 
 export interface Config {
-  dev_access_token?: string | null | undefined;
-  devAccessToken?: string | null | undefined;
-  figma_project_id?: string | null | undefined;
-  figmaProjectId?: string | null | undefined;
-  exportsOutputDirectory?: string;
-  sitesOutputDirectory?: string;
-  useVariables?: boolean;
+  dev_access_token?: EnvSecret<string | null>;
+  devAccessToken?: EnvSecret<string | null>;
+  figma_project_id?: EnvValue<string | null>;
+  figmaProjectId?: EnvValue<string | null>;
+  exportsOutputDirectory?: EnvValue<string>;
+  sitesOutputDirectory?: EnvValue<string>;
+  useVariables?: EnvValue<boolean>;
   /**
    * Configuration for React component docs generation (handoff-docgen).
    */
@@ -396,7 +393,26 @@ export interface ClientRuntimeConfig {
   connected: boolean;
 }
 
-export type ClientConfig = Pick<Config, 'app' | 'exportsOutputDirectory' | 'sitesOutputDirectory' | 'assets_zip_links' | 'useVariables'> & {
+/** Values available after config loading. Deferred references retain their names. */
+export type ResolvedConfig = Omit<
+  Config,
+  'dev_access_token' | 'devAccessToken' | 'figma_project_id' | 'figmaProjectId' |
+  'exportsOutputDirectory' | 'sitesOutputDirectory' | 'useVariables' | 'app' | 'runtime'
+> & {
+  dev_access_token?: string | null;
+  devAccessToken?: string | null;
+  figma_project_id?: string | null;
+  figmaProjectId?: string | null;
+  exportsOutputDirectory?: string;
+  sitesOutputDirectory?: string;
+  useVariables?: boolean;
+  app?: Omit<NextAppConfig, 'ports'> & { ports?: { app: number; websocket: number } };
+  runtime?: Omit<HandoffRuntimeConfig, 'registryConnection'> & {
+    registryConnection?: { url?: string; accessToken?: string };
+  };
+};
+
+export type ClientConfig = Pick<ResolvedConfig, 'app' | 'exportsOutputDirectory' | 'sitesOutputDirectory' | 'assets_zip_links' | 'useVariables'> & {
   runtime: ClientRuntimeConfig;
 };
 

package/templates/default/env.tpl

@@ -1,2 +1,12 @@
 HANDOFF_FIGMA_PROJECT_ID={{figmaProjectId}}
 HANDOFF_DEV_ACCESS_TOKEN={{figmaAccessToken}}
+
+# Optional. Select a Handoff configuration profile.
+# HANDOFF_PROFILE=local
+#
+# A selected profile also reads .env.<profile> on top of this file, when that file exists.
+
+# Optional. Connect this workspace to a registry.
+# A token is created in the registry under Account > Access tokens.
+# HANDOFF_REGISTRY_URL=https://registry.example.com
+# HANDOFF_REGISTRY_ACCESS_TOKEN=hnd_...

package/templates/default/gitignore.tpl

@@ -11,8 +11,15 @@ public/api
 
 # Environment
 .env
+.env.*
 .handoff/
 
+# Local configuration profile
+handoff.config.local.ts
+handoff.config.local.js
+handoff.config.local.cjs
+handoff.config.local.json
+
 # Deployment
 .vercel
 

package/templates/default/handoff.config.js.tpl

@@ -1,4 +1,4 @@
-const { defineConfig } = require('handoff-app');
+const { defineConfig, fromEnv } = require('handoff-app');
 /** @typedef {import('handoff-app').Config} HandoffConfig */
 
 /** @type {HandoffConfig} */
@@ -42,181 +42,30 @@ const config = {
     }
   },
 
-  // catalog: {
-  //   /**
-  //    * Directories to search for catalog items. A path is either an item directory or a
-  //    * collection directory whose subdirectories are each treated as an item. An item declares
-  //    * an implementation (React, Handlebars) or a composition of other items.
-  //    */
-  //   include: ["components", "patterns"],
-  // },
-
-  // Runtime settings, all optional. The default is workspace mode with the MCP endpoint served.
-  // `mcp: false` leaves the /api/mcp/ endpoint, and the connect affordance in the docs header, out
-  // of the build; the route then answers 404.
-  // The registry block is only needed when deploying a hosted registry, and is used by
-  // `build --target registry` and `db:migrate`. The default workspace mode uses no database.
-  // Handoff runs on PostgreSQL, and `driver` just picks the connection driver to use, not
-  // the database engine. Secrets are referenced by env var name and never written here.
-  // runtime: {
-  //   mode: "registry",
-  //   mcp: false,
-  //   registry: {
-  //     databaseUrlEnv: "DATABASE_URL",
-  //     database: { driver: "pg" }, // 'pg' | 'neon'
-  //   },
-  // },
-
-  // Optional handoff-docgen settings used by component docs generation
-  // reactDocgen: {
-  //   maxDepth: 7,
-  //   excludeDirectories: ["dist", "build", ".next"]
-  // },
-
-  hooks: {
-    /**
-     * Optional validation callback for components
-     * @param component - The component instance to validate
-     * @returns A record of validation results where keys are validation types and values are detailed validation results
-     *
-     * @example
-     * validateComponent: async (component) => ({
-     *   a11y: {
-     *     description: 'Accessibility validation check',
-     *     passed: true,
-     *     messages: ['No accessibility issues found']
-     *   },
-     *   responsive: {
-     *     description: 'Responsive design validation',
-     *     passed: false,
-     *     messages: ['Component breaks at mobile breakpoint']
-     *   }
-     * })
-     */
-    // validateComponent: async (component) => {
-    //   // Add your custom validation logic here
-    //   return {};
-    // },
-
-    /**
-     * Optional hook to override the SSR build configuration used in the ssrRenderPlugin
-     * @param config - The default esbuild configuration
-     * @returns Modified esbuild configuration
-     *
-     * @example
-     * ssrBuildConfig: (config) => {
-     *   // Modify the esbuild config as needed
-     *   return config;
-     * }
-     */
-    // ssrBuildConfig: (config) => {
-    //   // Add your custom SSR build configuration here
-    //   return config;
-    // },
-
-    /**
-     * Optional hook to override the client-side build configuration used in the ssrRenderPlugin
-     * @param config - The default esbuild configuration
-     * @returns Modified esbuild configuration
-     *
-     * @example
-     * clientBuildConfig: (config) => {
-     *   // Modify the esbuild config as needed
-     *   return config;
-     * }
-     */
-    // clientBuildConfig: (config) => {
-    //   // Add your custom client build configuration here
-    //   return config;
-    // },
+  // Where catalog items live. A path is either an item directory, or a collection directory whose
+  // subdirectories are each an item.
+  // catalog: { include: ["components", "patterns"] },
 
-    /**
-     * Optional hook to specify which export property contains the schema
-     * @param exports - The module exports object containing the schema
-     * @returns The schema object from the exports
-     *
-     * @example
-     * getSchemaFromExports: (exports) => exports.customSchema || exports.default
-     */
-    // getSchemaFromExports: (exports) => {
-    //   // Add your custom schema extraction logic here
-    //   return exports.default;
-    // },
-
-    /**
-     * Optional hook to transform the schema into properties
-     * @param schema - The schema object to transform
-     * @returns The transformed properties object
-     */
-    // schemaToProperties: (schema) => {
-    //   // Add your custom schema to properties transformation here
-    //   return {};
-    // },
-
-    /**
-     * Optional hook to override the JavaScript Vite configuration
-     * @param config - The default Vite configuration
-     * @returns Modified Vite configuration
-     *
-     * @example
-     * jsBuildConfig: (config) => {
-     *   // Modify the Vite config as needed
-     *   return config;
-     * }
-     */
-    // jsBuildConfig: (config) => {
-    //   // Add your custom JavaScript build configuration here
-    //   return config;
-    // },
-
-    /**
-     * Optional hook to override the CSS Vite configuration
-     * @param config - The default Vite configuration
-     * @returns Modified Vite configuration
-     *
-     * @example
-     * cssBuildConfig: (config) => {
-     *   // Modify the Vite config as needed
-     *   return config;
-     * }
-     */
-    // cssBuildConfig: (config) => {
-    //   // Add your custom CSS build configuration here
-    //   return config;
+  // `mode` selects the runtime: "workspace" (no database) or "registry" (Postgres). The registry
+  // block is read only by `build --target registry` and `db:migrate`, and secrets are referenced by
+  // env var name. A named profile (`handoff.config.registry.*`, `--profile registry`) is a good home
+  // for it.
+  runtime: {
+    mode: "workspace",
+    // mcp: false,
+    // registry: {
+    //   databaseUrl: fromEnv("DATABASE_URL"),
+    //   database: { driver: "pg" }, // 'pg' | 'neon'
     // },
+  },
 
-    /**
-     * Optional hook to override the HTML Vite configuration
-     * @param config - The default Vite configuration
-     * @returns Modified Vite configuration
-     *
-     * @example
-     * htmlBuildConfig: (config) => {
-     *   // Modify the Vite config as needed
-     *   return config;
-     * }
-     */
-    // htmlBuildConfig: (config) => {
-    //   // Add your custom HTML build configuration here
-    //   return config;
-    // },
+  // reactDocgen: { maxDepth: 7, excludeDirectories: ["dist", "build", ".next"] },
 
-    /**
-     * Optional hook run after built-in Handlebars helpers (`field`, `eq`) for preview HTML.
-     * @param context.handlebars - Handlebars module (use registerHelper)
-     * @param context.componentId - Current component id
-     * @param context.properties - Slot metadata map from the schema
-     * @param context.injectFieldWrappers - True when generating inspect-mode previews
-     *
-     * @example
-     * registerHandlebarsHelpers: ({ handlebars, componentId }) => {
-     *   handlebars.registerHelper('upperId', () => componentId.toUpperCase());
-     * }
-     */
-    // registerHandlebarsHelpers: ({ handlebars, componentId, properties, injectFieldWrappers }) => {
-    //   // Add your custom Handlebars helpers here
-    // },
-  },
+  // Optional build hooks: component validation, esbuild and Vite config overrides, Handlebars
+  // helper registration. Signatures and examples are on the `Config` type.
+  // hooks: {
+  //   validateComponent: async (component) => ({}),
+  // },
 };
 
 module.exports = defineConfig(config);

package/templates/default/handoff.config.ts.tpl

@@ -1,4 +1,4 @@
-import { defineConfig } from 'handoff-app';
+import { defineConfig, fromEnv } from 'handoff-app';
 
 export default defineConfig({
   app: {
@@ -40,163 +40,28 @@ export default defineConfig({
     }
   },
 
-  // catalog: {
-  //   /**
-  //    * Directories to search for catalog items. A path is either an item directory or a
-  //    * collection directory whose subdirectories are each treated as an item. An item declares
-  //    * an implementation (React, Handlebars) or a composition of other items.
-  //    */
-  //   include: ["components", "patterns"],
-  // },
-
-  // Runtime settings, all optional. The default is workspace mode with the MCP endpoint served.
-  // `mcp: false` leaves the /api/mcp/ endpoint, and the connect affordance in the docs header, out
-  // of the build; the route then answers 404.
-  // The registry block is only needed when deploying a hosted registry, and is used by
-  // `build --target registry` and `db:migrate`. The default workspace mode uses no database.
-  // Handoff runs on PostgreSQL, and `driver` just picks the connection driver to use, not
-  // the database engine. Secrets are referenced by env var name and never written here.
-  // runtime: {
-  //   mode: "registry",
-  //   mcp: false,
-  //   registry: {
-  //     databaseUrlEnv: "DATABASE_URL",
-  //     database: { driver: "pg" }, // 'pg' | 'neon'
-  //   },
-  // },
-
-  // Optional handoff-docgen settings used by component docs generation
-  // reactDocgen: {
-  //   maxDepth: 7,
-  //   excludeDirectories: ["dist", "build", ".next"]
-  // },
-
-  hooks: {
-    /**
-     * Optional validation callback for components
-     * @param component - The component instance to validate
-     * @returns A record of validation results where keys are validation types and values are detailed validation results
-     *
-     * @example
-     * validateComponent: async (component) => ({
-     *   a11y: {
-     *     description: 'Accessibility validation check',
-     *     passed: true,
-     *     messages: ['No accessibility issues found']
-     *   },
-     *   responsive: {
-     *     description: 'Responsive design validation',
-     *     passed: false,
-     *     messages: ['Component breaks at mobile breakpoint']
-     *   }
-     * })
-     */
-    // validateComponent: async (component) => {
-    //   // Add your custom validation logic here
-    //   return {};
-    // },
-
-    /**
-     * Optional hook to override the SSR build configuration used in the ssrRenderPlugin
-     * @param config - The default esbuild configuration
-     * @returns Modified esbuild configuration
-     *
-     * @example
-     * ssrBuildConfig: (config) => {
-     *   // Modify the esbuild config as needed
-     *   return config;
-     * }
-     */
-    // ssrBuildConfig: (config) => {
-    //   // Add your custom SSR build configuration here
-    //   return config;
-    // },
-
-    /**
-     * Optional hook to override the client-side build configuration used in the ssrRenderPlugin
-     * @param config - The default esbuild configuration
-     * @returns Modified esbuild configuration
-     *
-     * @example
-     * clientBuildConfig: (config) => {
-     *   // Modify the esbuild config as needed
-     *   return config;
-     * }
-     */
-    // clientBuildConfig: (config) => {
-    //   // Add your custom client build configuration here
-    //   return config;
-    // },
-
-    /**
-     * Optional hook to specify which export property contains the schema
-     * @param exports - The module exports object containing the schema
-     * @returns The schema object from the exports
-     *
-     * @example
-     * getSchemaFromExports: (exports) => exports.customSchema || exports.default
-     */
-    // getSchemaFromExports: (exports) => {
-    //   // Add your custom schema extraction logic here
-    //   return exports.default;
-    // },
-
-    /**
-     * Optional hook to transform the schema into properties
-     * @param schema - The schema object to transform
-     * @returns The transformed properties object
-     */
-    // schemaToProperties: (schema) => {
-    //   // Add your custom schema to properties transformation here
-    //   return {};
-    // },
+  // Where catalog items live. A path is either an item directory, or a collection directory whose
+  // subdirectories are each an item.
+  // catalog: { include: ["components", "patterns"] },
 
-    /**
-     * Optional hook to override the JavaScript Vite configuration
-     * @param config - The default Vite configuration
-     * @returns Modified Vite configuration
-     *
-     * @example
-     * jsBuildConfig: (config) => {
-     *   // Modify the Vite config as needed
-     *   return config;
-     * }
-     */
-    // jsBuildConfig: (config) => {
-    //   // Add your custom JavaScript build configuration here
-    //   return config;
+  // `mode` selects the runtime: "workspace" (no database) or "registry" (Postgres). The registry
+  // block is read only by `build --target registry` and `db:migrate`, and secrets are referenced by
+  // env var name. A named profile (`handoff.config.registry.*`, `--profile registry`) is a good home
+  // for it.
+  runtime: {
+    mode: "workspace",
+    // mcp: false,
+    // registry: {
+    //   databaseUrl: fromEnv("DATABASE_URL"),
+    //   database: { driver: "pg" }, // 'pg' | 'neon'
     // },
+  },
 
-    /**
-     * Optional hook to override the CSS Vite configuration
-     * @param config - The default Vite configuration
-     * @returns Modified Vite configuration
-     *
-     * @example
-     * cssBuildConfig: (config) => {
-     *   // Modify the Vite config as needed
-     *   return config;
-     * }
-     */
-    // cssBuildConfig: (config) => {
-    //   // Add your custom CSS build configuration here
-    //   return config;
-    // },
+  // reactDocgen: { maxDepth: 7, excludeDirectories: ["dist", "build", ".next"] },
 
-    /**
-     * Optional hook to override the HTML Vite configuration
-     * @param config - The default Vite configuration
-     * @returns Modified Vite configuration
-     *
-     * @example
-     * htmlBuildConfig: (config) => {
-     *   // Modify the Vite config as needed
-     *   return config;
-     * }
-     */
-    // htmlBuildConfig: (config) => {
-    //   // Add your custom HTML build configuration here
-    //   return config;
-    // },
-  },
+  // Optional build hooks: component validation, esbuild and Vite config overrides, Handlebars
+  // helper registration. Signatures and examples are on the `Config` type.
+  // hooks: {
+  //   validateComponent: async (component) => ({}),
+  // },
 });