@hustle-together/api-dev-tools 3.9.2 → 3.10.0

package/README.md

@@ -1,4 +1,4 @@
-# Hustle Development Tools for Claude Code v3.9.2
+# Hustle Development Tools for Claude Code v3.10.0
 
 **Interview-driven, research-first API and UI development with 100% phase enforcement**
 
@@ -20,13 +20,13 @@ npx @hustle-together/api-dev-tools --with-sandpack --with-storybook
 ```
 
 **What Gets Installed:**
-- 10 Hustle slash commands (API + UI + Combine)
-- 34 enforcement hooks (Python scripts)
+- 11 Hustle slash commands (API + UI + Page + Combine)
+- 38 enforcement hooks (Python scripts)
 - Multi-element state tracking (`api-dev-state.json`)
 - **Central registry** (`registry.json`) - tracks all APIs, components, pages
 - **Brand guide** (`BRAND_GUIDE.md`) - default branding template
-- **Showcase pages** - `/dev-tools`, `/api-showcase`, `/ui-showcase` *(NEW)*
-- **Component/Page templates** - Storybook stories, Playwright E2E tests *(NEW)*
+- **Showcase pages** - `/dev-tools`, `/api-showcase`, `/ui-showcase`
+- **Component/Page templates** - Storybook stories, Playwright E2E tests
 - Research cache with 7-day freshness (`research/`)
 - Session logging (`api-sessions/`)
 - MCP server integrations (Context7, GitHub)
@@ -34,8 +34,60 @@ npx @hustle-together/api-dev-tools --with-sandpack --with-storybook
 **Start Your First Workflow:**
 ```bash
 /hustle-api-create my-endpoint     # For APIs
-/hustle-ui-create                  # For UI components/pages (NEW)
-```
+/hustle-ui-create                  # For UI components
+/hustle-ui-create-page             # For Next.js pages (NEW in v3.10)
+/hustle-combine                    # For API orchestration
+```
+
+## What's New in v3.10.0
+
+### UI Page Mode Complete
+Full `/hustle-ui-create-page` workflow with dedicated documentation and hooks:
+- **Page Types**: landing, dashboard, form, list, detail, auth
+- **Page-Specific Hooks**: `check-api-routes.py`, `enforce-page-components.py`, `enforce-page-data-schema.py`
+- **Playwright E2E**: Full test suite generation with 15+ test cases
+- **Data Schema Validation**: Ensures API response types defined before implementation
+
+### Combine Workflow Completion
+Enhanced API orchestration with validation:
+- **2+ API Selection**: Validation that at least 2 APIs are selected
+- **Flow Types**: sequential, parallel, conditional orchestration patterns
+- **Orchestration Examples**: Auto-generated curl examples for combined endpoints
+- **Registry Verification**: Checks all source APIs exist before orchestration
+
+### Accessibility Automation
+New `enforce-a11y-audit.py` hook:
+- Triggers after TDD Green phase for UI workflows
+- WCAG 2.1 Level AA/AAA checklist injection
+- axe-core command generation for Storybook and pages
+- 4-step verification reminder (Responsive, Data, Tests, A11y)
+
+### Brand Color Validation
+Enhanced `enforce-brand-guide.py`:
+- Extracts allowed colors from BRAND_GUIDE.md
+- Validates hex colors, Tailwind classes, CSS variables
+- Notifies on non-brand color usage
+- Supports common utility colors (primary, secondary, accent, etc.)
+
+### UI Showcase Auto-Population
+`update-ui-showcase.py` now generates `data.json` from registry:
+- Components: id, name, type, path, storybook_url, variants, props
+- Pages: id, name, route, page_type, data_sources, requires_auth
+- Automatic refresh on each UI workflow completion
+
+### Enhanced State Template
+`api-dev-state.json` now includes:
+- `workflow` field: api-create, combine-api, ui-create-component, ui-create-page
+- `combine_config`: source_elements, flow_type, error_strategy, orchestration
+- `ui_config`: mode, component_type, page_type, accessibility_level, data_sources
+
+### Session Startup Context
+`session-startup.py` now shows workflow-specific context:
+- Combine workflows: source APIs, flow type, error strategy
+- UI workflows: brand guide status, component/page type, a11y level
+- Workflow-specific reminders and key files
+
+---
 
 ## What's New in v3.9.2
 
