🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Supernal Interface CLI
πŸ¦€ ClawHub

Supernal Interface CLI

by @ianderrington

CLI tool for generating tests, scanning contracts, managing story-based tests, and setting up MCP integration in web projects.

Versionv1.0.0
Downloads769
#writing#legal
TERMINAL
clawhub install si

πŸ“– About This Skill

name: si description: Supernal Interface CLI for test generation, contract scanning, story system, and MCP setup. Use when: (1) scanning Next.js routes/components for contracts, (2) generating tests from @Tool decorators, (3) recording/validating story-based tests, (4) setting up MCP integration, (5) validating contracts. NOT for: task management (use sc), orchestration (use orch), or CLI/API generation patterns (use universal-command).

si - Supernal Interface CLI

Test generation, contract scanning, story-based testing, and MCP setup for web applications.

Installation

npm install -g @supernal/interface

Quick Reference

Contract Generation & Scanning

# Scan Next.js pages β†’ generate route contracts
si scan-routes
si scan-routes -p ./src/pages -o ./src/routes/Routes.ts
si scan-routes --framework nextjs --watch        # Watch mode
si scan-routes --git-commit                      # Auto-commit
Scan components β†’ generate name contracts (data-testid)

si scan-names
si scan-names -c ./src/components -o ./src/names/Components.ts
si scan-names --flat                             # Components.Header vs Header.submitButton
iOS-specific scanning

si scan-ios-views      # SwiftUI views β†’ component names
si scan-ios-routes     # SwiftUI navigation β†’ route contracts
si scan-ios-names      # Swift accessibility identifiers

Validation

si validate --all                    # Validate everything
si validate --routes           # Validate route contracts
si validate --names            # Validate name contracts
si validate --tools                  # Validate @Tool decorators
si validate --no-cache               # Force refresh
si validate-graph                    # Detect broken links, orphan routes

Test Generation

# From @Tool decorators
si generate-tests
si generate-tests --tools src/tools/index.ts
si generate-tests --include-e2e      # Add Playwright E2E tests
si generate-tests -f jest            # Framework: jest (default)
From Gherkin feature files

si generate-story-tests        # Multi-platform test generation

Story System (BDD Testing)

# Record story videos
si story record          # Record .story.ts execution
Test without video

si story test          # Run Gherkin scenarios
Validate before running

si story validate      # Check syntax, steps, components
List available steps

si story list-steps                  # Show allowed Gherkin patterns
si list-steps                        # Alias

Testing Commands

# Graph-based testing (routes graph)
si test graph                        # All modes: visual, perf, a11y, SEO
si test graph --modes visual,performance
si test graph --start-url /dashboard
Shortcuts

si test visual                       # Visual regression (screenshots)
si test performance                  # Core Web Vitals, Lighthouse
si test a11y                         # WCAG compliance (axe-core)
Record test video

si test record            # Playwright video capture
si record                 # Alias

Project Setup

# Initialize in Next.js project
si init                              # Current directory
si init ./my-project                 # Specific directory
si init --scan-only                  # Report only, no generation
si init --inject                     # Inject data-testid into components
si init --migrate                    # Migrate imports to contracts
si init --dry-run                    # Preview changes
si init --revert                     # Restore from backups
Route migration

si migrate-routes                    # Migrate hardcoded strings β†’ Routes

MCP Setup

# Fully automated MCP setup (zero manual steps)
si setup-mcp                         # Configure IDE + create server
si setup-mcp --force                 # Overwrite existing
si setup-mcp --skip-test             # Skip server startup test
si setup-mcp --manual                # Create files only, skip IDE config
Claude Code integration

si setup-claude                      # Install skills + agents

Utilities

si cache-tools                 # Cache @Tool decorators
si benchmark-cache                   # Test caching performance
si feedback                          # File GitHub issue

Common Patterns

New Project Setup

cd my-nextjs-project
si init
si scan-routes
si scan-names
si setup-mcp

Pre-PR Validation

si validate --all
si test visual                       # Check for visual regressions
si test a11y                         # Accessibility compliance

Story-Driven Development

# 1. Write Gherkin feature
echo 'Feature: Login
  Scenario: Valid credentials
    Given I am on the login page
    When I enter valid credentials
    Then I should see the dashboard' > login.feature
2. Validate

si story validate login.feature
3. Create story implementation (.story.ts)


4. Record demonstration

si story record login.story.ts
5. Generate tests

si generate-story-tests login.feature

Contract-First Development

# Generate contracts from existing code
si scan-routes --git-commit
si scan-names --git-commit
Validate contracts stay in sync

si validate --routes ./src/routes/Routes.ts
si validate --names ./src/names/Components.ts

Integration with Other Tools

| Tool | Relationship | |------|--------------| | sc | Task management, project health β€” use sc for dev workflow | | orch | Agent orchestration β€” si focuses on testing/contracts | | universal-command | si uses universal-command pattern internally for CLI/API/MCP |

Environment

  • Routes file: ./src/routes/Routes.ts (default)
  • Names file: ./src/names/Components.ts (default)
  • Tests output: ./tests/generated/ (default)
  • Framework: Next.js (default), React Router supported

    • πŸ”’ Constraints

    si validate --all                    # Validate everything
si validate --routes           # Validate route contracts
si validate --names            # Validate name contracts
si validate --tools                  # Validate @Tool decorators
si validate --no-cache               # Force refresh
    si validate-graph                    # Detect broken links, orphan routes

    Test Generation

    # From @Tool decorators
si generate-tests
si generate-tests --tools src/tools/index.ts
si generate-tests --include-e2e      # Add Playwright E2E tests
si generate-tests -f jest            # Framework: jest (default)
    From Gherkin feature files
    
si generate-story-tests        # Multi-platform test generation

    Story System (BDD Testing)

    # Record story videos
si story record          # Record .story.ts execution
    Test without video
    
si story test          # Run Gherkin scenarios
    Validate before running
    
si story validate      # Check syntax, steps, components
    List available steps
    
si story list-steps                  # Show allowed Gherkin patterns
si list-steps                        # Alias

    Testing Commands

    # Graph-based testing (routes graph)
si test graph                        # All modes: visual, perf, a11y, SEO
si test graph --modes visual,performance
si test graph --start-url /dashboard
    Shortcuts
    
si test visual                       # Visual regression (screenshots)
si test performance                  # Core Web Vitals, Lighthouse
si test a11y                         # WCAG compliance (axe-core)
    Record test video
    
si test record            # Playwright video capture
si record                 # Alias

    Project Setup

    # Initialize in Next.js project
si init                              # Current directory
si init ./my-project                 # Specific directory
si init --scan-only                  # Report only, no generation
si init --inject                     # Inject data-testid into components
si init --migrate                    # Migrate imports to contracts
si init --dry-run                    # Preview changes
si init --revert                     # Restore from backups
    Route migration
    
si migrate-routes                    # Migrate hardcoded strings β†’ Routes

    MCP Setup

    # Fully automated MCP setup (zero manual steps)
si setup-mcp                         # Configure IDE + create server
si setup-mcp --force                 # Overwrite existing
si setup-mcp --skip-test             # Skip server startup test
si setup-mcp --manual                # Create files only, skip IDE config
    Claude Code integration
    
si setup-claude                      # Install skills + agents

    Utilities

    si cache-tools                 # Cache @Tool decorators
si benchmark-cache                   # Test caching performance
si feedback                          # File GitHub issue