@catchdrift/cli 0.1.18 → 0.1.19

package/commands/drift-sync.md

@@ -0,0 +1,229 @@
+---
+description: "Sync Figma and/or Storybook into drift.config.ts and regenerate CLAUDE.md, .cursorrules, and .windsurfrules. Run after adding new DS components or updating Figma."
+allowed-tools: Read, Glob, Grep, Bash, Edit, Write
+argument-hint: "[figma | storybook | tokens | status | --dry-run]"
+disable-model-invocation: true
+---
+
+# /drift-sync — Sync Figma + Storybook → update manifest
+
+Pull the latest component state from Figma and/or Storybook and keep
+`drift.config.ts`, `CLAUDE.md`, `.cursorrules`, and `.windsurfrules` in sync.
+Works with any product team — property management, SaaS, fintech, consumer, B2B.
+
+## Arguments: `$ARGUMENTS`
+- *(no args)* — sync from both Storybook and Figma, update all config files
+- `figma`     — pull component list from Figma only (all pages)
+- `storybook` — re-discover components from Storybook index only
+- `tokens`    — run figma-sync (design tokens + icons only, no component changes)
+- `status`    — report sync status without making changes (safe read-only audit)
+- `--dry-run` — show what would change without writing any files
+
+---
+
+## Step 1 — Read current state
+
+Read `drift.config.ts` (or `src/ds-coverage/config.ts`) to get:
+- **Figma source** — the config may use either shape:
+  - Single file: `figmaFileKey` + optional `figmaComponentPages` (one-file setup)
+  - Multi-file: `figmaFiles: [{ key: string, componentPages?: string[] }, ...]` (components spread across multiple Figma files, e.g. Core DS, Icons, Patterns)
+  - Normalise both into a working array: `const files = config.figmaFiles ?? (config.figmaFileKey ? [{ key: config.figmaFileKey, componentPages: config.figmaComponentPages }] : [])`
+- `storybookUrl`
+- `components` — the current registry (component name → storyPath / figmaLink)
+- `threshold`
+- Any `approvedGaps` entries
+
+**Component pages** are an inclusive filter — only pull components from these pages. If `componentPages` is not set for a file, include all pages (and flag any page whose name contains "wip", "in progress", "draft", "proposal", "graveyard", or "archive" as potentially unready so the team can review them).
+
+---
+
+## Step 2 — Dispatch
+
+### `status` → Read-only audit
+
+Report sync status across all sources without changing anything:
+
+```
+## Drift Sync Status — <date>
+
+Storybook: <storybookUrl>
+  Last successful sync: <date if known, else "unknown">
+  Reachable: ✅ / ❌
+
+Figma files: <N> configured
+  figma.com/design/<key1>  Reachable: ✅ / ❌
+  figma.com/design/<key2>  Reachable: ✅ / ❌   (if multi-file)
+  FIGMA_API_TOKEN: ✅ set / ❌ missing
+
+Config: drift.config.ts
+  Components registered: N
+  Missing storyPath: N
+  Missing figmaLink: N
+  Approved gaps: N
+
+AI rules files:
+  CLAUDE.md: ✅ / ❌ (stale — last component: <X>)
+  .cursorrules: ✅ / ❌
+  .windsurfrules: ✅ / ❌
+```
+
+---
+
+### `tokens` or no args → sync tokens from Figma
+
+Run:
+```bash
+npm run figma-sync
+```
+
+Requires `FIGMA_API_TOKEN`. If missing:
+```
+export FIGMA_API_TOKEN=your-token
+npm run figma-sync
+
+Get token: figma.com → Profile → Settings → Security → Personal access tokens
+```
+
+After running, report which token categories updated (colors added/changed, typography changes, spacing changes).
+
+---
+
+### `storybook` or no args → re-discover from Storybook
+
+Fetch `{storybookUrl}/index.json`. The response has a flat map of all stories
+across all story files. Parse it to get unique component names and story paths.
+
+If Storybook isn't reachable, try the deployed URL (`chromaticUrl`) from config. If
+neither is reachable, report:
+```
+⚠️  Storybook not reachable at <url>
+Run `npm run storybook` first, or provide your deployed Storybook URL in drift.config.ts:
+  chromaticUrl: 'https://main--abc123.chromatic.com'
+```
+
+Compare against `config.components` and report:
+
+```
+## Storybook sync
+
+New (in Storybook, not in config):
+  + DataTable    → story: data-table--default
+  + FilterBar    → story: filters-filter-bar--default
+
+Removed (in config, no matching story):
+  - OldWidget
+
+Unchanged: 34 components
+```
+
+Ask for each new/removed component before changing config. For removed components,
+ask whether to delete from config or keep with a `deprecated: true` flag.
+
+---
+
+### `figma` or no args → pull all published components from Figma
+
+**Key:** Figma components live on different pages. Use the dedicated
+`/components` endpoint — it returns ALL published components across ALL pages
+with page metadata included. Do NOT try to walk the file tree page by page.
+
+Iterate over every file in the normalised `files` array (see Step 1). For each:
+```
+GET https://api.figma.com/v1/files/{file.key}/components
+Headers: X-Figma-Token: {FIGMA_API_TOKEN}
+```
+
+Each component in the response has:
+- `name` — full path e.g. `"Button/Primary/Default"` or `"Forms/Input/Filled"`
+- `node_id` — unique ID for building the figmaLink URL
+- `containing_frame.name` — the frame it lives in
+- `containing_frame.pageName` — **the Figma page it's on**
+- `description` — designer's notes (preserve this — use as component description in config)
+
+Group and display results by file, then by page within each file. If multiple files are configured, prefix each section with the file key/URL so it's clear which file the components come from:
+```
+## Figma components found
+
+### figma.com/design/<key1>  (Core DS)
+📄 Primitives (12 components)
+  ✅ Button         → in config
+  ✅ Input          → in config
+  ❌ Toggle         → NOT in config  (node: 123:456)
+  ❌ Checkbox       → NOT in config  (node: 123:789)
+
+📄 🚧 In Progress (3 components)
+  ⚠️  SearchBar     → draft (will not be added)
+  ⚠️  FilterChip    → draft (will not be added)
+
+### figma.com/design/<key2>  (Icons & Patterns)
+📄 Patterns (8 components)
+  ✅ TenantsTable   → in config
+  ❌ DataGrid       → NOT in config  (node: 456:123)
+```
+
+For each file, apply the `componentPages` filter:
+- If `componentPages` is set: only include components from those pages; skip everything else
+- If not set: include all pages, but flag any page matching "wip/draft/graveyard/archive/proposal" in a separate "Unreviewed pages" section so the team can decide whether to add them
+
+For each component NOT in config (excluding draft pages), ask:
+```
+Add these to drift.config.ts?
+  - Toggle   (key1 / Primitives page)
+  - Checkbox (key1 / Primitives page)
+  - DataGrid (key2 / Patterns page)
+
+For each, I'll also add the figmaLink pointing to that node.
+Reply with which ones to add, or "all" / "none".
+```
+
+When adding, build the figmaLink URL using the file key that component came from:
+```
+https://www.figma.com/design/{file.key}?node-id={node_id}
+```
+
+Also report components in the codebase (from static scan of `src/`) that exist
+in Storybook but have NO matching Figma component — these are code-first gaps:
+```
+In code but not in Figma (consider pushing to Figma):
+  ⚡ OccupancyWidget  — used 1× — run /drift-push OccupancyWidget to add
+  ⚡ FMKPIRow         — used 1×
+```
+
+---
+
+## Step 3 — Update files
+
+After confirmation (or immediately if `--dry-run` was NOT passed), update:
+
+1. **`drift.config.ts`** — add components with storyPath + figmaLink where available; mark removed with `deprecated: true` rather than deleting (preserves history)
+2. **`CLAUDE.md`** — regenerate only the components table (preserve all other content — rules, workflow, etc.)
+3. **`.cursorrules`** — same regeneration (Cursor reads this automatically)
+4. **`.windsurfrules`** — same regeneration (Windsurf reads this automatically); create if it doesn't exist
+
+For AI rules files, regenerate ONLY the component table section, bounded by these markers:
+```
+<!-- drift:components-start -->
+...
+<!-- drift:components-end -->
+```
+If markers don't exist, append the table at the end of the file.
+
+Report:
+```
+## Sync complete — <date>
+
+drift.config.ts   — +3 added, 0 deprecated (37 total)
+CLAUDE.md         — components table updated (37 components)
+.cursorrules      — components table updated
+.windsurfrules    — created (37 components)
+
+New figmaLinks added: Toggle, Checkbox, DataGrid
+New storyPaths added: DataTable, FilterBar
+
+Storybook links: 37/37 ✅
+Figma links: 31/37 (6 missing — run /drift-push gaps to add them)
+
+Next: npm run dev and press D to see the updated overlay.
+```
+
+If `--dry-run` was passed, show what would change without writing anything.

