---

✨ Features

- 🚀 Parallel Execution - Run tasks concurrently with configurable limits
- 🎬 Live Updates - Animated spinners and real-time status in your terminal
- 🎯 Priority Control - Execute tasks in specific order or randomize for testing
- ⚡ Fail-Fast Mode - Stop immediately on first error
- 📊 Multiple Formats - Table, minimal, or JSON output
- 🎨 Horizontal Layout - Optimized for terminal space (services × tasks)
- 🔧 Task Overrides - Customize tasks per service
- ✨ Optional Tasks - Skip tasks that don't apply to certain services
- ⏱️ Timeout Support - Set time limits for tasks
- 🌍 Environment Variables - Per-task and per-service configuration
- 🎲 Random Execution - Test robustness with randomized order
- 🔄 CI/CD Ready - Proper exit codes (0=success, 1=errors, 2=config error)

📦 Installation

``bash
npm install verify-grid
`

🚀 Quick Start

1. Create configuration file qa.config.js:

`javascript
export default {
tasks: {
lint: { command: 'npm', args: ['run', 'lint'], priority: 10 },
test: { command: 'npm', args: ['test'], priority: 5 },
build: { command: 'npm', args: ['run', 'build'] },
},
services: [
{ name: 'api', cwd: './services/api' },
{ name: 'web', cwd: './services/web' },
],
};
`

2. Run tasks:

`bash


Run all tasks on all services

qa run

Run specific tasks

qa run --tasks lint,test

Stop on first error

qa run --fail-fast

Randomize execution order

qa run --random
`

🎮 CLI Commands

$3

Execute tasks across services with live status updates.

#### Options

| Option | Description | Default |
|--------|-------------|---------|
| --tasks | Comma-separated tasks or "all" | all |
| --services | Comma-separated services or "all" | all |
| --concurrency | Maximum parallel jobs | CPU count |
| --fail-fast | Stop on first error | false |
| --random | Randomize execution order | false |
| --no-watch | Disable live updates | enabled in TTY |
| --format | Output: table, minimal, json | table |
| --output | Save JSON to file | - |
| --timeout | Timeout per task (milliseconds) | - |
| --no-color | Disable colors | enabled in TTY |
| --config | Custom config file path | qa.config.js |

#### Examples

`bash


Run all tasks

qa run

Run specific tasks on specific services

qa run --tasks lint,test --services api,web

Limit concurrency and stop on error

qa run --concurrency 2 --fail-fast

Output as JSON

qa run --format json --output results.json

Set timeout (30 seconds)

qa run --timeout 30000

Randomize for testing

qa run --random
`

⚙️ Configuration

$3

`javascript
{
tasks: {
taskName: {
command: 'npm', // Command to execute (required)
args: ['test'], // Arguments (optional)
shell: false, // Run in shell (optional)
timeout: 30000, // Timeout in ms (optional)
priority: 10, // Higher = earlier (optional)
optional: false, // Skip if not applicable (optional)
env: { // Environment variables (optional)
NODE_ENV: 'test'
}
}
}
}
`

Task Properties:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| command | string | ✅ | Command to execute |
| args | string[] | ❌ | Command arguments |
| shell | boolean | ❌ | Run in shell (default: false) |
| timeout | number | ❌ | Timeout in milliseconds |
| priority | number | ❌ | Execution priority (higher first, default: 0) |
| optional | boolean | ❌ | Skip task if command not defined (default: false) |
| env | Record | ❌ | Environment variables |

$3

`javascript
{
services: [
{
name: 'api', // Service name (required)
cwd: './services/api', // Working directory (required)
tasks: { // Task overrides (optional)
test: {
args: ['test', '--coverage'],
priority: 5
}
},
env: { // Environment variables (optional)
PORT: '3000'
}
}
]
}
`

Service Properties:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| name | string | ✅ | Service name |
| cwd | string | ✅ | Working directory path |
| tasks | Record> | ❌ | Override task properties |
| env | Record | ❌ | Environment variables |

$3

`javascript
export default {
tasks: {
lint: {
command: 'npm',
args: ['run', 'lint'],
timeout: 30000,
priority: 10,
},
test: {
command: 'npm',
args: ['test'],
priority: 5,
env: { NODE_ENV: 'test' },
},
build: {
command: 'npm',
args: ['run', 'build'],
timeout: 60000,
},
typecheck: {
command: 'tsc',
args: ['--noEmit'],
},
screenshot: {
command: '',
optional: true, // Only runs if service defines it
},
},
services: [
{
name: 'api',
cwd: './services/api',
env: { PORT: '3000' },
tasks: {
test: {
args: ['test', '--coverage'],
timeout: 45000,
},
},
},
{
name: 'web',
cwd: './services/web',
env: { PORT: '3001' },
tasks: {
screenshot: {
command: 'npm',
args: ['run', 'screenshot'],
},
},
},
{
name: 'shared',
cwd: './packages/shared',
tasks: {
build: { command: 'tsup' },
},
},
],
};
`

📊 Output Formats

$3

Horizontal matrix with live updates:

`
Service | lint | test | build
---------|-----------|--------------|-------
api | ✓ done | ⠋ running | ⏳ queued
web | ✓ done | ✓ done | ⏳ queued
shared | ✓ done | ✗ error | - skipped
`

$3

Simple text output:

`
lint api done
lint web done
test api running
`

$3

Structured output for automation:

`json
{
"startedAt": 1234567890,
"endedAt": 1234567900,
"durationMs": 10000,
"matrix": {
"lint": {
"api": { "status": "done", "exitCode": 0, "durationMs": 1234 }
}
},
"errors": []
}
`

🚦 Exit Codes

| Code | Meaning |
|------|---------|
| 0 | All tasks completed successfully ✅ |
| 1 | One or more tasks failed ❌ |
| 2` | Configuration error or invalid arguments ⚠️ |

📝 License

MIT