inventive-ui 0.0.1

package/README.md

@@ -0,0 +1,650 @@
+# IUI CLI
+
+The official command-line tool for the **Inventive UI** design system. Use it to authenticate, initialize projects, install the framework and component library, manage asset packages, and keep everything up to date.
+
+**Architecture:** For the full end-to-end flow — how the CLI connects to Framework, Components, the three config files, asset packages, and bundlers — see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+---
+
+## Installation
+
+The CLI is published on **public npm**:
+
+```bash
+npm install -g inventive-ui
+```
+
+Requires **Node.js 20+**.
+
+After install, run `iui login` once to authenticate for private `@inventive-ui/*` packages (framework, components, assets) on the Inventive UI registry.
+
+**Maintainers:** bump `package.json` version and push to `main` — GitHub Actions publishes to npm when the version is new (`NPM_TOKEN` secret). Or run `npm run publish:public` locally.
+
+---
+
+## Compile-first CSS (framework ≥ 1.0.50)
+
+Inventive UI builds utility CSS at **dev/build time** (Node), then injects it into `<head>` before paint. The CLI scaffolds the wiring; you still need the matching bundler plugin.
+
+| Bundler | What `iui init` / doctor expect |
+|---------|----------------------------------|
+| Vite 6+ | `vite.config.ts` with `inventiveUiVite({ root: import.meta.dirname })` and `optimizeDeps.exclude: [...IUI_ASSET_OPTIMIZE_DEPS_EXCLUDE]` (asset packages only) |
+
+`inventiveUiVite()` excludes `@inventive-ui/framework` from `optimizeDeps` automatically — do not add it to `vite.config.ts` or to `optimizeDeps.include`.
+| Webpack | `plugins: [...inventiveUiWebpack()]` + `html-webpack-plugin` in the app |
+| Next.js | `export default withIUI({ ... })` + root `<IUIRegistry>` |
+
+`iui.config.ts` can include an optional compile-first `build` block. **`scanDirs` / `scanPackages` are not required** — Framework defaults to `["src", ".iui"]` and `["@inventive-ui/components"]`.
+
+Documented init toggles (`packageSafelist`, `includeShadeMatrix`, theme/palette/arbitrary flags, etc.) are listed in Framework `docs/01-compile-first-guide.md` for the docs site.
+
+**Do not** import style-map `.generated` files into the browser — keep them on the scanner path (default `src` / `.iui`, or custom `build.scanDirs`).
+
+`iui doctor` warns when Vite/Webpack/Next tooling is present but the plugin (or Next registry) is missing.
+
+---
+
+## Quick start
+
+### New project
+
+```bash
+iui login
+iui init                    # interactive — creates configs, installs framework
+iui install components      # install @inventive-ui/components + prepare slots
+iui install assets          # optional — interactive asset picker
+```
+
+Non-interactive example:
+
+```bash
+iui init -y -f vite
+```
+
+### Joining an existing team repo
+
+If the repo already has a committed `.iui/` folder, skip `iui init`:
+
+```bash
+iui login
+git clone <repo> && cd <repo>
+iui setup                   # registry config, workspace install, diagnostics
+```
+
+See [Team onboarding](docs/TEAM-ONBOARDING.md) for admin/teammate flows and CI setup.
+
+---
+
+## Command reference
+
+Every command below is implemented in the CLI today. Run `iui --help` or `iui <command> --help` for built-in usage text.
+
+### All commands at a glance
+
+| Command | What it does | Auth required |
+| ------- | ------------ | ------------- |
+| `iui login` | Sign in with GitHub OAuth; link license; configure npm auth | No |
+| `iui logout` | Remove stored credentials and npm registry auth | No |
+| `iui whoami` | Show GitHub identity, plan, license, seats, update window | No |
+| `iui init` | Initialize a new project: register, install framework, write configs | Yes |
+| `iui setup` | Clone-to-green: `.npmrc`, install deps, run doctor | Yes |
+| `iui install framework` | Install or reinstall `@inventive-ui/framework` | Yes |
+| `iui install components` | Install `@inventive-ui/components` and rebuild slot registry | Yes |
+| `iui install assets [ids...]` | Install asset packages (interactive picker if no ids) | Yes |
+| `iui list` | Show installed framework, components, assets, and slots | No |
+| `iui list -a` | Show all components available in the registry | No |
+| `iui update` | Check and apply framework, component, asset, and CLI updates | Yes |
+| `iui doctor` | Run project health diagnostics | No |
+| `iui assets list` | Show available and installed asset packages | Yes |
+| `iui assets remove <id>` | Uninstall an asset package and update slot registry | Yes |
+| `iui team list` | List team seat assignments (admin) | Yes |
+| `iui team add [email]` | Add a teammate to team seats (admin) | Yes |
+| `iui team remove [email]` | Remove a teammate from active seats (admin) | Yes |
+| `iui devices list` | List CLI devices authorized for your account | Yes |
+| `iui devices revoke [id]` | Revoke a device login | Yes |
+| `iui deploy-token list` | List deploy tokens for CI/hosting | Yes |
+| `iui deploy-token create [name]` | Create a short-lived scoped deploy token | Yes |
+| `iui deploy-token revoke <id>` | Revoke a deploy token immediately | Yes |
+
+**Note:** Inside an initialized project, most commands automatically validate and repair the slot registry before running.
+
+### Global options
+
+These work with any command:
+
+| Option | Description |
+| ------ | ----------- |
+| `-C, --cwd <dir>` | Run as if started in the given directory |
+| `-q, --quiet` | Minimal output (also respects `IUI_QUIET=1`) |
+| `--no-color` | Disable ANSI colors |
+| `-V, --version` | Print CLI version |
+| `-h, --help` | Show help for a command |
+
+---
+
+### `iui login`
+
+Authenticate with GitHub OAuth, link your Inventive UI license, and write npm registry auth to `~/.npmrc`.
+
+**What it does:**
+- Opens the browser for GitHub OAuth (polls until complete or timeout)
+- Saves session to `~/.iui/config.json`
+- Configures global npm auth for `@inventive-ui/*` installs
+- Reuses an existing valid session unless `--force` is passed
+
+| Option | Description |
+| ------ | ----------- |
+| `-f, --force` | Force re-authentication and register this device |
+| `--bootstrap` | After login, optionally prompt to run `iui init` and install assets |
+
+```bash
+iui login
+iui login --force
+iui login --bootstrap
+```
+
+---
+
+### `iui logout`
+
+Remove locally stored credentials and clear npm registry auth written by the CLI.
+
+```bash
+iui logout
+```
+
+---
+
+### `iui whoami`
+
+Show the currently signed-in GitHub user, plan type, license status, seat usage, and update window expiry.
+
+```bash
+iui whoami
+```
+
+---
+
+### `iui init`
+
+Initialize an Inventive UI project in the current directory (or workspace root with `--workspace`).
+
+**What it does:**
+- Validates auth and license
+- Registers the project with the Inventive UI API
+- Writes project `.npmrc` (scope line only) and updates `.gitignore`
+- Ensures React 19.x or Vite 6.x+ is present (installs if missing)
+- Installs `@inventive-ui/framework` and `@inventive-ui/components`
+- Generates `iui.config.ts` (with compile-first `build` block), `component.config.ts`, `assets.config.json`, and Vite/TS configs as needed
+- Creates `.iui/project.json`, component/package manifests, and the slot registry
+
+| Option | Description |
+| ------ | ----------- |
+| `-f, --framework <preset>` | Framework preset: `react` or `vite` |
+| `-y, --yes` | Non-interactive with default confirmations |
+| `--workspace` | Monorepo: init once at workspace root and link all workspace apps |
+| `--source <api\|registry>` | Install source for framework/components (default: `api`) |
+
+```bash
+iui init
+iui init -y -f vite
+iui init -y -f react --workspace
+iui init --source registry
+```
+
+---
+
+### `iui setup`
+
+Set up a cloned project for a teammate. Does **not** upgrade packages — installs what is in `package.json` and the lockfile.
+
+**What it does:**
+- Ensures you are authenticated
+- Writes project `.npmrc` and global npm auth
+- Runs `npm install` / `pnpm install` / `yarn install` at the workspace root (monorepo-aware)
+- Runs `iui doctor` for every app with a `.iui/` folder
+
+| Option | Description |
+| ------ | ----------- |
+| `--fix` | Apply safe automatic fixes during diagnostics |
+| `-y, --yes` | Non-interactive with default confirmations |
+
+```bash
+iui setup
+iui setup --fix
+iui setup --fix -y
+```
+
+Use `iui update` when you need newer framework, component, or asset versions.
+
+---
+
+### `iui install framework`
+
+Install or reinstall `@inventive-ui/framework`. Requires an initialized project (`.iui/project.json`).
+
+**What it does:**
+- Resolves install path for monorepos (installs at workspace root)
+- Downloads and installs the framework package
+- Syncs `package.json` if `node_modules` is ahead of the declared semver range
+
+| Option | Description |
+| ------ | ----------- |
+| `--source <api\|registry>` | Install source (default: `api`) |
+
+```bash
+iui install framework
+iui install framework --source registry
+iui -C apps/docs install framework
+```
+
+---
+
+### `iui install components`
+
+Install or reinstall `@inventive-ui/components` and rebuild the slot registry.
+
+**What it does:**
+- Installs the component library package
+- Regenerates `.iui/generated/` slot files and updates manifests
+- Syncs `package.json` if `node_modules` is ahead of the declared semver range
+- Skips reinstall if the same version is already installed (unless upgrading via `iui update`)
+
+| Option | Description |
+| ------ | ----------- |
+| `--source <api\|registry>` | Install source (default: `api`) |
+
+```bash
+iui install components
+iui -C apps/landing install components
+```
+
+---
+
+### `iui install assets [ids...]`
+
+Install one or more asset packages (icons, illustrations, logos, flags, emoji, loaders, file types).
+
+**What it does:**
+- Validates license
+- Shows an interactive picker when no package ids are given
+- Installs selected packages and updates `assets.config.json` and the slot registry
+
+| Option | Description |
+| ------ | ----------- |
+| `--source <api\|registry>` | Install source (default: `api`) |
+
+**Available package ids:**
+
+| Id | Package |
+| -- | ------- |
+| `icons-lucide` | Lucide Icons |
+| `icons-material` | Material Icons |
+| `icons-phosphor` | Phosphor Icons |
+| `material-symbols` | Material Symbols |
+| `illustrations` | Storyset Illustrations |
+| `logos` | Mono Logos |
+| `color-logos` | Color Logos |
+| `flags` | Flagpack |
+| `emoji` | Emoji |
+| `loaders` | LDRS Loaders |
+| `file-types` | File Type Icons |
+
+```bash
+iui install assets                              # interactive picker
+iui install assets icons-lucide material-symbols
+iui install assets illustrations flags emoji
+```
+
+---
+
+### `iui list`
+
+Show installed framework version, component count, asset packages, and slot registry status for the current project.
+
+```bash
+iui list
+iui -C apps/docs list
+```
+
+---
+
+### `iui list -a` / `iui list --available`
+
+Fetch and display all components available in the remote registry. Marks which ones are already installed. Works outside an initialized project.
+
+```bash
+iui list -a
+iui list --available
+```
+
+---
+
+### `iui update`
+
+Check for and apply updates to the framework, components, individual components, and asset packages.
+
+**What it does:**
+- Reports if a newer CLI version exists (upgrade with `npx inventive-ui@latest`)
+- Checks registry for component, framework, and asset updates
+- Respects license update window (expired licenses see available versions but cannot install)
+- Installs selected updates and rebuilds slot registry
+- Syncs `@inventive-ui/*` entries in `package.json` to `^<installed>` when `node_modules` is ahead
+
+| Option | Description |
+| ------ | ----------- |
+| `-y, --yes` | Apply all eligible updates without prompts |
+| `--check` | Check only; exit code `1` when updates exist |
+| `--source <api\|registry>` | Install source for updates (default: `api`) |
+
+```bash
+iui update
+iui update -y
+iui update --check
+iui -C apps/docs update -y
+```
+
+---
+
+### `iui doctor`
+
+Run a multi-point health check. Read-only by default; exits with code `1` if any check fails.
+
+**What it checks:**
+- Authentication and license validity (skipped with `--config-only`)
+- Registry reachability (skipped with `--config-only`)
+- `package.json` present
+- Project initialized (`.iui/project.json`)
+- `@inventive-ui/framework` and `@inventive-ui/components` installed
+- React 19.x or Vite 6.x (and matching `react-dom`)
+- **Three-config tiers:** `iui.config.ts` must not import `assets.config.json` or contain asset/component keys; `assets.config.json` schema + `globalIcons`; `component.config.ts` must not contain theme keys
+- Component and asset package counts
+- Slot registry integrity
+- Package compatibility between framework and components
+- Whether installed versions are behind latest (warns to run `iui update`)
+- Syncs `package.json` when `node_modules` is ahead of declared ranges
+- Generated slot file validity
+- `component.config.ts` validity (TypeScript check)
+- Compile-first bundler wiring (Vite/Webpack/Next plugin present when tooling detected)
+
+In monorepos, doctors every app with a `.iui/` folder when run from the workspace root.
+
+| Option | Description |
+| ------ | ----------- |
+| `--fix` | Apply safe fixes (strip assets from `iui.config.ts`, patch build block, repair slots, install TypeScript for config validation) |
+| `--config-only` | Config tiers + slots + compile-first only — no auth/registry. Use in CI and pre-commit hooks |
+
+```bash
+iui doctor
+iui doctor --config-only    # CI / pre-commit — no login required
+iui doctor --fix
+iui -C apps/docs doctor
+```
+
+---
+
+### `iui assets list`
+
+Show all available asset packages grouped by category, with installed status.
+
+```bash
+iui assets list
+```
+
+---
+
+### `iui assets remove <id>`
+
+Remove an installed asset package, update `assets.config.json`, and prune its slots.
+
+```bash
+iui assets remove illustrations
+iui assets remove icons-lucide
+```
+
+---
+
+### `iui team` (admin, Team plan)
+
+Manage team seat assignments. `iui team` alone runs `iui team list`.
+
+#### `iui team list`
+
+List active team seat assignments.
+
+| Option | Description |
+| ------ | ----------- |
+| `--all` | Include inactive/removed seat records |
+
+```bash
+iui team
+iui team list
+iui team list --all
+```
+
+#### `iui team add [email]`
+
+Add a GitHub-linked email to team seats. Prompts for email if omitted.
+
+```bash
+iui team add teammate@example.com
+iui team add
+```
+
+#### `iui team remove [email]`
+
+Remove a user from active team seats. Prompts for email if omitted.
+
+```bash
+iui team remove teammate@example.com
+```
+
+See [Team onboarding](docs/TEAM-ONBOARDING.md) for the full admin flow.
+
+---
+
+### `iui devices`
+
+Manage CLI devices authorized for your account. `iui devices` alone runs `iui devices list`.
+
+#### `iui devices list`
+
+List all devices that have completed `iui login`.
+
+```bash
+iui devices
+iui devices list
+```
+
+#### `iui devices revoke [device-id]`
+
+Revoke a device. Prompts to pick one if id is omitted.
+
+```bash
+iui devices revoke abc123
+iui devices revoke
+```
+
+Use when offboarding a machine or cleaning up stale logins.
+
+---
+
+### `iui deploy-token`
+
+Manage short-lived deploy tokens for CI and hosting. `iui deploy-token` alone runs `iui deploy-token list`.
+
+#### `iui deploy-token list`
+
+List deploy tokens (active, expired, and revoked).
+
+```bash
+iui deploy-token
+iui deploy-token list
+```
+
+#### `iui deploy-token create [name]`
+
+Create a scoped deploy token. Store the output as `IUI_DEPLOY_TOKEN` in your CI secrets.
+
+| Option | Description |
+| ------ | ----------- |
+| `--days <days>` | Validity in days, 1–30 (default: `7`) |
+| `--packages <packages>` | Comma-separated package ids or `*` (default: `*`) |
+
+```bash
+iui deploy-token create
+iui deploy-token create "github-actions" --days 7 --packages "*"
+iui deploy-token create "vercel" --days 14 --packages "framework,components"
+```
+
+#### `iui deploy-token revoke <token-id>`
+
+Revoke a deploy token immediately.
+
+```bash
+iui deploy-token revoke tok_abc123
+```
+
+See [Team onboarding](docs/TEAM-ONBOARDING.md) and [examples/github-actions/consumer-ci.yml](examples/github-actions/consumer-ci.yml) for CI setup.
+
+---
+
+## Monorepos
+
+Supported layouts: npm/pnpm/yarn workspaces (`apps/*`, `packages/*`, explicit paths, nested globs).
+
+| Approach | When to use |
+| -------- | ----------- |
+| Per-app `iui init` (`.iui/` in each app) | Recommended for multi-app repos (e.g. docs + landing) |
+| `iui init --workspace` (single root `.iui/`) | Opt-in shared root setup |
+
+From the workspace root:
+
+```bash
+iui setup    # installs at root; doctors every app with .iui/
+```
+
+From an app directory (`apps/docs`, `apps/landing`):
+
+```bash
+npx iui update -y
+npx iui install framework
+```
+
+Installs still run at the workspace root. Use `-C apps/docs` to target a specific app from elsewhere.
+
+---
+
+## Install source
+
+By default, packages install via the **Inventive UI API** (tarball download). Developers do not need GitHub Packages credentials for normal CLI use after `iui login`.
+
+To install from the npm registry instead (internal/dev):
+
+```bash
+iui install components --source registry
+iui update --source registry
+```
+
+Or set `IUI_INSTALL_SOURCE=registry`.
+
+---
+
+## Project files
+
+After `iui init`, the CLI manages:
+
+| Path | Purpose |
+| ---- | ------- |
+| `iui.config.ts` | `IUIThemeConfig` — theme, states, core, compile-first `build` block (no assets import) |
+| `component.config.ts` | `ComponentConfigMap` — default variants, presets, cTags per component |
+| `assets.config.json` | `IUIAssetsConfig` — libraries, `globalIcons`, `@alias` maps, binding/preload |
+| `.iui/project.json` | Project ID, license, repo metadata |
+| `.iui/components.json` | Installed component versions |
+| `.iui/packages.json` | Installed asset package versions |
+| `.iui/slots.json` | Slot registry (components + assets) |
+| `.iui/generated/` | Managed slot helpers from the components **public slot contract** (do not edit) |
+| `.iui/slot-registration-state.json` | Operational checksum/state for no-op validation (ephemeral) |
+| `.iui/slot-registration.lock` | Short-lived lock file during slot reconciliation (ephemeral) |
+| `.iui/classes.cache.json`, `.iui/build-*`, `public/iui/` | Compile-first build cache artifacts (ephemeral) |
+
+Framework install status comes from `@inventive-ui/framework` in `node_modules`, not from `.iui/` metadata.
+
+Commit `package.json`, one lockfile, `.iui/` metadata and generated slot helpers, config files, and the project `.npmrc` scope line (no tokens). Do not commit ephemeral `.iui` state/lock/build-cache files. See [Team onboarding](docs/TEAM-ONBOARDING.md#what-to-commit-in-a-shared-repo).
+
+For the full integration map (Framework, Components, configs, bundlers), see [Architecture](docs/ARCHITECTURE.md). For ownership rules, validate vs repair, grouped slot codegen driven by `public-slot-contract.json`, and write-amplification KPIs, see [Consumer Codegen & Config Ownership](docs/CONSUMER-CODEGEN.md).
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+| -------- | ------- | ----------- |
+| `IUI_API_URL` | `https://api.inventiveui.com` | Override the backend API URL |
+| `IUI_INSTALL_SOURCE` | `api` | Default install source: `api` or `registry` |
+| `IUI_DEPLOY_TOKEN` | — | CI/hosting registry auth (from `deploy-token create`) |
+| `IUI_QUIET` | — | Set to `1` for minimal output |
+| `IUI_NO_BANNER` | — | Set to `1` to hide the CLI banner |
+| `IUI_CI` | — | Set to `1` in trusted CI for non-interactive behavior |
+| `IUI_YES` | — | Set to `1` to auto-confirm prompts where supported |
+| `IUI_ALLOW_CUSTOM_API` | — | Allow non-default `IUI_API_URL` hosts (dev only) |
+
+Local API example:
+
+```bash
+export IUI_API_URL="http://localhost:3000"
+```
+
+---
+
+## CI deploy checklist
+
+1. Admin runs `iui deploy-token create "ci" --days 7 --packages "*"` and stores the token as `IUI_DEPLOY_TOKEN`.
+2. Commit a project `.npmrc` with only the scope line:
+
+   ```ini
+   @inventive-ui:registry=https://api.inventiveui.com/registry/npm
+   ```
+
+3. Inject auth at build time (never commit tokens):
+
+   ```bash
+   printf '%s\n%s\n' \
+     "//api.inventiveui.com/registry/npm/:_authToken=${IUI_DEPLOY_TOKEN}" \
+     "always-auth=true" >> ~/.npmrc
+   ```
+
+4. Run `npm ci` / `pnpm install` / `yarn install`, then your build.
+
+**Do not** use `NODE_AUTH_TOKEN` in app repos — that secret belongs on the API server only. Personal `iui login` sessions are for developer machines, not CI.
+
+---
+
+## Development
+
+```bash
+npm install
+npm run build          # compile to dist/
+npm run dev            # watch mode
+npm test               # typecheck + unit tests
+npm run start -- <cmd> # run built CLI locally, e.g. npm run start -- doctor
+```
+
+---
+
+## Documentation
+
+| Doc | Audience |
+| --- | --- |
+| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | **Start here** — full CLI flow and integration with Framework, Components, configs, bundlers |
+| [CONSUMER-CODEGEN.md](docs/CONSUMER-CODEGEN.md) | File ownership, validate vs repair, slot codegen |
+| [TEAM-ONBOARDING.md](docs/TEAM-ONBOARDING.md) | Clone-to-green, CI tokens, what to commit |
+| [RFC-002](docs/RFC-002-package-owned-runtime-registry.md) | 2.0 package-owned slot registry direction |
+| [RFC-003](docs/RFC-003-CLI-GATING.md) | CLI gating / release policy |
+
+---
+
+## License
+
+Inventive UI operates under a **Perpetual License + 1 Year Updates** model.  
+See [inventiveui.com](https://inventiveui.com) for licensing details.