configuring-devenv

# Devenv Configuration

Initializes, configures, and searches devenv development environments.

## Your Task

Determine action from $ARGUMENTS or context:

| Intent | Action |
|--------|--------|
| "init devenv", "set up devenv", "new devenv" | Initialize new project |
| "add package", "configure", "enable" | Modify configuration |
| "search", "find package", "how to add" | Search packages/options |

## Progress Checklist

- [ ] Determine action (init/config/search)
- [ ] Check current state
- [ ] Execute action
- [ ] Validate changes
- [ ] Guide next steps

---

## Initializing Projects

### Step 1: Check Prerequisites

```bash
# Check if devenv exists
test -f devenv.nix && echo "exists" || echo "new"

# Check if devenv is installed
devenv version
```

If not installed: `curl -L https://get.devenv.sh | sh`

### Step 2: Detect Project Type

| File | Project Type |
|------|--------------|
| `package.json` | Node.js |
| `pyproject.toml`, `requirements.txt` | Python |
| `Cargo.toml` | Rust |
| `go.mod` | Go |
| Multiple | Full-stack |

### Step 3: Create Configuration

**Python:**

```nix
{ pkgs, ... }:

{
  languages.python = {
    enable = true;
    version = "3.11";
    venv.enable = true;
  };

  scripts = {
    test.exec = "pytest";
    lint.exec = "ruff check .";
  };

  git-hooks.hooks = {
    black.enable = true;
    ruff.enable = true;
  };
}
```

**Node.js:**

```nix
{ pkgs, ... }:

{
  languages.javascript = {
    enable = true;
    npm.enable = true;  # or bun.enable
  };

  scripts = {
    dev.exec = "npm run dev";
    test.exec = "npm test";
  };

  git-hooks.hooks = {
    prettier.enable = true;
    eslint.enable = true;
  };
}
```

**Rust:**

```nix
{ pkgs, ... }:

{
  languages.rust.enable = true;

  packages = with pkgs; [ cargo-watch ];

  scripts = {
    dev.exec = "cargo watch -x run";
    test.exec = "cargo test";
  };

  git-hooks.hooks = {
    rustfmt.enable = true;
    clippy.enable = true;
  };
}
```

**Go:**

```nix
{ pkgs, ... }:

{
  languages.go.enable = true;

  packages = with pkgs; [ golangci-lint air ];

  scripts = {
    dev.exec = "air";
    test.exec = "go test ./...";
  };

  git-hooks.hooks = {
    gofmt.enable = true;
    govet.enable = true;
  };
}
```

### Step 4: Create Supporting Files

**.envrc:**

```bash
use devenv
```

**.gitignore additions:**

```
.devenv*
devenv.lock
.direnv
```

### Step 5: Validate

```bash
nix-instantiate --parse devenv.nix
devenv info
direnv allow
```

---

## Configuring Projects

### Always Read First

```bash
cat devenv.nix
```

### Languages

```nix
languages = {
  javascript = {
    enable = true;
    npm.enable = true;      # or bun.enable, pnpm.enable
  };
  python = {
    enable = true;
    version = "3.11";
    venv.enable = true;
  };
  rust.enable = true;
  go.enable = true;
};
```

### Packages

```nix
packages = with pkgs; [
  gh            # GitHub CLI
  jq            # JSON processor
  docker
  kubectl
];
```

### Scripts

```nix
scripts = {
  dev.exec = "npm run dev";
  test.exec = "pytest tests/";
  db-reset.exec = ''
    dropdb myapp --if-exists
    createdb myapp
  '';
};
```

### Git Hooks

```nix
git-hooks.hooks = {
  prettier.enable = true;
  eslint.enable = true;
  black.enable = true;
  rustfmt.enable = true;
  shellcheck.enable = true;
  gitleaks.enable = true;
};
```

### Services

```nix
services = {
  postgres = {
    enable = true;
    initialDatabases = [{ name = "myapp_dev"; }];
  };
  redis.enable = true;
  mysql.enable = true;
};
```

### Processes

```nix
processes = {
  backend.exec = "uvicorn main:app --reload";
  frontend.exec = "npm run dev";
};
```

Start all with `devenv up`.

### Environment Variables

```nix
env = {
  DATABASE_URL = "postgresql://localhost/myapp";
  API_KEY = "dev-key";
};
```

### Validation After Changes

```bash
nix-instantiate --parse devenv.nix
devenv info
direnv reload
```

---

## Searching Packages/Options

### Using CLI

```bash
devenv search <query>
```

### Using MCP Tools

Use `mcp__mcp_devenv_sh__search_packages` and `mcp__mcp_devenv_sh__search_options`.

### Common Corrections

| User Types | Search For |
|------------|------------|
| node, npm | nodejs |
| pg, postgresql | postgres |
| k8s | kubectl |
| python3 | python |
| mongo | mongodb |

### Present Results

```markdown
## Search Results for "{query}"

### Configuration Options
| Option | Description |
|--------|-------------|
| `languages.python.enable` | Enable Python support |

### Packages
| Package | Description |
|---------|-------------|
| `python311` | Python 3.11 interpreter |

### Usage Example
(show nix snippet)
```

---

## Full-Stack Configuration

For frontend + backend + database:

```nix
{ pkgs, ... }:

{
  languages = {
    javascript = {
      enable = true;
      npm.enable = true;
    };
    python = {
      enable = true;
      version = "3.11";
      venv.enable = true;
    };
  };

  env = {
    DATABASE_URL = "postgresql://localhost:5432/myapp_dev";
    API_URL = "http://localhost:8000";
  };

  services.postgres = {
    enable = true;
    initialDatabases = [{ name = "myapp_dev"; }];
  };

  processes = {
    backend = {
      exec = "cd backend && uvicorn main:app --reload --port 8000";
      process-compose = {
        depends_on.postgres.condition = "process_healthy";
      };
    };
    frontend = {
      exec = "cd frontend && npm run dev";
      process-compose = {
        depends_on.backend.condition = "process_healthy";
      };
    };
  };

  scripts = {
    dev.exec = "devenv up";
    db-reset.exec = ''
      dropdb myapp_dev --if-exists
      createdb myapp_dev
    '';
  };

  git-hooks.hooks = {
    prettier.enable = true;
    black.enable = true;
  };
}
```

---

## Error Handling

| Issue | Solution |
|-------|----------|
| devenv not found | `curl -L https://get.devenv.sh \| sh` |
| Syntax error | `nix-instantiate --parse devenv.nix` |
| Package not found | Search with MCP tools or `devenv search` |
| Changes not appearing | `direnv reload` or restart shell |
| Service won't start | Check `$DEVENV_STATE` logs |
| Port in use | `lsof -i :<port>` to find process |
| Hook not running | `devenv gc && direnv allow` |

---

## Tips

- Always read devenv.nix before editing
- Use MCP search tools to find correct names
- Prefer `languages.*` over adding interpreter packages
- Use `services.*` for databases (auto-configured)
- Use `processes` for multi-service development
- Test changes with `devenv info` after editing
- Scripts become shell commands automatically