@calibrate-ds/cli 0.1.0 → 0.1.3

package/README.md

@@ -0,0 +1,556 @@
+# Calibrate
+
+**Calibrate is a local-first design system compiler for design engineers.** It reads your design tool, builds a normalized model of your design system, and uses it to scaffold typed components, design tokens, MDX documentation, and AI implementation prompts — all from the terminal.
+
+No cloud sync. No proprietary lock-in. Your design system lives in git.
+
+---
+
+## What it does
+
+```
+Figma  →  ptb scan  →  ptb generate-components  →  typed React shells
+                    →  ptb generate-tokens        →  CSS custom properties
+                    →  ptb document component     →  MDX docs + Storybook stories
+                    →  ptb implement component    →  AI-written component code
+                    →  ptb status                 →  staleness tracking in CI
+```
+
+When your designer updates a component in Figma, `ptb scan` picks up the change, `ptb diff` shows what changed, and `ptb status` tells you which implementations are now stale. The whole team stays in sync through a committed `ptb.lock` file — no external service required.
+
+---
+
+## Install
+
+**Requirements:** Node.js ≥ 20
+
+> **macOS users:** Do not use the system Node or a Homebrew Node for global installs — you'll hit permission errors. Use nvm (step 1 below). It takes 30 seconds and fixes the problem permanently.
+
+### Step 1 — Install nvm (skip if you already have it)
+
+```bash
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
+source ~/.zshrc        # or: source ~/.bashrc  (if you use bash)
+```
+
+### Step 2 — Install Node 22
+
+```bash
+nvm install 22
+```
+
+### Step 3 — Install Calibrate
+
+```bash
+npm install -g @calibrate-ds/cli
+source ~/.zshrc        # reload PATH so ptb is found
+ptb --version          # should print the installed version
+```
+
+**Already have Node 20+ via nvm?** Skip to step 3.
+
+**Getting `permission denied` errors?** You are using the system Node. Run steps 1–3 above.
+
+---
+
+## Quickstart
+
+### 1. Initialize
+
+```bash
+cd your-project
+ptb init
+```
+
+PTB detects whether your repo is fresh or existing:
+- **Fresh repo** — scaffolds `packages/ui/` with framework-specific `package.json`, `tsconfig.json`, and component/token directories
+- **Existing repo** — writes `ptb.config.json` and `.gitignore` entries only, leaves your code untouched
+
+You will be asked to choose:
+- Framework (React, Vue, Svelte, React Native)
+- Solo or team project
+- Figma plan (Organization/Enterprise for direct API, or Pro/Starter for the Calibrate plugin)
+- Documentation tool (Storybook, Docusaurus, or plain MDX)
+
+### 2. Set your Figma token
+
+```bash
+export FIGMA_ACCESS_TOKEN=your_token_here
+```
+
+Generate a token at **Figma → Account Settings → Security → Generate New Token**. PTB never stores the token — `ptb.config.json` only stores the env var name.
+
+### 3. Scan your Figma file
+
+```bash
+ptb scan
+```
+
+Fetches your Figma file, normalizes it into a `DesignSystemModel`, saves it to `.ptb/latest.json`, and exports component context files to `.ptb/context/`.
+
+Find your file key in the Figma URL: `figma.com/design/<FILE_KEY>/...`
+
+### 4. Generate components and tokens
+
+```bash
+ptb generate-components    # typed React shells in packages/ui/src/components/
+ptb generate-tokens        # CSS custom properties in packages/ui/src/tokens/
+```
+
+### 5. Document components
+
+```bash
+ptb document component .   # generates MDX + Storybook stories for all components
+```
+
+### 6. Implement with AI
+
+```bash
+ptb ai setup               # configure Claude or OpenAI once
+ptb implement component Button
+```
+
+### 7. Track freshness
+
+```bash
+ptb status                 # shows which components are stale vs implemented
+ptb stamp component Button # mark Button as implemented against the current design
+```
+
+---
+
+## Figma workflows
+
+PTB supports two workflows depending on your Figma plan.
+
+### Direct Fetch (Organization / Enterprise)
+
+PTB reads tokens directly from the Figma API. No plugin required.
+
+```bash
+ptb flow direct   # step-by-step checklist
+```
+
+### Plugin Export (Pro / Starter / Free)
+
+Use the **Calibrate** Figma plugin to export variables and tokens, then import them into PTB.
+
+```bash
+# 1. In Figma: run Calibrate → Export
+# 2. Place the export file in your project named as imported-tokens.json
+# 3. Place it in the .ptb root folder. (If you don't see .ptb folder while exporting, press Cmd+Shift+. to show hidden files)
+ptb scan
+ptb generate-tokens
+ptb generate-components
+```
+
+---
+
+## Configuration
+
+`ptb init` creates `ptb.config.json` at your project root. All fields:
+
+```json
+{
+  "designTool": {
+    "provider": "figma",
+    "fileKey": "YOUR_FIGMA_FILE_KEY",
+    "accessTokenEnv": "FIGMA_ACCESS_TOKEN"
+  },
+  "project": {
+    "rootDir": "."
+  },
+  "output": {
+    "componentsDir": "packages/ui/src/components",
+    "tokensDir": "packages/ui/src/tokens",
+    "metadataDir": ".ptb"
+  },
+  "framework": {
+    "name": "react",
+    "typescript": true,
+    "styling": "css-modules"
+  },
+  "generation": {
+    "stories": true,
+    "tests": false,
+    "types": true,
+    "indexFiles": true,
+    "cssFiles": true
+  },
+  "naming": {
+    "componentCase": "PascalCase",
+    "folderCase": "kebab-case",
+    "tokenCase": "camelCase"
+  },
+  "classification": {
+    "treatComponentSetsAsCanonical": true,
+    "treatStandaloneComponentsAsCanonical": true,
+    "treatNestedInstancesAsReferences": true
+  },
+  "docs": {
+    "tool": "storybook",
+    "format": "both"
+  },
+  "ai": {
+    "active": "claude",
+    "providers": {
+      "claude": {
+        "model": "claude-sonnet-4-6",
+        "accessTokenEnv": "ANTHROPIC_API_KEY"
+      }
+    }
+  }
+}
+```
+
+**`designTool.accessTokenEnv`** stores the name of the env var, never the token itself. PTB validates that this value is `SCREAMING_SNAKE_CASE` on startup.
+
+---
+
+## AI setup
+
+```bash
+ptb ai setup        # interactive: choose provider, set env var name, pick model
+ptb ai list         # show all configured providers
+ptb ai use claude   # switch active provider
+ptb ai model        # change model for active provider
+```
+
+Supported providers: **Claude** (Anthropic), **OpenAI**. Local models via OpenAI-compatible `baseUrl` are also supported.
+
+PTB uses fuzzy matching during `ptb ai setup` — if you mistype a provider name (e.g. `opneai`), it suggests the closest known provider before proceeding.
+
+```bash
+# Claude
+export ANTHROPIC_API_KEY=sk-ant-...
+ptb ai setup   # choose "claude"
+
+# OpenAI
+export OPENAI_API_KEY=sk-...
+ptb ai setup   # choose "openai"
+```
+
+---
+
+## Implementing components with AI
+
+`ptb implement component <name>` sends a rich context package to your configured AI provider and writes the component files. **The quality of the output depends entirely on the model you use.**
+
+### Recommended models
+
+For best results use a top-tier coding model:
+
+| Provider | Recommended model |
+|---|---|
+| Anthropic | `claude-opus-4-7` or `claude-sonnet-4-6` |
+| OpenAI | `gpt-4o` or `o3` |
+
+Weaker models (GPT-3.5, smaller Ollama models) will produce code that compiles but misses design intent — wrong spacing, ignored variants, missing accessibility attributes.
+
+```bash
+ptb ai setup          # set your provider and model
+ptb ai model          # change model at any time
+```
+
+### Alternative: use any AI IDE with PTB context files
+
+`ptb implement` is useful for batch generation. For interactive development, you can skip it entirely and use PTB's context files directly in any AI IDE — Claude Code, Cursor, Copilot, or any other.
+
+PTB already extracts and normalizes everything from Figma into structured JSON. Your AI IDE doesn't need a live Figma connection — the context files have everything: variant axes, token bindings, state contracts, layout, render trees, and interaction contracts.
+
+**Workflow:**
+1. Run `ptb export context` after each scan
+2. Run `ptb document system` to generate `AI.md` at your package root — most AI IDEs pick this up automatically
+3. Use `ptb prompt component <name>` to get a structured prompt for a specific component
+4. Open your AI IDE and point it at `.ptb/context/<component>.json` or paste the prompt
+5. Let the AI write the component — it has full design intent without needing Figma access
+
+This gives you more control, lets you iterate interactively, and works with whatever AI IDE you already use.
+
+---
+
+## Team workflow
+
+PTB tracks design-to-implementation freshness through a committed `ptb.lock` file. No server required.
+
+### Setup
+
+```bash
+ptb init          # scaffolds project, registers you as lead, creates ptb.lock
+ptb join          # teammates register themselves (they join as members)
+git add ptb.lock ptb-team.json
+```
+
+### Roles
+
+Every team member has a role: **lead** or **member**.
+
+- The person who runs `ptb init` is automatically the **lead**.
+- The first person to run `ptb join` on a fresh roster also becomes a **lead** automatically — this prevents the deadlock where the only member can't promote themselves (only leads can change roles).
+- All subsequent `ptb join` calls give the **member** role.
+- Leads can assign components to anyone, reassign, and stamp any component.
+- Members can only self-assign and stamp components assigned to them.
+- The last lead cannot be demoted — PTB blocks the operation until another lead is promoted first.
+
+```bash
+ptb team                          # show roster with roles
+ptb team role @alice lead         # promote alice to lead (leads only)
+ptb team role @bob member         # demote to member (leads only, can't remove last lead)
+```
+
+### Assigning work
+
+```bash
+ptb assign Button                  # self-assign Button to yourself
+ptb assign Button @alice           # assign to alice (leads only)
+ptb assign . @alice                # assign all unimplemented to alice (leads only)
+ptb assign Button --clear          # unassign (members can only clear their own)
+ptb status --team                  # view workload by assignee
+ptb status --mine                  # view only your assignments
+```
+
+### Stamping implementations
+
+When a developer finishes implementing a component against the current design:
+
+```bash
+ptb stamp component Button
+ptb stamp component Button -m "implemented with new focus ring per design v2"
+```
+
+Members can only stamp components assigned to them. Leads can stamp anything.
+
+This writes the current `designHash` into `ptb.lock` as `stampedHash`. When `ptb status` sees they match, the component is **ready**. When Figma changes and PTB re-scans, `designHash` updates but `stampedHash` stays — making the component **stale**.
+
+### Viewing history
+
+```bash
+ptb log            # show design changes and stamps from git history
+ptb diff           # show unstamped design changes since last scan
+```
+
+---
+
+## CI integration
+
+```bash
+ptb ci setup      # leads only
+```
+
+Generates `.github/workflows/ptb.yml` — a GitHub Actions workflow that runs `ptb status --fail-on-stale` on every push and PR. Blocks merges when components are stale.
+
+```bash
+git add .github/workflows/ptb.yml
+git commit -m "ci: add PTB design freshness check"
+```
+
+For CI to work without a Figma token, commit your context files after each scan:
+
+```bash
+ptb export context
+git add .ptb/context/ ptb.lock
+git commit -m "chore: update design system context"
+```
+
+---
+
+## Documentation
+
+### Component docs
+
+```bash
+ptb document component Button          # single component
+ptb document component .               # all components
+ptb document component Button --force  # overwrite existing
+ptb document component Button --no-ai  # skip AI prose, deterministic tables only
+```
+
+On first run, PTB asks two one-time questions and saves the answers to `ptb.config.json` — they won't be asked again:
+- **Documentation tool**: Storybook, Docusaurus, or plain MDX
+- **Format** (Storybook only): MDX doc only, Stories only, or Both
+
+Override the format per-run with `--format mdx|stories|both`.
+
+For Storybook, PTB detects whether Storybook is installed (monorepo-aware — correctly handles hoisted `node_modules`) and offers to run the setup steps for you. After `storybook init`, PTB automatically removes Storybook's example `src/stories/` scaffold so it doesn't pollute your component directory.
+
+### System documentation
+
+```bash
+ptb document system
+```
+
+Generates two files at your component library root:
+
+- **`AI.md`** — design system intent map for AI coding assistants (Claude Code, Cursor, Copilot)
+- **`components.md`** — human-readable component inventory with import paths and descriptions
+
+---
+
+## Context and prompts
+
+```bash
+ptb export context                    # export all component context to .ptb/context/
+ptb context component Button          # display rich context in terminal
+ptb context component Button --json   # machine-readable JSON
+ptb prompt component Button           # print AI implementation prompt
+ptb prompt component . --format json  # write all prompts to .ptb/prompts/
+```
+
+Context files in `.ptb/context/` are designed to be committed and read by AI tools. They contain the full component model: variant axes, token bindings, state contracts, layout, render tree, and interaction contracts.
+
+---
+
+## Health checks
+
+```bash
+ptb doctor                       # system check: config, token, snapshot age, component health
+ptb doctor component Button      # deep audit: 10-point score for one component
+ptb doctor component .           # scorecard table for all components
+ptb doctor tokens                # token resolution coverage
+ptb doctor context Button        # AI context quality score
+```
+
+The doctor checks whether your Figma components have the data PTB needs to generate high-quality code: Auto Layout, token bindings, variant axes, state contracts, render trees, and descriptions.
+
+A low doctor score means your generated code will be less accurate. Fix the issues in Figma, re-scan, and the score improves.
+
+---
+
+## Getting help
+
+```bash
+ptb --help                  # full command list
+ptb <command> --help        # flags and options for one command
+ptb guide                   # list all topic guides
+ptb guide <topic>           # focused reference for a feature area
+```
+
+Available topics: `setup` · `context` · `implement` · `document` · `status` · `team` · `ai` · `doctor` · `ci`
+
+---
+
+## Command reference
+
+### Setup & scanning
+
+| Command | What it does |
+|---|---|
+| `ptb init` | Initialize PTB, scaffold fresh repos, write config |
+| `ptb scan` | Fetch Figma file, save snapshot, export context |
+| `ptb generate-components [name]` | Scaffold typed component shells |
+| `ptb generate-tokens` | Scaffold CSS token files |
+| `ptb import-tokens <path>` | Import a Calibrate token export |
+
+### Context & prompts
+
+| Command | What it does |
+|---|---|
+| `ptb export context` | Export component context files for AI tools |
+| `ptb context component <name>` | Display rich component context |
+| `ptb prompt component <name>` | Print AI implementation prompt |
+
+### AI implementation
+
+| Command | What it does |
+|---|---|
+| `ptb implement component <name>` | AI-generate component implementation |
+| `ptb plan` | Show which files are affected by the latest diff |
+| `ptb apply` | Regenerate only the files affected by design changes |
+| `ptb prune` | Remove stale component folders no longer in Figma |
+
+### Documentation
+
+| Command | What it does |
+|---|---|
+| `ptb document component <name>` | Generate MDX docs and Storybook stories |
+| `ptb document system` | Generate AI.md and components.md |
+
+### Status & tracking
+
+| Command | What it does |
+|---|---|
+| `ptb status` | Check implementation freshness |
+| `ptb diff` | Show unstamped design changes since last scan |
+| `ptb log` | Show design change and stamp history |
+| `ptb stamp component <name>` | Mark a component as implemented |
+| `ptb assign <name> [person]` | Assign a component to a developer |
+
+### Team
+
+| Command | What it does |
+|---|---|
+| `ptb join` | Register yourself in the team roster |
+| `ptb team` | Show team roster and workload |
+| `ptb team role <handle> <role>` | Promote or demote a team member (leads only) |
+
+### AI providers
+
+| Command | What it does |
+|---|---|
+| `ptb ai setup` | Configure AI provider |
+| `ptb ai list` | List saved providers and active one |
+| `ptb ai use <provider>` | Switch active provider |
+| `ptb ai model [id]` | Change model for active provider |
+
+### Health & CI
+
+| Command | What it does |
+|---|---|
+| `ptb doctor` | System and component health audit |
+| `ptb ci setup` | Generate GitHub Actions freshness workflow (leads only) |
+| `ptb remove` | Remove all PTB config and metadata from this project (leads only) |
+
+### Help & onboarding
+
+| Command | What it does |
+|---|---|
+| `ptb guide [topic]` | Focused workflow reference per feature area |
+| `ptb learn` | Interactive onboarding walkthrough |
+| `ptb flow direct` | Checklist for direct Figma API workflow |
+| `ptb flow plugin` | Checklist for Calibrate plugin workflow |
+
+---
+
+## What gets committed to git
+
+```
+ptb.config.json        # your PTB configuration
+ptb.lock               # design hash tracking — commit this
+ptb-team.json          # team roster — commit this
+.ptb/context/          # component context files — commit after ptb export context
+.ptb/manifest.json     # generated file tracking — commit this
+.github/workflows/     # CI workflow — commit this
+```
+
+```
+.ptb/latest.json       # gitignored — large Figma snapshot
+.ptb/history/          # gitignored — snapshot history
+*.ptb-meta.json        # gitignored — inline metadata
+```
+
+`ptb init` writes the correct `.gitignore` entries automatically. If you have an old project with `.ptb/` blanket-ignored, running `ptb export context` will migrate it.
+
+---
+
+## Supported frameworks
+
+| Framework | Scan & Track | Generate Components | Storybook |
+|---|---|---|---|
+| React | ✓ | ✓ | ✓ |
+| Vue 3 | ✓ | coming soon | ✓ (Vite) |
+| Svelte | ✓ | coming soon | ✓ (Vite) |
+| React Native | ✓ | coming soon | — |
+
+All frameworks support the full governance workflow (scan, diff, status, stamp, assign, CI) and documentation generation. Code generation is React-first for v1.
+
+---
+
+## Contributing
+
+See [PTB.md](./PTB.md) for architecture, type definitions, the generator interface, and internal conventions.
+
+```bash
+pnpm install
+pnpm build
+node apps/cli/dist/index.js --help
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calibrate-ds/cli",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,10 +22,10 @@
     "commander": "^14.0.3",
     "openai": "^6.34.0",
     "zod": "^4.3.6",
-    "@calibrate-ds/core": "0.1.0",
-    "@calibrate-ds/figma-client": "0.1.0",
-    "@calibrate-ds/shared-types": "0.1.0",
-    "@calibrate-ds/generator-react": "0.1.0"
+    "@calibrate-ds/core": "0.1.3",
+    "@calibrate-ds/generator-react": "0.1.3",
+    "@calibrate-ds/figma-client": "0.1.3",
+    "@calibrate-ds/shared-types": "0.1.3"
   },
   "devDependencies": {
     "@types/node": "^22.13.5",