A²D CLI Tool

The a2d script is a unified command-line interface that simplifies the entire A²D development workflow. It manages Supabase, runs tests, handles git operations, and provides automated workflows.

Overview

The a2d CLI provides:

One-command operations - Start/stop everything with a single command
Comprehensive testing - Run unit, integration, and API tests
Supabase health checks - Automatic validation before running DB-dependent tests
Git workflow automation - Branch management, commits, and PRs
Safety features - Protected branches, confirmation prompts, and validation

Location: /path/to/a2d-mocks/a2d (parent repository)

Quick Start

# Start everything (Supabase + dev server)
./a2d start
 
# Run unit tests (no DB required)
./a2d test unit
 
# Run integration tests (starts Supabase if needed)
./a2d test integration
 
# Stop everything
./a2d stop
 
# Get help
./a2d help

Installation

The a2d script is included in the parent a2d-mocks repository:

# Clone the parent repository
git clone <a2d-mocks-repo-url>
cd a2d-mocks
 
# Initialize submodules
git submodule update --init --recursive
 
# Make script executable (if needed)
chmod +x a2d
 
# Verify installation
./a2d help

Prerequisites

Name	Type	Description
`Docker Desktop`	required	Install from docker.com - Required for Supabase
`Supabase CLI`	required	`brew install supabase/tap/supabase` or see Supabase docs
`psql`	required	PostgreSQL client - `brew install libpq && brew link --force libpq`
`Node.js v18+`	required	From nodejs.org or via `nvm install 18`
`npm`	required	Included with Node.js
`gh CLI`	optional	For PR creation - `brew install gh` or see GitHub CLI

Command Reference

Help and Information

./a2d help        # Show full help
./a2d --help      # Alias
./a2d -h          # Short alias

Starting Services

./a2d start                # Start both Supabase and dev server (interactive)
./a2d start supabase       # Start only Supabase
./a2d start dev            # Start only Next.js dev server
./a2d start --help         # Show detailed start options

What happens:

Checks Docker is running
Checks Supabase CLI is installed
Starts Supabase containers (first run downloads images ~2-5 min)
Applies database migrations
Seeds test data
Optionally starts Next.js dev server
Shows connection details and test users

Stopping Services

./a2d stop                 # Stop both dev server and Supabase
./a2d stop supabase        # Stop only Supabase containers
./a2d stop dev             # Stop only Next.js dev server
./a2d stop --help          # Show detailed stop options

Resetting Database

./a2d reset supabase       # Destroy local DB, re-migrate, re-seed

This only affects your LOCAL database. Remote/linked databases are never touched.

Running Tests

The a2d test command provides comprehensive testing with automatic Supabase health checks:

./a2d test                          # Run all tests (requires Supabase)
./a2d test unit                     # Unit tests only (no DB needed)
./a2d test integration              # Integration tests (requires Supabase)
./a2d test api                      # API route tests (requires Supabase)
./a2d test actions                  # Server action tests (requires Supabase)
./a2d test platform-mcp             # Platform MCP tests (requires Supabase)
./a2d test platform-mcp unit        # Platform MCP unit tests (no DB needed)
./a2d test platform-mcp integration # Platform MCP integration tests (requires Supabase)
./a2d test watch                    # Watch mode (re-runs on file changes)
./a2d test coverage                 # Run with coverage report
./a2d test ui                       # Interactive UI mode
./a2d test --help                   # Show all test options

Test Types Explained

Test Type	Requires Supabase	Description	Speed
`unit`	❌ No	Fast unit tests for pure functions and components	Very Fast (seconds)
`integration`	✅ Yes	Full integration tests with database	Moderate
`api`	✅ Yes	API route testing with real database	Moderate
`actions`	✅ Yes	Server action testing	Moderate
`platform-mcp`	✅ Yes	All Platform MCP tests	Moderate
`platform-mcp unit`	❌ No	Platform MCP unit tests only	Fast
`platform-mcp integration`	✅ Yes	Platform MCP integration tests	Moderate

Automatic Supabase Health Checks

When running tests that require Supabase, the CLI automatically:

Checks if Supabase is running - Validates Docker, containers, and DB connection
Prompts to start if needed - Offers to start Supabase automatically
Verifies health before tests - Ensures everything is ready

Example workflow:

$ ./a2d test integration
 
⚠  This test requires Supabase to be running
 
  Docker is running but Supabase is not started.
 
Start Supabase now? (y/n): y
 
✓ Starting Supabase...
✓ Supabase is now running
 
