Initial upload: config-converter-cli v1.0.0

README.md

@@ -1,3 +1,228 @@
-# config-converter-cli
+# ConfigConverter CLI
 
-A CLI tool for real-time bidirectional conversion and validation between JSON, YAML, and TOML formats with JMESPath query support.
+A CLI tool for real-time bidirectional conversion and validation between JSON, YAML, and TOML formats with JMESPath query support.
+
+## Features
+
+- **Bidirectional Format Conversion**: Convert between JSON, YAML, and TOML formats
+- **Syntax Validation**: Validate configuration files with colored error output
+- **Pretty-Printing**: Format output with configurable indentation levels (2, 4, 8 spaces)
+- **JMESPath Query Support**: Filter and extract data using JMESPath queries
+- **Stdin/Stdout Pipeline Support**: Read from stdin and write to stdout for pipeline integration
+- **Batch File Processing**: Process multiple files in batch mode
+
+## Installation
+
+```bash
+pip install config-converter-cli
+```
+
+Or install from source:
+
+```bash
+git clone <repository>
+cd config-converter-cli
+pip install -e .
+```
+
+## Quick Start
+
+### Convert a file
+
+```bash
+# Convert JSON to YAML
+config-converter convert config.json --to yaml -o config.yaml
+
+# Convert YAML to TOML
+config-converter convert config.yaml --to toml
+
+# Convert with custom indentation
+config-converter convert config.json --to yaml --indent 4
+```
+
+### Validate a file
+
+```bash
+# Validate a JSON file
+config-converter validate config.json
+
+# Validate with format hint
+config-converter validate config.cfg --format yaml
+
+# Quiet mode (only exit code)
+config-converter validate --quiet config.json
+```
+
+### Query data
+
+```bash
+# Query a specific key
+config-converter query config.json "server.host"
+
+# Query nested values
+config-converter query config.yaml "database.settings.port"
+
+# Use JMESPath expressions
+config-converter query config.json "services[?enabled==`true`].name"
+```
+
+### Format/pretty-print
+
+```bash
+# Format with 4-space indentation
+config-converter format config.json --indent 4
+
+# Convert and format
+config-converter format config.yaml --to json
+```
+
+### Batch processing
+
+```bash
+# Convert multiple files
+config-converter batch *.json --to yaml
+
+# Convert to output directory
+config-converter batch config1.yaml config2.yaml --to toml --output-dir converted/
+```
+
+## Commands
+
+### convert
+
+Convert a configuration file from one format to another.
+
+```bash
+config-converter convert [OPTIONS] [INPUT_FILE]
+```
+
+Options:
+- `--from, -f FORMAT`: Input format (auto-detected if not specified)
+- `--to, -t FORMAT`: Output format (required)
+- `--indent, -i LEVEL`: Indentation level (2, 4, or 8)
+- `--output, -o FILE`: Output file
+- `--validate/--no-validate`: Validate input before conversion
+
+### validate
+
+Validate the syntax of a configuration file.
+
+```bash
+config-converter validate [OPTIONS] [INPUT_FILE]
+```
+
+Options:
+- `--format, -F FORMAT`: Format hint (auto-detected if not specified)
+- `--quiet, -q`: Only return exit code, no output
+
+### query
+
+Query configuration data using JMESPath.
+
+```bash
+config-converter query [OPTIONS] [INPUT_FILE] EXPRESSION
+```
+
+Options:
+- `--format, -F FORMAT`: Format hint (auto-detected if not specified)
+- `--output, -o FORMAT`: Output format (json or text)
+
+### format
+
+Format/pretty-print a configuration file.
+
+```bash
+config-converter format [OPTIONS] [INPUT_FILE]
+```
+
+Options:
+- `--indent, -i LEVEL`: Indentation level (2, 4, or 8)
+- `--to, -t FORMAT`: Output format
+- `--compact, -c`: Use compact output
+
+### batch
+
+Convert multiple files in batch mode.
+
+```bash
+config-converter batch [OPTIONS] INPUT_FILES...
+```
+
+Options:
+- `--from, -f FORMAT`: Input format (auto-detected if not specified)
+- `--to, -t FORMAT`: Output format (required)
+- `--indent, -i LEVEL`: Indentation level (2, 4, or 8)
+- `--output-dir, -o DIR`: Output directory for converted files
+
+## Pipeline Support
+
+All commands support stdin/stdout with `-`:
+
+```bash
+# Read from stdin
+cat config.json | config-converter convert --to yaml
+
+# Write to stdout
+config-converter convert config.json --to yaml > config.yaml
+
+# Chained pipelines
+cat config.json | config-converter query "server" | config-converter format --indent 4
+```
+
+## Examples
+
+### CI/CD Pipeline Integration
+
+```bash
+# Validate configuration in CI
+config-converter validate --quiet config/$ENV/config.json || exit 1
+
+# Convert and deploy
+config-converter convert config/$ENV/app.json --to yaml | kubectl apply -f -
+```
+
+### Configuration Transformation
+
+```bash
+# Extract specific settings
+config-converter query config.json "database.settings" > db_settings.json
+
+# Reformat with consistent indentation
+config-converter format config.yaml --indent 4 --to json > config_formatted.json
+```
+
+### JMESPath Queries
+
+```bash
+# Get all enabled services
+config-converter query config.json "services[?enabled==`true`].name"
+
+# Get nested values
+config-converter query config.yaml "server.tls.cert_path"
+
+# Transform output
+config-converter query config.json "{host: server.host, port: server.port}"
+```
+
+## Configuration
+
+No configuration file required. All options are passed via command-line arguments.
+
+## Error Handling
+
+The tool provides detailed error messages with:
+- Line and column numbers for syntax errors
+- Colored output for better visibility
+- Context snippets around error locations
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests: `pytest -v`
+5. Submit a pull request
+
+## License
+
+MIT License