Cloud Environment Setup

Original source / Raw SKILL.md

---
name: Cloud Environment Setup
description: Set up Claude Code cloud/mobile environments for AILANG development. Use when starting a new cloud session, when tools are missing (Go, make, gh), or when user says "setup cloud", "setup environment", or mentions mobile Claude Code.
---

# Cloud Environment Setup

Set up a fresh cloud/mobile Claude Code environment with all tools needed for AILANG development.

## Quick Start

Run the setup script to install all required tools:

```bash
.claude/skills/cloud-setup/scripts/setup.sh
```

Or verify an existing environment:

```bash
.claude/skills/cloud-setup/scripts/verify.sh
```

## When to Use This Skill

Use this skill when:
- Starting a new cloud/mobile Claude Code session
- `go`, `make`, or `gh` commands are not found
- User says "setup cloud", "setup environment", "install tools"
- Build commands fail due to missing tools
- User mentions "mobile Claude Code" or "cloud environment"

## Environment Requirements

### Required Tools

| Tool | Purpose | Minimum Version |
|------|---------|-----------------|
| **Go** | Build AILANG | 1.24+ |
| **make** | Build automation | GNU Make 4+ |
| **gh** | GitHub CLI | 2.0+ |
| **git** | Version control | 2.0+ |

### Resource Requirements

| Resource | Minimum | Recommended |
|----------|---------|-------------|
| RAM | 4 GB | 8+ GB |
| Disk | 5 GB free | 10+ GB |
| CPUs | 2 | 4+ |
| Network | Required | Required |

## Setup Workflow

### Step 1: Assess Current Environment

```bash
# Check what's available
which go make gh git 2>/dev/null
go version 2>/dev/null
```

### Step 2: Fix DNS (if needed)

Cloud environments sometimes have broken DNS. Fix with:

```bash
echo "nameserver 8.8.8.8" > /etc/resolv.conf
echo "nameserver 8.8.4.4" >> /etc/resolv.conf
```

### Step 3: Install Go

```bash
# Install via apt (may get older version)
apt-get update && apt-get install -y golang-go make

# OR install specific version directly
wget --no-check-certificate https://go.dev/dl/go1.24.4.linux-amd64.tar.gz -O /tmp/go.tar.gz
rm -rf /usr/local/go && tar -C /usr/local -xzf /tmp/go.tar.gz
export PATH=/usr/local/go/bin:$PATH
```

### Step 4: Install GitHub CLI

```bash
# Download and install
curl -L https://github.com/cli/cli/releases/download/v2.63.2/gh_2.63.2_linux_amd64.tar.gz -o /tmp/gh.tar.gz
tar -xzf /tmp/gh.tar.gz -C /tmp
mv /tmp/gh_*/bin/gh /usr/local/bin/
rm -rf /tmp/gh*
```

### Step 5: Configure Go Environment

```bash
export PATH=/usr/local/go/bin:$PATH
export GOTOOLCHAIN=local      # Prevent auto-download of newer Go
export GOPROXY=direct         # Bypass proxy if blocked
```

### Step 6: Build AILANG

```bash
# Download dependencies
go mod download

# Build
make build

# Verify
./bin/ailang run examples/runnable/hello.ail
```

## Available Scripts

### `scripts/setup.sh`

Full automated setup - installs Go, make, gh, and builds AILANG.

**Usage:**
```bash
.claude/skills/cloud-setup/scripts/setup.sh
```

**What it does:**
1. Checks current environment
2. Fixes DNS if needed
3. Installs Go 1.24.4
4. Installs make
5. Installs GitHub CLI
6. Downloads Go modules
7. Builds AILANG
8. Runs verification

### `scripts/verify.sh`

Verify environment is correctly set up.

**Usage:**
```bash
.claude/skills/cloud-setup/scripts/verify.sh
```

**Checks:**
- Go version and PATH
- make availability
- gh CLI availability
- AILANG binary exists
- AILANG can run examples
- Core tests pass

## Resources

### Troubleshooting Guide
See [`resources/troubleshooting.md`](resources/troubleshooting.md) for common issues and solutions.

## Known Issues

### 1. Go Toolchain Auto-Download

**Symptom:** Go tries to download newer toolchain, fails with network error

**Solution:** Set `GOTOOLCHAIN=local`

### 2. DNS Resolution Failures

**Symptom:** `dial tcp: lookup ... on [::1]:53: connection refused`

