Add README, LICENSE, package.json, and CHANGELOG
This commit is contained in:
340
README.md
340
README.md
@@ -1,3 +1,339 @@
|
||||
# cli-spec-generator
|
||||
# CLI Spec Generator
|
||||
|
||||
A CLI tool that generates consistent argument parsers, shell completions, and man pages from YAML/JSON specifications
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://www.typescriptlang.org/)
|
||||
[](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
|
||||
|
||||
Reference in New Issue
Block a user