@eldrforge/kodrdriv 0.0.14 → 0.0.17

package/docs/public/configuration.md

@@ -1,274 +0,0 @@
-# Configuration
-
-KodrDriv provides flexible configuration options through command-line arguments, configuration files, and environment variables. This section covers all available configuration methods and options.
-
-## Configuration File
-
-You can create a `config.json` file in your `.kodrdriv` directory to set default options for all commands. This allows you to avoid repeating command-line options and ensures consistent behavior across your project.
-
-Example configuration file (`.kodrdriv/config.json`):
-
-```json
-{
-  "model": "gpt-4o-mini",
-  "verbose": true,
-  "contextDirectories": ["src", "docs"],
-  "publish": {
-    "mergeMethod": "merge",
-    "dependencyUpdatePatterns": ["@company/*", "@myorg/*"],
-    "requiredEnvVars": ["NODE_AUTH_TOKEN", "CUSTOM_TOKEN"],
-    "linkWorkspacePackages": true,
-    "unlinkWorkspacePackages": true
-  },
-  "commit": {
-    "add": true,
-    "messageLimit": 5
-  },
-  "release": {
-    "from": "main",
-    "to": "HEAD",
-    "messageLimit": 10
-  },
-  "link": {
-    "scopeRoots": {
-      "@company": "../",
-      "@myorg": "../../org-packages/",
-      "@tools": "../shared-tools/"
-    },
-    "workspaceFile": "pnpm-workspace.yaml"
-  },
-  "excludedPatterns": [
-    "node_modules",
-    "dist",
-    "*.log"
-  ]
-}
-```
-
-Configuration options set in the file can be overridden by command-line arguments. The precedence order is:
-1. Command-line arguments (highest priority)
-2. Configuration file
-3. Default values (lowest priority)
-
-## Hierarchical Configuration
-
-KodrDriv supports hierarchical configuration, which means it will automatically search for and merge configuration files from parent directories. This allows you to set global defaults at higher directory levels while still being able to override them for specific projects.
-
-**How it works:**
-
-1. **Directory Traversal**: Starting from your current working directory, KodrDriv searches upward through parent directories looking for `.kodrdriv/config.json` or `.kodrdriv/config.yaml` files.
-
-2. **Automatic Merging**: Configuration files found in parent directories are merged together, with configurations closer to your current directory taking precedence over those higher up.
-
-3. **Final Override**: Command-line arguments have the highest precedence and will override any configuration file settings.
-
-**Example Hierarchy:**
-
-```
-/home/user/
-├── .kodrdriv/
-│   └── config.json          # Global user defaults
-└── projects/
-    ├── .kodrdriv/
-    │   └── config.json      # Project-specific defaults
-    └── my-app/
-        ├── .kodrdriv/
-        │   └── config.json  # App-specific overrides
-        └── src/             # Your working directory
-```
-
-When running KodrDriv from `/home/user/projects/my-app/src/`, the configuration hierarchy would be:
-
-1. **Base defaults** (built into KodrDriv)
-2. **Global config** (`/home/user/.kodrdriv/config.json`)
-3. **Project config** (`/home/user/projects/.kodrdriv/config.json`)
-4. **App config** (`/home/user/projects/my-app/.kodrdriv/config.json`)
-5. **Command-line arguments** (highest priority)
-
-**Use Cases:**
-
-- **Team Standards**: Store team-wide configuration defaults in your repository root
-- **Personal Preferences**: Keep personal defaults in your home directory
-- **Project-Specific Settings**: Override settings for specific projects or environments
-- **Monorepo Management**: Different packages in a monorepo can have their own settings while inheriting common defaults
-
-**Debugging Configuration:**
-
-Use the `--check-config` flag to see exactly how your configuration is being merged:
-
-```bash
-kodrdriv --check-config
-```
-
-This will show you which configuration files are being loaded and how the final configuration values are determined.
-
-## Configuration Directory
-
-KodrDriv uses a configuration directory to store custom settings, instructions, and other configuration files. You can specify a custom location using the `--config-dir` option:
-
-```bash
-kodrdriv --config-dir ~/custom-kodrdriv-config
-```
-
-By default, the configuration directory is set to `.kodrdriv` in your current working directory. This directory is created automatically if it doesn't exist.
-
-The configuration directory structure is as follows:
-
-```
-.kodrdriv/
-├── instructions/
-│   ├── commit.md         # Override for commit instructions
-│   ├── commit-pre.md     # Content prepended to default commit instructions
-│   ├── commit-post.md    # Content appended to default commit instructions
-│   ├── release.md        # Override for release instructions
-│   ├── release-pre.md    # Content prepended to default release instructions
-│   └── release-post.md   # Content appended to default release instructions
-├── config.json           # Main configuration file
-└── ...                   # Other configuration files
-```
-
-## Environment Variables
-
-### OpenAI Configuration
-
-KodrDriv requires OpenAI API credentials for AI-powered features:
-
-- `OPENAI_API_KEY`: OpenAI API key (required)
-
-You can also set these via command line:
-
-- `--openai-api-key <key>`: OpenAI API key
-- `--model <model>`: OpenAI model to use (default: 'gpt-4o-mini')
-
-> [!NOTE]
-> ### Security Considerations
-> 
-> The OpenAI API key should be handled securely. While the `--openai-api-key` option is available, it's recommended to use environment variables instead. KodrDriv automatically loads environment variables from a `.env` file in your current working directory.
-> 
-> While environment variables are a common approach for configuration, they can still pose security risks if not properly managed. We strongly encourage users to utilize secure credential management solutions like 1Password, HashiCorp Vault, or other keystores to protect sensitive information. This helps prevent accidental exposure of API keys and other credentials in logs, process listings, or environment dumps.
-
-### GitHub Configuration
-
-For publish command functionality:
-
-- `GITHUB_TOKEN`: Required for GitHub API operations (creating pull requests, releases, etc.)
-
-### Additional Environment Variables
-
-The publish command supports configurable additional environment variables specific to your project:
-
-```json
-{
-  "publish": {
-    "requiredEnvVars": [
-      "NODE_AUTH_TOKEN",
-      "DEPLOY_KEY", 
-      "CUSTOM_API_TOKEN",
-      "CODECOV_TOKEN"
-    ]
-  }
-}
-```
-
-## Content Configuration
-
-Control what content is included in analysis:
-
-- `-c, --content-types [types...]`: Content types to include in the summary (default: ['diff'])
-  - Available types: 'log', 'diff'
-  - Can specify multiple types: `--content-types log diff`
-
-## Excluded Patterns
-
-Filter out specific files or directories from analysis:
-
-- `--excluded-paths [excludedPatterns...]`: Paths to exclude from the diff (can specify multiple patterns)
-
-Examples:
-```bash
-# Exclude specific files or directories from diff analysis
-kodrdriv commit --excluded-paths "*.lock" "dist/" "node_modules/"
-
-# Exclude patterns from release notes
-kodrdriv release --excluded-paths "package-lock.json" "pnpm-lock.yaml"
-```
-
-You can also configure excluded patterns in your configuration file:
-
-```json
-{
-  "excludedPatterns": [
-    "node_modules",
-    "dist",
-    "*.log",
-    "*.lock"
-  ]
-}
-```
-
-## Command-Specific Configuration
-
-### Commit Configuration
-
-```json
-{
-  "commit": {
-    "add": true,
-    "messageLimit": 5,
-    "cached": false,
-    "sendit": false
-  }
-}
-```
-
-### Release Configuration
-
-```json
-{
-  "release": {
-    "from": "main",
-    "to": "HEAD",
-    "messageLimit": 10
-  }
-}
-```
-
-### Publish Configuration
-
-```json
-{
-  "publish": {
-    "mergeMethod": "squash",
-    "dependencyUpdatePatterns": ["@company/*"],
-    "requiredEnvVars": ["NODE_AUTH_TOKEN"],
-    "linkWorkspacePackages": true,
-    "unlinkWorkspacePackages": true
-  }
-}
-```
-
-### Link Configuration
-
-```json
-{
-  "link": {
-    "scopeRoots": {
-      "@company": "../",
-      "@myorg": "../../org-packages/"
-    },
-    "workspaceFile": "pnpm-workspace.yaml"
-  }
-}
-```
-
-## Basic Options
-
-Global options that apply to all commands:
-
-- `--dry-run`: Perform a dry run without saving files (default: false)
-- `--verbose`: Enable verbose logging (default: false)
-- `--debug`: Enable debug logging (default: false)
-- `--overrides`: Enable instruction overrides (allows custom instruction files to override defaults)
-- `--config-dir <configDir>`: Specify a custom configuration directory (default: '.kodrdriv')
-- `--check-config`: Display the current configuration hierarchy showing how values are merged from defaults, config files, and CLI arguments. This is useful for debugging configuration issues and understanding which settings are active.
-- `--version`: Display version information 