@@ -4646,40 +4698,106 @@ npx @hustle-together/api-dev-tools --scope=project
 
 ### Optional Development Tools
 
-After running the installer, you may want to set up additional development tools:
+The following tools enhance UI development but are **optional**. You can install them:
+1. **During NPX install** - Using `--with-*` flags (see below)
+2. **During UI workflow** - Hooks will prompt when needed
 
-**Storybook (Component Development)**
+#### Installation Methods
+
+**Option 1: Install with NPX Flags**
 ```bash
-npx storybook@latest init
+# Install all optional tools at once
+npx @hustle-together/api-dev-tools --with-storybook --with-playwright --with-sandpack
+
+# Or selectively
+npx @hustle-together/api-dev-tools --with-storybook
 ```
+
+**Option 2: Install During UI Workflow**
+When you run `/hustle-ui-create` without the required tools:
+1. The hook **blocks** writing test/story files
+2. You see the exact install command needed
+3. Claude offers to run the install for you
+4. After installing, the workflow continues automatically
+
+This "just-in-time" installation means you only install what you actually need.
+
+---
+
+#### Tool Details
+
+**Storybook (Component Development)**
+| Property | Value |
+|----------|-------|
+| Size | ~50MB |
+| Purpose | Visual component testing, interactive docs |
+| Required for | `/hustle-ui-create` (component mode) |
+| Without it | Cannot write `.stories.tsx` files |
+| Install flag | `--with-storybook` |
+| Manual command | `npx storybook@latest init` |
+| Hook | `check-storybook-setup.py` |
+
 Used for:
 - Interactive component development
 - Visual testing of variants
 - Component documentation
 
-The installer creates Storybook story templates (`Component.stories.tsx`) but does **not** install Storybook itself. The `check-storybook-setup.py` hook will detect if Storybook is installed and guide you through setup.
+---
 
 **Playwright (E2E Testing)**
-```bash
-npm init playwright@latest
-```
+| Property | Value |
+|----------|-------|
+| Size | ~200MB (includes browser binaries) |
+| Purpose | End-to-end page testing, cross-browser |
+| Required for | `/hustle-ui-create` (page mode) |
+| Without it | Cannot write `.e2e.test.ts` files |
+| Install flag | `--with-playwright` |
+| Manual command | `npm init playwright@latest` |
+| Hook | `check-playwright-setup.py` |
+
 Used for:
 - Page-level E2E tests
 - Accessibility testing
 - Cross-browser verification
 
-The installer creates Playwright test templates (`page.e2e.test.ts`) but does **not** install Playwright itself. The `check-playwright-setup.py` hook will detect if Playwright is installed and guide you through setup.
+---
 
 **Sandpack (Live UI Previews)**
-```bash
-pnpm add @codesandbox/sandpack-react
-```
+| Property | Value |
+|----------|-------|
+| Size | ~5MB |
+| Purpose | Live code editing in UI Showcase |
+| Required for | Interactive component playground |
+| Without it | Static previews only (still functional) |
+| Install flag | `--with-sandpack` |
+| Manual command | `npm install @codesandbox/sandpack-react` |
+
 Used for:
 - Live component editing in UI Showcase
 - Interactive code previews
 - No server required
 
-The UI Showcase page uses Sandpack for live component previews. Without it, components will display in a static iframe.
+---
+
+#### UI Workflow Hook Behavior
+
+When Storybook or Playwright is not installed:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  HOOK BLOCKED: check-storybook-setup.py                     │
+├─────────────────────────────────────────────────────────────┤
+│  Cannot write .stories.tsx without Storybook installed.     │
+│                                                             │
+│  Install with: npx storybook@latest init                    │
+│                                                             │
+│  Or skip stories and continue (Phase 8-10 will be blocked)  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+Claude will then offer: "Would you like me to install Storybook now?"
+
+This ensures you're always informed about what's needed without forcing installation upfront.
 
 ### Showcase Pages
 
@@ -6887,6 +7005,180 @@ Browse sessions: /hustle-api-sessions --list
 
 </details>
 
