handoff-app 2.0.0-7 → 2.0.0-9

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) => ({}),
+  // },
 });

package/templates/default/handoff.config.with-examples.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,183 +42,32 @@ const config = {
     }
   },
 
+  // A path is either an item directory, or a collection directory whose subdirectories are each an
+  // item.
   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.
-     *
-     * @example include: ["components", "patterns"]
-     */
     include: ["components/button"],
   },
 
-  // 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 {};
-    // },
-
-    /**
-     * 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.with-examples.ts.tpl

@@ -1,4 +1,4 @@
-import { defineConfig } from 'handoff-app';
+import { defineConfig, fromEnv } from 'handoff-app';
 
 export default defineConfig({
   app: {
@@ -40,165 +40,30 @@ export default defineConfig({
     }
   },
 
+  // A path is either an item directory, or a collection directory whose subdirectories are each an
+  // item.
   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.
-     *
-     * @example include: ["components", "patterns"]
-     */
     include: ["components/button"],
   },
 
-  // 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;
+  // `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 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 {};
-    // },
+  // reactDocgen: { maxDepth: 7, excludeDirectories: ["dist", "build", ".next"] },
 
-    /**
-     * 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;
-    // },
-
-    /**
-     * 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) => ({}),
+  // },
 });