# CLAUDE.md

## Project Overview

This repository contains a dual-mode setup script for creating OrbStack-based development sandboxes tailored for Claude Code with Elixir/Erlang, browser automation, and PostgreSQL.

## Repository Structure

```
setup_env.sh        - Main script (macOS host mode + Linux VM provisioning mode)
config.env.example  - Example credentials file
config.env          - User credentials (gitignored, created on first run)
.gitignore          - Ignores config.env
README.md           - User-facing documentation
CLAUDE.md           - This file (context for Claude Code sessions)
```

## How the Script Works

The script has two modes, detected via `uname -s`:

- **Darwin (macOS)**: Orchestrator mode. Checks for OrbStack, reads/creates `config.env`, creates a VM, copies itself in, runs itself inside the VM with `--non-interactive`.
- **Linux (VM)**: Provisioning mode. Installs all tools, configures PostgreSQL, sets up VNC, installs Claude Code plugins.

This means `./setup_env.sh my-vm` on macOS does everything end-to-end.

## Key Technical Details

- **Target environment**: OrbStack Ubuntu VM on macOS Apple Silicon (ARM64)
- **Version manager**: mise (manages Node.js, Erlang, Elixir)
- **Language versions**: Configured at the top of `setup_env.sh` as variables (`ERLANG_VERSION`, `ELIXIR_VERSION`)
- **PostgreSQL auth**: Peer for local socket, trust for localhost TCP (127.0.0.1), scram-sha-256 for host network (192.168.0.0/16)
- **Browser**: Chromium (no Chrome ARM64 Linux builds exist), symlinked to `google-chrome`
- **VNC**: TigerVNC + XFCE on display :1 (port 5901), controlled via `vnc-start`/`vnc-stop` helpers in `~/bin`
- **Shared credentials**: `config.env` is created once and reused for all VMs

## Working on This Project

### Editing setup_env.sh

- The macOS host-mode block is at the top (inside the `if [[ "$(uname -s)" == "Darwin" ]]` block)
- The Linux VM-mode block is everything after that conditional
- Version numbers are defined as variables at the top (`ERLANG_VERSION`, `ELIXIR_VERSION`)
- All installation steps must be idempotent (safe to run multiple times)
- Use `log_info`, `log_warn`, `log_error` helpers for output
- New apt packages go in the base dependencies section
- New Claude plugins go in the appropriate array (`ANTHROPIC_PLUGINS` or `SUPERPOWERS_PLUGINS`)
- Redirect verbose output to `$LOG_FILE`, show only meaningful progress to the user
- The `LOG_FILE` variable is only set in VM mode (not available in macOS host mode)
- Each optional component is wrapped in `prompt_install "Name" "Description"` — this handles both interactive prompts and `--yes`/`--non-interactive` auto-accept
- Track dependency flags (`INSTALLED_NODE`, `INSTALLED_CHROMIUM`) to skip dependent components gracefully

### Script Conventions

- `set -euo pipefail` is enforced - handle potential failures with `|| true` or explicit checks
- Use `command_exists` to check for already-installed tools
- Use `apt-get` (not `apt`) for scripting reliability
- Quote all variable expansions
- Use `find` for PostgreSQL config paths (version-agnostic)
- The `--non-interactive` flag is for VM mode (implies `--yes`); macOS mode always uses config.env
- `--yes`/`-y` accepts all components without prompting but still allows interactive credential entry
- `MISE_GLOBAL_CONFIG_FILE` and `MISE_CONFIG_DIR` are set to prevent OrbStack host-mount config pollution

### Testing

There are no automated tests. To test changes:
1. Remove an existing test VM: `orb delete test-sandbox`
2. Run: `./setup_env.sh test-sandbox`
3. Verify provisioning completes
4. Run again to verify idempotency: `ssh test-sandbox@orb -- bash /tmp/setup_env.sh --non-interactive` (will need env vars)
5. Test VNC: `ssh test-sandbox@orb -- vnc-start`, then `open vnc://test-sandbox.orb.local:5901`
6. Clean up: `orb delete test-sandbox`

### Security Considerations

- `config.env` is chmod 600 and gitignored
- PostgreSQL remote access uses scram-sha-256 (not trust)
- The script refuses to run as root inside the VM
- VNC password is required (min 6 chars)
- VNC binds to all interfaces (`-localhost no`) to allow connections from the macOS host — this is intentional for the OrbStack use case