Running integration tests
...
✓ Tests passed

Git Workflow Commands

Branch Management

./a2d branch list                  # List all branches
./a2d branch create feature-name   # Create and switch to new branch
./a2d branch delete feature-name   # Delete branch (with confirmation)
./a2d branch switch branch-name    # Switch to existing branch
./a2d branch rename new-name       # Rename current branch

Protected branches: main and develop cannot be deleted

Status and Sync

./a2d status                       # Show git status and branch info
./a2d pull                         # Pull latest changes (checks for uncommitted changes)
./a2d fetch                        # Fetch from origin

Commits and Push

./a2d commit "message"             # Create commit with message
./a2d push                         # Push to origin (with confirmation)
./a2d push -f                      # Force push (requires confirmation)

Pull Requests

./a2d pr create "PR title"         # Create PR via gh CLI
./a2d pr list                      # List open PRs
./a2d pr view 123                  # View PR details

Requires GitHub CLI (gh) to be installed and authenticated.

Daily Development Workflow

Morning: Start Work

./a2d pull                         # Get latest changes
./a2d branch create feature/cool-thing
./a2d start                        # Start Supabase + dev server

During Development

# Make changes in your editor
 
./a2d test unit                    # Quick unit test feedback
./a2d test integration             # Full integration tests
 
./a2d status                       # Check what changed

End of Day: Ship Work

./a2d test                         # Run all tests
./a2d commit "Add cool feature"    # Commit changes
./a2d push                         # Push to origin
./a2d pr create "Add cool thing"   # Create PR
./a2d stop                         # Stop services

Test-Driven Development Workflow

# 1. Start with unit tests (fast feedback loop)
./a2d test unit
 
# 2. Implement feature
# ... edit code ...
 
# 3. Re-run unit tests
./a2d test unit
 
# 4. Run integration tests
./a2d test integration
 
# 5. Run full test suite
./a2d test
 
# 6. Commit when all tests pass
./a2d commit "Implement feature X with tests"

Safety Features

Protected Branches

main and develop branches are protected:

Cannot be deleted via ./a2d branch delete
Push operations require explicit confirmation
Prevents accidental destructive operations

Confirmation Prompts

Risky operations require confirmation:

Pushing to origin
Force pushing
Deleting branches
Resetting database

Pre-flight Checks

Before operations, the script validates:

Git repository exists
Submodules are initialized
No uncommitted changes (when switching/pulling)
Docker is running (for Supabase operations)
Required tools are installed

Never Force Pushes Automatically

The script never does force pushes without explicit confirmation, protecting against:

Overwriting remote commits
Losing team members’ work
Destroying history

Environment Structure

The a2d CLI manages a multi-repository structure:

a2d-mocks/                         # Parent repository
├── a2d                            # This CLI script
├── mulesoft-mcp-mock-specs/       # Main app (submodule)
│   ├── app/                       # Next.js App Router
│   ├── lib/                       # Utilities
│   ├── components/                # React components
│   ├── supabase/                  # Migrations
│   ├── scripts/                   # Local Supabase scripts
│   ├── __tests__/                 # Test files
│   └── package.json               # Dependencies and test scripts
└── ma2d-docs/                     # Documentation site (submodule)
    └── pages/                     # MDX documentation

Submodule Commands

./a2d submodule init               # Initialize submodules
./a2d submodule update             # Update submodules to latest
./a2d submodule status             # Check submodule status

Configuration

Database Connection

When Supabase is running locally, the connection URL is:

postgresql://postgres:postgres@127.0.0.1:54322/postgres

The a2d start command automatically generates .env.supabase with all required credentials.

Environment Variables

Required variables (auto-generated by ./a2d start):

NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=<auto-generated>
SUPABASE_SERVICE_ROLE_KEY=<auto-generated>
A2D_PLATFORM_ADMIN_EMAILS=admin@test.local

Copy to .env.local:

cd mulesoft-mcp-mock-specs
cp .env.supabase .env.local

Troubleshooting

”Docker is not running”

Problem: The CLI cannot connect to Docker

Solution:

Start Docker Desktop
Wait for it to fully initialize (whale icon stops animating)
Retry your command

”Supabase CLI not found”

Problem: Supabase CLI is not installed

Solution:

# macOS
brew install supabase/tap/supabase
 
# Verify
supabase --version

“psql: command not found”

Problem: PostgreSQL client not installed

Solution:

# macOS
brew install libpq
brew link --force libpq
 
# Verify
psql --version

Tests fail with “Database connection error”

