@kaiord/cli 0.1.1 → 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pablo Albaladejo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -87,6 +87,62 @@ Example `tolerance.json`:
 }
 ```
 
+## Configuration File
+
+You can create a `.kaiordrc.json` file to set default options. The CLI will search for this file in:
+
+1. Current working directory
+2. User home directory (`~/.kaiordrc.json`)
+
+CLI options always take precedence over config file defaults.
+
+### Example Configuration
+
+Create `.kaiordrc.json` in your project or home directory:
+
+```json
+{
+  "defaultInputFormat": "fit",
+  "defaultOutputFormat": "krd",
+  "defaultOutputDir": "./converted",
+  "defaultToleranceConfig": "./tolerance.json",
+  "verbose": false,
+  "quiet": false,
+  "json": false,
+  "logFormat": "pretty"
+}
+```
+
+### Configuration Options
+
+- **defaultInputFormat**: Default input format (`fit`, `krd`, `tcx`, `zwo`)
+- **defaultOutputFormat**: Default output format (`fit`, `krd`, `tcx`, `zwo`)
+- **defaultOutputDir**: Default output directory for batch conversions
+- **defaultToleranceConfig**: Path to default tolerance configuration file
+- **verbose**: Enable verbose logging by default
+- **quiet**: Enable quiet mode by default
+- **json**: Enable JSON output by default
+- **logFormat**: Default log format (`pretty` or `structured`)
+
+### Usage with Config File
+
+With a config file, you can simplify your commands:
+
+```bash
+# Without config file
+kaiord convert --input workout.fit --output workout.krd --output-format krd
+
+# With config file (defaultOutputFormat: "krd")
+kaiord convert --input workout.fit --output workout.krd
+```
+
+CLI options override config defaults:
+
+```bash
+# Config has verbose: true, but --quiet overrides it
+kaiord convert --input workout.fit --output workout.krd --quiet
+```
+
 ## Global Options
 
 ### Verbosity Control
@@ -112,14 +168,6 @@ kaiord convert --input workout.fit --output workout.krd --log-format pretty
 kaiord convert --input workout.fit --output workout.krd --log-format json
 ```
 
-## Environment Variables
-
-The CLI automatically detects the environment and adjusts its behavior:
-
-- **CI=true**: Enables structured JSON logging
-- **NODE_ENV=production**: Enables structured JSON logging
-- **TTY detection**: Automatically disables colors and spinners in non-interactive environments
-
 ## Supported Formats
 
 - **FIT** (.fit) - Garmin's binary workout file format
@@ -127,47 +175,63 @@ The CLI automatically detects the environment and adjusts its behavior:
 - **TCX** (.tcx) - Training Center XML format
 - **ZWO** (.zwo) - Zwift workout XML format
 
-## Exit Codes
+### Plugin System (Future Enhancement)
 
-- **0**: Success
-- **1**: Error (invalid arguments, file not found, parsing error, validation error)
+The CLI is designed with a plugin architecture that will allow third-party developers to add support for custom workout file formats without modifying the core library. See [Plugin Architecture Documentation](./docs/plugin-architecture.md) for details on the design.
 
-## Troubleshooting
+**Planned Features:**
 
-### File Not Found
+- Dynamic plugin discovery and loading
+- Type-safe plugin interface
+- Automatic format detection for plugin formats
+- Plugin configuration via `.kaiordrc.json`
+- Plugin management commands (`kaiord plugins list`, `install`, etc.)
 
-Ensure the input file path is correct and the file exists:
+**Example Plugin Usage (Future):**
 
 ```bash
-ls -la workout.fit
-kaiord convert --input workout.fit --output workout.krd
+# Install a plugin
+npm install -g @kaiord/plugin-gpx
+
+# Use plugin format
+kaiord convert --input workout.gpx --output workout.krd
 ```
 
-### Permission Errors
+See [Example GPX Plugin](./docs/example-plugin-gpx.md) for a complete plugin implementation example.
 
-Check file permissions:
+## Exit Codes
 
-```bash
-chmod 644 workout.fit
-kaiord convert --input workout.fit --output workout.krd
-```
+- **0**: Success
+- **1**: Error (invalid arguments, file not found, parsing error, validation error)
 
-### Format Detection Issues
+## Documentation
 
-If automatic format detection fails, use explicit format flags:
+### Main Documentation
 
-```bash
-kaiord convert --input data.bin --input-format fit --output workout.krd --output-format krd
-```
+- **[Getting Started](../../docs/getting-started.md)** - Installation and basic usage
+- **[KRD Format Specification](../../docs/krd-format.md)** - Complete format documentation
+- **[Deployment Guide](../../docs/deployment.md)** - CI/CD and npm publishing
+
+### Package-Specific Documentation
 
-### Corrupted Files
+- **[npm Publish Verification](./docs/npm-publish-verification.md)** - Publishing checklist and verification
 
-If a file is corrupted, the CLI will display a descriptive error message:
+## Development
 
 ```bash
-kaiord convert --input corrupted.fit --output workout.krd
-# Error: Failed to parse FIT file
-# Details: Corrupted file header
+# Install dependencies
+pnpm install
+
+# Build the CLI
+pnpm build
+
+# Run in development mode
+pnpm dev -- convert --input workout.fit --output workout.krd
+
+# Link for local testing
+npm link
+kaiord --version
+npm unlink -g
 ```
 
 ## Testing
@@ -191,37 +255,6 @@ pnpm test:smoke
 pnpm test:watch
 ```
 
-## Development
-
-```bash
-# Install dependencies
-pnpm install
-
-# Build the CLI
-pnpm build
-
-# Run in development mode
-pnpm dev -- convert --input workout.fit --output workout.krd
-
-# Link for local testing
-npm link
-kaiord --version
-npm unlink -g
-```
-
-## Documentation
-
-For more information about the Kaiord project and the KRD format, see:
-
-- [Kaiord Core Library](https://github.com/your-org/kaiord/tree/main/packages/core)
-- [KRD Format Specification](https://github.com/your-org/kaiord/blob/main/docs/KRD_FORMAT.md)
-- [Contributing Guide](https://github.com/your-org/kaiord/blob/main/CONTRIBUTING.md)
-
 ## License
 
 MIT - See [LICENSE](../../LICENSE) file for details.
-
-## Support
-
-- Report issues: [GitHub Issues](https://github.com/your-org/kaiord/issues)
-- Ask questions: [GitHub Discussions](https://github.com/your-org/kaiord/discussions)