# CLI Spec Generator

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)

A powerful CLI tool that generates consistent argument parsers, shell completions, and man pages from a simple YAML/JSON specification file. Define your CLI interface once in a declarative format, and automatically generate code for multiple languages.

## Features

- **Multi-Language Code Generation**: Python argparse, Go flag, Rust clap, Node.js commander/yargs
- **Shell Completions**: Auto-generate completions for Bash, Zsh, and Fish
- **Documentation**: Generate man pages and README documentation
- **Interactive Wizard**: Create specs interactively with the built-in wizard
- **Validation**: Catch errors early with built-in spec validation
- **Type Safety**: Written in TypeScript with full type definitions

## Installation

### Global Installation

```bash
npm install -g cli-spec-generator
```

### Using npx

```bash
npx cli-spec-generator <command>
```

### From Source

```bash
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/cli-spec-generator.git
cd cli-spec-generator
npm install
npm run build
npm link
```

## Quick Start

### 1. Create a Specification File

Create a file named `my-cli.yaml` with your CLI definition:

```yaml
name: my-cli
version: 1.0.0
description: My awesome CLI tool
author: John Doe
bin: my-cli

globalOptions:
  - name: verbose
    short: v
    description: Enable verbose output
    type: boolean
    default: false

commands:
  - name: start
    description: Start the service
    options:
      - name: port
        short: p
        description: Port number
        type: number
        default: 8080
    arguments:
      - name: service
        description: Service name
        required: true
```

### 2. Generate Code

Generate code for all supported languages:

```bash
cli-spec-gen all my-cli.yaml -o generated/
```

### 3. Generate Shell Completions

```bash
cli-spec-gen completion my-cli.yaml --all -o generated/
```

### 4. Generate Documentation

```bash
cli-spec-gen docs my-cli.yaml -o generated/
```

## Command Reference

| Command | Alias | Description |
|---------|-------|-------------|
| `generate <file>` | `gen` | Generate code from a spec |
| `completion <file>` | `comp` | Generate shell completions |
| `docs <file>` | - | Generate man page and README |
| `init` | `new` | Interactive spec wizard |
| `validate <file>` | `check` | Validate a spec file |
| `all <file>` | - | Generate everything |

### Global Options

| Option | Description |
|--------|-------------|
| `-l, --language` | Target language for code generation |
| `-o, --output` | Output directory |
| `-s, --shell` | Target shell for completions |
| `--all` | Generate for all languages/shells |
| `--help` | Show help |
| `--version` | Show version |

## Specification Format

### Basic Structure

```yaml
name: cli-name           # CLI name (kebab-case, required)
version: 1.0.0           # Semantic version (required)
description: Description # Brief description (required)
author: Name             # Optional author name
license: MIT             # Optional license identifier
bin: cli-name           # Binary name (defaults to name)
```

### Global Options

Options available to all commands:

```yaml
globalOptions:
  - name: verbose        # Long flag name (required)
    short: v            # Optional short flag
    description: Enable verbose output
    type: string        # string, number, boolean, array
    required: false     # Whether option is required
    default: value      # Default value
    choices: [a, b, c]  # Allowed values
```

### Commands

```yaml
commands:
  - name: start          # Command name (required)
    description: Start the service
    options:             # Command-specific options
      - name: port
        type: number
    arguments:           # Positional arguments
      - name: service
        required: true
    subcommands:         # Nested subcommands
      - name: child
        description: Child command
```

### Arguments

```yaml
arguments:
  - name: input          # Argument name (required)
    description: Input file path
    required: true       # Default is true
    variadic: false      # Accept multiple values
```

### Examples

```yaml
examples:
  - description: Start the server
    command: my-cli start api-server
    output: "Server started on port 8080"
```

## Supported Languages

| Language | Library | Extension |
|----------|---------|-----------|
| Python | argparse | `.py` |
| Go | flag | `.go` |
| Rust | clap | `.rs` |
| Node.js | commander | `.js` |
| Node.js | yargs | `.js` |

## Shell Completions

| Shell | File | Install |
|-------|------|---------|
| Bash | `_cli-name.bash` | `source _cli-name.bash` |
| Zsh | `_cli-name.zsh` | `~/.zsh/completion/` |
| Fish | `_cli-name.fish` | `~/.config/fish/completions/` |

## Examples

### Generate Python Code Only

```bash
cli-spec-gen generate my-cli.yaml -l python
```

### Generate All Shell Completions

```bash
cli-spec-gen completion my-cli.yaml --all
```

### Generate Specific Shell Completion

```bash
cli-spec-gen completion my-cli.yaml -s zsh
```

### Interactive Spec Creation

```bash
cli-spec-gen init -o my-cli.yaml
```

### Validate a Spec

```bash
cli-spec-gen validate my-cli.yaml
```

## Generated Output Structure

```
output/
├── python/
│   └── my-cli.py
├── go/
│   └── my-cli.go
├── rust/
│   └── my-cli.rs
├── node-commander/
│   └── my-cli.js
├── node-yargs/
│   └── my-cli.js
├── completions/
│   ├── _my-cli.bash
│   ├── _my-cli.zsh
│   └── _my-cli.fish
└── docs/
    ├── my-cli.1
    └── CLI_DOCS.md
```

## API Usage

### Programmatic Usage

```typescript
import { generateAll } from 'cli-spec-generator';

const spec = await parseSpec('my-cli.yaml');
await generateAll(spec, { output: './generated' });
```

### Available Functions

- `parseSpec(filePath)`: Parse a YAML/JSON spec file
- `generateCode(spec, language)`: Generate code for a specific language
- `generateCompletions(spec, shell)`: Generate completions for a shell
- `generateDocs(spec)`: Generate documentation
- `validateSpec(spec)`: Validate a spec file
- `runWizard()`: Run interactive spec wizard

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/my-feature`
3. Commit changes: `git commit -am 'Add my feature'`
4. Push to branch: `git push origin feature/my-feature`
5. Submit a Pull Request

### Development Setup

```bash
# Clone the repository
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/cli-spec-generator.git
cd cli-spec-generator

# Install dependencies
npm install

# Run development build
npm run dev

# Run tests
npm test

# Run linting
npm run lint

# Format code
npm run format
```

### Adding New Templates

1. Create a Handlebars template in `src/templates/`
2. Add the template to the appropriate generator
3. Update the language/shell mappings
4. Add tests

## Testing

```bash
# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch
```

## Versioning

This project uses [Semantic Versioning](https://semver.org/). See [CHANGELOG.md](./CHANGELOG.md) for version history.

## License

This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.

## Support

- Create an [issue](https://7000pct.gitea.bloupla.net/7000pctAUTO/cli-spec-generator/issues) for bugs
- Start a [discussion](https://7000pct.gitea.bloupla.net/7000pctAUTO/cli-spec-generator/discussions) for questions
- Read the [wiki](https://7000pct.gitea.bloupla.net/7000pctAUTO/cli-spec-generator/wiki) for documentation