handoff-app 2.0.0-9 → 2.0.1

package/AGENTS.md

@@ -1,7 +1,96 @@
-# Instructions
+# AGENTS.md
+
+## Local instructions
 
 Before starting work, check whether `AGENTS.local.md` exists in the repository root.
 
 If it exists, read and follow its instructions in addition to this file. Treat `AGENTS.local.md` as developer-specific local guidance.
 
 If it does not exist, proceed normally.
+
+## Project
+
+`handoff-app` is an npm package (CLI + library) that turns design tokens (fetched from Figma), components, patterns, and Markdown pages into a Next.js documentation app and distributable artifacts. User-facing docs: [README.md](README.md), [RECIPES.md](RECIPES.md), [docs/cli.md](docs/cli.md), [docs/api.md](docs/api.md), [UPGRADE.md](UPGRADE.md).
+
+Requires Node.js >= 22 and npm >= 10.
+
+## Commands
+
+```bash
+npm run build     # tsc: compiles src/ (except src/app) to dist/
+npm run lint      # next lint over src/app
+npm test          # alias for lint; there is no unit test suite
+npx tsc -p src/app/tsconfig.json --noEmit   # typecheck the Next.js app (root tsc excludes src/app);
+                                            # errors under a stale src/app/.next/types are not real
+npx drizzle-kit generate                    # generate a registry migration after editing src/registry/db/schema.ts
+```
+
+The CLI (`dist/cli.js`, bin `handoff-app`) always runs against a **working directory**: the directory that holds `handoff.config.ts` (or `HANDOFF_WORKING_PATH`). This repo is not a Handoff project, so to exercise a change, build here and run the CLI from a consumer project that uses this build (`start`, `dev`, `build`, `fetch`, `publish`, `checkout`, ...). Verify behavior there; `npm run lint` and the two `tsc` runs are the only checks in this repo.
+
+Formatting: Prettier (config in `package.json`: 140 cols, single quotes, `es5` trailing commas, Tailwind class sorting) and `.editorconfig` (2 spaces, LF).
+
+## Architecture
+
+### Runtime modes
+
+- **Workspace** (default): local files are the source of truth; no database. It is the **only** place that builds content.
+- **Registry**: a deployed catalog backed by PostgreSQL (Drizzle). It serves only what a workspace publishes. It never builds and never reads workspace source.
+- A **connected workspace** publishes to / checks out from a registry; it is not a third mode.
+
+`runtime.mode` selects the mode; `build --target registry` sets registry mode in the generated app. Keep registry-only dependencies (Drizzle/Postgres) out of the workspace and static paths — e.g. `src/store/index.ts` deliberately does not re-export the registry store; registry consumers import `@handoff/store/registry` lazily.
+
+### Two TypeScript programs
+
+- **`src/` (minus `src/app`)** — the Node CLI/library, CommonJS, compiled by root `tsconfig.json` to `dist/`. `src/index.ts` holds the `Handoff` class (`fetch`, `build`, `publish`, `checkout`, `start`, `dev`); `src/cli.ts` registers the yargs commands in `src/commands/`.
+- **`src/app/`** — the Next.js (pages router) documentation app. It is not compiled by `tsc`; at build/start time `src/app-builder` stages it into `.handoff/<projectId>/` under the package and runs `next build` / `next dev`. It imports the core via the `@handoff/*` alias (→ `src/*`). It also hosts the APIs: docs API, registry API, MCP endpoint (`/api/mcp`), auth, and the AI assistant (`src/app/lib/*`, `src/app/pages/api/*`).
+
+### Main flows
+
+- **fetch**: `src/pipeline` — Figma auth → extract → fonts → token transformers; output goes to the working directory's `exported/`.
+- **build/start**: `src/config` loads `handoff.config.*` + profile sidecar + env, then `initRuntimeConfig()` normalizes catalog declarations (`src/catalog`) into component/pattern records; `src/transformers` builds previews with Vite/esbuild per renderer (React, Handlebars, CSF); `src/cache` skips unchanged components (`.handoff/.cache/build-cache.json`, bypass with `--force`); `src/app-builder` builds the app (static → `out/static`, registry → `out/registry`, `--package vercel` → `.vercel/output`). Watch mode uses chokidar + a WebSocket reload server with diff-aware rebuilds.
+- **publish/checkout**: `src/registry` (`publish/`, `checkout/`, `transfer.ts`, `tokens/`, `assets/`, `auth/`) against the registry API in `src/app/lib/registry-api`. Storage is abstracted by `src/store` (filesystem vs. registry implementations of the same interfaces). Asset blobs go through a pluggable storage provider; email and AI providers are also pluggable custom server modules (`handoff-app/providers`).
+- **Migrations**: SQL in `drizzle/` ships with the package and is applied by `handoff-app db:migrate`.
+
+### Config and server-module rules
+
+- **Baked vs. request-time values.** For a `fromEnv('NAME')` value, the build keeps only the variable name, and a deployed registry reads the value at request time. Secrets must use `fromEnv()`. These settings change the shape of the build and are baked, so a change needs a rebuild: `runtime.mode`, `runtime.mcp`, `runtime.ai.enabled`, the database driver, the asset storage and email providers, and every custom server module. A new or changed setting must fit one of these two categories.
+- **Custom server modules** (asset storage, email, AI providers) are `.js`/`.mjs` files, relative to the working directory, that import their define helper from `handoff-app/providers`. The registry build stops when a module imports `handoff-app`. The build copies each module and the packages it imports into the registry bundle.
+
+Package entry points (`handoff-app`, `/react`, `/handlebars`, `/pattern`, `/providers`) map to `src/index.ts`, `src/react.ts`, `src/handlebars.ts`, `src/pattern.ts`, `src/providers.ts`. Adding a renderer touches several `Record<RendererKind, …>` maps — see [src/catalog/README.md](src/catalog/README.md).
+
+Most `src/<module>/` directories have a `README.md` describing their files and flow. Read it before changing a module, and update it when the module's contract changes.
+
+## Conventions
+
+- **Breaking changes** get migration steps in [UPGRADE.md](UPGRADE.md), per major version.
+- **Changelog**: [CHANGELOG.md](CHANGELOG.md) follows Keep a Changelog + SemVer. Entries are written during release prep on the release branch. Do not add or edit entries in feature or fix work unless asked.
+- **Docs style**: README/RECIPES/CHANGELOG use short, plain, imperative sentences (Simplified Technical English style).
+
+### Branches and releases
+
+- **Branch names**: `<category>/<kebab-case-topic>`, e.g. `feature/config-profiles`, `bugfix/code-toc-md`, `docs/readme-rewrite`, `chore/remove-mdx`. Categories in use: `feature/`, `bugfix/`, `docs/`, `chore/`, `release/`.
+- **Release branches**: each release has a `release/X.Y.Z` branch. Feature and fix branches start from it and merge back into it through a PR, not into `main`. A major release can first collect work in a long-running `integration/X.Y.Z` branch, from which `release/X.Y.Z` is cut (as for 2.0.0).
+- **Prereleases and final version**: `np` (`npm run release`) runs on the release branch. It publishes prereleases (`X.Y.Z-N`) and then the final `X.Y.Z`; each creates a commit whose message is the bare version and a `vX.Y.Z[-N]` tag. Do not write these commits by hand. Release prep (changelog entries and date, last fixes) is committed directly on the release branch.
+- **`main`** receives only release merges: a PR from `release/X.Y.Z` into `main` ships the release.
+
+### Commit messages
+
+Use a Conventional Commit subject with no scope and, normally, no body:
+
+```
+<type>: <description>
+```
+
+- Types: `feat`, `fix`, `chore`, `refactor`, `docs`, `test`, `build`, `ci`, `perf`, `style`.
+- Description: lowercase, imperative, no trailing period. State what the change achieves for the user, not how the code does it; omit file names and implementation details unless needed for clarity.
+- Several distinct changes in one commit: one imperative clause each, separated by `; `. Supporting changes belong to the change they support and are not listed separately.
+- No fixed length limit; the purpose sets the length.
+
+Examples from history:
+
+```
+fix: use plain JSON Schema for MCP tool inputs
+feat: move Figma settings to integrations.figma
+refactor: rename define entry point and storage adapter to providers
+feat: accept fromEnv() references in asset storage options and resolve them at request time; remove providerId and record blobs as database or custom
+```

