handoff-app 2.0.0-8 → 2.0.0

package/docs/cli.md

@@ -1,78 +1,299 @@
 # Handoff CLI
 
-The Handoff cli allows you to interact with your Figma file and Handoff app
-via the command line. It allows you to run handoff in any folder with
-no other configuration or setup.  
+The `handoff-app` CLI fetches Figma foundations, builds and serves the
+documentation, and transfers content between a workspace and a registry. The
+[README](../README.md) explains the concepts and the configuration. This page
+lists every command and option.
 
-## Interacting with Figma
-The CLI will allow you to fetch all data from Figma, build the documentation
-app and run a local dev site. For these use the build, fetch, and serve commands
-documented below.  
+## Run the CLI
 
-## Configuring a handoff project
-The CLI will allow you to build the various kinds of configurations that you
-will need for interacting with Figma. Handoff has sane configuration defaults
-but the various kinds of configurations can be tailored or extended.
+`init` installs `handoff-app` in the project and adds npm scripts for the
+common commands. Use the npm scripts, so that local development and CI use the
+project version:
 
-Handoff has 4 configuration areas - 
+```bash
+npm run build -- --target registry
+```
 
-`handoff.config.*` - Defines the general handoff configuration. Supported files are `handoff.config.ts`, `handoff.config.js`, `handoff.config.cjs`, and `handoff.config.json` (resolved in that precedence order). Pass `-c, --config <file>` to load one specific file instead, resolved from the working directory (`HANDOFF_WORKING_PATH`, or the directory the command runs in).
-`pages` - Markdown files that will create or customize pages in the documentation
-app
-`exportables` - JSON schemas for each component in your figma file that you
-want to pull into handoff.
-`integration` - scss mappings and html templates for making it easy to map
-handoff tokens to your frontend framework.
+npm forwards the arguments after `--` to the CLI. For a command without an npm
+script, use `npx`:
 
-The CLI exposes two ways to manage the config - `make` and `eject`. 
+```bash
+npx handoff-app validate:components
+```
 
-__Eject__ commands will take the default configuration and eject them into
-the current working directory. If you customize these configurations, then run 
-handoff commands in that directory, these configs will be executed. `eject:config` now prompts for TypeScript or JavaScript config format.
-__Make__ commands will generate a boilerplate configuration in the current
-working directory. This is useful for extending handoff for different components
-or integrations.
+Show the help of the CLI or of one command:
 
-## Requirements
-Node 16+
+```bash
+npx handoff-app --help
+npx handoff-app publish --help
+```
 
-## Install the CLI 
+Each command runs against the working directory. The working directory is the
+directory that holds `handoff.config.ts`. It is the current directory, or the
+directory that `HANDOFF_WORKING_PATH` sets.
 
-`npm install -g handoff-app`
+## Shared options
 