package/docs/public/examples.md

@@ -1,352 +0,0 @@
-# Examples
-
-This section provides practical examples of using KodrDriv commands in various scenarios.
-
-## Basic Usage Examples
-
-### Commit Examples
-
-Basic commit message generation:
-```bash
-kodrdriv commit
-```
-
-Generate a commit message and automatically commit it:
-```bash
-kodrdriv commit --sendit
-```
-
-Use custom context and message limit:
-```bash
-kodrdriv commit --context "Refactoring for performance" --message-limit 5
-```
-
-Work with staged changes only:
-```bash
-git add src/components/
-kodrdriv commit --cached
-```
-
-### Release Examples
-
-Basic release notes generation:
-```bash
-kodrdriv release
-```
-
-Generate release notes for a specific range:
-```bash
-kodrdriv release --from v1.0.0 --to v1.1.0
-```
-
-Include both git log and diff information:
-```bash
-kodrdriv release --content-types log diff
-```
-
-Use custom context for quarterly release:
-```bash
-kodrdriv release --context "Quarterly release, focus on stability" --message-limit 20
-```
-
-### Publish Examples
-
-Basic publish with default settings:
-```bash
-kodrdriv publish
-```
-
-Publish with different merge methods:
-```bash
-# Use merge commit (preserves individual commits)
-kodrdriv publish --merge-method merge
-
-# Use rebase (clean linear history)
-kodrdriv publish --merge-method rebase
-```
-
-### Link Examples
-
-Basic linking with single scope:
-```bash
-kodrdriv link --scope-roots '{"@company": "../"}'
-```
-
-Multiple scopes with different root directories:
-```bash
-kodrdriv link --scope-roots '{"@company": "../", "@tools": "../../tools/"}'
-```
-
-Dry run to preview changes:
-```bash
-kodrdriv link --scope-roots '{"@company": "../"}' --dry-run --verbose
-```
-
-Custom workspace file:
-```bash
-kodrdriv link --scope-roots '{"@company": "../"}' --workspace-file "workspace.yaml"
-```
-
-Real-world example: linking @company packages from company directory:
-```bash
-kodrdriv link --scope-roots '{"@company": "../../company/"}'
-```
-
-## Advanced Examples
-
-### Using Custom Instructions
-
-Use custom instructions from a file:
-```bash
-kodrdriv release --instructions ./my-custom-instructions.md
-```
-
-Enable instruction overrides (requires custom instruction files in `.kodrdriv/instructions/`):
-```bash
-kodrdriv commit --overrides
-```
-
-Use custom config directory with overrides:
-```bash
-kodrdriv release --config-dir ~/my-kodrdriv-config --overrides
-```
-
-### Excluding Patterns
-
-Exclude specific files or directories from diff analysis:
-```bash
-kodrdriv commit --excluded-paths "*.lock" "dist/" "node_modules/"
-```
-
-Exclude patterns from release notes:
-```bash
-kodrdriv release --excluded-paths "package-lock.json" "pnpm-lock.yaml"
-```
-
-### Verbose and Debug Mode
-
-Run in verbose mode with a custom OpenAI model:
-```bash
-kodrdriv commit --verbose --model gpt-4
-```
-
-Enable debug logging:
-```bash
-kodrdriv release --debug
-```
-
-### Configuration Debugging
-
-Check current configuration (useful for debugging):
-```bash
-kodrdriv --check-config
-```
-
-## Workflow Examples
-
-### Development Workflow
-
-1. Make changes to your code
-2. Stage the changes you want to commit:
-   ```bash
-   git add src/components/Button.tsx
-   ```
-3. Generate and commit with a message:
-   ```bash
-   kodrdriv commit --cached --sendit
-   ```
-
-### Release Workflow
-
-1. Generate release notes for review:
-   ```bash
-   kodrdriv release --dry-run
-   ```
-2. Generate and save release notes:
-   ```bash
-   kodrdriv release
-   ```
-3. Automated publish process:
-   ```bash
-   kodrdriv publish
-   ```
-
-### Monorepo Development Workflow
-
-1. Link local packages for development:
-   ```bash
-   kodrdriv link --scope-roots '{"@company": "../", "@tools": "../../tools/"}'
-   ```
-2. Make changes across packages
-3. Generate commit messages for each package:
-   ```bash
-   cd package-a
-   kodrdriv commit --context "Cross-package refactoring"
-   cd ../package-b
-   kodrdriv commit --context "Cross-package refactoring"
-   ```
-
-## Environment-Specific Examples
-
-### CI/CD Pipeline
-
-```bash
-# Set required environment variables
-export GITHUB_TOKEN="your-token"
-export OPENAI_API_KEY="your-key"
-export NODE_AUTH_TOKEN="your-npm-token"
-
-# Run publish command in CI
-kodrdriv publish --verbose
-```
-
-### Local Development
-
-```bash
-# Load environment from .env file
-# (KodrDriv automatically loads .env files)
-
-# Use specific model for local development
-kodrdriv commit --model gpt-4o-mini --verbose
-```
-
-### Team Collaboration
-
-```bash
-# Use team-specific configuration
-kodrdriv commit --config-dir ./.team-kodrdriv
-
-# Generate release notes with team context
-kodrdriv release --context ./team-context.md
-```
-
-## Real-World Scenarios
-
-### Feature Development
-
-```bash
-# Start working on a feature
-git checkout -b feature/user-authentication
-
-# Make incremental commits with context
-kodrdriv commit --context "Implementing user authentication system"
-kodrdriv commit --context "Adding password validation"
-kodrdriv commit --context "Integrating with OAuth provider"
-
-# Generate comprehensive release notes
-kodrdriv release --from main --to feature/user-authentication
-```
-
-### Bug Fix
-
-```bash
-# Quick bug fix with automatic commit
-git add src/utils/validation.ts
-kodrdriv commit --sendit --context "Fixing validation bug #123"
-```
-
-### Dependency Updates
-
-```bash
-# Update dependencies and commit
-pnpm update
-kodrdriv commit --context "Routine dependency updates"
-```
-
-### Documentation Updates
-
-```bash
-# Update documentation
-git add docs/
-kodrdriv commit --context "Updating API documentation"
-```
-
-## Configuration Examples
-
-### Personal Configuration
-
-`.kodrdriv/config.json`:
-```json
-{
-  "model": "gpt-4o-mini",
-  "verbose": true,
-  "commit": {
-    "messageLimit": 5
-  },
-  "excludedPatterns": [
-    "*.lock",
-    "dist/",
-    ".DS_Store"
-  ]
-}
-```
-
-### Team Configuration
-
-`.kodrdriv/config.json`:
-```json
-{
-  "model": "gpt-4o-mini",
-  "publish": {
-    "mergeMethod": "squash",
-    "dependencyUpdatePatterns": ["@company/*"],
-    "requiredEnvVars": ["NODE_AUTH_TOKEN", "CODECOV_TOKEN"]
-  },
-  "link": {
-    "scopeRoots": {
-      "@company": "../",
-      "@shared": "../../shared-packages/"
-    }
-  }
-}
-```
-
-### Project-Specific Configuration
-
-```json
-{
-  "contextDirectories": ["src", "docs", "tests"],
-  "release": {
-    "messageLimit": 15
-  },
-  "excludedPatterns": [
-    "coverage/",
-    "*.generated.ts",
-    "build/"
-  ]
-}
-```
-
-## Error Handling Examples
-
-### Missing Environment Variables
-
-```bash
-# This will fail with helpful error message
-kodrdriv publish
-# Error: Missing required environment variables: GITHUB_TOKEN, OPENAI_API_KEY
-
-# Set the variables and retry
-export GITHUB_TOKEN="your-token"
-export OPENAI_API_KEY="your-key"
-kodrdriv publish
-```
-
-### Missing prepublishOnly Script
-
-```bash
-# This will fail if package.json doesn't have prepublishOnly script
-kodrdriv publish
-# Error: prepublishOnly script is required in package.json
-
-# Add script to package.json and retry
-# "prepublishOnly": "pnpm run lint && pnpm run build && pnpm run test"
-```
-
-### Dry Run for Safety
-
-```bash
-# Always test with dry run first
-kodrdriv publish --dry-run
-kodrdriv link --scope-roots '{"@company": "../"}' --dry-run
-``` 

