npm package: @sihle.dev/yugo-kit-dev-cli
Description: Advanced development CLI for Yugo Kit - supports local and remote environment management
Author: Yugo Kit Team
Latest version: 0.1.1

# @yugo-kit/dev-cli

Advanced TypeScript CLI for Yugo Kit development environment management.

## Features

- 🚀 **Environment Management**: Manage local, remote, and Kubernetes environments
- 🐳 **Docker Integration**: Full Docker Compose support with health monitoring  
- 🔐 **Permission System**: Role-based access control for different environments
- 🎯 **Type Safety**: Built with TypeScript for better reliability
- 🌐 **Remote Support**: SSH and Kubernetes API integration for remote operations
- 📊 **Monitoring**: Built-in health checks and service monitoring
- 🗄️ **Database Migrations**: Complete Drizzle ORM migration management
- 🧩 **Extensible**: Can be used both as CLI and programmatic library

## Installation

```bash
# Install dependencies
bun install

# Build the package
bun run build

# Run in development mode
bun run dev [command]

# Use the built CLI
node dist/cli.js [command]
```

## Usage

### Environment Management

```bash
# List all environments
node dist/cli.js env list

# Show environment details
node dist/cli.js env show local

# Show environment details for staging
node dist/cli.js env show staging
```

### Setup and Deployment

```bash
# Full setup (creates configs, starts services)
node dist/cli.js setup

# Quick setup (skip monitoring setup)
node dist/cli.js setup --quick

# Setup specific environment
node dist/cli.js setup --environment staging

# Skip waiting for services to be ready
node dist/cli.js setup --skip-wait
```

### Service Management

```bash
# Check service status
node dist/cli.js status

# Check status for specific environment
node dist/cli.js status --environment staging
```

### Database Migrations

```bash
# Check migration status
node dist/cli.js migrate status

# Generate new migrations
node dist/cli.js migrate generate

# Push schema changes (development)
node dist/cli.js migrate push

# Apply migrations (production)
node dist/cli.js migrate run

# Open Drizzle Studio
node dist/cli.js migrate studio

# Drop database (dangerous!)
node dist/cli.js migrate drop
```

**Migration Features:**
- **Status Checking**: View migration files and database state
- **Schema Generation**: Auto-generate migrations from schema changes
- **Development Workflow**: Push changes directly for quick iteration
- **Production Safety**: Apply tracked migrations with rollback support
- **Visual Management**: Drizzle Studio integration for database browsing
- **Complete Reset**: Drop database for development resets

## Architecture

### Environment Types

- **Local**: Docker Compose based development
- **Remote**: SSH-based remote server deployment
- **Kubernetes**: Kubernetes cluster deployment

### Permission System

The CLI implements a role-based permission system:

- **Developer**: Can deploy to local/staging, view logs, access shell
- **Admin**: Full access to all environments and operations
- **Viewer**: Read-only access, can view logs and status

### Configuration

Configuration files are stored in `~/.yugo-kit/`:

- `environments.json`: Environment definitions
- `user.json`: User permissions and preferences

## Programmatic Usage

The CLI can also be used as a library:

```typescript
import { YugoDevCLI, EnvironmentManager, DockerManager } from '@yugo-kit/dev-cli';

// Use as library
const cli = new YugoDevCLI();
await cli.run(['setup', '--environment', 'local']);

// Use individual managers
const envManager = new EnvironmentManager();
const environments = await envManager.loadEnvironments();

const dockerManager = new DockerManager();
const result = await dockerManager.startServices(environments[0]);
```

## Development

```bash
# Install dependencies
bun install

# Run in development mode
bun run dev [command]

# Build for production
bun run build

# Run tests
bun run test

# Lint code
bun run lint

# Clean build artifacts
bun run clean
```

## Migration from Bash Scripts

This TypeScript CLI replaces the previous bash scripts with these improvements:

- **Type Safety**: Compile-time error checking
- **Better Error Handling**: Structured error reporting
- **Remote Support**: Can manage remote and Kubernetes environments
- **Permissions**: Role-based access control
- **Extensibility**: Can be extended and imported as a library
- **Maintainability**: Much easier to maintain and extend

### Command Mapping

| Old Bash Script | New CLI Command |
|----------------|----------------|
| `tools/scripts/setup.sh` | `setup` |
| `tools/scripts/dev.sh status` | `status` |
| `tools/scripts/test.sh` | Coming soon |
| `tools/scripts/cleanup.sh` | Coming soon |
| `drizzle-kit generate` | `migrate generate` |
| `drizzle-kit push` | `migrate push` |
| `drizzle-kit migrate` | `migrate run` |
| `drizzle-kit studio` | `migrate studio` |

## Configuration Examples

### Local Environment
```json
{
  "name": "local",
  "type": "local",
  "dockerCompose": "docker-compose.prod.yml",
  "services": [
    { "name": "app", "port": 3000, "healthCheck": "/health" }
  ]
}
```

### Remote Environment
```json
{
  "name": "staging",
  "type": "remote", 
  "host": "staging.example.com",
  "username": "deploy",
  "dockerCompose": "docker-compose.prod.yml"
}
```

### Kubernetes Environment
```json
{
  "name": "production",
  "type": "kubernetes",
  "kubeconfig": "~/.kube/config",
  "context": "production",
  "namespace": "yugo-kit"
}
```

## Documentation

- **[Migration Guide](MIGRATION_GUIDE.md)** - Comprehensive database migration documentation
- **[Migration Summary](MIGRATION_SUMMARY.md)** - Technical implementation details
- **[CLI Reference](../docs/development/cli.md)** - Complete command reference

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see LICENSE file for details.