npm package: @openverb/cli
Description: OpenVerb CLI tools
Latest version: 2.0.0-alpha.6

# @openverb/cli

Command-line tools for the OpenVerb Framework.

## Installation
```bash
npm install -g @openverb/cli
```

Or use with npx:
```bash
npx @openverb/cli --help
```

## Commands

### `openverb validate [path]`

Validate verb definitions.
```bash
# Validate all verbs in current directory
openverb validate

# Validate specific directory
openverb validate ./verbs

# Validate single file
openverb validate ./verbs/user.create.json
```

**Output:**
```
✓ user.create.json - Valid
✓ user.update.json - Valid
✗ todo.create.json - Invalid
  - inputSchema.properties.title: Required field missing
  - effects: Must be an array
```

### `openverb init [options]`

Initialize OpenVerb in a project.
```bash
# Interactive setup
openverb init

# With options
openverb init --typescript --example todo
```

**Options:**
- `--typescript` - Use TypeScript
- `--javascript` - Use JavaScript
- `--example <name>` - Include example verbs (todo, user, blog)

**Creates:**
```
openverb/
├── verbs/           # Verb definitions
│   └── example.ping.json
├── handlers/        # Handler implementations
│   └── example/
│       └── ping.ts
└── runtime.ts       # Runtime configuration
```

### `openverb generate <type> <name>`

Generate boilerplate code.
```bash
# Generate a verb + handler
openverb generate verb user.create

# Generate just a verb definition
openverb generate verb todo.update

# Generate a handler
openverb generate handler user/create
```

**Generated files:**
```
openverb/
├── verbs/
│   └── user.create.json    # Generated verb definition
└── handlers/
    └── user/
        └── create.ts       # Generated handler
```

## Verb Validation Rules

The validator checks:
- ✅ Required fields: `id`, `version`, `summary`, `handler`
- ✅ Schema validation: `inputSchema`, `outputSchema` are valid JSON Schema
- ✅ Effects array: Valid effect names
- ✅ ID format: Follows `namespace.action` pattern
- ✅ Version format: Semantic versioning (e.g., `1.0.0`)
- ✅ Handler path: Exists in handlers directory

## Example Workflow
```bash
# 1. Initialize project
openverb init --typescript

# 2. Generate a new verb
openverb generate verb user.register

# 3. Edit the generated files
# openverb/verbs/user.register.json
# openverb/handlers/user/register.ts

# 4. Validate before deployment
openverb validate

# 5. Deploy your app!
```

## Configuration

Create `.openverbrc.json` in your project:
```json
{
  "verbsDir": "./openverb/verbs",
  "handlersDir": "./openverb/handlers",
  "typescript": true
}
```

## Integration with Build Tools

### package.json scripts
```json
{
  "scripts": {
    "validate": "openverb validate",
    "generate": "openverb generate",
    "prebuild": "openverb validate"
  }
}
```

### CI/CD
```yaml
# .github/workflows/validate.yml
name: Validate Verbs
on: [push]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: npx @openverb/cli validate
```

## Related Packages

- [@openverb/runtime](https://www.npmjs.com/package/@openverb/runtime) - Execution runtime
- [@openverb/policy](https://www.npmjs.com/package/@openverb/policy) - Policy engine
- [@openverb/sdk](https://www.npmjs.com/package/@openverb/sdk) - Client SDK

## License

MIT