package/docs/public/kodrdriv-logo.svg

@@ -1,62 +0,0 @@
-<svg width="128" height="128" viewBox="0 0 128 128" xmlns="http://www.w3.org/2000/svg">
-  <!-- Background circle -->
-  <circle cx="64" cy="64" r="62" fill="#000000" stroke="#333333" stroke-width="2"/>
-  
-  <!-- Thor's hammer handle (vertical shaft) -->
-  <rect x="58" y="45" width="12" height="55" fill="#ffffff" rx="2"/>
-  
-  <!-- Hammer head (main block) -->
-  <rect x="35" y="25" width="58" height="25" fill="#ffffff" rx="3"/>
-  
-  <!-- Hammer head detail lines -->
-  <rect x="40" y="30" width="48" height="2" fill="#000000"/>
-  <rect x="40" y="35" width="48" height="2" fill="#000000"/>
-  <rect x="40" y="40" width="48" height="2" fill="#000000"/>
-  
-  <!-- Digital bytes/binary elements around the hammer -->
-  <!-- Top left -->
-  <rect x="20" y="15" width="3" height="3" fill="#ffffff"/>
-  <rect x="25" y="15" width="3" height="3" fill="#ffffff"/>
-  <rect x="25" y="20" width="3" height="3" fill="#ffffff"/>
-  
-  <!-- Top right -->
-  <rect x="100" y="15" width="3" height="3" fill="#ffffff"/>
-  <rect x="105" y="15" width="3" height="3" fill="#ffffff"/>
-  <rect x="100" y="20" width="3" height="3" fill="#ffffff"/>
-  
-  <!-- Bottom left -->
-  <rect x="15" y="100" width="3" height="3" fill="#ffffff"/>
-  <rect x="20" y="105" width="3" height="3" fill="#ffffff"/>
-  <rect x="25" y="100" width="3" height="3" fill="#ffffff"/>
-  
-  <!-- Bottom right -->
-  <rect x="100" y="105" width="3" height="3" fill="#ffffff"/>
-  <rect x="105" y="100" width="3" height="3" fill="#ffffff"/>
-  <rect x="110" y="105" width="3" height="3" fill="#ffffff"/>
-  
-  <!-- Circuit-like lines connecting to hammer -->
-  <path d="M 30 45 L 35 45" stroke="#ffffff" stroke-width="2" fill="none"/>
-  <path d="M 93 45 L 98 45" stroke="#ffffff" stroke-width="2" fill="none"/>
-  
-  <!-- Binary numbers around the hammer -->
-  <text x="15" y="65" fill="#ffffff" font-family="monospace" font-size="8">01</text>
-  <text x="105" y="65" fill="#ffffff" font-family="monospace" font-size="8">10</text>
-  <text x="60" y="20" fill="#000000" font-family="monospace" font-size="6">11</text>
-  <text x="60" y="115" fill="#ffffff" font-family="monospace" font-size="8">00</text>
-  
-  <!-- Hammer striking effect (lightning/energy) -->
-  <path d="M 64 50 L 60 55 L 68 55 L 64 60" fill="#ffffff"/>
-  
-  <!-- Corner circuit elements -->
-  <rect x="10" y="10" width="8" height="1" fill="#ffffff"/>
-  <rect x="10" y="10" width="1" height="8" fill="#ffffff"/>
-  
-  <rect x="110" y="10" width="8" height="1" fill="#ffffff"/>
-  <rect x="117" y="10" width="1" height="8" fill="#ffffff"/>
-  
-  <rect x="10" y="117" width="8" height="1" fill="#ffffff"/>
-  <rect x="10" y="110" width="1" height="8" fill="#ffffff"/>
-  
-  <rect x="110" y="117" width="8" height="1" fill="#ffffff"/>
-  <rect x="117" y="110" width="1" height="8" fill="#ffffff"/>
-</svg>