# Crackerjack 0.48.0 Migration Guide

**Migration Type:** Complete Architecture Modernization (legacy → Oneiric + mcp-common)
**Breaking Changes:** Yes (CLI commands, adapter APIs)
**Estimated Migration Time:** 10-15 minutes
**Risk Level:** Low (comprehensive testing completed)
**Status:** ✅ MIGRATION COMPLETE

______________________________________________________________________

## Overview

Version 0.47.0 represents a fundamental modernization of Crackerjack's architecture, migrating from legacy (Architecture Component Base) to Oneiric runtime management. While this is a significant internal change, the migration path for users is straightforward and well-tested.

**Key Benefits:**

- 65% reduction in CLI code complexity
- 100% test pass rate (up from 84%)
- Streamlined dependency management
- Simpler, more intuitive CLI commands
- Better integration with modern Python tooling
- 100% legacy-free architecture
- Complete Oneiric + mcp-common integration

______________________________________________________________________

## Breaking Changes Summary

### 1. CLI Commands (High Impact)

**Old Syntax** (v0.46.x):

```bash
python -m crackerjack run --start-mcp-server
python -m crackerjack run --stop-mcp-server
python -m crackerjack run --restart-mcp-server
```

**New Syntax** (v0.47.0):

```bash
python -m crackerjack start
python -m crackerjack stop
python -m crackerjack restart
python -m crackerjack status
python -m crackerjack health
python -m crackerjack health --probe
```

Legacy flags remain available under `python -m crackerjack run`, but prefer the command syntax above.

### 2. MCP Client Configuration (High Impact)

**Update Required:** All MCP client configurations (Claude Desktop, Cline, etc.) must be updated to use the new command syntax.

### 3. Adapter API (Low Impact)

**Only affects custom adapter developers:**

- Adapters now use constructor injection instead of DI
- All legacy `depends.set()` patterns removed
- Protocol-based registration via server initialization

### 4. Phase 5-7 Completion (No Impact)

**Internal cleanup completed:**

- ✅ Phase 5: Final legacy cleanup (comments, imports, backup files)
- ✅ Phase 6: Oneiric/mcp-common completion (type hints, query adapters, CLI facade)
- ✅ Phase 7: Validation & documentation
- `MODULE_STATUS` must use `AdapterStatus` enum (not strings)
- Static UUIDs from registry (see `ADAPTER_UUID_REGISTRY.md`)

______________________________________________________________________

## Pre-Migration Checklist

Before upgrading to v0.47.0, ensure you have:

