From ec9caa62838bb92f286cc601e76494c886259464 Mon Sep 17 00:00:00 2001 From: 7000pctAUTO Date: Fri, 30 Jan 2026 07:06:06 +0000 Subject: [PATCH] Add README, LICENSE, package.json, and CHANGELOG --- README.md | 340 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 338 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7ee7c04..48ffda0 100644 --- a/README.md +++ b/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 \ No newline at end of file +[![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 +``` + +### 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 ` | `gen` | Generate code from a spec | +| `completion ` | `comp` | Generate shell completions | +| `docs ` | - | Generate man page and README | +| `init` | `new` | Interactive spec wizard | +| `validate ` | `check` | Validate a spec file | +| `all ` | - | 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