**Solution:** Add Google DNS to `/etc/resolv.conf`:
```bash
echo "nameserver 8.8.8.8" > /etc/resolv.conf
```

### 3. Go Module Proxy Blocked

**Symptom:** Timeout connecting to `proxy.golang.org` or `storage.googleapis.com`

**Solution:** Use direct downloads:
```bash
export GOPROXY=direct
go mod download
```

### 4. SSL/TLS Handshake Failures

**Symptom:** `curl: (35) ... sslv3 alert handshake failure`

**Solution:** Use `wget --no-check-certificate` instead of `curl`

### 5. Missing Basic Commands

**Symptom:** `head`, `tail`, `grep` not found

**Solution:** Either install coreutils or avoid piping:
```bash
# Instead of: command | head -20
# Just run: command
# And manually inspect output
```

## Post-Setup Checklist

After setup, verify you can:

- [ ] `go version` shows 1.24+
- [ ] `make --version` works
- [ ] `gh --version` works
- [ ] `./bin/ailang run examples/runnable/hello.ail` outputs "Hello, AILANG!"
- [ ] `go test ./internal/lexer/...` passes

## Environment Variables

Set these in your session for reliable builds:

```bash
export PATH=/usr/local/go/bin:$PATH
export GOTOOLCHAIN=local
export GOPROXY=direct
```

## What You Can Do After Setup

With environment configured, you can:

1. **Build AILANG**: `make build`
2. **Run programs**: `./bin/ailang run --caps IO file.ail`
3. **Run tests**: `go test ./internal/...`
4. **Work on design docs**: Full read/write access
5. **Commit and push**: Git operations work
6. **UI development**: Node/npm available for `ui/` work


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### resources/troubleshooting.md

```markdown
# Cloud Setup Troubleshooting Guide

This guide covers common issues when setting up AILANG in cloud/mobile Claude Code environments.

## DNS Issues

### Symptom
```
dial tcp: lookup storage.googleapis.com on [::1]:53: read udp ... connection refused
```

### Cause
Cloud environment has no DNS configured or broken DNS resolution.

### Solution
```bash
# Add Google DNS servers
echo "nameserver 8.8.8.8" > /etc/resolv.conf
echo "nameserver 8.8.4.4" >> /etc/resolv.conf
```

---

## Go Toolchain Auto-Download

### Symptom
```
go: downloading go1.24.11 (linux/amd64)
go: download go1.24.11: ... connection refused
```

### Cause
The `go.mod` file specifies a `toolchain` directive, and Go tries to download that exact version.

### Solution
```bash
# Tell Go to use the installed version
export GOTOOLCHAIN=local
```

This prevents Go from trying to download a newer toolchain.

---

## Go Module Proxy Blocked

### Symptom
```
Get "https://proxy.golang.org/...": i/o timeout
```
or
```
Get "https://storage.googleapis.com/...": context deadline exceeded
```

### Cause
The Go module proxy (proxy.golang.org) or its backend (storage.googleapis.com) is blocked or slow.

### Solution
```bash
# Bypass proxy, download directly from sources
export GOPROXY=direct
go mod download
```

---

## SSL/TLS Handshake Failures

### Symptom
```
curl: (35) OpenSSL/3.0.13: error:0A000410:SSL routines::sslv3 alert handshake failure
```

### Cause
Some cloud environments have SSL/TLS issues with certain endpoints.

### Solution
Use `wget` with certificate checking disabled:
```bash
# Instead of curl:
wget --no-check-certificate https://go.dev/dl/go1.24.4.linux-amd64.tar.gz -O /tmp/go.tar.gz
```

---

## Missing Basic Commands

### Symptom
```
/bin/bash: line 1: head: command not found
/bin/bash: line 1: tail: command not found
/bin/bash: line 1: grep: command not found
```

### Cause
Minimal container image without coreutils.

### Solutions

**Option 1**: Install coreutils
```bash
apt-get update && apt-get install -y coreutils grep
```

**Option 2**: Avoid piping, run commands directly
```bash
# Instead of: go test ./... 2>&1 | tail -20
# Just run: go test ./...
# And manually scan output
```

---

## apt-get Issues

### Symptom
```
E: Malformed entry in list file
E: The list of sources could not be read
```

### Cause
Corrupted apt sources list.

### Solution
```bash
# Remove problematic source
rm -f /etc/apt/sources.list.d/problematic-file.list
apt-get update
```

---

## Go Version Mismatch

### Symptom
```
go: go.mod requires go >= 1.24
```

### Cause
apt-get installed older Go version (e.g., 1.22).

### Solution
Install Go directly from golang.org:
```bash
wget --no-check-certificate https://go.dev/dl/go1.24.4.linux-amd64.tar.gz -O /tmp/go.tar.gz
rm -rf /usr/local/go
tar -C /usr/local -xzf /tmp/go.tar.gz
export PATH=/usr/local/go/bin:$PATH
```

---

## Tests Hanging

### Symptom
Tests start running but hang indefinitely on certain packages.

### Cause
Some test packages (eval harness, AI clients) may require network access that's blocked or slow.

### Solution
Run targeted tests instead of full suite:
```bash
# Core packages (no network needed)
go test ./internal/lexer/... ./internal/parser/... ./internal/types/... ./internal/eval/... -count=1

