handoff-app 2.0.0-6 → 2.0.0-8

package/README.md

@@ -66,11 +66,16 @@ my-handoff-project/
 └─ out/            # build output; gitignored
 ```
 
-## Components and patterns
+## Catalog items
 
-An implementation and a `*.handoff.ts` declaration are required for a
-TypeScript React component. Stable identity, documentation metadata, source
-entries, and previews are supplied by the declaration.
+Every documented UI entry is a catalog item. Each item declares either an implementation or a composition of other items.
+An implementation names its renderer. `defineCatalogItem` comes from the module for that renderer.
+The declaration supplies stable identity, documentation metadata, source entries, and previews.
+
+### React
+
+Handoff finds the implementation file from its import, so you do not need to repeat the path.
+Previews are named exports. `Preview<typeof item>` gives them the implementation's argument type.
 
 ```tsx
 // components/example/Component.tsx
@@ -83,61 +88,136 @@ export default function Component({ label }: ComponentProps) {
 }
 ```
 
-```ts
-// components/example/component.handoff.ts
-import { defineReactComponent } from 'handoff-app';
+```tsx
+// components/example/example.handoff.ts
+import { defineCatalogItem, type Preview } from 'handoff-app/react';
 import Component from './Component';
 
-export default defineReactComponent(Component, {
+const item = defineCatalogItem({
   id: 'component-id',
   name: 'Component name',
   description: 'Usage guidance for the component.',
   group: 'Group name',
-  entries: {
-    component: './Component.tsx',
-  },
-  previews: {
-    default: {
-      title: 'Default',
-      args: { label: 'Example' },
-    },
-  },
+  implementation: Component,
+});
+
+export default item;
+
+type ComponentPreview = Preview<typeof item>;
+
+export const Default = {
+  args: { label: 'Example' },
+} satisfies ComponentPreview;
+```
+
+The export name is the preview name. Use `name` to set a different display title.
+
+### Handlebars
+
+The implementation is the path to the template. Arguments are `Record<string, unknown>` by default;
+an explicit argument type is supplied through `defineCatalogItem<BadgeArgs>`.
+
+```ts
+// components/badge/badge.handoff.ts
+import { defineCatalogItem, type Preview } from 'handoff-app/handlebars';
+
+const item = defineCatalogItem({
+  id: 'badge',
+  name: 'Badge',
+  implementation: './Badge.hbs',
 });
+
+export default item;
+
+type BadgePreview = Preview<typeof item>;
+
+export const Primary = {
+  args: { variant: 'primary', children: 'New' },
+} satisfies BadgePreview;
+```
+
+### CSF
+
+CSF is a source format. A story file uses the renderer from the module that declares it. A React item references an existing CSF file with `fromCSF`.
+The CSF file stays unchanged and defines its previews through named exports. Each story's `args` merge with and override `meta.args`.
+Handoff preserves story names, `argTypes`, and `render` functions.
+It finds the React component through `meta.component`, then documents and publishes it with the story file.
+
+```ts
+// components/card/card.handoff.ts
+import { defineCatalogItem, fromCSF } from 'handoff-app/react';
+
+export default defineCatalogItem({
+  id: 'card',
+  name: 'Card',
+  implementation: fromCSF('./Card.stories.tsx'),
+});
+```
+
+`Meta` and `StoryObj` are exported from `handoff-app/react`, so a story file type-checks without a
+Storybook dependency. A project that already has Storybook keeps using its own types.
+
+```tsx
+// components/card/Card.stories.tsx
+import { type Meta, type StoryObj } from 'handoff-app/react';
+import Card from './Card';
+
+const meta = { component: Card } satisfies Meta<typeof Card>;
+export default meta;
+
+export const Primary: StoryObj<typeof meta> = {
+  args: { title: 'Example' },
+};
 ```
 
