npm package: @servlyadmin/cli
Description: Servly component code generator - Generate typed component wrappers for your codebase
Author: Servly
Latest version: 0.2.1

# @servlyadmin/cli

Generate strongly-typed component wrappers for Servly components in your codebase.

## Features

- 🎯 **Full TypeScript Support** - Autocomplete, type checking, hover docs
- 🔧 **Multi-Framework** - React, Vue, Svelte, Angular, Solid
- 🤖 **AI-Friendly** - Generated context files for Cursor, Windsurf, MCP
- ⚡ **Fast** - Incremental updates, local caching
- 📦 **Zero Runtime Overhead** - Types are compile-time only
- 🎨 **Interactive Mode** - Visual component picker with categories
- 🌳 **Dependency Visualization** - See component dependency trees
- 💡 **Smart Error Messages** - Helpful suggestions when things go wrong

## Quick Start

```bash
# Install
npm install -D @servlyadmin/cli

# Initialize
npx servly init

# Generate typed components
npx servly generate
```

## Usage

```tsx
// Import generated components
import { PricingCard, ContactForm } from './.servly';

// Full TypeScript support!
<PricingCard
  title="Pro Plan"           // ✓ string
  price={2999}               // ✓ number
  features={['API Access']}  // ✓ string[]
  onSelect={(id) => {}}      // ✓ (id: string) => void
/>
```

## Commands

### `servly init`

Initialize `.servly` directory in your project.

```bash
npx servly init
npx servly init --framework react
npx servly init --output .servly
```

Options:
- `-f, --framework <framework>` - Target framework (react, vue, svelte, angular, solid, auto)
- `-o, --output <dir>` - Output directory (default: `.servly`)
- `-r, --registry <url>` - Registry URL
- `--no-ai-context` - Skip generating AI context files

### `servly generate`

Generate typed component wrappers from registry.

```bash
npx servly generate
npx servly generate --force
npx servly generate --components pricing-card,contact-form
npx servly generate --interactive
```

Options:
- `--force` - Force regeneration of all components
- `-f, --framework <framework>` - Target framework
- `-c, --components <ids>` - Comma-separated component IDs to generate
- `-e, --exclude <ids>` - Comma-separated component IDs to exclude
- `--dry-run` - Show what would be generated
- `-i, --interactive` - Interactive mode with component picker

#### Interactive Mode

Use `--interactive` or `-i` for a visual component selection experience:

```bash
npx servly generate --interactive
```

```
🎨 Servly Interactive Component Generator
──────────────────────────────────────────────────

Available Components:

  📁 Cards
      1. Pricing Card (5 props) - A pricing card for SaaS pages
      2. Feature Card (3 props) - Display a feature with icon

  📁 Forms
      3. Contact Form (4 props) - Contact form with validation

──────────────────────────────────────────────────

Selection Options:
  • Enter numbers separated by commas: 1,3,5
  • Enter a range: 1-5
  • Enter "all" to select all components
  • Enter "q" to cancel

Select components: 1,3
```

### `servly watch`

Watch for registry changes and regenerate.

```bash
npx servly watch
npx servly watch --interval 60000
```

Options:
- `-i, --interval <ms>` - Polling interval in milliseconds (default: 30000)

### `servly validate`

Validate generated files.

```bash
npx servly validate
```

### `servly info <componentId>`

Show detailed information about a component.

```bash
npx servly info pricing-card
```

### `servly deps <componentId>`

Show component dependency tree.

```bash
npx servly deps pricing-card
# Output:
# pricing-card (1.2.0)
# ├── feature-list (^1.0.0)
# │   └── icon-check (^2.0.0)
# └── button-primary (^1.2.0)
```

### `servly list`

List available components.

```bash
npx servly list
npx servly list --category cards
npx servly list --search pricing
```

Options:
- `-c, --category <category>` - Filter by category
- `-s, --search <query>` - Search components

## Configuration

Create `servly.config.json` in your project root:

```json
{
  "registry": {
    "url": "https://core-api.servly.app/v1/views/registry",
    "apiKey": "your-api-key"
  },
  "generate": {
    "outputDir": ".servly",
    "framework": "react",
    "typescript": true,
    "includeAIContext": true
  },
  "components": {
    "include": ["pricing-*", "contact-*"],
    "exclude": ["internal-*"]
  }
}
```

## Generated Structure

```
.servly/
├── index.ts              # Main exports
├── manifest.json         # Component metadata
├── ai-context.md         # AI documentation
├── .cursorrules          # Cursor AI rules
├── mcp-tools.json        # MCP server tools
├── types/
│   ├── index.d.ts        # Type exports
│   └── *.d.ts            # Per-component types
├── components/
│   ├── index.ts          # Component exports
│   └── *.tsx             # Component wrappers
└── hooks/
    ├── useServlyComponent.ts
    └── useServlyRegistry.ts
```

## Environment Variables

- `SERVLY_REGISTRY_URL` - Override registry URL
- `SERVLY_API_KEY` - API key for authentication
- `SERVLY_FRAMEWORK` - Default framework

## Error Messages

The CLI provides helpful error messages with suggestions:

```bash
# Authentication error
Error: Failed to fetch components from registry

Authentication required. Try one of:
  1. Add API key to servly.config.json:
     { "registry": { "apiKey": "sk_live_xxx" } }
  2. Set environment variable:
     export SERVLY_API_KEY=sk_live_xxx
  3. Get an API key at: https://servly.app/developers/api-keys

# Component not found
No components found to generate

Did you mean one of these?
  • pricing-card - Pricing Card
  • pricing-table - Pricing Table

Run 'servly list' to see available components.
```

## Requirements

- Node.js >= 18.0.0
- One of: React, Vue, Svelte, Angular, or Solid

## License

MIT