package/{Changelog.md → CHANGELOG.md}

@@ -6,7 +6,111 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## \[1.2.2] - TBD
+## \[2.0.1] - 2026-11-01
+
+This release makes catalog items smaller to publish and reports packages that
+are too large for the registry.
+
+### Changed
+
+* Client bundles of interactive React previews use the minified production
+  build of React. This reduces each bundle by about 1 MB, so components and
+  patterns publish within the registry request limit more often. In the local
+  workspace, previews no longer show React development warnings. To get them
+  back, set `minify: false` and a development `process.env.NODE_ENV` in
+  `hooks.clientBuildConfig`, then rebuild with `--force`.
+
+### Fixed
+
+* `publish` stops before the upload when a package is larger than the 4.5 MB
+  registry limit and names the largest files.
+* A `413` response from the registry now shows a clear "too large" message.
+
+## \[2.0.0] - 2026-10-16
+
+Handoff 2.0 adds a shared registry to the local workspace. You write content in
+a workspace, publish it to a registry, and check it out in other projects.
+Coding agents and an AI assistant can read the design system through MCP.
+
+### Registry and connected workspaces
+
+* Added the registry: a deployed catalog with a PostgreSQL database. It stores
+  the catalog items, pages, tokens, and assets that a workspace publishes.
+* Added `publish` and `checkout`. Each command transfers all content, one
+  kind, or specific ids. `--dry-run` lists the changes and writes nothing.
+* Added registry accounts, invitations, password reset, and access tokens with
+  read or read-and-write access.
+* Added `login` and `logout`. `login` authorizes the CLI with a device code in
+  the browser.
+* Added `build --target registry` for a standalone registry server, and
+  `--package vercel` for a Vercel bundle of either build target.
+* Added `db:migrate` to apply the registry database migrations.
+* Added asset storage. The registry stores assets in PostgreSQL by default. A
+  custom provider module can store them in a different service and can accept
+  direct uploads.
+* Added registry email through SMTP or a custom provider module.
+
+### MCP and AI assistant
+
+* Added an MCP endpoint at `/api/mcp/`. Coding agents use it to search and read
+  components, previews, component source, tokens, and pages.
+* Added a connect dialog with client settings for Claude Code, Cursor, and
+  VS Code.
+* Added an AI assistant to the documentation app. It uses the same MCP tools,
+  knows the current page, and links to the content that it read.
+* Added AI connections for OpenAI-compatible APIs, for example gateways and
+  local Ollama, and for custom provider modules. In registry mode, readers can
+  add their own keys.
+
+MCP and the AI assistant need a server: a workspace or a registry. A static
+site has neither.
+
+### Catalog authoring
+
+* Added `defineCatalogItem`, one API for components and patterns.
+  `catalog.include` registers the catalog directories.
+* Previews are named exports. `Preview<typeof item>` gives a React preview the
+  argument type of its component. A preview can declare a `render` function.
+* Handoff builds the CSS of a React item from the stylesheets that its imports
+  load.
+* Previews keep their export order in builds, publish, and checkout.
+
+### Other changes
+
+* Added config profiles (`--profile`, `HANDOFF_PROFILE`), `fromEnv()`
+  references, and one registry login for each profile.
+* Added `-c, --config` to every command.
+* The build cache records every file that the last build of a component read,
+  Sass partials included. Every full build and every publish uses the cache.
+* Page titles use `app.title`. The default pages no longer show a hard-coded
+  Handoff title.
+* Reorganized the README, and added RECIPES.md and a migration guide in
+  UPGRADE.md.
+
+### Breaking changes
+
+* Handoff requires Node.js 22 or newer and npm 10 or newer.
+* `defineCatalogItem` replaces `defineReactComponent`,
+  `defineHandlebarsComponent`, `defineCsfComponent`, `defineComponent`, and
+  `definePattern`.
+* `catalog.include` replaces `entries.components` and `entries.patterns`.
+* Previews are named exports, not a `previews` map. Some fields have new
+  names, for example `title` is `name` and `values` is `args`.
+* Declarations use `.handoff.ts`, `.handoff.js`, or `.handoff.cjs`. Handoff
+  does not read JSON declarations or legacy `<name>.json` and `<name>.js` files.
+* Figma settings moved to `integrations.figma`. The access token must be an
+  environment reference.
+* The static build goes to `out/static`, and fetched tokens and assets go to
+  `exported/`. Neither path contains the project id. Removed the
+  `public-<projectId>` directories.
+* Removed the `make:template` command.
+* Removed the legacy `/assets` pages. The foundation pages show logos and
+  icons.
+
+See the [migration guide](UPGRADE.md#version-1xx-to-version-2xx) for the
+upgrade steps.
+
+## \[1.2.2] - 2026-08-03
 
 This patch release improves watch-mode reliability for patterns, broadens slot
 default typing, clears downstream lint/build compatibility issues, and fixes a

package/CLAUDE.md

@@ -1,7 +1,98 @@
-# Instructions
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Local instructions
 
 Before starting work, check whether `AGENTS.local.md` exists in the repository root.
 
 If it exists, read and follow its instructions in addition to this file. Treat `AGENTS.local.md` as developer-specific local guidance.
 
 If it does not exist, proceed normally.
+
+## Project
+
+`handoff-app` is an npm package (CLI + library) that turns design tokens (fetched from Figma), components, patterns, and Markdown pages into a Next.js documentation app and distributable artifacts. User-facing docs: [README.md](README.md), [RECIPES.md](RECIPES.md), [docs/cli.md](docs/cli.md), [docs/api.md](docs/api.md), [UPGRADE.md](UPGRADE.md).
+
+Requires Node.js >= 22 and npm >= 10.
+
+## Commands
+
+```bash
+npm run build     # tsc: compiles src/ (except src/app) to dist/
+npm run lint      # next lint over src/app
+npm test          # alias for lint; there is no unit test suite
+npx tsc -p src/app/tsconfig.json --noEmit   # typecheck the Next.js app (root tsc excludes src/app);
+                                            # errors under a stale src/app/.next/types are not real
+npx drizzle-kit generate                    # generate a registry migration after editing src/registry/db/schema.ts
+```
+
+The CLI (`dist/cli.js`, bin `handoff-app`) always runs against a **working directory**: the directory that holds `handoff.config.ts` (or `HANDOFF_WORKING_PATH`). This repo is not a Handoff project, so to exercise a change, build here and run the CLI from a consumer project that uses this build (`start`, `dev`, `build`, `fetch`, `publish`, `checkout`, ...). Verify behavior there; `npm run lint` and the two `tsc` runs are the only checks in this repo.
+
+Formatting: Prettier (config in `package.json`: 140 cols, single quotes, `es5` trailing commas, Tailwind class sorting) and `.editorconfig` (2 spaces, LF).
+
+## Architecture
+
+### Runtime modes
+
+- **Workspace** (default): local files are the source of truth; no database. It is the **only** place that builds content.
+- **Registry**: a deployed catalog backed by PostgreSQL (Drizzle). It serves only what a workspace publishes. It never builds and never reads workspace source.
+- A **connected workspace** publishes to / checks out from a registry; it is not a third mode.
+
+`runtime.mode` selects the mode; `build --target registry` sets registry mode in the generated app. Keep registry-only dependencies (Drizzle/Postgres) out of the workspace and static paths — e.g. `src/store/index.ts` deliberately does not re-export the registry store; registry consumers import `@handoff/store/registry` lazily.
+
+### Two TypeScript programs
+
+- **`src/` (minus `src/app`)** — the Node CLI/library, CommonJS, compiled by root `tsconfig.json` to `dist/`. `src/index.ts` holds the `Handoff` class (`fetch`, `build`, `publish`, `checkout`, `start`, `dev`); `src/cli.ts` registers the yargs commands in `src/commands/`.
+- **`src/app/`** — the Next.js (pages router) documentation app. It is not compiled by `tsc`; at build/start time `src/app-builder` stages it into `.handoff/<projectId>/` under the package and runs `next build` / `next dev`. It imports the core via the `@handoff/*` alias (→ `src/*`). It also hosts the APIs: docs API, registry API, MCP endpoint (`/api/mcp`), auth, and the AI assistant (`src/app/lib/*`, `src/app/pages/api/*`).
+
+### Main flows
+
+- **fetch**: `src/pipeline` — Figma auth → extract → fonts → token transformers; output goes to the working directory's `exported/`.
+- **build/start**: `src/config` loads `handoff.config.*` + profile sidecar + env, then `initRuntimeConfig()` normalizes catalog declarations (`src/catalog`) into component/pattern records; `src/transformers` builds previews with Vite/esbuild per renderer (React, Handlebars, CSF); `src/cache` skips unchanged components (`.handoff/.cache/build-cache.json`, bypass with `--force`); `src/app-builder` builds the app (static → `out/static`, registry → `out/registry`, `--package vercel` → `.vercel/output`). Watch mode uses chokidar + a WebSocket reload server with diff-aware rebuilds.
+- **publish/checkout**: `src/registry` (`publish/`, `checkout/`, `transfer.ts`, `tokens/`, `assets/`, `auth/`) against the registry API in `src/app/lib/registry-api`. Storage is abstracted by `src/store` (filesystem vs. registry implementations of the same interfaces). Asset blobs go through a pluggable storage provider; email and AI providers are also pluggable custom server modules (`handoff-app/providers`).
+- **Migrations**: SQL in `drizzle/` ships with the package and is applied by `handoff-app db:migrate`.
+
+### Config and server-module rules
+
+- **Baked vs. request-time values.** For a `fromEnv('NAME')` value, the build keeps only the variable name, and a deployed registry reads the value at request time. Secrets must use `fromEnv()`. These settings change the shape of the build and are baked, so a change needs a rebuild: `runtime.mode`, `runtime.mcp`, `runtime.ai.enabled`, the database driver, the asset storage and email providers, and every custom server module. A new or changed setting must fit one of these two categories.
+- **Custom server modules** (asset storage, email, AI providers) are `.js`/`.mjs` files, relative to the working directory, that import their define helper from `handoff-app/providers`. The registry build stops when a module imports `handoff-app`. The build copies each module and the packages it imports into the registry bundle.
+
+Package entry points (`handoff-app`, `/react`, `/handlebars`, `/pattern`, `/providers`) map to `src/index.ts`, `src/react.ts`, `src/handlebars.ts`, `src/pattern.ts`, `src/providers.ts`. Adding a renderer touches several `Record<RendererKind, …>` maps — see [src/catalog/README.md](src/catalog/README.md).
+
+Most `src/<module>/` directories have a `README.md` describing their files and flow. Read it before changing a module, and update it when the module's contract changes.
+
+## Conventions
+
+- **Breaking changes** get migration steps in [UPGRADE.md](UPGRADE.md), per major version.
+- **Changelog**: [CHANGELOG.md](CHANGELOG.md) follows Keep a Changelog + SemVer. Entries are written during release prep on the release branch. Do not add or edit entries in feature or fix work unless asked.
+- **Docs style**: README/RECIPES/CHANGELOG use short, plain, imperative sentences (Simplified Technical English style).
+
+### Branches and releases
+
+- **Branch names**: `<category>/<kebab-case-topic>`, e.g. `feature/config-profiles`, `bugfix/code-toc-md`, `docs/readme-rewrite`, `chore/remove-mdx`. Categories in use: `feature/`, `bugfix/`, `docs/`, `chore/`, `release/`.
+- **Release branches**: each release has a `release/X.Y.Z` branch. Feature and fix branches start from it and merge back into it through a PR, not into `main`. A major release can first collect work in a long-running `integration/X.Y.Z` branch, from which `release/X.Y.Z` is cut (as for 2.0.0).
+- **Prereleases and final version**: `np` (`npm run release`) runs on the release branch. It publishes prereleases (`X.Y.Z-N`) and then the final `X.Y.Z`; each creates a commit whose message is the bare version and a `vX.Y.Z[-N]` tag. Do not write these commits by hand. Release prep (changelog entries and date, last fixes) is committed directly on the release branch.
+- **`main`** receives only release merges: a PR from `release/X.Y.Z` into `main` ships the release.
+
+### Commit messages
+
+Use a Conventional Commit subject with no scope and, normally, no body:
+
+```
+<type>: <description>
+```
+
+- Types: `feat`, `fix`, `chore`, `refactor`, `docs`, `test`, `build`, `ci`, `perf`, `style`.
+- Description: lowercase, imperative, no trailing period. State what the change achieves for the user, not how the code does it; omit file names and implementation details unless needed for clarity.
+- Several distinct changes in one commit: one imperative clause each, separated by `; `. Supporting changes belong to the change they support and are not listed separately.
+- No fixed length limit; the purpose sets the length.
+
+Examples from history:
+
+```
+fix: use plain JSON Schema for MCP tool inputs
+feat: move Figma settings to integrations.figma
+refactor: rename define entry point and storage adapter to providers
+feat: accept fromEnv() references in asset storage options and resolve them at request time; remove providerId and record blobs as database or custom
+```

package/{License.md → LICENSE.md}

@@ -1,4 +1,4 @@
-Copyright 2025 Convertiv Inc.
+Copyright 2023-2026 Convertiv Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of 
 this software and associated documentation files (the “Software”), to deal in