FlowSpec CLI

🚀 AI-powered autonomous React test generation with intelligent file watching

FlowSpec automatically generates, executes, and maintains comprehensive test suites for your React applications using GPT-4. Features intelligent file watching, incremental updates, and token optimization.

![npm version](https://badge.fury.io/js/%40cosmah%2Fflowspec-cli)
![License: MIT](https://opensource.org/licenses/MIT)

✨ Features

- 🤖 AI-Powered Generation - GPT-4 analyzes your components and generates comprehensive tests
- 👀 Intelligent File Watching - Automatically detects new/changed React components
- 🔄 Incremental Updates - Only updates changed parts of existing tests (saves tokens)
- 📊 Real-time Dashboard - Monitor coverage, performance, and team productivity
- ⚡ Zero Configuration - Works out of the box with React, Next.js, and more
- 🎯 Smart Context - Uses codebase embedding for intelligent test generation
- 🔧 Auto-Installation - Automatically installs and configures Vitest dependencies
- 💰 Token Optimized - Smart duplication guards and incremental updates
- ⚡ Smart Caching - Instant test generation for unchanged components (5-second rule)
- 🔧 Auto-Healing - Automatically fixes test syntax and import errors
- 📈 Test Debt Counter - Track untested components and estimate coverage time
- 🎨 Design System Awareness - Detects and leverages UI libraries (Shadcn, MUI, Chakra, Ant Design)
- 📦 Data Archetype Detection - Automatically finds and uses factories, mocks, and test data
- 🔄 Background Execution - Non-blocking test execution with real-time feedback

🚀 Quick Start

$3

``bash

`Install globally`


npm install -g @cosmah/flowspec-cli@latest
Verify installation

flowspec --version

$3

`bash

`1. Create account and login`


flowspec signup
flowspec login
2. Initialize in your React project

cd my-react-app
flowspec init
3. Start intelligent file watching (auto-embeds codebase)

flowspec watch    # Automatically embeds codebase + generates tests for ALL existing files + watches for changes


📋 Commands
$3

bash
flowspec signup              # Create new account
flowspec login               # Login to existing account  
flowspec logout              # Logout from FlowSpec

$3

bash
flowspec init                # Initialize FlowSpec in project
flowspec embed               # Embed codebase for AI context
flowspec status              # Show project status and info
flowspec dashboard           # Open web dashboard
flowspec update              # Update CLI to latest version

$3

bash
flowspec generate     # Generate tests for specific files
flowspec watch               # Auto-generate tests for existing + new files


🛠️ How It Works
$3

FlowSpec watches multiple directories and automatically detects React components:
-

src/*/.{tsx,jsx}

 (Create React App)
-

app/*/.{tsx,jsx}

 (Next.js App Router) 
-

pages/*/.{tsx,jsx}

 (Next.js Pages Router)
-

components/*/.{tsx,jsx}

lib/*/.{tsx,jsx}


$3

Before generating tests, FlowSpec:
- ✅ Checks if test file already exists
- ✅ Compares modification times (component vs test)
- ✅ Skips generation if test is up-to-date
- ✅ Only updates when component is newer
$3

For existing tests:
- 🔄 Sends existing test code to AI
- ✏️ AI only modifies changed/new parts
- 💰 Saves ~60% on API tokens
- 🎯 Preserves working test logic
$3

When you run

flowspec watch

:
1. 🔍 Scans all existing React components
2. 🧪 Generates tests for components without tests
3. 👀 Starts watching for new files and changes
4. ⚡ Auto-generates tests for any new/modified components
📁 Supported Project Structures
FlowSpec works with all React project structures:
$3


src/
├── components/
│   ├── Button.tsx          → Button.test.tsx
│   └── Header.tsx          → Header.test.tsx
└── pages/
    └── Home.tsx            → Home.test.tsx

$3


app/
├── components/
│   └── Navigation.tsx      → Navigation.test.tsx
├── dashboard/
│   └── page.tsx           → page.test.tsx
└── (auth)/
    └── login/
        └── page.tsx       → page.test.tsx

$3


pages/
├── index.tsx              → index.test.tsx
├── about.tsx              → about.test.tsx
└── api/                   (ignored)
components/
└── Layout.tsx             → Layout.test.tsx


⚙️ Configuration
$3

json
{
  "projectId": "proj_abc123",
  "userId": "user_xyz789",
  "name": "My React App", 
  "framework": "react",
  "apiUrl": "https://api.flowspecai.dev"
}


🎯 File Watching Behavior
$3

- ✅

.tsx and .jsx

 files only
- ✅ Files starting with capital letter (React components)
- ✅ Files in

src/, app/, pages/, components/, lib/


$3

- ❌

*/.test.{tsx,jsx}

 (existing test files)
- ❌

*/.spec.{tsx,jsx}

 (spec files)
- ❌

node_modules/, dist/, build/, .next/


- ❌ Files starting with lowercase (utilities, not components)
$3

bash
$ flowspec watch
Starting FlowSpec file watcher...
Found 12 existing components
Generating tests for existing files...
File found: src/components/Button.tsx
Generated test for src/components/Button.tsx
   Test file: src/components/Button.test.tsx
   Status: Passing
   Attempts: 1
File found: app/dashboard/Header.tsx  
Test exists: app/dashboard/Header.test.tsx - checking for updates...
Skipping app/dashboard/Header.tsx - test is up to date
Initial sync complete! Processed 12 existing files
FlowSpec watcher is ready and monitoring for changes
Press Ctrl+C to stop watching

File changed: src/components/Button.tsx Updated test for src/components/Button.tsx Test file: src/components/Button.test.tsx Status: Passing Attempts: 1`

`💰 Token Optimization Features`

`$3`


- Before: Generated tests for all files every time
- After: Only generates when needed (new files or component changes)
- Savings: ~60% reduction in API calls
$3

- Before: Rewrote entire test file for small component changes
- After: Sends existing test + component changes for incremental updates
- Savings: ~40% reduction in prompt tokens
$3

- Before: Tests included decorative comments and emojis
- After: Clean, minimal test code focused on functionality
- Savings: ~20% reduction in response tokens
🚨 Troubleshooting
$3

"Project not initialized"`bash flowspec init`

"Not logged in"`bash flowspec login`

"No components found" Make sure you have.tsx or .jsxfiles starting with capital letters in: -src/, app/, pages/, components/, or lib/ directories

"Test generation failed" - Check internet connection - Verify you have sufficient API credits - Tryflowspec status to check connection

`🤝 Contributing`

We welcome contributions! Please see our Contributing Guide for details.

`$3`

bash
git clone https://github.com/cosmah/flowspec-cli.git
cd flowspec-cli
npm install
npm run dev


📄 License
MIT License - see LICENSE file for details.
🔗 Links
- 🌐 Website: https://flowspecai.dev 
- 📚 Documentation: https://flowspecai.dev/docs
- 🐛 Issues: GitHub Issues
- 💬 Support: support@flowspecai.dev
🎉 What's New in v2.1.0
$3

- 📦 Auto-Installation: FlowSpec automatically detects and installs missing dependencies during test generation
- 🔍 Smart Verification: Checks both

package.json and actual node_modules

 to ensure dependencies exist
- 🔄 Automatic Retry: Tests automatically retry after dependency installation completes
- 🎯 Error Classification: Distinguishes between dependency errors (auto-installs) and test code errors (auto-heals)
$3

- 🛡️ Resource Cleanup: Enhanced connection pool management and cleanup prevents resource leaks
- 🔄 Process Management: Improved child process tracking ensures no orphaned processes on exit
- ⏱️ HTTP Timeouts: All HTTP requests now have explicit timeouts for better reliability
- 🚪 Graceful Shutdown: Enhanced signal handling ensures proper cleanup on all exit paths
$3

- ✅ Healer Node: Fixed critical bug preventing auto-healing (

 module import)
- ✅ Code Extraction: Improved healer response parsing and validation
- ✅ Dependency Errors: Fixed false auto-healing triggers on dependency issues
$3

- ⚡ Smart Caching (Ghost Runner): Instant test generation for unchanged components - bypass API calls when code hasn't changed
- 🔧 Auto-Healing: Automatically detects and fixes test syntax errors, import issues, and component mismatches
- 📈 Test Debt Counter: Real-time visibility into untested components with time-to-coverage estimates
- 🎨 Design System Awareness: Automatically detects UI libraries (Shadcn, MUI, Chakra, Ant Design) and tailors test generation
- 📦 Data Archetype Detection: Finds and leverages existing factories, mocks, and test data patterns
- 🔄 Background Test Execution: Non-blocking test runs with silent notifications for seamless workflow
- 🎯 Intelligent Failure Analysis: Classifies test failures as "our fault" (auto-heals) vs "their fault" (shows suggestions)
- ⚡ 5-Second Rule: Smart caching ensures sub-5-second response times for cached components
🎉 What's New in v2.0.0

- 🆕 Intelligent File Watching: Automatically processes existing files + watches for changes - 🆕 Next.js App Router Support: Full support forapp/` directory structure
- 🆕 Incremental Updates: Only updates changed parts of existing tests
- 🆕 Token Optimization: Smart duplication guards save ~60% on API costs
- 🆕 Initial Sync: Processes all existing components when starting watcher
- 🆕 Clean Output: Removed decorative elements for professional test code
- 🆕 Better Performance: File modification time checking prevents unnecessary updates

---

Made with ❤️ by the FlowSpec Team

FlowSpec CLI

🚀 AI-powered autonomous React test generation with intelligent file watching

![npm version](https://badge.fury.io/js/%40cosmah%2Fflowspec-cli)
![License: MIT](https://opensource.org/licenses/MIT)

✨ Features

🚀 Quick Start

$3

``bash

`Install globally`


npm install -g @cosmah/flowspec-cli@latest
Verify installation

flowspec --version

$3

`bash

`1. Create account and login`


flowspec signup
flowspec login
2. Initialize in your React project

cd my-react-app
flowspec init
3. Start intelligent file watching (auto-embeds codebase)

flowspec watch    # Automatically embeds codebase + generates tests for ALL existing files + watches for changes


📋 Commands
$3

bash
flowspec signup              # Create new account
flowspec login               # Login to existing account  
flowspec logout              # Logout from FlowSpec

$3

bash
flowspec init                # Initialize FlowSpec in project
flowspec embed               # Embed codebase for AI context
flowspec status              # Show project status and info
flowspec dashboard           # Open web dashboard
flowspec update              # Update CLI to latest version

$3

bash
flowspec generate     # Generate tests for specific files
flowspec watch               # Auto-generate tests for existing + new files


🛠️ How It Works
$3

FlowSpec watches multiple directories and automatically detects React components:
-

src/*/.{tsx,jsx}

 (Create React App)
-

app/*/.{tsx,jsx}

 (Next.js App Router) 
-

pages/*/.{tsx,jsx}

 (Next.js Pages Router)
-

components/*/.{tsx,jsx}

lib/*/.{tsx,jsx}


$3

Before generating tests, FlowSpec:
- ✅ Checks if test file already exists
- ✅ Compares modification times (component vs test)
- ✅ Skips generation if test is up-to-date
- ✅ Only updates when component is newer
$3

For existing tests:
- 🔄 Sends existing test code to AI
- ✏️ AI only modifies changed/new parts
- 💰 Saves ~60% on API tokens
- 🎯 Preserves working test logic
$3

When you run

flowspec watch

:
1. 🔍 Scans all existing React components
2. 🧪 Generates tests for components without tests
3. 👀 Starts watching for new files and changes
4. ⚡ Auto-generates tests for any new/modified components
📁 Supported Project Structures
FlowSpec works with all React project structures:
$3


src/
├── components/
│   ├── Button.tsx          → Button.test.tsx
│   └── Header.tsx          → Header.test.tsx
└── pages/
    └── Home.tsx            → Home.test.tsx

$3


app/
├── components/
│   └── Navigation.tsx      → Navigation.test.tsx
├── dashboard/
│   └── page.tsx           → page.test.tsx
└── (auth)/
    └── login/
        └── page.tsx       → page.test.tsx

$3


pages/
├── index.tsx              → index.test.tsx
├── about.tsx              → about.test.tsx
└── api/                   (ignored)
components/
└── Layout.tsx             → Layout.test.tsx


⚙️ Configuration
$3

json
{
  "projectId": "proj_abc123",
  "userId": "user_xyz789",
  "name": "My React App", 
  "framework": "react",
  "apiUrl": "https://api.flowspecai.dev"
}


🎯 File Watching Behavior
$3

- ✅

.tsx and .jsx

 files only
- ✅ Files starting with capital letter (React components)
- ✅ Files in

src/, app/, pages/, components/, lib/


$3

- ❌

*/.test.{tsx,jsx}

 (existing test files)
- ❌

*/.spec.{tsx,jsx}

 (spec files)
- ❌

node_modules/, dist/, build/, .next/


- ❌ Files starting with lowercase (utilities, not components)
$3

bash
$ flowspec watch
Starting FlowSpec file watcher...
Found 12 existing components
Generating tests for existing files...
File found: src/components/Button.tsx
Generated test for src/components/Button.tsx
   Test file: src/components/Button.test.tsx
   Status: Passing
   Attempts: 1
File found: app/dashboard/Header.tsx  
Test exists: app/dashboard/Header.test.tsx - checking for updates...
Skipping app/dashboard/Header.tsx - test is up to date
Initial sync complete! Processed 12 existing files
FlowSpec watcher is ready and monitoring for changes
Press Ctrl+C to stop watching

File changed: src/components/Button.tsx Updated test for src/components/Button.tsx Test file: src/components/Button.test.tsx Status: Passing Attempts: 1`

`💰 Token Optimization Features`

`$3`


- Before: Generated tests for all files every time
- After: Only generates when needed (new files or component changes)
- Savings: ~60% reduction in API calls
$3

- Before: Rewrote entire test file for small component changes
- After: Sends existing test + component changes for incremental updates
- Savings: ~40% reduction in prompt tokens
$3

- Before: Tests included decorative comments and emojis
- After: Clean, minimal test code focused on functionality
- Savings: ~20% reduction in response tokens
🚨 Troubleshooting
$3

"Project not initialized"`bash flowspec init`

"Not logged in"`bash flowspec login`

"No components found" Make sure you have.tsx or .jsxfiles starting with capital letters in: -src/, app/, pages/, components/, or lib/ directories

"Test generation failed" - Check internet connection - Verify you have sufficient API credits - Tryflowspec status to check connection

`🤝 Contributing`

We welcome contributions! Please see our Contributing Guide for details.

`$3`

bash
git clone https://github.com/cosmah/flowspec-cli.git
cd flowspec-cli
npm install
npm run dev


📄 License
MIT License - see LICENSE file for details.
🔗 Links
- 🌐 Website: https://flowspecai.dev 
- 📚 Documentation: https://flowspecai.dev/docs
- 🐛 Issues: GitHub Issues
- 💬 Support: support@flowspecai.dev
🎉 What's New in v2.1.0
$3

- 📦 Auto-Installation: FlowSpec automatically detects and installs missing dependencies during test generation
- 🔍 Smart Verification: Checks both

package.json and actual node_modules

 to ensure dependencies exist
- 🔄 Automatic Retry: Tests automatically retry after dependency installation completes
- 🎯 Error Classification: Distinguishes between dependency errors (auto-installs) and test code errors (auto-heals)
$3

- 🛡️ Resource Cleanup: Enhanced connection pool management and cleanup prevents resource leaks
- 🔄 Process Management: Improved child process tracking ensures no orphaned processes on exit
- ⏱️ HTTP Timeouts: All HTTP requests now have explicit timeouts for better reliability
- 🚪 Graceful Shutdown: Enhanced signal handling ensures proper cleanup on all exit paths
$3

- ✅ Healer Node: Fixed critical bug preventing auto-healing (

 module import)
- ✅ Code Extraction: Improved healer response parsing and validation
- ✅ Dependency Errors: Fixed false auto-healing triggers on dependency issues
$3

- ⚡ Smart Caching (Ghost Runner): Instant test generation for unchanged components - bypass API calls when code hasn't changed
- 🔧 Auto-Healing: Automatically detects and fixes test syntax errors, import issues, and component mismatches
- 📈 Test Debt Counter: Real-time visibility into untested components with time-to-coverage estimates
- 🎨 Design System Awareness: Automatically detects UI libraries (Shadcn, MUI, Chakra, Ant Design) and tailors test generation
- 📦 Data Archetype Detection: Finds and leverages existing factories, mocks, and test data patterns
- 🔄 Background Test Execution: Non-blocking test runs with silent notifications for seamless workflow
- 🎯 Intelligent Failure Analysis: Classifies test failures as "our fault" (auto-heals) vs "their fault" (shows suggestions)
- ⚡ 5-Second Rule: Smart caching ensures sub-5-second response times for cached components
🎉 What's New in v2.0.0

---

Made with ❤️ by the FlowSpec Team