# Registry Install and Upgrade

Cadence UI now supports a minimal internal registry flow for source-owned consumers.
The goal is not package publishing yet. The goal is to make one reviewed repo state
directly consumable by another app.

## What the registry contains

- `registry/config.json`: the authored registry format
- `registry/index.json`: generated install metadata
- `scripts/build-registry.mjs`: rebuilds and validates the generated index
- `scripts/registry-install.mjs`: copies selected source files into a consumer project

`registry/index.json` is intentionally machine-readable. It records:

- installable item names
- entrypoints and copied files
- transitive source files required by each item
- external package dependencies
- the package versions that produced the registry snapshot

## Maintainer workflow

Whenever `packages/ui` or `packages/tokens` changes in a way that affects installable
source, refresh the registry metadata:

```bash
pnpm registry:build
```

To verify that the generated file is current:

```bash
pnpm registry:check
```

The pull request workflow now runs `pnpm registry:check`, and the release version PR
workflow refreshes the registry automatically via `pnpm release:version`.

The generated index includes transitive local helpers, not just component entrypoints. If a
component starts importing a shared file such as `packages/ui/src/lib/icons.tsx`, rebuild the
index before merge so source-copy consumers receive the full dependency graph.

To validate the end-to-end consumer flow locally:

```bash
pnpm test:registry:consumer
```

That smoke test creates a temporary app, runs the registry installer, installs the
required dependencies, and verifies that the copied source both typechecks and builds.

## Consumer install flow

### 1. Pin the Cadence UI source

Consumers should install from a reviewed Cadence UI repo state, usually:

- the merge commit of a version PR, or
- a maintainer-created tag that points at that versioned commit

The consumer does not need this repo as a runtime dependency. It only needs access to
the checked-out source when running the installer.

### 2. Run the installer from the Cadence UI repo

From this repository checkout:

```bash
pnpm registry:install --project ../acme-app button dialog
```

The installer will:

- include `tokens` automatically when a component requires it
- copy files into `src/cadence-ui`
- preserve shared internal imports under `src/cadence-ui/components`, `src/cadence-ui/lib`,
  and `src/cadence-ui/tokens`
- add any missing runtime dependencies to the consumer's `package.json`
- write `src/cadence-ui/.install-manifest.json`

Useful flags:

- `--target-dir src/shared/cadence-ui`: customize the destination root
- `--skip-package-json`: copy files without editing the consumer package manifest
- `--dry-run`: preview copied files and package changes

## Consumer upgrade flow

Upgrades stay source-owned. There is no generated wrapper or hidden runtime.

1. Update the Cadence UI checkout to the new reviewed commit or tag.
2. Re-run the installer against the same consumer project.

```bash
pnpm registry:install --project ../acme-app
```

If no item names are provided, the installer reuses the list stored in
`src/cadence-ui/.install-manifest.json`.

After that:

- review the consumer diff
- run the consumer package manager install if `package.json` changed
- verify imports still point at `src/cadence-ui/tokens/styles.css`

## Expected consumer import points

At minimum, the consumer app should import:

- `src/cadence-ui/tokens/styles.css` from its global app stylesheet or entry module

For package consumers instead of source-copy installs, the equivalent convenience import
is:

- `@ai-ui/ui/styles.css`

If the consumer wants the theme helpers, they can also import from:

- `src/cadence-ui/tokens/index.ts`

## Current scope

This registry flow is intentionally minimal:

- it copies source files
- it writes dependency intent into the consumer app
- it supports reinstalling the same item set for upgrades

It does not yet:

- publish to npm
- host a remote registry API
- auto-tag or auto-publish releases
- resolve consumer-specific codemods during upgrade