package/commands/drift.md

@@ -0,0 +1,252 @@
+---
+description: "Analyze DS coverage across the codebase. Find gaps, suggest DS replacements, migrate components, approve exceptions, promote candidates. Sub-commands: fix, approve, promote, manifest, check, history, audit."
+allowed-tools: Read, Glob, Grep, Bash, Edit
+argument-hint: "[fix <ComponentName> | approve <Name> \"<reason>\" | promote <Name> | manifest | check | history | audit]"
+---
+
+# /drift — Design System Drift Analyzer
+
+Analyze design system coverage for this codebase. Identify components that drift from
+the DS, suggest replacements, and optionally migrate code. Works with any React
+product team — property management, SaaS, fintech, e-commerce, etc.
+
+## Arguments: `$ARGUMENTS`
+
+Supported sub-commands:
+- *(no args)* — full coverage report + top gap analysis
+- `fix <ComponentName>` — migrate one custom component to its DS equivalent
+- `approve <ComponentName> "<rationale>"` — approve a gap with documented rationale
+- `promote <ComponentName>` — flag a high-frequency custom component for DS promotion
+- `manifest` — print the DS component registry with story + Figma links
+- `check` — run the headless drift-check script and parse results
+- `history` — show coverage trend over last N scans (from saved reports)
+- `audit` — full audit mode: coverage + token violations + rationale gaps + promotion candidates
+
+---
+
+## Step 1 — Read the DS registry
+
+Read `src/ds-coverage/config.ts` (or `drift.config.ts` at project root) to understand:
+- Every registered DS component, its story path, and Figma link
+- `threshold` — the CI pass/fail threshold
+- `storybookUrl` and `figmaFileKey`
+
+---
+
+## Step 2 — Dispatch on $ARGUMENTS
+
+### No arguments → Full Coverage Report
+
+1. Glob `src/**/*.tsx` (excluding `src/stories/`, `src/tokens/`, `node_modules/`, `*.stories.*`, `*.test.*`, `*.spec.*`) to find all screens, views, and feature files.
+2. Grep each file for JSX component usage. Classify every component as:
+   - **DS** — name is in `config.components`
+   - **Approved gap** — custom, but has an approval entry (check for `// drift-approved:` comment or approval record)
+   - **Custom** — name is not in `config.components` and not approved
+3. Compute per-file and overall DS coverage %.
+4. List the top custom components by frequency (the gap map).
+5. For any custom component used ≥ 3 times:
+   - Check whether a DS equivalent exists → suggest it
+   - If used ≥ 5 times → flag as **promotion candidate**
+6. Print a report in this format:
+
+```
+## Drift Report — <date>
+
+Overall DS coverage: XX% (threshold: XX%)
+Status: ✅ PASS  or  🔴 FAIL
+
+### By file
+| File | DS | Custom | Approved | Coverage |
+|------|----|--------|----------|----------|
+| ...  | .. | ...    | ...      | ...%     |
+
+### Top gaps (custom components not in DS)
+| Component | Uses | Status | Suggested DS replacement |
+|-----------|------|--------|--------------------------|
+| BtnGrp    | 6    | ⚠️ Gap  | Use `<Tabs>` (segmented variant) |
+| LinkBtn   | 5    | 🔁 Promote candidate | Use `<Button variant="ghost">` |
+| AvatarRow | 3    | ✅ Approved — "needed for nav micro-interaction" | — |
+
+### Token violations
+| File | Violation | Line |
+|------|-----------|------|
+| ... | Hardcoded `#3b82f6` — use `var(--ds-color-brand-500)` | 42 |
+
+### Promotion candidates (used ≥5× with no DS equivalent)
+These components appear frequently enough to justify adding to the DS:
+1. <ComponentName> — used N× across N files
+   → Run `/drift promote <ComponentName>` to create a promotion request
+
+### Recommendations
+1. Highest impact: migrate <X> → saves N% coverage across N files
+2. ...
+```
+
+---
+
+### `fix <ComponentName>`
+
+1. Find all usages of `<ComponentName>` across `src/` (excluding stories and tests).
+2. Read the DS equivalent component file to understand its props API.
+3. For each usage, generate a code diff that replaces the custom component with the DS component, preserving existing behavior.
+4. Show a summary first:
+   ```
+   Found 6 usages of <ComponentName> across 3 files.
+   DS equivalent: <DSName> — props mapping:
+     old.size="large"  → new.size="lg"
+     old.color="red"   → new.variant="danger"
+
+   Estimated coverage improvement: +2.3%
+
+   Apply changes? (yes/no/preview)
+   ```
+5. After applying, re-run coverage calculation and show before/after.
+
+---
+
+### `approve <ComponentName> "<rationale>"`
+
+Approve a custom component as an intentional exception to DS coverage rules.
+
+Use this when a custom component is genuinely needed and cannot be replaced by a DS component. Rationale must include:
+- Why no DS component covers this need
+- Whether it should be proposed for DS inclusion in the future
+
+1. Verify the component is actually used in the codebase.
+2. Check it's not already approved.
+3. Add an approval entry to `drift.config.ts`:
+   ```ts
+   approvedGaps: {
+     '<ComponentName>': {
+       rationale: '<rationale>',
+       approvedBy: '<ask for name>',
+       approvedAt: '<today ISO date>',
+       promoteToDS: true/false,  // ask: "Should this be proposed for DS inclusion?"
+     }
+   }
+   ```
+4. Also add an inline comment convention to the usage site so rationale travels with the code:
+   ```tsx
+   {/* drift:ignore reason="<rationale>" approvedBy="<name>" */}
+   <ComponentName ... />
+   ```
+   This is visible in code review without needing to cross-reference config.
+5. Confirm: "Approved. This component will show as ✅ Approved in drift reports and will not count against coverage."
+
+---
+
+### `promote <ComponentName>`
+
+Flag a high-frequency custom component as a DS promotion candidate.
+
+1. Read the component file (or search for it if it's a one-off inline component).
+2. Count its usage frequency and list the files it appears in.
+3. Generate a promotion brief:
+   ```
+   ## DS Promotion Request: <ComponentName>
+
+   **Usage:** N× across N files
+   **Files:** list up to 5 most common locations
+
+   **Props API (current):**
+   <extracted interface or inferred from usage>
+
+   **Suggested DS entry:**
+   <ComponentName>: {
+     storyPath: '<suggested-story-path>',
+   }
+
+   **Design request:** This component appears frequently enough to warrant a
+   Figma design + DS review. Recommend filing a design request.
+
+   Next steps:
+   1. Designer creates the spec in Figma
+   2. Run /drift-push <ComponentName> to attach implementation notes
+   3. After Figma review, run /drift-sync to register it officially
+   ```
+4. Ask if user wants to open a Jira ticket (if `jiraBaseUrl` is configured).
+
+---
+
+### `manifest`
+
+Print a formatted table of all DS components from `config.components`:
+
+```
+## DS Component Registry — <date>
+
+| Component          | Story | Figma | Status |
+|--------------------|-------|-------|--------|
+| Button             | ✅    | ✅    | Stable |
+| Tabs               | ✅    | —     | Needs Figma |
+| ...                | ...   | ...   | ...    |
+
+Approved gaps (N):
+| Component    | Rationale | Approved by |
+|--------------|-----------|-------------|
+| CustomHeader | "..." | Michelle, 2026-01-15 |
+
+Missing story paths: X components
+Missing Figma links: X components
+Run /drift-sync to fill gaps automatically.
+```
+
+---
+
+### `check`
+
+Run the headless drift check and parse results:
+
+```bash
+npm run build && npx vite preview --port 4173 &
+npx wait-on http://localhost:4173 --timeout 30000
+node scripts/drift-check.mjs --url http://localhost:4173 --json > /tmp/drift-report.json
+```
+
+Then read `/tmp/drift-report.json` and print the full report format including:
+- Coverage % vs threshold
+- Per-route breakdown
+- Token violations (hardcoded colors, spacing)
+- Gap map with promotion candidates
+
+---
+
+### `history`
+
+Read any saved `drift-report-*.json` files or GitHub Actions artifacts from `.github/`.
+Show coverage trend:
+
+```
+## Coverage History
+
+Date         Coverage   Delta    Status
+2026-03-30   78%        +2%      🔴 Below threshold
+2026-03-23   76%        +1%      🔴 Below threshold
+2026-03-16   75%        —        🔴 Below threshold
+
+Trend: ↑ improving (+3% over 3 weeks)
+At current rate, threshold (80%) reached in ~2 weeks.
+```
+
+---
+
+### `audit`
+
+Full audit combining all modes:
+1. Run `check` (headless scan)
+2. Run the static analysis (no-args path)
+3. Cross-reference: flag any component approved as a gap that now has a DS equivalent
+4. List components that have been custom for ≥ 30 days (from git log if available)
+5. Output a single comprehensive report suitable for a DS quarterly review
+
+---
+
+## Style rules for output
+
+- Lead with the numbers — coverage %, counts, file names
+- Use exact component names from the codebase (case-sensitive)
+- When suggesting a DS replacement, always show a before/after code snippet
+- If coverage is below threshold, surface the 3 highest-impact gaps first with estimated improvement per fix
+- Never suggest creating new components — only DS components from `config.components`
+- For teams unfamiliar with the DS, always explain *why* a replacement is better, not just *what* to use
+- Approved gaps always show ✅ and are excluded from failure calculations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catchdrift/cli",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "CLI for Drift — install, check, and manage design system coverage for any React app.",
   "keywords": [
     "design-system",
@@ -31,6 +31,7 @@
     "bin",
     "src",
     "scripts",
+    "commands",
     "LICENSE",
     "README.md"
   ],

package/src/commands/init.mjs

@@ -32,6 +32,7 @@ import {
 import {
   writeDriftConfig,
   writeAIRulesFiles,
+  writeClaudeSkills,
   patchAppEntry,
   writeGithubAction,
 } from '../lib/writers.mjs'
@@ -349,7 +350,8 @@ export async function init(argv) {
     storybookUrl: storybookUrl || '',
     figmaFiles:   figmaFiles.length ? figmaFiles : undefined,
   })
-  spinner.stop(`Written: ${rulesFiles.join(', ')}`)
+  const skillFiles = writeClaudeSkills(cwd)
+  spinner.stop(`Written: ${rulesFiles.join(', ')}${skillFiles.length ? ` + ${skillFiles.length} Claude skills` : ''}`)
 
   // ── Step 8: Install @catchdrift/overlay ──────────────────────────────────────
   const pkgJson = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'))
@@ -417,6 +419,7 @@ export async function init(argv) {
 ${pc.bold('What was created:')}
   drift.config.ts                    ${pc.dim('DS component registry')}
   ${rulesFiles.map(f => f.padEnd(34)).join('\n  ')}${pc.dim('AI constraints')}
+  ${skillFiles.length ? `.claude/commands/               ${pc.dim('Claude Code skills (/drift-sync, /drift-scaffold, etc.)')}` : ''}
   ${addCI ? '.github/workflows/drift-check.yml  ' + pc.dim('CI drift check on every PR') : ''}
   ${patched ? patched.padEnd(34) + pc.dim('DriftOverlay added (dev-only)') : ''}
 

package/src/lib/writers.mjs

@@ -3,11 +3,14 @@
  * All writers are idempotent — safe to re-run.
  */
 
-import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'fs'
+import { writeFileSync, readFileSync, existsSync, mkdirSync, readdirSync } from 'fs'
 import { resolve, join, dirname, relative, posix } from 'path'
+import { fileURLToPath } from 'url'
 import { buildComponentRegistry } from './storybook.mjs'
 import { findAppEntry } from './detect.mjs'
 
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
 // ── drift.config.ts ───────────────────────────────────────────────────────────
 
 export function writeDriftConfig(cwd, { storybookUrl, chromaticUrl, figmaFiles, dsPackages, threshold, components }) {
@@ -327,3 +330,26 @@ jobs:
 
   writeFileSync(filepath, yaml, 'utf8')
 }
+
+// ── Claude Code skill files ───────────────────────────────────────────────────
+
+export function writeClaudeSkills(cwd) {
+  // Skills ship with the CLI package under commands/
+  const skillsSource = resolve(__dirname, '../../commands')
+  if (!existsSync(skillsSource)) return []
+
+  const destDir = join(cwd, '.claude', 'commands')
+  mkdirSync(destDir, { recursive: true })
+
+  const written = []
+  for (const file of readdirSync(skillsSource)) {
+    if (!file.endsWith('.md')) continue
+    const dest = join(destDir, file)
+    // Don't overwrite files the user may have customised
+    if (!existsSync(dest)) {
+      writeFileSync(dest, readFileSync(join(skillsSource, file), 'utf8'), 'utf8')
+      written.push(file)
+    }
+  }
+  return written
+}