# Skip problematic packages
go test $(go list ./... | grep -v eval_harness | grep -v /ai/) -count=1
```

---

## GitHub CLI Authentication

### Symptom
```
gh: To use GitHub CLI, run 'gh auth login' first.
```

### Cause
gh CLI is installed but not authenticated.

### Solution
```bash
# Interactive login
gh auth login

# Or use token
gh auth login --with-token < token.txt

# Check status
gh auth status
```

---

## Build Failures

### Symptom
```
make: *** [Makefile:40: build] Error 1
```

### Cause
Various - check the actual error message above this line.

### Common Fixes

**Missing dependencies:**
```bash
go mod download
```

**Wrong Go version:**
```bash
export PATH=/usr/local/go/bin:$PATH
export GOTOOLCHAIN=local
```

**Network issues:**
```bash
export GOPROXY=direct
```

---

## Quick Diagnostic Commands

```bash
# Check all tools
which go make gh git

# Check Go setup
go version
go env GOPATH GOROOT GOTOOLCHAIN GOPROXY

# Check network
curl -s --connect-timeout 5 https://api.github.com | head -1

# Check DNS
cat /etc/resolv.conf
host google.com

# Check disk space
df -h .

# Check memory
free -h
```

---

## Environment Variables Checklist

Set these at the start of every session:

```bash
export PATH=/usr/local/go/bin:$PATH
export GOTOOLCHAIN=local
export GOPROXY=direct
```

Or add to `~/.bashrc` for persistence:

```bash
echo 'export PATH=/usr/local/go/bin:$PATH' >> ~/.bashrc
echo 'export GOTOOLCHAIN=local' >> ~/.bashrc
echo 'export GOPROXY=direct' >> ~/.bashrc
```

```

### scripts/setup.sh