+<details>
+<summary><strong>enforce-a11y-audit.py</strong> - Accessibility Audit (v3.10.0+)</summary>
+
+**Event:** PostToolUse (Write|Edit)
+**Purpose:** Trigger WCAG accessibility audit after TDD Green phase for UI workflows
+
+**The Problem It Solves:**
+UI components and pages often ship with accessibility violations:
+- Missing alt text
+- Poor color contrast
+- No keyboard navigation
+- Missing ARIA labels
+
+**How It Works:**
+1. Detects UI workflow (ui-create-component or ui-create-page)
+2. Checks if TDD Green phase is complete
+3. Injects WCAG 2.1 checklist into context
+4. Provides axe-core commands for automated testing
+
+**Example 1: Accessibility Audit Required**
+```
+Accessibility audit required for Button (WCAG 2.1 AA)
+
+Quick Commands:
+# Storybook accessibility check
+pnpm storybook --ci
+pnpm dlx @storybook/test-runner --url http://localhost:6006
+
+WCAG 2.1 AA Checklist:
+  - Color contrast: 4.5:1 for normal text, 3:1 for large text
+  - Focus visible: All interactive elements show focus state
+  - Keyboard nav: All functionality accessible via keyboard
+  - Labels: All form inputs have associated labels
+  - Alt text: All images have meaningful alt text
+```
+
+**Example 2: Page Accessibility Check**
+```
+# Page accessibility check
+pnpm dev
+# Then in another terminal:
+pnpm dlx @axe-core/cli http://localhost:3000/dashboard
+
+# Or use Playwright accessibility tests:
+pnpm test:e2e --grep 'accessibility'
+```
+
+</details>
+
+<details>
+<summary><strong>check-api-routes.py</strong> - Verify API Routes Exist (v3.10.0+)</summary>
+
+**Event:** PreToolUse (Write|Edit)
+**Purpose:** Block page implementation until required API routes exist
+
+**The Problem It Solves:**
+Pages are implemented before their data sources exist:
+- Page expects `/api/users` but route doesn't exist
+- Frontend code calls APIs that haven't been created
+- Runtime errors in production
+
+**How It Works:**
+1. Detects ui-create-page workflow
+2. Checks Phase 7 (ENVIRONMENT) status
+3. Scans project for existing API routes
+4. Blocks page.tsx creation if environment check incomplete
+
+**Example 1: Environment Check Required**
+```
+ENVIRONMENT CHECK REQUIRED (Phase 7)
+
+You are implementing the main page, but the Environment phase is not complete.
+
+Before implementing page.tsx:
+1. Verify required API routes exist
+2. Check authentication configuration
+3. Verify required packages are installed
+4. Update state: phases.environment_check.status = "complete"
+
+Existing API Routes Found:
+  - /api/v2/brandfetch
+  - /api/v2/openai
+  - /api/v2/wordpress
+  ... and 12 more
+
+If you need new API routes, use /api-create to create them first.
+```
+
+</details>
+
+<details>
+<summary><strong>enforce-page-components.py</strong> - Registry Component Reuse (v3.10.0+)</summary>
+
+**Event:** PreToolUse (Write|Edit)
+**Purpose:** Check registry for reusable components before creating new ones
+
+**The Problem It Solves:**
+Duplicate components are created instead of reusing existing ones:
+- Multiple Button components across the project
+- Inconsistent styling and behavior
+- Wasted development time
+
+**How It Works:**
+1. Detects ui-create-page workflow
+2. Checks if creating a standalone component (src/components/)
+3. Loads registry.json to show available components
+4. Blocks if Page Analysis phase not complete
+
+**Example 1: Page Analysis Required**
+```
+PAGE ANALYSIS REQUIRED (Phase 5)
+
+You are creating a new standalone component, but Page Analysis phase is not complete.
+
+Before creating new components:
+1. Check the registry for existing components
+2. Decide which existing components to reuse
+3. Update state: phases.page_analysis.status = "complete"
+
+Available Components in Registry:
+  - Button
+  - Card
+  - Modal
+  - Input
+  - Select
+  ... and 5 more
+
+If you need a NEW component, consider:
+- Using /ui-create to properly create and document it
+- Or create a page-specific component in src/app/{page}/_components/
+```
+
+**Note:** Page-specific components in `_components/` folders are always allowed.
+
+</details>
+
+<details>
+<summary><strong>enforce-page-data-schema.py</strong> - Data Schema Validation (v3.10.0+)</summary>
+
+**Event:** PreToolUse (Write|Edit)
+**Purpose:** Ensure API response types are defined before page implementation
+
+**The Problem It Solves:**
+Pages are implemented without knowing the data structure:
+- TypeScript errors when data shape is wrong
+- Runtime errors from missing properties
+- Inconsistent data handling
+
+**How It Works:**
+1. Detects ui-create-page workflow
+2. Checks Phase 6 (DATA SCHEMA) status
+3. Blocks page.tsx/layout.tsx creation if schema not complete
+4. Allows type files and test files to be written
+
+**Example 1: Data Schema Required**
+```
+DATA SCHEMA REQUIRED (Phase 6)
+
+You are trying to implement page code, but the data schema phase is not complete.
+
+Before writing page implementation:
+1. Define TypeScript interfaces for API responses
+2. Create types in src/app/{page}/_types/index.ts
+3. Update state: phases.data_schema.status = "complete"
+
+Page implementation requires knowing the data structure first.
+```
+
+**What's Allowed Without Schema:**
+- Type definition files (`_types/`)
+- Test files (`__tests__/`, `.test.`, `.spec.`)
+
+</details>
+
 ---
 
 ## Links

