flowlock-uxcg

flowlock-uxcg (CLI)

Command-line interface for FlowLock UX validation and code generation.

Installation

# Global installation (recommended)
npm install -g flowlock-uxcg

# Local installation
npm install --save-dev flowlock-uxcg

Commands

uxcg init

Initialize a new FlowLock project with interactive prompts.

Options:

• Use current folder or scaffold new project
• Choose template (Blank or Next.js + Tailwind)
• Add Claude/Cursor command cards
• Setup GitHub Actions workflow
• Add npm scripts

Example:

uxcg init
# Follow interactive prompts

uxcg audit [--level <level>] [--fix]

Run validation checks on your UX specification with graduated validation levels.

Options:

• --level <level> - Validation level: basic|enhanced|strict (default: enhanced)
• --fix - Enable auto-healing for common issues
• --spec <file> - Specify spec file (default: uxspec.json)
• --outDir <dir> - Output directory (default: artifacts)
• --inventory - Require runtime inventory (auto-enabled for strict level)
• --only <checks> - Run only specific checks (comma-separated)
• --skip <checks> - Skip specific checks (comma-separated)
• --json - Output results as JSON
• --quiet - Suppress non-error output

Validation Levels:

• basic - Core 7 checks only for essential UX consistency
  • HONEST, CREATABLE, REACHABILITY, UI, STATE, SCREEN, SPEC
• enhanced (default) - Basic + Extended checks for comprehensive validation
  • Adds: JTBD, RELATIONS, ROUTES, CTAS, RUNTIME_DETERMINISM
• strict - Enhanced + Runtime checks for full system validation
  • Adds: INVENTORY, DATABASE_VALIDATION, MIGRATION_VALIDATION
  • Requires runtime inventory (run uxcg inventory first)

Auto-fix capabilities:

• Adds missing top-level roles
• Converts string roles to objects
• Infers screen types from names
• Ensures UI states (empty/loading/error)
• Generates missing IDs from names
• Assigns roles to screens

Examples:

# Basic validation (Core 7 checks only)
npx flowlock-uxcg audit --level=basic

# Enhanced validation (default)
npx flowlock-uxcg audit
# or explicitly
npx flowlock-uxcg audit --level=enhanced

# Strict validation (requires inventory)
npx flowlock-uxcg inventory  # Generate inventory first
npx flowlock-uxcg audit --level=strict

# With auto-fix at any level
npx flowlock-uxcg audit --level=basic --fix

# Custom paths
npx flowlock-uxcg audit --spec my-spec.json --outDir my-artifacts

# JSON output for CI/CD
npx flowlock-uxcg audit --level=enhanced --json

uxcg diagrams

Generate only diagram artifacts (ER and Flow diagrams).

Generates:

• er.mmd - Entity relationship Mermaid source
• er.svg - Entity relationship diagram
• flow.mmd - User flow Mermaid source
• flow.svg - User flow diagram

Example:

uxcg diagrams

uxcg export <format>

Export artifacts in specific formats.

Formats:

• junit - JUnit XML test results
• csv - Screen inventory spreadsheet
• svg - Diagram images

Example:

uxcg export junit
uxcg export csv
uxcg export svg

uxcg watch [options]

Watch mode for development with auto-refresh.

Options:

• --cloud - Enable cloud sync
• --cloudUrl <url> - Cloud endpoint URL
• --projectId <id> - Project identifier

Example:

# Basic watch mode
uxcg watch

# With cloud sync
uxcg watch --cloud --cloudUrl https://flowlock-cloud.onrender.com --projectId my-project

uxcg inventory [options]

Build runtime inventory from your codebase for strict validation.

Options:

• --config <path> - Path to flowlock.config.json (default: flowlock.config.json)
• --out <file> - Output file path (default: artifacts/runtime_inventory.json)
• --db-only - Extract only database entities
• --api-only - Extract only API endpoints
• --ui-only - Extract only UI reads/writes

Example:

# Build full inventory
npx flowlock-uxcg inventory

# Database entities only
npx flowlock-uxcg inventory --db-only

# Custom output location
npx flowlock-uxcg inventory --out my-inventory.json

uxcg agent [options]

Connect to FlowLock Cloud for remote command execution.

Options:

• --cloud <url> - Cloud base URL (required)
• --project <id> - Project ID (default: demo)
• --token <token> - Bearer token for authentication

Features:

• Polls for pending commands
• Executes audit/diagrams remotely
• Streams results to cloud dashboard
• Maintains persistent connection

Example:

uxcg agent --cloud https://flowlock-cloud.onrender.com --project my-app --token secret

Generated Artifacts

After running uxcg audit, the following files are created in the artifacts/ directory:

File	Description
er.mmd	Entity relationship diagram (Mermaid source)
er.svg	Entity relationship diagram (rendered)
flow.mmd	User flow diagram (Mermaid source)
flow.svg	User flow diagram (rendered)
screens.csv	Screen inventory with types and roles
results.junit.xml	Test results for CI/CD
gap_report.md	Detailed issues and recommendations
acceptance_criteria.feature	Gherkin test scenarios

Exit Codes

• 0 - Success, all checks passed
• 1 - Validation errors found
• 2 - Invalid specification or parse error

Environment Variables

• DEBUG=* - Enable verbose debug output
• NO_COLOR - Disable colored output

Programmatic Usage

const { spawn } = require('child_process');

// Run audit programmatically
const audit = spawn('uxcg', ['audit', '--fix']);

audit.stdout.on('data', (data) => {
  console.log(`Output: ${data}`);
});

audit.on('close', (code) => {
  if (code === 0) {
    console.log('Audit passed!');
  } else {
    console.error(`Audit failed with code ${code}`);
  }
});

Configuration Files

.claude/commands/

Auto-generated command cards for Claude/Cursor:

• ux-contract-init.md - Create/refine spec
• ux-guardrails-validate.md - Fix audit failures
• ux-generate-ui.md - Scaffold components
• flow-audit-fix.md - Close gaps

package.json Scripts

Add to your project:

{
  "scripts": {
    "flowlock:init": "uxcg init",
    "flowlock:audit": "uxcg audit",
    "flowlock:fix": "uxcg audit --fix",
    "flowlock:watch": "uxcg watch"
  }
}

Troubleshooting

Module not found

npm install -g flowlock-uxcg

Permission denied

Run terminal as administrator or use:

sudo npm install -g flowlock-uxcg

No diagrams generated

Install Mermaid CLI:

npm install -g @mermaid-js/mermaid-cli

License

MIT