@codemieai/code 0.0.3 → 0.0.5

package/.codemie/guides/git-workflow.md

@@ -1,493 +0,0 @@
-# Git Workflow Policy
-
-This document defines the git workflow standards for the codemie-tools repository.
-
-## Core Principles
-
-**IMPORTANT - Always use feature branches:**
-- NEVER commit directly to `main` branch
-- ALWAYS create a feature branch for changes
-- ALL changes must go through Pull Request review
-- Keep branches focused on a single feature or fix
-
-## Branch Naming Conventions
-
-Use descriptive, lowercase branch names with hyphens:
-
-### Patterns
-
-- `feature/add-something` - New features or enhancements
-- `fix/issue-description` - Bug fixes
-- `docs/update-readme` - Documentation changes
-- `refactor/component-name` - Code refactoring without behavior change
-- `chore/update-dependencies` - Maintenance tasks (dependencies, config, etc.)
-- `test/add-tests` - Adding or updating tests
-
-### Guidelines
-
-- Use lowercase with hyphens (kebab-case)
-- Be descriptive but concise
-- Include ticket/issue number if applicable:
-  - `feature/GH-123-add-jira-integration`
-  - `fix/JIRA-456-auth-timeout`
-- Keep branch names under 50 characters when possible
-- Avoid special characters except hyphens
-
-### Examples
-
-✅ **Good:**
-- `feature/add-slack-notifications`
-- `fix/memory-leak-in-parser`
-- `docs/update-api-guide`
-- `refactor/simplify-error-handling`
-- `chore/bump-dependencies`
-
-❌ **Bad:**
-- `my-branch` (not descriptive)
-- `Feature_Add_Something` (wrong case, underscores)
-- `fix` (too vague)
-- `johns-work` (not task-focused)
-
-## Standard Workflow
-
-### 1. Start from Main
-
-Always start from the latest `main` branch:
-
-```bash
-git checkout main
-git pull origin main
-```
-
-### 2. Create Feature Branch
-
-Create a descriptive feature branch:
-
-```bash
-git checkout -b feature/your-feature-name
-```
-
-### 3. Make Changes
-
-Work on your changes, committing regularly:
-
-```bash
-# Stage changes
-git add <files>
-
-# Or stage all changes
-git add .
-
-# Commit with descriptive message
-git commit -m "type: description"
-```
-
-### 4. Push Branch
-
-Push your feature branch to remote:
-
-```bash
-# First push (set upstream)
-git push -u origin feature/your-feature-name
-
-# Subsequent pushes
-git push
-```
-
-### 5. Create Pull Request
-
-Create a PR using GitHub UI or CLI:
-
-```bash
-# Using GitHub CLI
-gh pr create --title "Add feature XYZ" --body "Description of changes"
-
-# Or use GitHub web interface
-```
-
-### 6. After PR Approval
-
-Once approved and CI passes, merge the PR:
-- Use GitHub's "Squash and merge" for clean history
-- Delete the feature branch after merge
-
-## Commit Message Guidelines
-
-Follow [Conventional Commits](https://www.conventionalcommits.org/) specification:
-
-### Format
-
-```
-type: short description (72 chars max)
-
-Optional longer description explaining the change.
-Can span multiple lines.
-
-Fixes #123
-Co-authored-by: CodeMie AI <codemie.ai@gmail.com>
-```
-
-### Co-Author Attribution
-
-**When work is assisted by CodeMie AI**, add the co-author line at the end of the commit message:
-
-```
-Co-authored-by: CodeMie AI <codemie.ai@gmail.com>
-```
-
-This ensures:
-- GitHub properly recognizes CodeMie AI contributions
-- Contribution graphs show AI-assisted commits
-- Clear attribution for AI-generated or AI-assisted code
-
-**Usage:**
-```bash
-# Single line commit with co-author
-git commit -m "feat: add feature" -m "Co-authored-by: CodeMie AI <codemie.ai@gmail.com>"
-
-# Or using heredoc for multi-line
-git commit -m "$(cat <<EOF
-feat: add new feature
-
-Detailed description of the changes made.
-
-Co-authored-by: CodeMie AI <codemie.ai@gmail.com>
-EOF
-)"
-```
-
-**How GitHub displays co-authors:**
-- Appears in commit details on GitHub UI
-- Shows in contribution graphs
-- Listed in repository insights
-- Appears in PR commit lists
-- Format must be exact: `Co-authored-by: Name <email@domain.com>`
-
-**Benefits:**
-- Clear visibility of AI-assisted work
-- Proper attribution in open source contributions
-- Transparent collaboration tracking
-- Organization-wide AI contribution metrics
-
-### Types
-
-- `feat:` - New feature
-- `fix:` - Bug fix
-- `docs:` - Documentation only
-- `refactor:` - Code refactoring (no behavior change)
-- `test:` - Adding or updating tests
-- `chore:` - Maintenance (dependencies, config, build)
-- `style:` - Code style changes (formatting, whitespace)
-- `perf:` - Performance improvements
-- `ci:` - CI/CD changes
-
-### Examples
-
-✅ **Good commit messages:**
-```
-feat: add Slack notification integration
-
-Implements Slack webhook support for sending notifications
-when tickets are created or updated.
-
-Closes #234
-Co-authored-by: CodeMie AI <codemie.ai@gmail.com>
-```
-
-```
-fix: resolve memory leak in report parser
-
-The parser was not releasing file handles after processing.
-Added proper cleanup in finally block.
-
-Fixes #456
-Co-authored-by: CodeMie AI <codemie.ai@gmail.com>
-```
-
-```
-docs: update installation guide with Poetry commands
-
-Added missing steps for virtual environment setup
-and dependency installation using Poetry.
-
-Co-authored-by: CodeMie AI <codemie.ai@gmail.com>
-```
-
-```
-refactor: simplify error handling in ITSM toolkit
-
-Consolidated duplicate error handling code into base class.
-No functional changes.
-
-Co-authored-by: CodeMie AI <codemie.ai@gmail.com>
-```
-
-❌ **Bad commit messages:**
-```
-Update files          # Too vague
-Fixed stuff           # Not descriptive
-WIP                   # Work in progress, don't commit
-test commit           # Not meaningful
-asdfasdf              # Nonsense
-```
-
-### Commit Message Best Practices
-
-- **First line**: Concise summary (≤72 characters)
-- **Type prefix**: Always use conventional commit type
-- **Imperative mood**: "add" not "added" or "adds"
-- **Lowercase**: Start description with lowercase
-- **No period**: Don't end summary with period
-- **Body**: Add context if needed (blank line after summary)
-- **References**: Link to issues/PRs when applicable
-- **Breaking changes**: Use `!` after type or `BREAKING CHANGE:` in body
-
-## Pull Request Guidelines
-
-### PR Title
-
-Use the same format as commit messages:
-```
-feat: add feature name
-fix: resolve bug description
-```
-
-### PR Description Template
-
-```markdown
-## Summary
-Brief description of changes
-
-## Changes Made
-- Bullet point list
-- Of specific changes
-- In this PR
-
-## Testing
-- [ ] Manual testing performed
-- [ ] Existing tests pass
-- [ ] New tests added (if applicable)
-
-## Screenshots (if applicable)
-Add screenshots or GIFs
-
-## Related Issues
-Closes #123
-Relates to #456
-
-## Checklist
-- [ ] Code follows project style guidelines
-- [ ] Documentation updated (if needed)
-- [ ] Tests added/updated (if needed)
-- [ ] All CI checks passing
-```
-
-### Review Process
-
-1. **Self-review**: Review your own changes before requesting review
-2. **Request review**: Assign relevant reviewers
-3. **Address feedback**: Respond to all comments
-4. **Keep updated**: Merge main into your branch if conflicts arise
-5. **Clean history**: Squash unnecessary commits if needed
-
-## Working with Main Branch
-
-### Keeping Branch Updated
-
-If `main` has moved ahead while working on your feature:
-
-```bash
-# From your feature branch
-git fetch origin
-git merge origin/main
-
-# Or use rebase for cleaner history
-git fetch origin
-git rebase origin/main
-```
-
-### Handling Merge Conflicts
-
-If conflicts occur:
-
-```bash
-# 1. Identify conflicted files
-git status
-
-# 2. Edit files to resolve conflicts
-# Look for <<<<<<, ======, >>>>>> markers
-
-# 3. Mark conflicts as resolved
-git add <resolved-files>
-
-# 4. Continue merge/rebase
-git merge --continue
-# or
-git rebase --continue
-```
-
-## Emergency Hotfixes
-
-For critical production issues:
-
-```bash
-# 1. Create hotfix branch from main
-git checkout main
-git pull origin main
-git checkout -b fix/critical-bug-name
-
-# 2. Make fix and test thoroughly
-
-# 3. Push and create PR
-git push -u origin fix/critical-bug-name
-
-# 4. Request expedited review
-# Tag PR with "urgent" or "hotfix" label
-
-# 5. Merge after approval (may skip some CI checks if critical)
-```
-
-## Best Practices
-
-### Do's ✅
-
-- **Do** create small, focused branches
-- **Do** commit frequently with clear messages
-- **Do** keep commits atomic (one logical change per commit)
-- **Do** write descriptive PR descriptions
-- **Do** respond to review feedback promptly
-- **Do** update documentation with code changes
-- **Do** delete branches after merging
-- **Do** test thoroughly before pushing
-
-### Don'ts ❌
-
-- **Don't** commit directly to `main`
-- **Don't** push broken code
-- **Don't** commit secrets or sensitive data
-- **Don't** mix unrelated changes in one commit
-- **Don't** use vague commit messages
-- **Don't** leave branches stale for weeks
-- **Don't** force push to shared branches
-- **Don't** commit merge conflicts
-
-## Git Commands Reference
-
-### Essential Commands
-
-```bash
-# Check status
-git status
-
-# View changes
-git diff                    # Unstaged changes
-git diff --staged          # Staged changes
-
-# Create branch
-git checkout -b branch-name
-
-# Switch branches
-git checkout branch-name
-
-# Stage changes
-git add <file>
-git add .                  # All changes
-
-# Commit
-git commit -m "message"
-git commit --amend         # Amend last commit
-
-# Push
-git push
-git push -u origin branch  # First push with upstream
-
-# Pull latest changes
-git pull origin main
-
-# View commit history
-git log
-git log --oneline
-git log --graph
-
-# Undo changes
-git checkout -- <file>     # Discard unstaged changes
-git reset HEAD <file>      # Unstage changes
-git reset --soft HEAD~1    # Undo last commit (keep changes)
-
-# Branch management
-git branch                 # List branches
-git branch -d branch-name  # Delete local branch
-git push origin --delete branch-name  # Delete remote branch
-```
-
-## Integration with CI/CD
-
-All branches automatically trigger:
-- Linting checks
-- Unit tests
-- Build verification
-- Code quality checks
-
-PRs cannot be merged until:
-- All CI checks pass
-- At least one approval received
-- No merge conflicts
-- Branch is up to date with main
-
-## Troubleshooting
-
-### "Branch is behind main"
-
-```bash
-git fetch origin
-git merge origin/main
-git push
-```
-
-### "Merge conflicts"
-
-```bash
-# See conflicted files
-git status
-
-# After resolving conflicts
-git add <resolved-files>
-git commit
-```
-
-### "Accidentally committed to main"
-
-```bash
-# Create branch from current state
-git branch feature/my-changes
-
-# Reset main to match remote
-git reset --hard origin/main
-
-# Switch to new branch
-git checkout feature/my-changes
-
-# Push branch
-git push -u origin feature/my-changes
-```
-
-### "Need to update commit message"
-
-```bash
-# Last commit only
-git commit --amend -m "new message"
-
-# Push (requires force if already pushed)
-git push --force-with-lease
-```
-
-## Additional Resources
-
-- [Conventional Commits](https://www.conventionalcommits.org/)
-- [Git Best Practices](https://git-scm.com/book/en/v2)
-- [GitHub Flow](https://guides.github.com/introduction/flow/)
-- [Semantic Versioning](https://semver.org/)
-
----
-
-**Remember**: Following these guidelines ensures clean git history, easier code review, and better collaboration across the team.

package/CLAUDE.md

@@ -1,225 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Critical First Step: ALWAYS Read Documentation
-
-**MANDATORY**: Before writing ANY code, you MUST:
-1. Read the `README.md` file - this is your PRIMARY source of truth
-2. Review this CLAUDE.md for architectural patterns and conventions
-3. Study reference implementations mentioned in this guide
-
-## Common Commands
-
-```bash
-# Installation & Setup
-npm install                 # Install dependencies
-npm link                    # Link globally for local testing
-
-# Building
-npm run build              # Compile TypeScript
-npm run dev                # Watch mode for development
-
-# Code Quality
-npm run lint               # Check code style with ESLint (max 10 warnings)
-npm run lint:fix           # Fix linting issues automatically
-npm run ci                 # Run full CI pipeline (license-check + lint + build)
-
-# Development Workflow
-npm run build && npm link  # Build and link for testing
-codemie doctor             # Verify installation and configuration
-codemie-code health        # Test built-in agent health
-
-# Testing the Built-in Agent
-codemie-code --task "test"  # Single task execution
-codemie-code --debug       # Interactive with debug logging
-
-# Direct Agent Shortcuts (bypass registry)
-codemie-claude             # Direct Claude Code access
-codemie-codex              # Direct Codex access
-codemie-claude health      # Claude health check
-codemie-codex health       # Codex health check
-
-# Release & Publishing
-git tag -a v0.0.1 -m "Release version 0.0.1"  # Create release tag
-git push origin v0.0.1                         # Push tag to trigger publish
-```
-
-## Core Principles
-
-**ALWAYS follow these fundamental principles:**
-
-### KISS (Keep It Simple, Stupid)
-- Write simple, straightforward code that's easy to understand
-- Avoid over-engineering and unnecessary complexity
-- Remove redundant code, scripts, and configuration
-- If something can be done in fewer lines/steps, do it
-- Question every piece of complexity - is it truly needed?
-
-### DRY (Don't Repeat Yourself)
-- Never duplicate code, logic, or configuration
-- Extract common patterns into reusable functions/utilities
-- Reuse existing utilities from \`src/utils/\` before creating new ones
-- If you find yourself copying code, refactor it into a shared function
-- One source of truth for each piece of knowledge
-
-**Remember:** Simple, clean code is better than clever, complex code.
-
-## Project Overview
-
-**CodeMie** is a unified CLI wrapper for managing multiple AI coding agents, featuring:
-
-1. **External Agent Management**: Install and run external agents (Claude Code, Codex)
-2. **Built-in Agent**: CodeMie Native - a LangGraph-based coding assistant
-3. **Configuration Management**: Unified config system supporting multiple AI providers
-4. **Multiple Interfaces**: CLI commands, direct executables, and programmatic APIs
-
-## Architecture Overview
-
-### High-Level Structure
-
-```
-codemie-code/
-├── bin/                     # Executable entry points
-│   ├── codemie.js          # Main CLI entry
-│   ├── codemie-code.js     # Direct built-in agent executable
-│   ├── codemie-claude.js   # Claude agent wrapper
-│   └── codemie-codex.js    # Codex agent wrapper
-├── src/
-│   ├── cli/                # CLI command implementations
-│   ├── agents/             # Agent registry and adapters
-│   ├── env/                # Environment and config management
-│   ├── utils/              # Shared utilities
-│   └── index.ts           # Main package exports
-```
-
-### Core Components
-
-#### 1. Agent System (`src/agents/`)
-
-- **Registry** (`registry.ts`): Central registry managing all available agents
-- **Adapters** (`adapters/`): Standardized interfaces for external agents
-  - `claude-code.ts`: Anthropic Claude Code integration
-  - `codex.ts`: OpenAI Codex integration
-  - `codemie-code.ts`: Built-in agent adapter
-- **Built-in Agent** (`codemie-code/`): Full LangGraph-based agent implementation
-
-#### 2. CLI System (`src/cli/`)
-
-- **Main CLI** (`index.ts`): Commander.js-based CLI with all commands
-- **Commands** (`commands/`): Individual command implementations
-  - `setup.ts`: Interactive configuration wizard
-  - `install.ts`/`uninstall.ts`: Agent management
-  - `run.ts`: Agent execution with environment passing
-  - `doctor.ts`: Health checks and diagnostics
-  - `config.ts`: Configuration management
-
-#### 3. Configuration System (`src/env/`)
-
-- **EnvManager** (`manager.ts`): Global config at `~/.codemie/config.json`
-- **Priority**: Environment variables override config file
-- **Providers**: Anthropic, OpenAI, Azure, Bedrock, LiteLLM
-- **Model Validation**: Real-time model fetching via `/v1/models` endpoints
-
-#### 4. Built-in Agent Architecture (`src/agents/codemie-code/`)
-
-**Multi-layered architecture:**
-
-- **Main Interface** (`index.ts`): `CodeMieCode` class - primary API
-- **Agent Core** (`agent.ts`): `CodeMieAgent` - LangGraph integration
-- **Configuration** (`config.ts`): Provider config loading and validation
-- **Tools System** (`tools/`): Modular tool implementations
-  - `filesystem.ts`: File operations with security controls
-  - `command.ts`: Shell command execution
-  - `git.ts`: Git operations and status
-  - `security.ts`: Security filters and validation
-- **UI System** (`ui.ts`, `streaming/`): Modern terminal interfaces
-- **Types** (`types.ts`): Comprehensive TypeScript definitions
-
-### Key Architectural Patterns
-
-#### Agent Adapter Pattern
-All agents implement the `AgentAdapter` interface:
-```typescript
-interface AgentAdapter {
-  name: string;
-  displayName: string;
-  description: string;
-  install(): Promise<void>;
-  uninstall(): Promise<void>;
-  isInstalled(): Promise<boolean>;
-  run(args: string[], env?: Record<string, string>): Promise<void>;
-  getVersion(): Promise<string | null>;
-}
-```
-
-#### Configuration Hierarchy
-1. Environment variables (highest priority)
-2. Global config file (`~/.codemie/config.json`)
-3. Default values (lowest priority)
-
-#### Tool System Architecture
-- **Modular Design**: Each tool type in separate file
-- **Security First**: All operations go through security filters
-- **Type Safety**: Full TypeScript coverage with Zod validation
-- **Error Handling**: Structured error types with context
-
-#### Execution Modes
-- **Interactive**: Full terminal UI with streaming responses
-- **Task Mode**: Single task execution with `--task` flag
-- **Health Checks**: Connection and configuration validation
-
-### Technology Stack
-
-- **TypeScript**: Full type safety with ES2024 + NodeNext modules
-- **Commander.js**: CLI framework with subcommands
-- **LangChain/LangGraph**: Agent orchestration and tool calling
-- **Clack**: Modern terminal user interface
-- **Chalk**: Terminal styling and colors
-- **Zod**: Runtime type validation
-- **ESLint**: Code quality (max 10 warnings allowed)
-
-## Development Guidelines
-
-### Working with Agent Shortcuts
-
-When modifying the direct agent shortcuts (`codemie-claude`, `codemie-codex`):
-
-1. **Configuration Override Pattern**: All shortcuts support CLI overrides for:
-   - `--model`: Override model selection
-   - `--provider`: Override provider
-   - `--api-key`: Override API key
-   - `--base-url`: Override base URL
-   - `--timeout`: Override timeout
-
-2. **Pass-through Architecture**: Use `allowUnknownOption()` and `passThroughOptions()` to forward all unrecognized options to the underlying agent
-
-3. **Model Validation**:
-   - Codex must validate OpenAI-compatible models only
-   - Claude accepts both Claude and GPT models
-   - Provide helpful error messages with actionable suggestions
-
-4. **Health Check Pattern**: Each shortcut should implement a `health` subcommand that:
-   - Verifies agent installation
-   - Shows version information
-   - Tests basic configuration
-
-### Adding New Agent Shortcuts
-
-To add a new direct agent shortcut (e.g., `codemie-newagent`):
-
-1. Create `bin/codemie-newagent.js` following the existing pattern
-2. Add the executable to `package.json` bin field
-3. Implement the adapter in `src/agents/adapters/`
-4. Register in `src/agents/registry.ts`
-5. Update documentation in README.md and CLAUDE.md
-
-### Built-in Agent Development
-
-When working on the CodeMie Native agent (`src/agents/codemie-code/`):
-
-- **Tools**: Add new tools in `tools/` directory with proper security filtering
-- **UI**: Use Clack components for consistent terminal interface
-- **Streaming**: Implement proper event handling for real-time responses
-- **Configuration**: Follow the provider config pattern in `config.ts`
-- **Error Handling**: Use structured error types with context information