Env Manager

SKILL.md

---
name: env-manager
description: Set up and manage dev environments. Python/Node/Docker/Go/Rust project scaffolding, port tracking, service management, and cleanup. Zero external dependencies.
---

# Env Manager 🛠️

**Stop setting up dev environments by hand. Start scaffolding them in seconds.**

## The Problem

Every new project needs a dev environment: Python venv, Node project, Docker setup, Go module, or Rust crate. That's boilerplate you don't want to type every time.

Env Manager automates environment scaffolding, port tracking, and service management.

## Quick Start

### Create a Python environment

```bash
node skills/env-manager/env-manager.js --setup python my-project
```

Creates a virtualenv with activation instructions.

### Create a Node project

```bash
node skills/env-manager/env-manager.js --setup node my-app
```

Creates package.json, index.js, and .gitignore.

### Create a Docker project

```bash
node skills/env-manager/env-manager.js --setup docker my-service
```

Creates Dockerfile and docker-compose.yml.

### Create a Go project

```bash
node skills/env-manager/env-manager.js --setup go my-api
```

Initializes Go module with main.go.

### Create a Rust project

```bash
node skills/env-manager/env-manager.js --setup rust my-cli
```

Creates Cargo.toml and src/main.rs.

### List managed ports

```bash
node skills/env-manager/env-manager.js --ports
```

### Find free ports

```bash
node skills/env-manager/env-manager.js --ports --free
```

### List managed services

```bash
node skills/env-manager/env-manager.js --services
```

### Check service health

```bash
node skills/env-manager/env-manager.js --services --status my-service
```

### Start/stop a service

```bash
node skills/env-manager/env-manager.js --services --start my-service
node skills/env-manager/env-manager.js --services --stop my-service
```

### Clean up inactive environments

```bash
node skills/env-manager/env-manager.js --cleanup
```

### Status overview

```bash
node skills/env-manager/env-manager.js --status
```

## Features

### Multi-Language Scaffolding

- **Python** — venv with python3, pip detection
- **Node** — package.json with dev scripts, .gitignore
- **Docker** — Dockerfile + docker-compose.yml
- **Go** — go.mod + main.go
- **Rust** — Cargo.toml + src/main.rs

### Port Tracking

- Tracks which ports are managed by which services
- Finds free ports in range 3000-9000 (multiples of 10)
- Shows running/stopped status

### Service Management

- List, start, stop, and health check services
- Port-based health detection via `lsof`
- Persistent service state in JSON

### Environment Cleanup

- Identifies inactive environments
- Reports what would be cleaned
- No destructive action by default

### Environment Types Tracking

- Counts environments by type
- Shows version info for each environment
- Persistent across restarts

## Configuration

Data files stored in: `memory/environments/`

- `environments.json` — Environment definitions
- `ports.json` — Port tracking
- `services.json` — Service management

Environments created in: `environments/`

Override data directory:
```bash
--dir /path/to/data
```

## Agent Protocol

When setting up new projects:

1. **Choose the right type** — `--setup <python|node|docker|go|rust>`
2. **Name explicitly** — `--setup node my-app` (auto-names are hard to find)
3. **Check ports** — `--ports --free` before starting new services
4. **Track services** — Register new services in `services.json`
5. **Clean up** — `--cleanup` periodically to remove stale environments

## Heartbeat Integration

Add to your `HEARTBEAT.md`:

```markdown
### 🛠️ Environment Check

- Run `node skills/env-manager/env-manager.js --services --status` to check service health
- Run `node skills/env-manager/env-manager.js --ports` to check port usage
```

## Limitations

- Service start/stop is state tracking only (no actual process management)
- Port detection uses `lsof` (Linux only)
- Environment creation depends on tools being installed (python3, node, docker, go, rustc)
- No automatic dependency installation

## Comparison

| Approach | Scaffolding | Port Tracking | Service Mgmt |
|----------|------------|---------------|--------------|
| Manual | ❌ | ❌ | ❌ |
| Docker Compose | ⚠️ | ❌ | ⚠️ |
| **Env Manager** | **✅** | **✅** | **✅** |

**Env Manager gives you multi-language scaffolding + port tracking + service management in one tool.**

## Security

### Command Allowlist
Only pre-approved binaries can be executed: `python3`, `node`, `npm`, `docker`, `go`, `rustc`, `pip3`, `lsof`

### Shell Escaping
All user-provided values (environment names, paths, port numbers) are shell-escaped to prevent injection.

### Path Validation
Before executing any command, the skill validates that the binary exists on the system.

### Dry-Run Mode
Set `ENV_DRY_RUN=1` to see what commands would run without executing them. Useful for reviewing actions before they happen.

## Design Principles

1. **Zero setup** — Works immediately, no config needed
2. **No dependencies** — Pure Node.js fs/child_process, no npm packages
3. **Multi-language** — Python, Node, Docker, Go, Rust in one tool
4. **Persistent** — Environments, ports, and services tracked in JSON
5. **Safe** — Dry-run cleanup, no destructive action by default