fluxwing-validator

Fluxwing Validator

Validate uxscii components and screens against JSON Schema with interactive workflows.

Overview

This skill provides two modes of operation:

1. Interactive Mode: User invocation with menu and minimal output
2. Direct Mode: Script calls from other skills with verbose output

When to Use This Skill

User says:

• "Validate my components"
• "Check if everything is valid"
• "Run validation on my screens"
• "Validate the project"

Other skills: Call validator scripts directly (see Technical Reference below)

Interactive Validation Workflow

Step 1: Present Validation Options

Use AskUserQuestion to present menu:

What would you like to validate?

Options:

1. Everything in this project - Validates all components and screens
2. Just components - Validates ./fluxwing/components/*.uxm
3. Just screens - Validates ./fluxwing/screens/*.uxm
4. Let me specify a file or pattern - Custom path/glob pattern

Step 2: Check What Exists

Before running validation, check if directories exist:

# Check for components
test -d ./fluxwing/components

# Check for screens
test -d ./fluxwing/screens

If neither exists:

• Inform user: "No components or screens found. Create some first!"
• Exit cleanly

If option 4 (custom) selected:

• Ask user for the pattern/file path
• Validate it's not empty
• Proceed with user-provided pattern

Step 3: Run Validation

Based on user selection:

Option 1: Everything

# Validate components
node {SKILL_ROOT}/validate-batch.js \
  "./fluxwing/components/*.uxm" \
  "{SKILL_ROOT}/../fluxwing-component-creator/schemas/uxm-component.schema.json" \
  --json

# Validate screens
node {SKILL_ROOT}/validate-batch.js \
  "./fluxwing/screens/*.uxm" \
  "{SKILL_ROOT}/../fluxwing-component-creator/schemas/uxm-component.schema.json" \
  --screens \
  --json

Option 2: Just components

node {SKILL_ROOT}/validate-batch.js \
  "./fluxwing/components/*.uxm" \
  "{SKILL_ROOT}/../fluxwing-component-creator/schemas/uxm-component.schema.json" \
  --json

Option 3: Just screens

node {SKILL_ROOT}/validate-batch.js \
  "./fluxwing/screens/*.uxm" \
  "{SKILL_ROOT}/../fluxwing-component-creator/schemas/uxm-component.schema.json" \
  --screens \
  --json

Option 4: Custom pattern

# Use user-provided pattern
node {SKILL_ROOT}/validate-batch.js \
  "${userPattern}" \
  "{SKILL_ROOT}/../fluxwing-component-creator/schemas/uxm-component.schema.json" \
  --json

Step 4: Parse Results and Show Minimal Summary

Parse JSON output from validator to extract:

• total: Total files validated
• passed: Number of valid files
• failed: Number of failed files
• warnings: Total warning count

Display minimal summary:

✓ 12/14 components valid
✗ 2/14 components failed
⚠ 3 warnings total

If all passed:

✓ All 14 components valid
⚠ 3 warnings

If everything failed:

✗ All 14 components failed

If nothing to validate:

No files found matching pattern

Step 5: Ask About Details

Use AskUserQuestion to ask:

Show error details?

Options:

1. Yes - Display full validation output
2. No - Clean exit

Step 6: Display Details (if requested)

If user selects "Yes", show full validation output including:

Failed files section:

Failed Files:

  ✗ broken-button (./fluxwing/components/broken-button.uxm)
    Errors: 2
      1. must have required property 'fidelity'
      2. ASCII template file not found

  ✗ old-card (./fluxwing/components/old-card.uxm)
    Errors: 1
      1. invalid version format

Passed with warnings section:

Passed with Warnings:

  ✓ login-screen (2 warnings)
  ✓ dashboard (1 warning)

Fully passed section (optional, only if not too many):

Fully Passed:

  ✓ primary-button
  ✓ secondary-button
  ✓ email-input
  ...

Edge Cases

No fluxwing directory exists

No components or screens found. Create some first!

Empty directories

✓ 0/0 components valid

Invalid glob pattern (option 4)

No files found matching pattern: ${pattern}

Validation script fails to execute

Error: Cannot execute validator. Node.js required.

Technical Reference (For Other Skills)

Direct Script Calls

Other skills (component-creator, screen-scaffolder) call validator scripts directly:

Validate single component:

node {SKILL_ROOT}/../fluxwing-validator/validate-component.js \
  ./fluxwing/components/button.uxm \
  {SKILL_ROOT}/schemas/uxm-component.schema.json

Validate single screen:

node {SKILL_ROOT}/../fluxwing-validator/validate-screen.js \
  ./fluxwing/screens/login-screen.uxm \
  {SKILL_ROOT}/schemas/uxm-component.schema.json

Batch validate:

node {SKILL_ROOT}/../fluxwing-validator/validate-batch.js \
  "./fluxwing/components/*.uxm" \
  {SKILL_ROOT}/schemas/uxm-component.schema.json

Output modes:

• Default: Human-readable (verbose, full errors/warnings)
• --json: Machine-readable JSON

Exit codes:

• 0: All files valid
• 1: One or more files invalid
• 2: Missing dependencies or invalid arguments

Validator Scripts

Available scripts:

• validate-component.js - Validate single component file
• validate-screen.js - Validate single screen file (with screen-specific checks)
• validate-batch.js - Validate multiple files with glob patterns
• test-validator.js - Test component templates
• test-screen-validator.js - Test screen templates

npm Scripts (for testing)

cd {SKILL_ROOT}

# Run tests
npm test                    # Test component templates
npm run test:screens       # Test screen templates

# Batch validation
npm run validate:components  # Validate all components
npm run validate:screens     # Validate all screens
npm run validate:all         # Validate everything

Example Interactions

Example 1: Validate Everything

User: "Validate my components"

Skill:

What would you like to validate?

1. Everything in this project
2. Just components
3. Just screens
4. Let me specify a file or pattern

User selects: Option 1

Skill runs validation and shows:

✓ 12/14 components valid
✗ 2/14 components failed
⚠ 3 warnings total

✓ 2/2 screens valid
⚠ 1 warning

Show error details?

User: "yes"

Skill shows full error details for failed files

Example 2: Validate Specific Pattern

User: "Validate my components"

Skill: (presents menu)

User selects: Option 4 (custom pattern)

Skill: "What file or pattern would you like to validate?"

User: "./fluxwing/components/*-button.uxm"

Skill validates and shows:

✓ 3/3 files valid

Show error details?

Implementation Notes

Parse JSON output:

const result = JSON.parse(bashOutput);
const total = result.total;
const passed = result.passed;
const failed = result.failed;
const warnings = result.warnings;

Summary formatting:

• Show passed/failed ratio for quick scan
• Highlight failures prominently
• Warnings shown but not intrusive
• Clean, minimal output by default

Error detail formatting:

• Group by status (failed, warnings, passed)
• Show file path and error count
• Display first 2-3 errors per file
• Indicate if more errors exist

---

Skill Status: Ready for use Version: 1.0.0