@catchdrift/cli 0.1.17 → 0.1.19

package/commands/drift-context.md

@@ -0,0 +1,208 @@
+---
+description: "Show a full DS snapshot — registry, static coverage, recent gaps, and prioritized next actions. Run this first to orient before any session involving the design system."
+allowed-tools: Read, Glob, Grep, Bash
+argument-hint: "[quick | file <path> | --export]"
+---
+
+# /drift-context — Instant DS snapshot for your current session
+
+Gives you a complete picture of the design system state in one shot — no grepping,
+no file hunting. Run this at the start of any session to orient yourself before
+building, reviewing, or planning.
+
+Designed for every persona:
+- **PdMs/Designers** — "what components exist right now?"
+- **Developers joining a project** — "what's the DS state before I touch anything?"
+- **Code reviewers** — "what does drift look like for this file/feature?"
+- **AI tools** — load this context before scaffolding or fixing
+
+## Arguments: `$ARGUMENTS`
+- *(no args)* — full snapshot: registry + coverage + gaps + recent drift
+- `quick`     — registry only (component list, no coverage scan)
+- `file <path>` — DS coverage for a specific file only
+- `--export`  — output as markdown block suitable for pasting into a PRD, Jira ticket, or AI prompt
+
+---
+
+## Step 1 — Find the config
+
+Look for config in this order:
+1. `drift.config.ts` at project root
+2. `src/ds-coverage/config.ts`
+3. If neither exists, stop:
+   ```
+   No drift config found. Run /drift-setup to get started.
+   ```
+
+Read the config and extract:
+- Component registry (names, storyPaths, figmaLinks)
+- `storybookUrl` / `chromaticUrl`
+- `figmaFileKey`
+- `threshold`
+- `approvedGaps` (if any)
+
+---
+
+## Step 2 — Dispatch
+
+### No args → Full snapshot
+
+**A. Registry summary** (read from config — no network call needed)
+
+```
+## DS Context — <project name from package.json> — <date>
+
+### Component Registry (<N> components)
+| Component          | Story | Figma | Status        |
+|--------------------|-------|-------|---------------|
+| Button             | ✅    | ✅    | stable        |
+| Input              | ✅    | —     | needs figma   |
+| TenantsTable       | ✅    | ✅    | stable        |
+| ...                |       |       |               |
+
+Missing storyPaths: N  →  run /drift-sync storybook to fill
+Missing figmaLinks: N  →  run /drift-push gaps to fill
+
+Approved exceptions: N
+  • <ComponentName> — "<rationale>" (approved by <name>)
+```
+
+**B. Static coverage scan** (grep src/ — fast, no build needed)
+
+Glob all `.tsx` files in `src/` (excluding stories, tests, tokens, node_modules).
+For each file, count DS vs custom component usage.
+
+```
+### Coverage (static scan)
+Overall: XX% DS  (threshold: XX%)
+Status: ✅ PASS / 🔴 FAIL
+
+Top 5 files by custom usage:
+  src/features/dashboard/KPIRow.tsx     — 3 custom, 2 DS  (40%)
+  src/features/tenants/BulkActions.tsx  — 2 custom, 5 DS  (71%)
+  ...
+
+Top gaps (custom components not in DS):
+  CustomCard  — 8×   → no DS equivalent  (promote candidate)
+  IconBtn     — 5×   → use Button variant="ghost"
+  StatusPill  — 4×   → use Badge variant="status"
+```
+
+**C. Recent drift summary** (from git log — no build needed)
+
+```bash
+git log --oneline --since="7 days ago" -- "src/**/*.tsx"
+```
+
+Show files changed in the last 7 days, and for each, show whether DS coverage
+went up or down based on static diff (add/remove DS vs custom components).
+
+```
+### Recent changes (last 7 days)
+  src/features/payments/PaymentForm.tsx  — modified — DS coverage: stable
+  src/features/dashboard/NewWidget.tsx   — added    — 2 custom components (⚠️ check drift)
+```
+
+**D. Session recommendations**
+
+Based on the snapshot, output 1-3 prioritized actions:
+```
+### What to do next
+1. 🔴 CustomCard used 8× — biggest coverage win: /drift fix CustomCard
+2. ⚠️  src/features/dashboard/NewWidget.tsx added recently — run /drift file src/features/dashboard/NewWidget.tsx
+3. 📎  6 components missing figmaLinks — run /drift-push gaps
+```
+
+---
+
+### `quick` → Registry only
+
+Skip the coverage scan and git log. Just output the component table and approved gaps.
+Fast — reads only config.ts. Use this when you just need to know what's available.
+
+```
+## DS Components — <N> registered
+
+Primitives: Button, Input, Badge, Modal, Toast, Dropdown, Tabs, Icon
+Navigation: Navbar, Sidebar, Breadcrumb
+Patterns: TenantsTable, UnitDetailsCard, PaymentBanner, CommunicationsPanel, PinnedNotes
+
+Approved gaps (N): <list>
+Missing stories (N): <list>
+
+Storybook: <storybookUrl>
+Figma: https://figma.com/design/<figmaFileKey>
+```
+
+---
+
+### `file <path>` → Single-file coverage
+
+Read the specified file and classify every JSX component:
+
+```
+## Coverage: src/features/dashboard/NewWidget.tsx
+
+DS components (4):     Button, Badge, Tabs, Input
+Custom components (2): KPICard, TrendArrow
+
+Coverage: 67% (threshold: 80%) — 🔴 below threshold
+
+Gaps:
+  KPICard   — used 1× — no DS equivalent  → /drift promote KPICard
+  TrendArrow — used 1× — check Badge for icon variant  → /drift fix TrendArrow
+
+Token violations:
+  Line 34: color: '#3b82f6'  → use var(--ds-color-brand-500)
+```
+
+---
+
+### `--export` → Paste-ready block
+
+Formats the full snapshot as a clean markdown block for:
+- Pasting into a PRD / Linear issue (`/drift-prd` uses this internally)
+- Adding to a Jira ticket
+- Loading into an AI prompt as system context
+
+```markdown
+---
+drift-context: <project> — <date>
+threshold: XX%
+coverage: XX% (static)
+---
+
+## Design System: <N> components
+[component table]
+
+## Coverage snapshot
+[coverage summary]
+
+## Active gaps
+[gap list]
+
+## Approved exceptions
+[approved list]
+---
+```
+
+---
+
+## Performance notes
+
+- **No build required** — reads config and source files directly
+- **No network calls** in `quick` mode — instant
+- **Static scan only** — grep-based, not fiber-tree (for fiber-tree accuracy, run `/drift check`)
+- For large codebases (500+ files), the static scan may take a few seconds — this is expected
+- The `file <path>` mode is always instant regardless of codebase size
+
+## Why this exists
+
+Without this command, getting oriented in a new session requires:
+- Reading drift.config.ts manually
+- Grepping src/ for component usage
+- Running git log to see what changed
+- Cross-referencing all of it mentally
+
+`/drift-context` does all of that in one pass and surfaces the most important next action.
+It is designed to be the **first command you run** in any session involving the design system.