Problem: Supabase is not running

Solution:

./a2d start supabase
# Wait for it to complete
./a2d test integration

“Port already in use”

Problem: Another service is using port 3000 or Supabase ports

Solution:

# Stop existing services
./a2d stop
 
# Or kill processes manually
lsof -ti:3000 | xargs kill -9
lsof -ti:54321 | xargs kill -9

Submodules not initialized

Problem: mulesoft-mcp-mock-specs or ma2d-docs directories are empty

Solution:

./a2d submodule init
./a2d submodule update

Build fails after git pull

Problem: Dependencies changed

Solution:

cd mulesoft-mcp-mock-specs
npm install
./a2d test unit

Advanced Usage

Running Specific Test Files

cd mulesoft-mcp-mock-specs
 
# Run specific test file
npm test -- __tests__/api/admin-a2l.test.ts
 
# Run tests matching pattern
npm test -- --testNamePattern="approval"

Watch Mode for TDD

./a2d test watch
 
# In watch mode, press:
# a - run all tests
# f - run only failed tests
# p - filter by filename pattern
# t - filter by test name pattern
# q - quit watch mode

Coverage Reports

./a2d test coverage
 
# View HTML coverage report
cd mulesoft-mcp-mock-specs
open coverage/lcov-report/index.html

Interactive Test UI

./a2d test ui
 
# Opens Vitest UI in browser for visual test exploration

Continuous Integration

The a2d CLI is designed for both local development and CI environments:

GitHub Actions Example

name: Tests
on: [push, pull_request]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: recursive
 
      - uses: actions/setup-node@v3
        with:
          node-version: 18
 
      - name: Install Supabase CLI
        run: |
          brew install supabase/tap/supabase
 
      - name: Install dependencies
        run: |
          cd mulesoft-mcp-mock-specs
          npm ci
 
      - name: Start Supabase
        run: ./a2d start supabase
 
      - name: Run tests
        run: ./a2d test
 
      - name: Stop Supabase
        run: ./a2d stop supabase

Best Practices

1. Always Run Unit Tests First

Unit tests are fast and catch most issues:

./a2d test unit          # Takes seconds
./a2d test integration   # Takes longer, run after unit tests pass

2. Keep Supabase Running During Development

Avoid repeatedly starting/stopping:

# Start once in the morning
./a2d start
 
# Run tests many times
./a2d test unit
./a2d test integration
./a2d test api
 
# Stop at end of day
./a2d stop

3. Commit Often with Meaningful Messages

# ✅ Good - specific and clear
./a2d commit "Add user authentication flow"
./a2d commit "Fix MCP tool validation bug"
 
# ❌ Bad - vague
./a2d commit "updates"
./a2d commit "fixes"

4. Test Before Pushing

# Always run tests before pushing
./a2d test
./a2d commit "Feature X"
./a2d push

5. Use Feature Branches

# Don't work directly on develop
./a2d branch create feature/my-feature
 
# Make changes
./a2d commit "Implement feature"
./a2d push
./a2d pr create "Add my feature"

Comparison with Direct Scripts

Old Way (Direct Scripts)

cd mulesoft-mcp-mock-specs
./scripts/start-local-supabase.sh --quick
npm run dev
npm test
# ... later ...
npm run test:integration    # Might fail if Supabase stopped

New Way (a2d CLI)

./a2d start                  # Everything in one command
./a2d test unit             # Fast tests
./a2d test integration      # Auto-checks Supabase health
./a2d stop                  # Clean shutdown

Benefits:

✅ Unified interface - One command for everything
✅ Auto health checks - Validates Supabase before DB-dependent tests
✅ Better error messages - Clear guidance when something is wrong
✅ Git integration - Workflow automation included
✅ Safety features - Protected branches and confirmations

Command Cheat Sheet

Quick Reference

Task	Command
Show help	`./a2d help`
Start everything	`./a2d start`
Start only DB	`./a2d start supabase`
Stop everything	`./a2d stop`
Run unit tests	`./a2d test unit`
Run all tests	`./a2d test`
Create branch	`./a2d branch create feature-name`
Check status	`./a2d status`
Commit changes	`./a2d commit "message"`
Push to origin	`./a2d push`
Create PR	`./a2d pr create "title"`
Reset database	`./a2d reset supabase`

Next Steps

Local Development Setup - Detailed environment setup
Testing Framework - Learn about the test infrastructure
Contributing - How to contribute to A²D

Questions? Check the Troubleshooting section or open an issue.

Overview Local Development Setup