package/bin/cli.js

@@ -758,7 +758,7 @@ function main() {
   // Success Summary
   // ========================================
   log('\n' + '═'.repeat(60), 'green');
-  log('🎉 API Development Tools v3.9.2 installed successfully!', 'green');
+  log('🎉 API Development Tools v3.10.0 installed successfully!', 'green');
   log('═'.repeat(60) + '\n', 'green');
 
   log('📋 What was installed:', 'bright');
@@ -774,7 +774,10 @@ function main() {
   log('   MCP:       context7, github (via claude mcp add)', 'blue');
   log('   Test UI:   /api-test page + /api/test-structure API (if Next.js)', 'blue');
 
-  log('\n🆕 New in v3.9.2:', 'bright');
+  log('\n🆕 New in v3.10.0:', 'bright');
+  log('   • Enhanced installer with detailed optional tools info', 'cyan');
+  log('   • UI workflow auto-prompts for Storybook/Playwright installation', 'cyan');
+  log('   • Demo JSONs updated for 13-phase workflow accuracy', 'cyan');
   log('   • Animated 3D grid hero header on showcase pages', 'cyan');
   log('   • Dev Tools landing page at /dev-tools', 'cyan');
   log('   • Multi-endpoint API selector (e.g., /tts, /voices, /models)', 'cyan');
@@ -840,11 +843,55 @@ function main() {
   log('   /api-showcase  - Interactive API testing', 'blue');
   log('   /ui-showcase   - Live component previews', 'blue');
 
-  log('\n📦 Optional Tools (use --with-* flags to auto-install):', 'yellow');
-  log('   --with-sandpack    Live component editing in UI Showcase', 'yellow');
-  log('   --with-storybook   Component development environment', 'yellow');
-  log('   --with-playwright  E2E testing framework', 'yellow');
-  log('\n   Example: npx @hustle-together/api-dev-tools --with-sandpack --with-storybook\n', 'yellow');
+  // Enhanced Optional Development Tools Section
+  log('\n' + '─'.repeat(60), 'yellow');
+  log('📦 OPTIONAL DEVELOPMENT TOOLS', 'yellow');
+  log('─'.repeat(60), 'yellow');
+  log('   The following tools are OPTIONAL but enhance UI development.', 'bright');
+  log('   Install now with flags, or later when prompted during /hustle-ui-create.\n', 'bright');
+
+  log('   ┌──────────────────────────────────────────────────────────┐', 'cyan');
+  log('   │  STORYBOOK (Component Development)                       │', 'cyan');
+  log('   ├──────────────────────────────────────────────────────────┤', 'cyan');
+  log('   │  Size:      ~50MB                                        │', 'cyan');
+  log('   │  Purpose:   Visual component testing, interactive docs   │', 'cyan');
+  log('   │  Required:  /hustle-ui-create (component mode)           │', 'cyan');
+  log('   │  Without:   Cannot write .stories.tsx files              │', 'cyan');
+  log('   │  Install:   --with-storybook flag OR during UI workflow  │', 'cyan');
+  log('   │  Command:   npx storybook@latest init                    │', 'cyan');
+  log('   └──────────────────────────────────────────────────────────┘', 'cyan');
+
+  log('   ┌──────────────────────────────────────────────────────────┐', 'magenta');
+  log('   │  PLAYWRIGHT (E2E Testing)                                │', 'magenta');
+  log('   ├──────────────────────────────────────────────────────────┤', 'magenta');
+  log('   │  Size:      ~200MB (includes browser binaries)           │', 'magenta');
+  log('   │  Purpose:   End-to-end page testing, cross-browser       │', 'magenta');
+  log('   │  Required:  /hustle-ui-create-page (page mode)           │', 'magenta');
+  log('   │  Without:   Cannot write .e2e.test.ts files              │', 'magenta');
+  log('   │  Install:   --with-playwright flag OR during UI workflow │', 'magenta');
+  log('   │  Command:   npm init playwright@latest                   │', 'magenta');
+  log('   └──────────────────────────────────────────────────────────┘', 'magenta');
+
+  log('   ┌──────────────────────────────────────────────────────────┐', 'blue');
+  log('   │  SANDPACK (Live Editing)                                 │', 'blue');
+  log('   ├──────────────────────────────────────────────────────────┤', 'blue');
+  log('   │  Size:      ~5MB                                         │', 'blue');
+  log('   │  Purpose:   Live code editing in UI Showcase             │', 'blue');
+  log('   │  Required:  Interactive component playground             │', 'blue');
+  log('   │  Without:   Static previews only (still functional)      │', 'blue');
+  log('   │  Install:   --with-sandpack flag                         │', 'blue');
+  log('   │  Command:   npm install @codesandbox/sandpack-react      │', 'blue');
+  log('   └──────────────────────────────────────────────────────────┘', 'blue');
+
+  log('\n   💡 UI Workflow Behavior:', 'bright');
+  log('   When you run /hustle-ui-create without Storybook or Playwright:', 'bright');
+  log('   1. The hook will BLOCK writing test/story files', 'bright');
+  log('   2. You\'ll see the install command and be prompted to install', 'bright');
+  log('   3. After installing, the workflow continues automatically', 'bright');
+  log('   4. You can skip and install later, but Phase 8-10 will be blocked', 'bright');
+
+  log('\n   Example with all optional tools:', 'yellow');
+  log('   npx @hustle-together/api-dev-tools --with-storybook --with-playwright --with-sandpack\n', 'yellow');
 
   // ========================================
   // 5. Verify Installation

package/commands/hustle-api-create.md

@@ -101,7 +101,7 @@ Both conditions must be true for the flag to be set.
 /hustle-api-create [endpoint]
         │
         ▼
-┌─ PHASE 0: DISAMBIGUATION ─────────────────────────────────┐
+┌─ PHASE 1: DISAMBIGUATION ─────────────────────────────────┐
 │ Search 3-5 variations of the term:                        │
 │   • "[term]"                                              │
 │   • "[term] API"                                          │
@@ -128,7 +128,7 @@ Both conditions must be true for the flag to be set.
 └───────────────────────────────────────────────────────────┘
         │ Clear
         ▼
-┌─ PHASE 1: SCOPE CONFIRMATION ─────────────────────────────┐
+┌─ PHASE 2: SCOPE ──────────────────────────────────────────┐
 │                                                           │
 │ Present your understanding, then:                         │
 │                                                           │
@@ -153,7 +153,7 @@ Both conditions must be true for the flag to be set.
 └───────────────────────────────────────────────────────────┘
         │
         ▼
-┌─ PHASE 2: INITIAL RESEARCH ───────────────────────────────┐
+┌─ PHASE 3: INITIAL RESEARCH ───────────────────────────────┐
 │                                                           │
 │ Execute 2-3 initial searches:                             │
 │   • Context7: "[library/api name]"                        │
@@ -183,7 +183,7 @@ Both conditions must be true for the flag to be set.
 └───────────────────────────────────────────────────────────┘
         │
         ▼
-┌─ PHASE 3: INTERVIEW (Generated FROM Research) ────────────┐
+┌─ PHASE 4: INTERVIEW (Generated FROM Research) ────────────┐
 │                                                           │
 │ For EACH parameter discovered in research, ask ONE        │
 │ question at a time using AskUserQuestion:                 │
@@ -235,7 +235,7 @@ Both conditions must be true for the flag to be set.
 └───────────────────────────────────────────────────────────┘
         │
         ▼
-┌─ PHASE 4: DEEP RESEARCH (Adaptive) ───────────────────────┐
+┌─ PHASE 5: DEEP RESEARCH (Adaptive) ───────────────────────┐
 │                                                           │
 │ Based on interview answers, PROPOSE additional research.  │
 │                                                           │
@@ -260,7 +260,7 @@ Both conditions must be true for the flag to be set.
 └───────────────────────────────────────────────────────────┘
         │
         ▼
-┌─ PHASE 5: SCHEMA DESIGN ──────────────────────────────────┐
+┌─ PHASE 6: SCHEMA ─────────────────────────────────────────┐
 │                                                           │
 │ Create Zod schema from research + interview, then:        │
 │                                                           │
@@ -285,7 +285,7 @@ Both conditions must be true for the flag to be set.
 └───────────────────────────────────────────────────────────┘
         │
         ▼
-┌─ PHASE 6: ENVIRONMENT CHECK ──────────────────────────────┐
+┌─ PHASE 7: ENVIRONMENT ────────────────────────────────────┐
 │                                                           │
 │ Check required API keys, show status table, then:         │
 │                                                           │
@@ -309,7 +309,7 @@ Both conditions must be true for the flag to be set.
 └───────────────────────────────────────────────────────────┘
         │
         ▼
-┌─ PHASE 7: TDD RED (Write Failing Tests) ──────────────────┐
+┌─ PHASE 8: TDD RED (Write Failing Tests) ──────────────────┐
 │                                                           │
 │ Generate test matrix from schema + interview, then:       │
 │                                                           │
@@ -335,7 +335,7 @@ Both conditions must be true for the flag to be set.
 └───────────────────────────────────────────────────────────┘
         │
         ▼
-┌─ PHASE 8: TDD GREEN (Minimal Implementation) ─────────────┐
+┌─ PHASE 9: TDD GREEN (Minimal Implementation) ─────────────┐
 │                                                           │
 │ Write minimal code to pass ALL tests.                     │
 │ Tests derived from schema.                                │
@@ -347,7 +347,7 @@ Both conditions must be true for the flag to be set.
 └───────────────────────────────────────────────────────────┘
         │
         ▼
-┌─ PHASE 9: VERIFY (Re-Research After Green) ───────────────┐
+┌─ PHASE 10: VERIFY (Re-Research After Green) ──────────────┐
 │                                                           │
 │ MANDATORY: Re-read original documentation.                │
 │ Compare implementation to docs, then:                     │
@@ -374,7 +374,7 @@ Both conditions must be true for the flag to be set.
 └───────────────────────────────────────────────────────────┘
         │
         ▼
-┌─ PHASE 10: TDD REFACTOR ──────────────────────────────────┐
+┌─ PHASE 11: TDD REFACTOR ──────────────────────────────────┐
 │                                                           │
 │ Clean up code while tests stay green:                     │
 │   • Extract reusable patterns                             │
@@ -386,7 +386,7 @@ Both conditions must be true for the flag to be set.
 └───────────────────────────────────────────────────────────┘
         │
         ▼
-┌─ PHASE 11: DOCUMENTATION ─────────────────────────────────┐
+┌─ PHASE 12: DOCUMENTATION ─────────────────────────────────┐
 │                                                           │
 │ Update documentation files, then:                         │
 │                                                           │
@@ -411,7 +411,7 @@ Both conditions must be true for the flag to be set.
 └───────────────────────────────────────────────────────────┘
         │
         ▼
-┌─ PHASE 12: COMPLETION ────────────────────────────────────┐
+┌─ PHASE 13: COMPLETION ────────────────────────────────────┐
 │                                                           │
 │ Final verification:                                       │
 │   • All tests passing                                     │