npm package: @isolaitev2/cli
Description: AI-Powered Codebase Isolation Tool - Create isolated environments for safe testing and experimentation
Author: Isolaite Team
Latest version: 2.0.0

# Isolaite v2 - CLI Tool

> **AI-Powered Codebase Isolation Tool** - Create isolated environments for safe testing and experimentation with Claude Code-like UX.

[![npm version](https://badge.fury.io/js/@isolaitev2/cli.svg)](https://www.npmjs.com/package/@isolaitev2/cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🚀 Quick Start

```bash
# Install globally
npm install -g @isolaitev2/cli

# Or install using the shorter alias (when available)
npm install -g isolaite

# Verify installation
isolaite --help
```

## ✨ Features

- **🔒 Safe Isolation**: Create isolated copies of your codebase for experimentation
- **🤖 AI Chat**: Interactive chat with workspace context and easy switching
- **⚡ Smart Transformations**: Automatically handles ports, environment variables, and database configs
- **📋 Claude Code UX**: Plan-then-execute workflow with todo tracking and rich output
- **🎯 Easy Switching**: Seamlessly switch between original and isolated versions
- **💾 Auto-Backup**: Automatic backups when merging changes back

## 📖 Usage

### Isolate Your Project

```bash
# Basic isolation (smart mode)
isolaite isolate ./my-app

# Full isolation with all files
isolaite isolate ./my-app -d ./my-app-isolated -m full

# Minimal isolation (config files only)
isolaite isolate ./my-app -m minimal --db isolate
```

**Isolation Modes:**
- `full` - Copy all files (excluding node_modules, .git)
- `smart` - Copy project files + config files (default)
- `minimal` - Config files only

**Database Strategies:**
- `isolate` - Transform database names for isolation (default)
- `share` - Use same database (careful!)
- `remove` - Remove database references

### Interactive Chat

```bash
# Start AI chat with workspace context
isolaite chat

# Switch between original/isolated before starting
isolaite chat --switch
```

**Chat Commands:**
- `/switch` or `/sw` - Toggle between original/isolated
- `/workspace` or `/ws` - Show workspace info
- `/open` - Get IDE open command
- `exit` or `quit` - Exit chat

### Merge Changes Back

```bash
# Merge isolated version back to original
isolaite merge ./my-app-isolated

# Skip backup creation (not recommended)
isolaite merge ./my-app-isolated --no-backup

# Skip verification
isolaite merge ./my-app-isolated --no-verify
```

### Workspace Management

```bash
# Show current mode
isolaite mode --status

# Toggle Isolaite mode (auto-isolation)
isolaite mode --isolaite

# Switch interaction mode
isolaite mode --plan          # Plan mode (read-only)
isolaite mode --accept-edits  # Accept edits mode
isolaite mode --accept-all    # Accept all mode
```

## 🎨 Workflow Example

```bash
# 1. Isolate your project
isolaite isolate ./my-api
# → Creates ./my-api-isolated with transformed configs

# 2. Start interactive chat
isolaite chat
# → Shows workspace context
# → Suggests switching to isolated directory

# 3. Switch to isolated version (in chat)
You> /switch
# → Switched to ISOLATED
# → Path: ./my-api-isolated

# 4. Make changes in isolated version
# → Edit files, test safely
# → No risk to original codebase

# 5. Merge back when satisfied
isolaite merge ./my-api-isolated
# → Creates backup of original
# → Reverts transformations
# → Merges all changes
# → Original updated safely
```

## 🔧 What Gets Transformed?

When you isolate a project, Isolaite automatically transforms:

- **Ports**: `3000` → `4000` (configurable offset)
- **Environment Variables**: `DB_NAME` → `DB_NAME_ISOLATED`
- **Database Names**: `myapp_db` → `myapp_db_isolated`
- **File Paths**: Updates references in config files

Example `.env` transformation:

**Before:**
```env
PORT=3000
DB_NAME=myapp_db
DB_HOST=localhost
```

**After (in isolated version):**
```env
PORT_ISOLATED=4000
DB_NAME_ISOLATED=myapp_db_isolated
DB_HOST_ISOLATED=localhost
```

## 📂 Workspace Context

Isolaite tracks your workspace state in `~/.isolaite/workspace-context.json`:

```json
{
  "currentPath": "/path/to/isolated",
  "originalPath": "/path/to/original",
  "isolatedPath": "/path/to/isolated",
  "isolationActive": true,
  "lastSwitchedAt": "2026-01-04T21:24:17.159Z"
}
```

This enables:
- Easy switching between original/isolated
- Persistent workspace state across CLI invocations
- Smart suggestions in chat mode

## ⌨️ Keyboard Shortcuts

- `alt+i` - Toggle Isolaite mode (global auto-isolation)
- `alt+shift+p` - Plan mode (read-only exploration)
- `alt+shift+e` - Accept edits mode (approve each change)
- `alt+shift+a` - Accept all mode (full autonomy)

## 🌐 Cloud Integration (Coming Soon)

The CLI will integrate with Isolaite Cloud (`isolaite.com`) for:

- Cloud backups of isolated versions
- Sync across devices
- Team collaboration
- AI conversation memory persistence

## 📦 Installation

### Prerequisites

- Node.js >= 18.0.0
- npm or pnpm

### Install

```bash
# Using npm
npm install -g @isolaitev2/cli

# Using pnpm
pnpm add -g @isolaitev2/cli

# Using yarn
yarn global add @isolaitev2/cli
```

### Verify Installation

```bash
isolaite --version
isolaite --help
```

## 🤝 Contributing

Contributions are welcome! Please see our [Contributing Guide](../../CONTRIBUTING.md).

## 📝 License

MIT © Isolaite Team

## 🔗 Links

- [GitHub](https://github.com/isolaitev2/isolaite)
- [Documentation](https://docs.isolaite.com)
- [Website](https://isolaite.com) (coming soon)

## 🐛 Troubleshooting

**Issue**: `isolaite: command not found`

**Solution**:
- Make sure you installed globally: `npm install -g @isolaitev2/cli`
- Check npm global bin path: `npm config get prefix`
- Add npm bin to your PATH:

```bash
# macOS/Linux
export PATH=$(npm config get prefix)/bin:$PATH

# Windows (PowerShell)
$env:Path = (npm config get prefix) + "\bin;" + $env:Path
```

**Issue**: Permission errors

**Solution**:
- macOS/Linux: Use `sudo npm install -g @isolaitev2/cli`
- Or fix npm permissions: [npm docs](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally)

## 💡 Tips

1. **Start with smart mode**: It copies project files + configs, excluding build artifacts
2. **Always test in isolated first**: Never modify original directly
3. **Use chat for complex workflows**: Interactive mode is powerful
4. **Check workspace status**: Use `isolaite mode --status` to see current mode
5. **Keyboard shortcuts are faster**: Use alt+i to toggle Isolaite mode

## 🎯 Use Cases

- **Feature Development**: Isolate, develop new features, test, merge
- **Bug Fixing**: Create isolated environment to safely fix bugs
- **Experimentation**: Try new libraries or patterns without risk
- **Code Reviews**: Isolate and review changes safely
- **Testing**: Run tests in isolated environment with different configs
- **Learning**: Experiment with codebases without breaking anything

---

Made with ❤️ by the Isolaite Team