General lamcher

.claude/settings.json

@@ -1,5 +1,6 @@
 {
   "enabledPlugins": {
-    "test-automation": true
+    "test-automation": true,
+    "doc-enforcement": true
   }
 }

.launcher-config.template.yaml

@@ -0,0 +1,43 @@
+# Launcher Configuration Template
+# Copy this to your project root as .launcher-config.yaml
+
+project:
+  name: myproject              # Internal project name (lowercase, no spaces)
+  display_name: My Project     # Human-readable name shown in UI
+
+prerequisites:
+  required:
+    - docker
+    - git
+  optional:
+    - python
+    - uv
+
+setup:
+  command: ./setup.sh          # Command to run when setting up the project
+  env_vars:
+    - PROJECT_ROOT
+    - WORKTREE_PATH
+
+infrastructure:
+  compose_file: docker-compose.yml  # Path to compose file for shared infrastructure
+  project_name: myproject-infra     # Docker compose project name
+  profile: default                  # Optional: compose profile to use
+
+containers:
+  naming_pattern: "{env_name}-{service}"  # How containers are named
+  primary_service: backend              # Main service to health-check
+  health_endpoint: /health              # Health check endpoint
+  tailscale_project_prefix: myproject   # Optional: Tailscale prefix
+
+ports:
+  allocation_strategy: offset     # or: fixed
+  base_port: 8000                # Starting port for services
+  offset:
+    min: 0
+    max: 100
+    step: 10
+
+worktrees:
+  default_parent: ../worktrees/{project_name}  # Where worktrees are created
+  branch_prefix: env/                          # Optional prefix for environment branches

.launcher-config.yaml

@@ -0,0 +1,80 @@
+# Ushadow Launcher Configuration
+# This file defines how the launcher manages environments for this project
+
+project:
+  name: "ushadow"
+  display_name: "Ushadow"
+
+# Prerequisites required for this project
+prerequisites:
+  required:
+    - docker
+    - git
+    - python3
+  optional:
+    - tailscale
+    - uv
+
+# Environment setup configuration
+setup:
+  # Command to run when creating a new environment
+  # Available variables: {ENV_NAME}, {PORT_OFFSET}, {WORKING_DIR}
+  command: "uv run --with pyyaml setup/run.py --dev --quick --skip-admin"
+
+  # Environment variables passed during setup
+  env_vars:
+    - ENV_NAME
+    - PORT_OFFSET
+    - USHADOW_NO_BROWSER=1
+
+# Docker infrastructure configuration (shared services)
+infrastructure:
+  # Path to infrastructure compose file (relative to project root)
+  compose_file: "compose/docker-compose.infra.yml"
+
+  # Docker Compose project name for infrastructure
+  project_name: "infra"
+
+  # Profile to use when starting infrastructure (optional)
+  profile: "infra"
+
+# Container naming and discovery
+containers:
+  # Naming pattern for environment containers
+  # Variables: {project_name}, {env_name}, {service_name}
+  # Note: {env_name} will be empty for "default" environment
+  naming_pattern: "{project_name}{env_name}-{service_name}"
+
+  # Primary service that exposes the main application port
+  # This service's port is used to calculate other service ports
+  primary_service: "backend"
+
+  # Health check endpoint (relative to primary service)
+  health_endpoint: "/api/unodes/leader/info"
+
+  # Optional: Project prefix for Tailscale hostnames (for multi-project setups)
+  # If not set, Tailscale URLs will be: https://{env}.{tailnet}
+  # If set to "ushadow", URLs will be: https://ushadow-{env}.{tailnet}
+  # tailscale_project_prefix: "ushadow"
+
+# Port management
+ports:
+  # Strategy: "hash" (deterministic from env name) | "sequential" | "random"
+  allocation_strategy: "hash"
+
+  # Base port for primary service (default environment)
+  base_port: 8000
+
+  # Port offset configuration (for hash-based allocation)
+  offset:
+    min: 0
+    max: 500
+    step: 10  # Offsets are multiples of 10: 0, 10, 20, 30...
+
+# Worktree configuration
+worktrees:
+  # Default parent directory for worktrees (expandable via ~)
+  default_parent: "~/repos/worktrees/{project_name}"
+
+  # Optional prefix for branch names (e.g., "env/" creates "env/staging")
+  branch_prefix: ""

.workmux.yaml

@@ -53,8 +53,6 @@ panes:
   # Main pane - ready for commands or agent interaction
   - command: "echo '🚀 Ushadow Environment: $(basename $(pwd))' && echo '' && echo 'Quick commands:' && echo '  ./dev.sh    - Start in dev mode' && echo '  ./go.sh     - Start in prod mode' && echo '  make test   - Run tests' && echo '  code .      - Open in VSCode' && echo '' && $SHELL"
     focus: true
