@rethink-paradigms/ui-lab-cli

CLI for the React UI Lab architecture – a structured, scalable, and agent-friendly way to build React applications.

Overview

ui-lab is a command-line tool designed to help teams and LLM agents build UI applications using the UI Lab Architecture. This architecture promotes:

• Feature Isolation: Each feature is a self-contained "island" with its own UI, state, services, and models.
• Explicit Public API: Features expose only what is necessary via public.ts.
• Agent-Friendliness: Structured specifically to help LLMs understand boundaries and context.
• Standardization: Enforces folder structures and naming conventions automatically.

Installation

You can run the CLI directly using npx or install it globally.

Using npx (Recommended)

npx @rethink-paradigms/ui-lab-cli <command>

Global Installation

npm install -g @rethink-paradigms/ui-lab-cli
# or
pnpm add -g @rethink-paradigms/ui-lab-cli

Usage

Initialize a new project structure:

ui-lab init

Create a new feature:

ui-lab add-feature user-profile --route /profile

Check project health and architecture compliance:

ui-lab check

Commands

Command	Description
init	Initialize the lab.config.json and project folders.
add-feature	Scaffold a new feature with all required subdirectories.
check	Validate the project structure and check for architectural violations.
sync-rules	Scan features for public exports and update capability registries.
promote-model	Move a model from a feature to the shared core models.
describe-feature	Show a summary of a feature's entities, services, and public API.
explain-feature-spec	Output a sample JSON spec for generating features.
generate-feature-from-spec	Generate a full feature implementation from a JSON spec.

For a detailed reference, see COMMANDS.md.

Project Structure

The CLI enforces a specific directory structure optimized for maintainability and agent reasoning:

src/
├── app/              # Next.js App Router (or other router)
├── features/         # Feature Islands
│   ├── auth/
│   │   ├── ui/       # React components
│   │   ├── state/    # State management (hooks/stores)
│   │   ├── services/ # API clients & business logic
│   │   ├── models/   # TypeScript types/interfaces
│   │   ├── docs/     # Feature-specific documentation
│   │   └── public.ts # Public API surface
├── shared/           # Shared utilities, UI kit, core models
├── llm/              # Agent configurations & registries
└── lab.config.json   # Configuration file

See ARCHITECTURE.md for a deep dive.

Configuration

The behavior of the CLI is controlled by lab.config.json in your project root.

{
  "ruleset": {
    "id": "react-ui-lab",
    "version": "1.0.0"
  },
  "paths": {
    "appDir": "app",
    "featuresDir": "src/features",
    "sharedDir": "src/shared",
    "llmDir": "src/llm",
    "docsDir": "docs"
  }
}

Contributing

We welcome contributors! Please read CONTRIBUTING.md to get started.

License

ISC