-## Run the CLI
+Every command except `init` accepts these options:
+
+| Option | Description |
+| --- | --- |
+| `-c, --config <file>` | Load this config file, relative to the working directory, instead of `handoff.config.*` |
+| `--profile <name>` | Merge `handoff.config.<name>.*` onto the base config, and use the registry login of this profile. Has priority over `HANDOFF_PROFILE`. |
+| `-d, --debug` | Show debug logs |
+| `-f, --force` | Force the action. The effect depends on the command. |
+| `--help` | Show the help of the command |
+
+`handoff-app --version` shows the CLI version.
+
+`HANDOFF_LOG_LEVEL` (`debug`, `info`, `warn`, `error`, or `silent`) and
+`HANDOFF_LOG_SCOPES` (`handoff`, `vite`, `next`) control the log output of
+every command. The README lists all
+[environment variables](../README.md#environment-variables).
+
+## Project
+
+### init
+
+```bash
+npx handoff-app init
+```
+
+Creates a project with an interactive wizard. The wizard asks for the project
+name, sample content, JavaScript or TypeScript, an optional Vercel setup, and
+optional Figma credentials. It installs `handoff-app` and adds these npm
+scripts: `start`, `dev`, `fetch`, `build`, `login`, `logout`, `publish`,
+`checkout`, and `db:migrate`.
+
+### fetch
+
+```bash
+handoff-app fetch
+```
+
+Fetches tokens and assets from the Figma file and writes them to `exported/`.
+It reads `HANDOFF_FIGMA_PROJECT_ID` and `HANDOFF_DEV_ACCESS_TOKEN`. If a value
+is empty, `fetch` asks for it in the terminal. Without a terminal, `fetch`
+stops with an error that names the missing variable.
+
+### start
+
+```bash
+handoff-app start
+```
+
+Starts the workspace documentation server and the Handoff file watchers. While
+the command runs, Handoff rebuilds changed files and updates the
+documentation.
+
+### dev
+
+```bash
+handoff-app dev
+```
+
+Starts the workspace documentation server without the Handoff file watchers.
+
+### build
+
+```bash
+handoff-app build [--target static|registry] [--package standalone|vercel] [--skip-components]
+```
+
+Builds the documentation.
+
+| Option | Description |
+| --- | --- |
+| `--target static` | Default. Builds a static site in `out/static`. |
+| `--target registry` | Builds a standalone registry server in `out/registry`. The application is always in registry mode. |
+| `--package vercel` | Writes a Vercel Build Output bundle to `.vercel/output` for the selected target |
+| `--package standalone` | Writes the default output of the target |
+| `--skip-components` | Builds the application without a component build first |
+| `-f, --force` | Builds every component again, and ignores the build cache |
+
+`--package` never changes the target.
+
+### build:app
+
+```bash
+handoff-app build:app [--skip-components]
+```
+
+Builds the static site. It is the same as `build --target static`.
+
+### build:components
+
+```bash
+handoff-app build:components [component]
+```
+
+Builds the catalog items without the documentation application. A name builds
+only that item.
+
+### validate:components
+
+```bash
+handoff-app validate:components [--skip-build]
+```
+
+Validates the catalog items. `--skip-build` validates the existing build
+output without a build first.
+
+## Content
+
+### make:component
+
+```bash
+handoff-app make:component <name>
+```
+
+Creates a Handlebars catalog item: a template, a CommonJS declaration, and,
+if you select them, a JavaScript file and a Sass file. The item goes into the
+first directory in `catalog.include`, or into `components/`. If that directory
+is not registered, Handoff adds it to `catalog.include`. The name can contain
+letters, numbers, hyphens, and underscores. `--force` overwrites an existing
+template.
+
+### make:page
+
+```bash
+handoff-app make:page <name> [parent]
+```
+
+Creates a Markdown page in `pages/`, or in `pages/<parent>/`. If a default page
+has the same name, the new page starts with its content. `--force` overwrites
+an existing page.
+
+### scaffold
+
+```bash
+handoff-app scaffold
+```
+
+Creates catalog item stubs for the components in the fetched Figma data. The
+command asks which components to create and how.
+
+### eject:config
+
+```bash
+handoff-app eject:config
+```
+
+Writes the default config to the working directory. The command asks for
+TypeScript or JavaScript. `--force` overwrites an existing config file.
+
+### eject:pages
+
+```bash
+handoff-app eject:pages
+```
+
+Copies the default documentation pages to `pages/`, so that you can change
+them. `--force` adds the default pages that you did not change.
+
+### eject:theme
+
+```bash
+handoff-app eject:theme
+```
+
+Copies the Sass file of the selected theme to `theme/default.scss`, so that
+you can change it.
+
+## Registry
+
+### db:migrate
+
+```bash
+DATABASE_URL="postgresql://…" handoff-app db:migrate
+```
+
+Applies the registry database migrations. The command reads the project config
+and the database variables, and uses the same database driver as the registry
+build. Run it before the first deployment and before each upgrade. The build,
+the server start, and the installer never run migrations.
+
+### login
+
+```bash
+handoff-app login [--url <registry-url>] [--profile <name>] [--no-browser]
+```
+
+Authorizes the CLI through the device flow of the registry. The CLI saves the
+token in `.handoff/cli-auth.json`, under the selected profile.
+
+| Option | Description |
+| --- | --- |
+| `--url <registry-url>` | Registry URL, with its base path when the registry has one. Without it, the CLI uses the configured registry URL. |
+| `--profile <name>` | Saves the login under this profile. The profile needs no config file. |
+| `--no-browser` | Shows the approval URL, but does not open the browser. `HANDOFF_LOGIN_NO_BROWSER=true` does the same. |
+
+### logout
+
+```bash
+handoff-app logout [--profile <name>] [--url <registry-url>] [--all]
+```
+
+Revokes the saved token when possible. Then it removes the saved login of the
+selected profile.
+
+| Option | Description |
+| --- | --- |
+| `--url <registry-url>` | Revokes the login only if it belongs to this exact registry URL |
+| `--all` | Revokes and removes the logins of every profile |
+
+### publish
+
+```bash
+handoff-app publish <catalog|pages|tokens|assets|all> [id...] [--dry-run] [--no-build]
+```
+
+Builds the content and publishes it to the connected registry. `all` publishes
+every kind in dependency order. One or more ids limit the publish to those
+entities: catalog item ids, page ids, token set ids, or asset collections.
+`tokens` and `assets` run the Figma pipeline first.
 
-`handoff-app --help`
+| Option | Description |
+| --- | --- |
+| `--dry-run` | Lists the content that a real publish uploads. Does not connect to a registry. The build still runs. |
+| `--no-build` | Publishes the existing build output without a build first |
 
-## Commands and Flags
+### checkout
 
-Usage: handoff-app <cmd> <opts>
+```bash
+handoff-app checkout <catalog|pages|tokens|assets|all> [id...] [--dry-run]
+```
 
-Commands:
-  fetch [opts] - Fetches the design tokens from the design system
+Writes content from the connected registry into the workspace. Checkout writes
+declarations in the format that `runtime.workspace.declarationFormat` sets.
 
-  build [--target static|registry] [opts] - Builds the design system for the target (default: static export)
-    build:app [opts] - Builds the design system static application (alias of `build --target static`)
+| Option | Description |
+| --- | --- |
+| `--dry-run` | Lists the files that a real checkout creates or overwrites. Writes nothing. |
 
-  start [opts] - Starts the design system in development mode
+### Registry connection
 
-  db:migrate [opts] - Runs registry database migrations (Drizzle / PostgreSQL). Reads the project config and database env vars, applies the package-owned migration set, and runs independently of `build`.
+`publish` and `checkout` find the registry URL and the token in this order:
 
-  login [--profile <name>] --url <registry-url> - Authorizes this workspace in the browser and stores a revocable token in `.handoff/cli-auth.json`, under the selected profile.
+1. `HANDOFF_REGISTRY_URL` and `HANDOFF_REGISTRY_ACCESS_TOKEN`, or
+   `runtime.registryConnection` in the config.
+2. The saved login of the selected profile, if it belongs to the same registry
+   URL. A profile without a login uses the default login.
+3. `HANDOFF_SYNC_SECRET`, when no token and no login is available.
 
-  logout [--profile <name>] [--url <registry-url>] [--all] - Revokes the saved token when possible, then removes the local credential of the selected profile, or of every profile with `--all`.
+## Deprecated commands
 
-  make
-    make:component <name> [opts] - Creates a new catalog item with a declaration
-    make:page <component> <state> [opts] - Creates a new page
+These commands still work. Each shows a deprecation warning.
 
-  eject - Ejects the default entire configuration to the current directory
-    eject:config [opts] - Ejects the default configuration to the current directory
-    eject:integration [opts] - Ejects the default integration to the current directory
-    eject:pages [opts] - Ejects the default pages to the current directory
+| Command | Replacement |
+| --- | --- |
+| `push [type] [id...]` | `publish` |
+| `push:all` | `publish all` |
+| `push:tokens [setId...]` | `publish tokens` |
+| `push:assets [collection]` | `publish assets` |
+| `pull [type] [id...]` | `checkout` |
 
-Options:
-  -c, --config [file]      Define the path to the config file
-  -d, --debug              Show debug logs
-  -h, --help               Show this help message
-  -v, --version            Show the handoff version number
+The `push` and `pull` commands also accept `components` and `patterns` as the
+type. They accept the options for features that Handoff 2 does not have, and
+show a warning for each one.

package/drizzle/0007_add_ai_keys.sql

@@ -0,0 +1,11 @@
+CREATE TABLE "registry_ai_keys" (
+	"user_id" text NOT NULL,
+	"connection_id" text NOT NULL,
+	"encrypted_key" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "registry_ai_keys_user_id_connection_id_pk" PRIMARY KEY("user_id","connection_id"),
+	CONSTRAINT "registry_ai_keys_connection_not_blank" CHECK (length(btrim("registry_ai_keys"."connection_id")) > 0)
+);
+--> statement-breakpoint
+ALTER TABLE "registry_ai_keys" ADD CONSTRAINT "registry_ai_keys_user_id_registry_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."registry_users"("id") ON DELETE cascade ON UPDATE no action;

package/drizzle/0008_add_source_dir.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "components" ADD COLUMN "source_dir" text;--> statement-breakpoint
+ALTER TABLE "patterns" ADD COLUMN "source_dir" text;