```bash
#!/usr/bin/env bash
# Cloud Environment Setup for AILANG Development
# Installs Go, make, gh, and builds AILANG binary

set -euo pipefail

echo "=========================================="
echo "AILANG Cloud Environment Setup"
echo "=========================================="
echo ""

# Colors (if supported)
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

success() { echo -e "${GREEN}✓${NC} $1"; }
fail() { echo -e "${RED}✗${NC} $1"; }
warn() { echo -e "${YELLOW}⚠${NC} $1"; }
info() { echo "→ $1"; }

FAILURES=0

# Step 1: Check current environment
echo "Step 1/7: Assessing current environment..."
echo ""

info "System info:"
echo "  RAM: $(free -h 2>/dev/null | awk '/Mem:/ {print $2}' || echo 'unknown')"
echo "  CPUs: $(nproc 2>/dev/null || echo 'unknown')"
echo "  Disk: $(df -h . 2>/dev/null | awk 'NR==2 {print $4}' || echo 'unknown') available"
echo ""

# Step 2: Fix DNS if needed
echo "Step 2/7: Checking DNS..."

if ! host google.com > /dev/null 2>&1; then
    warn "DNS not working, configuring Google DNS..."
    echo "nameserver 8.8.8.8" > /etc/resolv.conf
    echo "nameserver 8.8.4.4" >> /etc/resolv.conf
    success "DNS configured"
else
    success "DNS working"
fi
echo ""

# Step 3: Install make
echo "Step 3/7: Installing make..."

if command -v make &> /dev/null; then
    success "make already installed: $(make --version 2>/dev/null | head -1)"
else
    info "Installing make via apt..."
    apt-get update -qq
    apt-get install -y -qq make
    success "make installed"
fi
echo ""

# Step 4: Install Go
echo "Step 4/7: Installing Go 1.24..."

GO_VERSION="1.24.4"
GO_INSTALLED_VERSION=$(go version 2>/dev/null | awk '{print $3}' | sed 's/go//' || echo "none")

if [[ "$GO_INSTALLED_VERSION" == "1.24"* ]]; then
    success "Go $GO_INSTALLED_VERSION already installed"
else
    info "Downloading Go $GO_VERSION..."

    # Try wget first (more reliable in some environments)
    if command -v wget &> /dev/null; then
        wget --no-check-certificate -q "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz" -O /tmp/go.tar.gz
    else
        curl -fsSL "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz" -o /tmp/go.tar.gz
    fi

    info "Installing Go..."
    rm -rf /usr/local/go
    tar -C /usr/local -xzf /tmp/go.tar.gz
    rm /tmp/go.tar.gz

    success "Go $GO_VERSION installed to /usr/local/go"
fi

# Ensure Go is in PATH
export PATH=/usr/local/go/bin:$PATH
echo ""

# Step 5: Install GitHub CLI
echo "Step 5/7: Installing GitHub CLI..."

GH_VERSION="2.63.2"

if command -v gh &> /dev/null; then
    success "gh already installed: $(gh --version 2>/dev/null | head -1)"
else
    info "Downloading gh $GH_VERSION..."

    if command -v wget &> /dev/null; then
        wget --no-check-certificate -q "https://github.com/cli/cli/releases/download/v${GH_VERSION}/gh_${GH_VERSION}_linux_amd64.tar.gz" -O /tmp/gh.tar.gz
    else
        curl -fsSL "https://github.com/cli/cli/releases/download/v${GH_VERSION}/gh_${GH_VERSION}_linux_amd64.tar.gz" -o /tmp/gh.tar.gz
    fi

    info "Installing gh..."
    tar -xzf /tmp/gh.tar.gz -C /tmp
    mv /tmp/gh_${GH_VERSION}_linux_amd64/bin/gh /usr/local/bin/
    rm -rf /tmp/gh*

    success "gh $GH_VERSION installed"
fi
echo ""

# Step 6: Download Go modules and build AILANG
echo "Step 6/7: Building AILANG..."

# Set environment for reliable builds
export GOTOOLCHAIN=local
export GOPROXY=direct

info "Downloading Go modules..."
go mod download

info "Building AILANG..."
make build

if [[ -f "bin/ailang" ]]; then
    success "AILANG built: bin/ailang"
else
    fail "AILANG build failed"
    FAILURES=$((FAILURES + 1))
fi
echo ""

# Step 7: Verify
echo "Step 7/7: Verification..."

# Test AILANG runs
if ./bin/ailang run examples/runnable/hello.ail 2>&1 | grep -q "Hello, AILANG!"; then
    success "AILANG runs correctly"
else
    fail "AILANG test failed"
    FAILURES=$((FAILURES + 1))
fi

# Quick test of core packages
info "Running quick test..."
if go test ./internal/lexer/... -count=1 > /tmp/setup_test.log 2>&1; then
    success "Core tests pass"
else
    warn "Some tests failed - see /tmp/setup_test.log"
fi
echo ""

# Summary
echo "=========================================="
if [[ $FAILURES -eq 0 ]]; then
    echo -e "${GREEN}✓ Setup Complete!${NC}"
    echo ""
    echo "Environment ready. You can now:"
    echo "  • Build: make build"
    echo "  • Run: ./bin/ailang run --caps IO file.ail"
    echo "  • Test: go test ./internal/..."
    echo ""
    echo "Set these in each session:"
    echo "  export PATH=/usr/local/go/bin:\$PATH"
    echo "  export GOTOOLCHAIN=local"
    echo "  export GOPROXY=direct"
else
    echo -e "${RED}✗ Setup had $FAILURES failure(s)${NC}"
    echo "Check the errors above and try again."
    exit 1
fi
echo "=========================================="

```

### scripts/verify.sh