-    split: horizontal
-    size: 75%
 
 # Agent status icons (shown in tmux status bar)
 status_icons:

ENV_CONFIG_GUIDE.md

@@ -0,0 +1,135 @@
+# Environment Configuration System
+
+## Overview
+
+The launcher now supports comprehensive environment configuration including:
+- Custom startup commands per project
+- Automatic port detection and allocation
+- Multi-environment support with port offsetting
+- Database and service port management
+
+## How It Works
+
+### 1. Project Configuration (`.launcher-config.yaml`)
+
+Each project can have a configuration file that defines:
+
+```yaml
+project:
+  name: myproject
+  display_name: My Project
+
+setup:
+  command: ./go.sh            # Command to start an environment
+  env_vars:                   # Vars to inject
+    - PROJECT_ROOT
+    - WORKTREE_PATH
+    - PORT_OFFSET             # Auto-calculated offset
+
+ports:
+  allocation_strategy: offset  # or: fixed
+  base_port: 8000
+  offset:
+    min: 0
+    max: 100
+    step: 10                   # Each env gets ports +10 from previous
+```
+
+### 2. Port Detection
+
+The launcher scans `.env.template` or `.env.example` to detect:
+- Port variables (e.g., `BACKEND_PORT`, `WEBUI_PORT`)
+- Database ports (e.g., `POSTGRES_PORT`, `REDIS_PORT`)
+- Default values
+
+**Example `.env.template`:**
+```bash
+BACKEND_PORT=8000
+WEBUI_PORT=3000
+POSTGRES_PORT=5432
+REDIS_PORT=6379
+```
+
+### 3. Port Allocation
+
+When creating environments, ports are automatically offset:
+
+**Environment 1 (offset=0):**
+- BACKEND_PORT=8000
+- WEBUI_PORT=3000
+- POSTGRES_PORT=5432
+
+**Environment 2 (offset=10):**
+- BACKEND_PORT=8010
+- WEBUI_PORT=3010
+- POSTGRES_PORT=5442
+
+**Environment 3 (offset=20):**
+- BACKEND_PORT=8020
+- WEBUI_PORT=3020
+- POSTGRES_PORT=5452
+
+### 4. Environment Startup
+
+When you create or start an environment:
+1. Launcher calculates the port offset
+2. Injects environment variables:
+   ```bash
+   PROJECT_ROOT=/Users/you/repos/myproject
+   WORKTREE_PATH=/Users/you/repos/worktrees/myproject/dev
+   PORT_OFFSET=10
+   ```
+3. Runs the startup command (e.g., `./go.sh`)
+4. Your startup script reads PORT_OFFSET and adjusts ports accordingly
+
+## Startup Script Pattern
+
+Your `go.sh` or startup script should use the PORT_OFFSET:
+
+```bash
+#!/bin/bash
+
+# Get port offset from environment (default to 0)
+OFFSET=${PORT_OFFSET:-0}
+
+# Calculate actual ports
+export BACKEND_PORT=$((8000 + OFFSET))
+export WEBUI_PORT=$((3000 + OFFSET))
+export POSTGRES_PORT=$((5432 + OFFSET))
+export REDIS_PORT=$((6379 + OFFSET))
+
+# Load base .env if it exists
+if [ -f .env.template ]; then
+  source .env.template
+fi
+
+# Override with offset ports
+cat > .env.local <<EOF
+BACKEND_PORT=${BACKEND_PORT}
+WEBUI_PORT=${WEBUI_PORT}
+POSTGRES_PORT=${POSTGRES_PORT}
+REDIS_PORT=${REDIS_PORT}
+EOF
+
+# Start services
+docker compose --env-file .env.local up -d
+```
+
+## Configuration UI
+
+Access the configuration editor:
+1. Enable Multi-Project Mode in settings
+2. Go to Install tab
+3. Add or select a project
+4. Click "Configure" or "Edit Config"
+5. Set startup command and port strategy
+6. Click "Scan .env files" to auto-detect ports
+
+## Next Steps
+
+- [ ] Add TypeScript interface for DetectedPort
+- [ ] Wire up ProjectConfigEditor in ProjectsPanel
+- [ ] Implement config save/load commands
+- [ ] Auto-calculate PORT_OFFSET when creating environments
+- [ ] Inject env vars when running startup commands
+- [ ] Add UI to show port allocations for each environment