package/commands/drift-prd.md

@@ -0,0 +1,250 @@
+---
+description: "Generate a DS component inventory for a feature spec — which components exist, which are gaps, with Storybook/Figma links. Outputs a .drift-spec.md file for CI enforcement. Paste into Linear, Notion, Confluence, or GitHub Issues."
+allowed-tools: Read, Glob, Grep, Edit, Write
+argument-hint: "[\"<feature description>\"] [--format linear|notion|confluence|github] [--update <file>] [--spec-only]"
+disable-model-invocation: true
+---
+
+# /drift-prd — Generate a DS-aware component inventory + enforcement spec
+
+Takes a feature description or existing PRD draft and outputs:
+1. A structured component inventory (which DS components, which gaps, Figma/Storybook links)
+2. A `.drift-spec.md` file that CI can validate against the implementation
+
+Designed for PdMs and designers — no code knowledge required. The spec file is version-controlled
+and automatically checked in every PR. If a developer uses a custom component that wasn't declared,
+the PR gets a warning before merge.
+
+Output is formatted to paste directly into Linear, Notion, Confluence, or GitHub Issues.
+
+## Arguments: `$ARGUMENTS`
+- *(no args)* — interactive mode: asks for feature description, then generates inventory + spec
+- `"<feature description>"` — generate inventory + spec from inline description
+- `--format linear` — output optimized for Linear (default)
+- `--format notion` — output as Notion-pasteable table
+- `--format confluence` — output as Confluence wiki markup
+- `--format github` — output as GitHub-flavored markdown
+- `--update <file>` — read an existing PRD file and inject the component inventory section into it
+- `--spec-only` — only write the .drift-spec.md file, skip the human-readable inventory
+
+---
+
+## Step 1 — Read the DS registry
+
+Read `drift.config.ts` (or `src/ds-coverage/config.ts`) to get:
+- Every registered DS component, its story path, and Figma link
+- `storybookUrl` and `chromaticUrl` (for building story links)
+- `figmaFileKey` (for building Figma links)
+- Any `approvedGaps` with rationale (these count as available, with a note)
+
+If no config is found:
+```
+No drift.config.ts found. Run /drift-setup first to register your DS components.
+```
+
+---
+
+## Step 2 — Get the feature description
+
+### No args — interactive mode
+
+Ask in a single prompt (don't ping-pong):
+```
+Describe the feature or screen you're planning. Include:
+
+1. What is this screen/feature? (1-2 sentences)
+2. What are the main user actions? (e.g. "user can filter, sort, view details")
+3. What data is displayed? (e.g. "list of tenants, unit number, balance")
+4. Are there any modals, drawers, or overlays?
+5. Any existing screen in the app this is similar to?
+
+You can answer in plain English — no need to list components.
+```
+
+### With description argument — proceed immediately
+
+Use the provided description as input.
+
+---
+
+## Step 3 — Analyze and classify components
+
+Based on the feature description, identify the UI components needed:
+
+1. **Infer the component list** from the description using product + UI knowledge:
+   - Navigation elements (tabs, breadcrumbs, nav bars)
+   - Data display (tables, cards, lists, badges, charts)
+   - Actions (buttons, dropdowns, menus)
+   - Forms (inputs, selects, checkboxes, date pickers)
+   - Feedback (toasts, banners, modals, loading states)
+   - Layout (headers, sidebars, panels)
+
+2. **Classify each component** against the DS registry:
+   - **✅ In DS** — exact match in `config.components`
+   - **🔁 Partial match** — a DS component covers this with a variant (e.g., `Button` covers "icon button" via `variant="ghost"`)
+   - **⚠️ Gap** — no DS component covers this need
+   - **✅ Approved exception** — in `approvedGaps` with documented rationale
+
+3. **For gaps**, check if a DS component could be extended:
+   - If yes: flag as "extension candidate" with the base component name
+   - If no: flag as "new component needed" with suggested design request
+
+---
+
+## Step 4 — Generate the PRD component inventory
+
+Output in the requested format. Default (Linear):
+
+```markdown
+## Component Inventory
+
+> Auto-generated by Drift on <date>. Run `/drift-prd` to regenerate.
+
+### DS Components (ready to use)
+| Component | Variant/Usage | Storybook | Figma |
+|-----------|--------------|-----------|-------|
+| Button | Primary — "Save", "Cancel" actions | [Story](<url>) | [Figma](<url>) |
+| Input | Text — search bar, form fields | [Story](<url>) | [Figma](<url>) |
+| Modal | Confirmation dialog | [Story](<url>) | [Figma](<url>) |
+| TenantsTable | Main data table | [Story](<url>) | — |
+| Badge | Status indicators | [Story](<url>) | [Figma](<url>) |
+
+### Partial Matches (DS component covers this with a variant)
+| Component Needed | Use Instead | Notes |
+|-----------------|-------------|-------|
+| Icon button | `Button` variant="ghost" | Add icon prop — story: primitives-button--ghost |
+| Danger confirm | `Button` variant="danger" | Already in DS |
+
+### Design Gaps (need Figma spec before engineering starts)
+| Component Needed | Priority | Suggested Owner | Next Step |
+|-----------------|----------|-----------------|-----------|
+| DateRangePicker | High | Design team | Run `/drift-push request DateRangePicker "date range selector for filter panel"` |
+| StatusTimeline | Medium | Design team | Run `/drift-push request StatusTimeline "chronological status history"` |
+
+### DS Coverage Estimate
+- Components in DS: N / N total (~XX%)
+- Gaps requiring design: N
+- Estimated dev-ready after design: <date estimate not provided — ask design team>
+
+### Engineering Notes
+- All DS components are in Storybook at: <storybookUrl>
+- Token reference: src/tokens/variables.css
+- To scaffold this screen: run `/drift-scaffold "<feature name>"`
+- To check DS coverage after building: run `/drift check`
+```
+
+---
+
+## Step 5 — Handle gaps
+
+For each gap component, offer to create a design request:
+
+```
+Found N gap components that need Figma specs:
+  1. DateRangePicker — no DS equivalent
+  2. StatusTimeline  — no DS equivalent
+
+Create design requests in Figma for these? (yes/no/select)
+This will run /drift-push request for each gap and post briefs to your Figma proposals page.
+```
+
+If yes, run the `/drift-push request` flow for each gap component.
+
+---
+
+## Step 6 — Update an existing PRD file (`--update <file>`)
+
+If `--update` was passed with a file path:
+
+1. Read the file
+2. Look for an existing component inventory section (search for "Component Inventory" heading)
+3. If found: replace the section between `<!-- drift:prd-start -->` and `<!-- drift:prd-end -->` markers
+4. If not found: append the inventory at the end of the file
+5. Write the updated file
+6. Report: "Updated <file> — added component inventory with N components (N gaps)"
+
+---
+
+---
+
+## Step 7 — Write the .drift-spec.md file
+
+After generating the human-readable inventory, write a machine-readable spec file that CI
+can validate against the implementation.
+
+### File location
+Create `specs/<feature-slug>.drift-spec.md` in the project root's `specs/` directory.
+If `specs/` doesn't exist, create it.
+
+### Spec format
+
+```markdown
+---
+drift-spec: "1.0"
+screen: <ScreenName>
+feature: <feature-slug>
+owner: <ask or infer from git config>
+created: <today ISO date>
+updated: <today ISO date>
+intent: |
+  <1-2 sentence description of what the screen does>
+components:
+  required: [<comma-separated DS component names from inventory>]
+  optional: [<components that may or may not appear>]
+  gaps:
+    - name: <GapComponentName>
+      description: "<what it does>"
+      priority: high|normal|low
+      approved: false
+      figma-request: pending
+tokens-required:
+  - "--ds-color-danger-*"
+threshold: <from drift.config.ts — default 80>
+status: draft
+---
+
+## Feature: <ScreenName>
+
+<intent text>
+
+### User actions
+- <describe key user actions>
+
+### Screens in scope
+- <list screens this spec covers>
+```
+
+### Rules for the spec file
+- `required` = DS components the implementation MUST use. Missing any → CI warning.
+- `optional` = DS components that may appear depending on state/data. Not enforced.
+- `gaps[].approved: false` = unapproved custom component. CI flags this until approved.
+- `gaps[].approved: true` = explicitly approved exception with documented rationale.
+- `threshold` = minimum DS coverage %. Pulled from `drift.config.ts` if set.
+- `status` starts as `draft`. Designer/TL changes to `approved` before engineering starts.
+
+### After writing the spec
+
+Tell the user:
+```
+✅ Spec written: specs/<feature-slug>.drift-spec.md
+
+This file is now version-controlled. In every PR:
+  • catchdrift spec validate checks that required components are actually used
+  • Unapproved gaps trigger a warning in the PR comment
+  • Designers can approve gaps by changing approved: true in this file
+
+To validate now: catchdrift spec validate specs/<feature-slug>.drift-spec.md
+To approve a gap: change approved: false → approved: true + add rationale comment
+```
+
+---
+
+## Style notes
+
+- Always lead with DS components the team can use immediately — show the good news first
+- Frame gaps as "design requests" not "missing components" — it's a workflow step, not a failure
+- Include direct story links when `chromaticUrl` or `storybookUrl` is set — PdMs will use these to preview components
+- Never invent component names. If unsure whether a DS component covers a need, classify as a gap
+- Keep the table concise — this is a spec document, not a technical breakdown
+- If the feature description is vague, generate a best-effort inventory and note what was assumed
+- The spec file is the contract. The inventory table is the human-readable explanation of that contract.