```bash
#!/usr/bin/env bash
# Verify AILANG cloud environment is correctly configured

set -euo pipefail

echo "=========================================="
echo "AILANG Environment Verification"
echo "=========================================="
echo ""

# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'

success() { echo -e "${GREEN}✓${NC} $1"; }
fail() { echo -e "${RED}✗${NC} $1"; }
warn() { echo -e "${YELLOW}⚠${NC} $1"; }

FAILURES=0
WARNINGS=0

# Ensure PATH includes Go
export PATH=/usr/local/go/bin:$PATH

echo "Checking tools..."
echo ""

# Check Go
if command -v go &> /dev/null; then
    GO_VER=$(go version 2>/dev/null | awk '{print $3}')
    if [[ "$GO_VER" == "go1.24"* ]]; then
        success "Go: $GO_VER"
    else
        warn "Go: $GO_VER (expected 1.24+)"
        WARNINGS=$((WARNINGS + 1))
    fi
else
    fail "Go: not found"
    FAILURES=$((FAILURES + 1))
fi

# Check make
if command -v make &> /dev/null; then
    success "make: $(make --version 2>/dev/null | head -1 | awk '{print $3}')"
else
    fail "make: not found"
    FAILURES=$((FAILURES + 1))
fi

# Check gh
if command -v gh &> /dev/null; then
    success "gh: $(gh --version 2>/dev/null | head -1 | awk '{print $3}')"
else
    warn "gh: not found (optional for GitHub operations)"
    WARNINGS=$((WARNINGS + 1))
fi

# Check git
if command -v git &> /dev/null; then
    success "git: $(git --version 2>/dev/null | awk '{print $3}')"
else
    fail "git: not found"
    FAILURES=$((FAILURES + 1))
fi

echo ""
echo "Checking AILANG binary..."
echo ""

# Check AILANG binary exists
if [[ -f "bin/ailang" ]]; then
    success "bin/ailang exists"
else
    fail "bin/ailang not found (run: make build)"
    FAILURES=$((FAILURES + 1))
fi

# Test AILANG runs
if [[ -f "bin/ailang" ]]; then
    OUTPUT=$(./bin/ailang run examples/runnable/hello.ail 2>&1 || true)
    if echo "$OUTPUT" | grep -q "Hello, AILANG!"; then
        success "AILANG executes correctly"
    else
        fail "AILANG execution failed"
        echo "    Output: $OUTPUT"
        FAILURES=$((FAILURES + 1))
    fi
fi

echo ""
echo "Checking environment variables..."
echo ""

# Check GOTOOLCHAIN
if [[ "${GOTOOLCHAIN:-}" == "local" ]]; then
    success "GOTOOLCHAIN=local"
else
    warn "GOTOOLCHAIN not set to 'local' (may cause auto-download issues)"
    WARNINGS=$((WARNINGS + 1))
fi

# Check GOPROXY
if [[ "${GOPROXY:-}" == "direct" ]]; then
    success "GOPROXY=direct"
else
    warn "GOPROXY not set to 'direct' (may cause proxy issues)"
    WARNINGS=$((WARNINGS + 1))
fi

echo ""
echo "Checking network..."
echo ""

# Check network connectivity
if curl -s --connect-timeout 5 -o /dev/null https://api.github.com 2>/dev/null; then
    success "Network: GitHub API accessible"
else
    warn "Network: GitHub API not accessible"
    WARNINGS=$((WARNINGS + 1))
fi

echo ""
echo "Running quick tests..."
echo ""

# Run lexer tests
if go test ./internal/lexer/... -count=1 > /tmp/verify_test.log 2>&1; then
    success "Lexer tests pass"
else
    fail "Lexer tests fail - see /tmp/verify_test.log"
    FAILURES=$((FAILURES + 1))
fi

# Run parser tests
if go test ./internal/parser/... -count=1 >> /tmp/verify_test.log 2>&1; then
    success "Parser tests pass"
else
    fail "Parser tests fail - see /tmp/verify_test.log"
    FAILURES=$((FAILURES + 1))
fi

echo ""
echo "=========================================="

if [[ $FAILURES -eq 0 ]] && [[ $WARNINGS -eq 0 ]]; then
    echo -e "${GREEN}✓ All checks passed!${NC}"
    echo ""
    echo "Environment is fully configured and ready."
elif [[ $FAILURES -eq 0 ]]; then
    echo -e "${YELLOW}⚠ Passed with $WARNINGS warning(s)${NC}"
    echo ""
    echo "Environment is usable but may have minor issues."
    echo "Consider setting environment variables:"
    echo "  export PATH=/usr/local/go/bin:\$PATH"
    echo "  export GOTOOLCHAIN=local"
    echo "  export GOPROXY=direct"
else
    echo -e "${RED}✗ $FAILURES check(s) failed${NC}"
    echo ""
    echo "Run setup script to fix:"
    echo "  .claude/skills/cloud-setup/scripts/setup.sh"
    exit 1
fi
echo "=========================================="

```