chore: add registry install flow

2026-03-20 10:38:05 +08:00
parent 5045756525
commit e8aea4b88a
13 changed files with 1788 additions and 20 deletions
@@ -0,0 +1,118 @@
+# 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`.
+
+## 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
+
+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