-Components are referenced by stable ID in patterns. A named preview can be
-selected and its arguments can be overridden by each reference. Additional
-references can be added as required by the composition.
+A CSF preview is rendered on the server and is not hydrated. A direct React implementation is
+hydrated in the browser.
+
+### Compositions
+
+A composition references other items by stable id. A named preview can be selected and its arguments
+can be overridden by each reference. A composition needs no renderer, so it is declared with
+`defineCatalogItem` from `handoff-app/pattern`.
 
 ```ts
-// patterns/example/pattern.handoff.ts
-import { definePattern } from 'handoff-app';
+// patterns/example/example.handoff.ts
+import { defineCatalogItem } from 'handoff-app/pattern';
 
-export default definePattern({
+export default defineCatalogItem({
   id: 'pattern-id',
   name: 'Pattern name',
   description: 'Purpose and usage of the composition.',
   group: 'Group name',
-  components: [
-    {
-      id: 'component-id',
-      preview: 'default',
-      args: { label: 'Pattern example' },
-    },
+  composition: [
+    { ref: 'component-id', preview: 'Default' },
+    { ref: 'badge', args: { children: 'Send' } },
   ],
 });
 ```
 
-Component and pattern directories are registered in the project config:
+An item declares `implementation` or `composition`, never both. Terms such as atom, element, and
+block stay optional classification metadata on `type` and `categories`.
+
+The `id` addresses the item everywhere: its artifacts, its documentation URL, and its publish and
+checkout commands. Components and patterns share one namespace, so each id must be unique across
+both.
+
+If two declarations claim one id, Handoff keeps the first and skips the second. The warning names
+both files. `publish` refuses to run until each id is unique.
+
+
+### Registration
+
+Catalog directories are registered in one place. A path is either an item directory or a collection
+directory whose subdirectories are each treated as an item.
 
 ```ts
 // handoff.config.ts
 import { defineConfig } from 'handoff-app';
 
 export default defineConfig({
-  entries: {
-    components: ['components/example'],
-    patterns: ['patterns'],
+  catalog: {
+    include: ['components', 'patterns'],
   },
   runtime: {
     workspace: {
@@ -147,6 +227,11 @@ export default defineConfig({
 });
 ```
 