- [ ] **Backup current installation** (or note current version for rollback)
- [ ] **Document current MCP configurations** (save copies of your `mcp.json` files)
- [ ] **Stop running MCP servers** (if any)
- [ ] **Check for custom integrations** (if you've developed custom adapters)
- [ ] **Review breaking changes** (above section)

______________________________________________________________________

## Migration Steps

### Step 1: Upgrade Crackerjack

```bash
# Option A: Using UV (recommended)
uv pip install --upgrade crackerjack

# Option B: Using pip
pip install --upgrade crackerjack

# Option C: From source (development)
cd /path/to/crackerjack
uv sync
```

**Verify Installation:**

```bash
python -m crackerjack --version
# Should show 0.47.0 or higher
```

### Step 2: Update MCP Client Configurations

#### For Claude Desktop Users:

1. **Locate your MCP configuration file:**

   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
   - Linux: `~/.config/Claude/claude_desktop_config.json`

1. **Update the Crackerjack server configuration:**

   **Before (v0.46.x):**

   ```json
   {
     "mcpServers": {
       "crackerjack": {
         "command": "uvx",
         "args": [
           "crackerjack",
           "--start-mcp-server"
         ]
       }
     }
   }
   ```

   **After (v0.47.0):**

   ```json
   {
     "mcpServers": {
       "crackerjack": {
         "command": "uvx",
         "args": [
           "crackerjack",
           "start"
         ]
       }
     }
   }
   ```

1. **For local development installations:**

   **Before (v0.46.x):**

   ```json
   {
     "mcpServers": {
       "crackerjack": {
         "command": "uvx",
         "args": [
           "--from",
           "/path/to/crackerjack",
           "crackerjack",
           "--start-mcp-server"
         ]
       }
     }
   }
   ```

   **After (v0.47.0):**

   ```json
   {
     "mcpServers": {
       "crackerjack": {
         "command": "uvx",
         "args": [
           "--from",
           "/path/to/crackerjack",
           "crackerjack",
           "start"
         ]
       }
     }
   }
   ```

1. **Restart Claude Desktop** to apply changes

#### For Other MCP Clients (Cline, Continue, etc.):

Apply the same pattern: replace `"--start-mcp-server"` with `"start"` in your MCP configuration.

### Step 3: Test MCP Server Startup

```bash
# Test the new command directly
python -m crackerjack start --verbose

# You should see:
# [green]Starting Crackerjack MCP server...[/green]
# [dim]Process ID: <PID>[/dim]

# Use Ctrl+C to stop the server
```

### Step 4: Verify MCP Integration

1. **Open your MCP client** (Claude Desktop, etc.)
1. **Verify Crackerjack server is listed** in available servers
1. **Test a simple command:**
   ```
   Can you run crackerjack quality checks on my project?
   ```
1. **Confirm tools are working** (execute_crackerjack, get_job_progress, etc.)

______________________________________________________________________

## Post-Migration Validation

Run these commands to verify the migration was successful:

```bash
# 1. Verify version
python -m crackerjack --version

# 2. Test quality checks (without MCP)
python -m crackerjack run --run-tests

# 3. Verify MCP server can start
python -m crackerjack start --verbose
# (Ctrl+C to stop)

# 4. Check no legacy dependencies remain
python -c "import crackerjack; print('✓ Import successful')"
```

**Expected Results:**

- ✅ Version shows 0.47.0 or higher
- ✅ Quality checks run successfully
- ✅ MCP server starts without errors
- ✅ No import errors or warnings

______________________________________________________________________

## Troubleshooting

### Issue: MCP Server Won't Start

**Symptoms:** Error when running `python -m crackerjack start`

**Solution:**

1. Check Python version: `python --version` (must be 3.13+)
1. Reinstall dependencies: `uv sync` or `pip install --force-reinstall crackerjack`
1. Check for conflicting processes: `lsof -i :8675`
1. Try verbose mode: `python -m crackerjack start --verbose`

### Issue: Claude Desktop Not Connecting

**Symptoms:** Claude can't see Crackerjack server or tools

**Solution:**

1. Verify configuration syntax (JSON must be valid)
1. Check file path in error logs: `~/Library/Logs/Claude/mcp*.log` (macOS)
1. Restart Claude Desktop completely (quit and reopen)
1. Test server independently: `python -m crackerjack start --verbose`
1. Verify `uvx` is in PATH: `which uvx`

### Issue: "Command Not Found" Error

**Symptoms:** `crackerjack: command not found` or similar

**Solution:**

1. Use full module syntax: `python -m crackerjack start`
1. Verify installation: `uv pip list | grep crackerjack`
1. Check Python environment: `which python`
1. Reinstall: `uv pip install --force-reinstall crackerjack`

### Issue: Old Flags Still in Scripts

**Symptoms:** Scripts using `--start-mcp-server` fail

**Solution:**
Update all scripts to use new command syntax:

```bash
# Old (will fail in 0.47.0)
python -m crackerjack run --start-mcp-server

# New (correct)
python -m crackerjack start
```

______________________________________________________________________

## Rollback Instructions

If you encounter issues and need to rollback to v0.46.4:

### Option 1: Downgrade with UV (Recommended)

```bash
uv pip install crackerjack==0.46.4
```

### Option 2: Downgrade with pip

```bash
pip install crackerjack==0.46.4
```

### Option 3: Restore from Backup

If you made a backup of your virtualenv:

```bash
# Restore your backed-up environment
rm -rf .venv
cp -r .venv.backup .venv
```

**After Rollback:**

1. Restore old MCP configurations (use `--start-mcp-server` flags)
1. Restart MCP clients
1. Verify v0.46.4: `python -m crackerjack --version`
1. Report issues: https://github.com/lesleslie/crackerjack/issues

______________________________________________________________________

## Custom Adapter Migration (Advanced)

**Only relevant if you've developed custom adapters.**

### Changes Required:

1. **Remove legacy Dependency Injection:**

   **Before (v0.46.x):**

   ```python
   from legacy.depends import depends, Inject


   @depends.inject
   def __init__(self, console: Inject[Console]):
       self.console = console
   ```

   **After (v0.47.0):**

   ```python
   from rich.console import Console


   def __init__(self, console: Console | None = None):
       self.console = console or Console()
   ```

1. **Use Static UUIDs:**

   **Before (v0.46.x):**

   ```python
   from uuid import uuid4

   MODULE_ID = uuid4()  # Dynamic UUID
   MODULE_STATUS = "stable"  # String status
   ```

   **After (v0.47.0):**

   ```python
   from uuid import UUID
   from crackerjack.models.adapter_metadata import AdapterStatus

   # Get your static UUID from ADAPTER_UUID_REGISTRY.md
   MODULE_ID = UUID("your-static-uuid-here")
   MODULE_STATUS = AdapterStatus.STABLE  # Enum
   ```

1. **Update Imports:**

   **Before (v0.46.x):**

   ```python
   from legacy.console import Console
   from legacy.config import Settings
   ```

   **After (v0.47.0):**

   ```python
   from rich.console import Console
   from crackerjack.config import CrackerjackSettings
   ```

______________________________________________________________________

## FAQ

### Q: Will my existing quality hooks still work?

**A:** Yes, all quality hooks are unchanged. The migration only affects server lifecycle commands.

### Q: Do I need to reconfigure pre-commit?

**A:** No, pre-commit hooks are unaffected by this migration.

### Q: What about the `--dashboard` command?

**A:** The WebSocket dashboard was removed in Phase 1, and there is no `--dashboard` flag in the current CLI. Use MCP integration (or `--monitor` / `--enhanced-monitor`) for monitoring instead.

### Q: When will `stop`/`restart`/`status`/`health` commands be functional?

**A:** These commands are available now via the MCPServerCLIFactory integration. Use `python -m crackerjack health --probe` for liveness checks.

### Q: Can I still use `python -m crackerjack run --run-tests`?

**A:** Yes! All quality check flags (`--run-tests`, `--ai-fix`, etc.) are still supported under `python -m crackerjack run`.

### Q: Will this break my CI/CD pipelines?

**A:** No, unless your CI/CD uses `--start-mcp-server` (unlikely). Most CI/CD uses `run --run-tests`, which is unchanged.

______________________________________________________________________

## Support

If you encounter issues during migration:

1. **Check this guide's Troubleshooting section** (above)
1. **Review the CHANGELOG:** `CHANGELOG.md` (comprehensive list of changes)
1. **Check migration status:** `ONEIRIC_MIGRATION_STATUS.md` (technical details)
1. **Report issues:** https://github.com/lesleslie/crackerjack/issues
1. **Community support:** GitHub Discussions

**When reporting issues, include:**

- Crackerjack version: `python -m crackerjack --version`
- Python version: `python --version`
- Operating system
- Full error message
- Steps to reproduce

______________________________________________________________________

## Summary

The migration to Crackerjack 0.47.0 primarily requires updating MCP client configurations to use the new `crackerjack start` command syntax. The process is straightforward and well-tested, with comprehensive rollback options available if needed.

**Migration Checklist:**

- ✅ Backup current installation
- ✅ Upgrade to v0.47.0
- ✅ Update MCP configurations (replace `--start-mcp-server` with `start`)
- ✅ Restart MCP clients
- ✅ Verify server startup
- ✅ Test MCP integration

**Estimated Time:** 10-15 minutes

For most users, this migration will be seamless. The architecture improvements lay the groundwork for future enhancements while maintaining all existing functionality.