+### Upgrade from version 1.x.x to version 2.x.x
+
+See the [version 1.x.x to version 2.x.x migration guide](UPGRADE.md#version-1xx-to-version-2xx)
+for breaking changes, migration steps, and upgrade verification.
+
 Custom documentation pages are Markdown files under `pages/`. Their relative
 paths become their routes and registry IDs.
 
@@ -274,12 +359,12 @@ runtime variables listed above are supplied through the deployment environment.
 
 #### Neon PostgreSQL
 
-The Neon connection driver is selected in `handoff.config.ts`:
+Import `fromEnv` from `handoff-app`. Select the Neon connection driver in `handoff.config.ts`:
 
 ```ts
 runtime: {
   registry: {
-    databaseUrlEnv: 'DATABASE_URL',
+    databaseUrl: fromEnv('DATABASE_URL'),
     database: {
       driver: 'neon',
     },
@@ -319,6 +404,12 @@ should not be left unattended before installation is complete.
 
 ### 4. Workspace authorization
 
+A workspace reaches a registry with a registry URL and an access token. There
+are two ways to supply them. Both use the same kind of token, and both are
+listed and revoked under Account → Access tokens in the registry.
+
+#### Device login
+
 CLI authorization is started from the source workspace with:
 
 ```bash
@@ -326,9 +417,48 @@ npm run login -- --url http://localhost:4000
 ```
 
 Registry sign-in, entry of the displayed device code, and CLI approval are
-completed in the browser. The revocable credential is saved in
+completed in the browser. The issued credential is saved in
 `.handoff/cli-auth.json` for that exact registry URL.
 
+One credential is saved per profile, so a workspace can stay signed in to
+several registries at the same time:
+
+```bash
+npm run login -- --profile staging --url https://staging.example.com
+npm run publish -- all --profile staging
+```
+
+A login profile name is free. It needs no `handoff.config.<name>.*` file, and
+`login` is the only command that accepts a new name. A profile without its own
+login falls back to the default login, so one `npm run login` is still enough
+for a workspace with one registry.
+
+`npm run logout` revokes and removes the login of the selected profile. The
+`--all` option removes every saved login.
+
+#### Environment variables
+
+A token is created in the registry under Account → Access tokens. Read and
+write access is required to publish; read access is enough to check out. The
+token and the registry URL are then set in `.env`:
+
+```dotenv
+HANDOFF_REGISTRY_URL=http://localhost:4000
+HANDOFF_REGISTRY_ACCESS_TOKEN=hnd_...
+```
+
+No configuration file entry is needed, because these two variables are the
+defaults for `runtime.registryConnection`. A selected profile reads
+`.env.<profile>` on top of `.env`, so one workspace can address a different
+registry per profile. In CI, the job environment supplies the same two
+variables instead of a file.
+
+Environment values win over a saved device login, so a CI job stays
+deterministic on a machine where a developer is signed in. A token is only used
+for the registry URL it was issued for. If the environment names a different
+registry than the login of the selected profile, publish and checkout report
+which login was skipped and why.
+
 ### 5. Content publishing
 
 Every kind in the workspace is published in dependency order with:
@@ -340,20 +470,23 @@ npm run publish -- all
 A single kind is published on its own:
 
 ```bash
-npm run publish -- components
-npm run publish -- patterns
+npm run publish -- catalog
 npm run publish -- pages
 npm run publish -- tokens
 npm run publish -- assets
 ```
 
+`catalog` covers every catalog item. An item is stored as a component or as a
+pattern, and its declaration decides which. The command names items and never a
+kind.
+
 Publishing tokens or assets runs the Figma data pipeline before upload, so the
 documented Figma credentials must be available.
 
 One or more IDs can be appended to narrow a publish to those entities:
 
 ```bash
-npm run publish -- components component-id another-id
+npm run publish -- catalog item-id another-id
 ```
 
 `--dry-run` reports what would be uploaded and contacts no registry at all, so
@@ -363,24 +496,29 @@ the existing output, and the two combine to leave the workspace untouched:
 
 ```bash
 npm run publish -- all --dry-run
-npm run publish -- components --no-build
+npm run publish -- catalog --no-build
 ```
 
 `checkout` takes the same `all`, multi-ID, and `--dry-run` forms. A dry-run
 checkout reads from the registry, lists the files it would create or overwrite,
 and writes nothing.
 
-After the registry is reloaded, the published components, patterns, and
-foundations should be visible. Published database records are read by registry
-pages; the local workspace is never read directly.
+After the registry is reloaded, the published catalog items and foundations are
+visible. Published database records are read by registry pages; the local
+workspace is never read directly.
 
-For CI, a registry connection and user-issued token are configured:
+For CI, supply `HANDOFF_REGISTRY_URL` and `HANDOFF_REGISTRY_ACCESS_TOKEN`
+through the job environment, as described under
+[Workspace authorization](#4-workspace-authorization). A connection block in
+`handoff.config.ts` is needed only to pin the URL in the repository, or to read
+the values from differently named variables (`fromEnv` is imported from
+`handoff-app`):
 
 ```ts
 runtime: {
   registryConnection: {
     url: 'https://registry.example.com',
-    accessTokenEnv: 'HANDOFF_REGISTRY_ACCESS_TOKEN',
+    accessToken: fromEnv('HANDOFF_REGISTRY_ACCESS_TOKEN'),
   },
 },
 ```
@@ -433,17 +571,19 @@ for Claude Code, Cursor and VS Code behind the plug icon in the header. By hand:
 ## Configuration
 
 Configuration is read from `handoff.config.ts`, `.js`, `.cjs`, or `.json`, in
-that order. `defineConfig` provides typed authoring. A partial `runtime` block
-is deep-merged with defaults.
+that order. `defineConfig` provides typed authoring. Values merge onto the
+defaults: plain objects merge recursively, and arrays, scalars, `null`, and
+functions replace.
 
 Useful environment variables:
 
 | Variable | Purpose |
 | --- | --- |
+| `HANDOFF_PROFILE` | Config profile merged onto the base config |
 | `HANDOFF_FIGMA_PROJECT_ID` | Figma file ID used by `fetch` |
 | `HANDOFF_DEV_ACCESS_TOKEN` | Figma personal access token used by `fetch` |
 | `HANDOFF_REGISTRY_URL` | Connected workspace registry URL |
-| `HANDOFF_REGISTRY_ACCESS_TOKEN` | User-issued CI token |
+| `HANDOFF_REGISTRY_ACCESS_TOKEN` | Registry access token used by a connected workspace |
 | `HANDOFF_SYNC_SECRET` | Optional deployment-wide registry credential |
 | `DATABASE_URL` | Registry PostgreSQL connection string |
 | `AUTH_SECRET` | Registry session-signing secret, at least 32 characters |
@@ -462,6 +602,52 @@ Vercel Blob or a custom adapter can be selected through
 selected through `runtime.registry.database.driver`; PostgreSQL is used by
 both.
 
+## Profiles
+
+A profile is a sidecar config file that merges onto the base config. It holds
+only what changes between environments, so a project keeps one shared config
+instead of a second complete copy of it.
+
+- The base config is `handoff.config.ts`, `.js`, `.cjs`, or `.json`. It is the
+  only config file loaded when no profile is selected.
+- A profile file is `handoff.config.<profile>.*`, with the same four
+  extensions.
+- Select a profile with `--profile <name>` or with `HANDOFF_PROFILE`.
+  `--profile` takes precedence over `HANDOFF_PROFILE`.
+- Profile names are not predefined. A name can contain lowercase letters,
+  numbers, and hyphens.
+- A selected profile must exist. If no `handoff.config.<name>.*` file is found,
+  the command stops with an error.
+- `login`, `logout`, `publish`, and `checkout` also accept a profile that has
+  only a saved registry login, because there the profile selects the registry.
+  Every other command still needs the config file.
+- Layers resolve as defaults, base config, profile, then programmatic config,
+  with the merge rules described under [Configuration](#configuration).
+- A selected profile also reads `.env.<profile>` on top of `.env`, when that
+  file exists. Both are read from the directory the command runs in, and a
+  variable already set in the environment beats both files.
+
+```bash
+npx handoff-app build --target registry --profile registry
+```
+
+`build --target registry` always packages a registry-mode application, so a
+profile does not need to set `runtime.mode`. This makes a profile a good place
+for the registry build settings: the database driver, the database
+environment-variable name, the asset storage, and whether MCP is enabled. A
+hosting provider or a CI job selects the profile through `HANDOFF_PROFILE`.
+
+`defineConfig` types a profile as well as a base config. The generated
+`.gitignore` lists `handoff.config.local.*`, which makes `local` the usual name
+for a profile that stays on one machine.
+
+Arrays replace, so a profile that declares `catalog.include` also decides what
+`make` and `checkout` register.
+
+`.env.<profile>` is read once at startup rather than watched.
+`HANDOFF_WORKING_PATH` cannot be set from it, because the working path is
+resolved before any profile is known.
+
 ## CLI reference
 
 | Command | Description |
@@ -473,12 +659,14 @@ both.
 | `npm run build -- [--target static\|registry]` | The static site or standalone registry bundle is built |
 | `npm run db:migrate` | Registry database migrations are applied |
 | `npm run validate` | Configured components are validated |
-| `npm run publish -- <kind\|all> [id...]` | Components, patterns, pages, tokens, or assets are published |
+| `npm run publish -- <kind\|all> [id...]` | Catalog items, pages, tokens, or assets are published |
 | `npm run checkout -- <kind\|all> [id...]` | Published content is pulled into a workspace |
-| `npm run login -- --url <url>` | The CLI is authorized through the registry device flow |
-| `npm run logout -- [--url <url>]` | A saved CLI credential is revoked and removed |
+| `npm run login -- [--profile <name>] --url <url>` | The CLI is authorized through the registry device flow |
+| `npm run logout -- [--profile <name>] [--all]` | Saved CLI credentials are revoked and removed |
 
-`publish` and `checkout` additionally accept `--dry-run`, and `publish` accepts `--no-build`.
+Every command except `init` accepts `-c, --config`, `--profile`, `-d, --debug`,
+and `-f, --force`. `publish` and `checkout` additionally accept `--dry-run`, and
+`publish` accepts `--no-build`.
 
 Arguments after `--` are forwarded to the local CLI. Exact options can be shown
 by adding `--help` after the separator. Advanced configuration and hooks are

package/UPGRADE.md

@@ -0,0 +1,218 @@
+# Upgrade Handoff
+
+This document contains migration steps for each major version upgrade.
+
+## Version 1.x.x to version 2.x.x
+
+This guide describes how to upgrade a Handoff project from version 1.x.x to version 2.x.x.
+Each feature section identifies the affected projects and the required changes.
+
+### Before you start
+
+1. Verify that the project builds with its current Handoff version.
+2. Save the project files, package version, and lockfile in version control.
+3. Install the version 2.x.x package that you plan to use.
+4. Apply the migration sections that affect your project.
+
+### Breaking changes
+
+| Change | Affected projects |
+| --- | --- |
+| [Figma token environment references](#figma-token-environment-references) | Projects that put a Figma token directly in config |
+| [Catalog items](#catalog-items) | Projects with component or pattern declarations |
+
+<!-- Add future breaking changes as feature sections before "Verify the upgrade". Add each section to this table. -->
+
+### Figma token environment references
+
+`devAccessToken` and its legacy spelling `dev_access_token` now accept 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:
+
+```ts
+import { defineConfig, fromEnv } from 'handoff-app';
+
+export default defineConfig({
+  devAccessToken: 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.
+
+### Catalog items
+
+#### Affected projects
+
+This change affects projects that use the old component or pattern registration API.
+It also affects projects that use the deprecated API from an earlier version 2.x.x prerelease.
+Version 2.x.x requires `defineCatalogItem` for implementations and compositions.
+
+#### Register catalog directories
+
+Move component and pattern directories from `entries` to `catalog.include`.
+
+Version 1.x.x:
+
+```js
+entries: { components: ['components'], patterns: ['patterns'], scss: 'styles/main.scss' }
+```
+
+Version 2.x.x:
+
+```js
+catalog: { include: ['components', 'patterns'] },
+entries: { scss: 'styles/main.scss' }
+```
+
+Each path can name one item directory or a collection of item directories. Global `entries.js` and `entries.scss` still work.
+
+#### Convert declaration files
+
+Use `<name>.handoff.ts`, `<name>.handoff.js`, or `<name>.handoff.cjs`.
+Replace legacy filenames such as `button.json` or `button.js`.
+
+Version 2.x.x does not support JSON item declarations, including `.handoff.json`.
+JSON project config (`handoff.config.json`) remains supported.
+
+If `runtime.workspace.declarationFormat` is `json`, change it to `ts`, `js`, or `cjs`. The default remains `ts`.
+
+#### Replace declaration helpers
+
+| Removed API | Replacement |
+| --- | --- |
+| `defineReactComponent(Component, config)` | `defineCatalogItem({ ...config, implementation: Component })` from `handoff-app/react` |
+| `defineHandlebarsComponent(config)` | `defineCatalogItem({ ...config, implementation: './Button.hbs' })` from `handoff-app/handlebars` |
+| `defineCsfComponent(config)` | `defineCatalogItem({ ...config, implementation: fromCSF('./Button.stories.tsx') })` from `handoff-app/react` |
+| `defineComponent(config)` | `defineCatalogItem({ ...config, implementation: './Button.tsx' })` from the module for its renderer |
+| `definePattern({ components })` | `defineCatalogItem({ composition })` from `handoff-app/pattern` |
+
+Remove the old `renderer`, `entries.component`, `entries.template`, and `entries.story` fields.
+The implementation supplies the renderer and source file.
+Keep the supporting `entries.js`, `entries.scss`, `entries.schema`, and `entries.templates` paths that your item uses.
+Rename the metadata fields:
+
+| Old field | Version 2.x.x field |
+| --- | --- |
+| `title` | `name` |
+| `should_do` | `shouldDo` |
+| `should_not_do` | `shouldNotDo` |
+
+##### React
+
+```ts
+import { defineCatalogItem, type Preview } from 'handoff-app/react';
+import Button from './Button';
+
+const item = defineCatalogItem({
+  name: 'Button',
+  implementation: Button,
+  entries: { scss: './button.scss' },
+});
+export default item;
+export const Primary = { args: { children: 'Save' } } satisfies Preview<typeof item>;
+```
+
+Imported components retain their prop types. A file path also works: `implementation: './Button.tsx'`.
+Keep implementation files inside the item directory to publish them.
+
+##### Handlebars and CommonJS
+
+```js
+const { defineCatalogItem } = require('handoff-app/handlebars');
+
+exports.default = defineCatalogItem({
+  name: 'Badge',
+  implementation: './Badge.hbs',
+});
+exports.Primary = { args: { children: 'New' } };
+```
+
+Use this form in `.handoff.js` or `.handoff.cjs`. JavaScript declarations can also use `import` and `export`.
+
+##### CSF
+
+```ts
+import { defineCatalogItem, fromCSF } from 'handoff-app/react';
+
+export default defineCatalogItem({
+  name: 'Button',
+  implementation: fromCSF('./Button.stories.tsx'),
+});
+```
+
+CSF is a React source format. The story file supplies the previews.
+The filename does not select CSF automatically.
+
+##### Compositions
+
+```ts
+import { defineCatalogItem } from 'handoff-app/pattern';
+
+export default defineCatalogItem({
+  name: 'Toolbar',
+  composition: [{ ref: 'button', preview: 'Primary', args: { children: 'Save' } }],
+});
+```
+
+Rename `components` to `composition`.
+Rename each member's `id` to `ref`.
+Keep item IDs stable.
+
+#### Export previews
+
+Remove the inline `previews` map.
+Export each preview beside the default catalog item.
+Rename preview `title` to `name`.
+Rename `values` to `args`:
+
+```ts
+export const Primary = { name: 'Primary action', args: { children: 'Save' } };
+```
+
+If a preview key is a valid export name, preserve its spelling and capitalization.
+If a key is not a valid export name, rename it.
+Update composition references to each renamed preview.
+
+Previews appear in source export order.
+
+For CommonJS declarations, use `exports.default` for the item.
+Use a named export such as `exports.Primary` for each preview.
+
+#### Replace declaration types
+
+Replace imports of the removed types:
+
+| Removed type | Replacement |
+| --- | --- |
+| `Component` | `CatalogItem` |
+| `DeclarationPreview` | `CatalogPreview` or `Preview<typeof item>` |
+| `PatternComponentRef` | `CompositionRef` |
+| `ReactDeclarationConfig`, `HandlebarsDeclarationConfig`, `CsfDeclarationConfig` | The catalog helper's input type |
+| `GenericDeclarationConfig`, `GenericPatternDeclarationConfig` | The catalog helper's input type, or `CatalogItemMeta` for shared metadata |
+
+`RendererKind` comes from the catalog API and contains `react` and `handlebars`.
+CSF uses `renderer: 'react'` with `format: 'csf'` inside `implementation`.
+
+#### Registry projects
+
+Checkout writes only catalog declarations.
+Registry records require explicit renderer and source-format metadata where applicable.
+
+### Verify the upgrade
+
+After you apply the required migrations, verify the project:
+
+1. Build the project with version 2.x.x.
+2. Verify that all expected catalog items appear in the documentation.
+3. Verify the preview order, arguments, and composition references.
+4. Start the workspace with file watchers.
+5. Edit a declaration to verify that its previews update.
+
+If the project uses a registry, verify the published items:
+
+1. Publish the migrated items.
+2. Verify that checkout produces valid declarations.
+3. Rebuild the checked-out items.

package/config/config.template.js

@@ -54,13 +54,10 @@ const config = {
     ports: { app: 3000, websocket: 3001 },
   },
   // These are the entry points used to compile the target application
+  catalog: { include: ['./components'] },
   entries: {
     scss: './sass/main.scss',
     js: './js/main.js',
-    components: ['./components'],
-    // Uncomment to enable pattern documentation pages.
-    // Patterns compose component previews into single-page views.
-    // patterns: ['./patterns'],
   },
   // These are the asset zip file download links
   assetsZipLinks: {

package/config/config.template.ts

@@ -34,11 +34,10 @@ export default defineConfig({
     },
     ports: { app: 3000, websocket: 3001 },
   },
+  catalog: { include: ['./components'] },
   entries: {
     scss: './sass/main.scss',
     js: './js/main.js',
-    components: ['./components'],
-    // patterns: ['./patterns'],
   },
   assetsZipLinks: {
     icons: null,