diff --git a/cli/docs/claude-code-web.md b/cli/docs/claude-code-web.md index 763fc82..3e36d23 100644 --- a/cli/docs/claude-code-web.md +++ b/cli/docs/claude-code-web.md @@ -7,17 +7,20 @@ Run this once per environment: ```bash -# Install toolchain +# Step 1: Install system dependencies (REQUIRED - builds will fail without these) +apt-get update && apt-get install -y build-essential libgmp-dev libpcre3-dev libffi-dev libncurses-dev pkg-config + +# Step 2: Install ghcup toolchain curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | \ BOOTSTRAP_HASKELL_NONINTERACTIVE=1 BOOTSTRAP_HASKELL_MINIMAL=1 sh -# Activate (do this in EVERY new shell) +# Step 3: Activate ghcup (do this in EVERY new shell) source ~/.ghcup/env -# Install Stack +# Step 4: Install Stack ghcup install stack -# CRITICAL: Configure proxy (Stack won't work without this) +# Step 5: Configure proxy (Stack won't work without this) mkdir -p ~/.stack cat > ~/.stack/config.yaml << 'EOF' http-proxy: http://egress.public-claude-proxy.svc.cluster.local:80 @@ -25,11 +28,7 @@ https-proxy: http://egress.public-claude-proxy.svc.cluster.local:80 EOF ``` -**Verify it worked:** -```bash -stack --version # Should show: Version 3.3.1 or similar -cat ~/.stack/config.yaml # Should show the proxy config -``` +That's it! You can now build the project. ## Every New Shell Session @@ -42,112 +41,46 @@ That's it. The proxy config persists, ghcup/stack binaries persist, but the PATH ## Common Commands ```bash -# Build the project -cd cli && stack build - -# Fast build (no optimizations, use during development) -stack build --fast +# Build (use --fast for development) +cd cli && stack build --fast # Run tests -stack test - -# Run tests fast stack test --fast -# Run the CLI -stack exec graph -- -stack exec graph -- --help -stack exec graph -- ls - # Format code (REQUIRED before commits) ghcup install ormolu # once find cli -name '*.hs' -exec ormolu --mode inplace {} \; -# Lint code -stack install hlint # once -hlint cli/ -``` - -## Errors You'll See (and Can Ignore) - -**This is NORMAL:** -``` -Warning: /root/.stack/config.yaml: Unrecognized fields in ConfigMonoid: http-proxy, https-proxy -``` -Stack doesn't officially support these fields but uses them anyway. Ignore. - -**This is NORMAL on first build:** -``` -Preparing to download ghc-tinfo6-9.6.7 ... -ghc-tinfo6-9.6.7: download has begun -ghc-tinfo6-9.6.7: ... (lots of progress lines) -``` -First build downloads ~200MB of GHC. Takes a few minutes. Subsequent builds are fast. - -## Errors That Mean Something Is Wrong - -**TLS/SSL handshake failures:** -``` -TLS HandshakeFailed (Error_Protocol ... HandshakeFailure) -``` -**Fix:** You forgot the proxy config. Run the proxy config commands from "First Time Setup" above. - -**stack: command not found:** -``` -/bin/bash: stack: command not found -``` -**Fix:** Run `source ~/.ghcup/env` - -**Permission denied on ~/.stack:** -``` -Permission denied ... ~/.stack +# Run the graph CLI +stack exec graph -- ls +stack exec graph -- --help ``` -**Fix:** This shouldn't happen with the config above, but if it does: `chmod -R u+w ~/.stack` - -## How It Works (for debugging) - -1. **ghcup** installs to `~/.ghcup/` and manages GHC/Stack/etc versions -2. **Stack** installs to `~/.ghcup/bin/stack` and stores its data in `~/.stack/` -3. The `~/.stack/config.yaml` file forces Stack to use the egress proxy -4. Without the proxy, Stack can't reach downloads.haskell.org or hackage.haskell.org -5. `source ~/.ghcup/env` adds `~/.ghcup/bin` to PATH - -## Quick Checks -```bash -# Is ghcup installed? -ls ~/.ghcup/bin/ - -# Is Stack installed? -source ~/.ghcup/env && stack --version +## What to Expect -# Is proxy configured? -cat ~/.stack/config.yaml +**Normal warnings (ignore these):** +- `Warning: /root/.stack/config.yaml: Unrecognized fields in ConfigMonoid: http-proxy, https-proxy` - Stack uses these fields even though they're "unrecognized" -# Can Stack reach the internet? -stack update # Should download Hackage index -``` +**First build:** +- Downloads ~200MB of GHC (takes 2-5 minutes) +- Compiles all dependencies (takes 5-10 minutes) +- Subsequent builds are much faster (seconds to minutes) -## Build Times Reference +## Troubleshooting -- **First build:** 5-15 minutes (downloads GHC + all dependencies) -- **Subsequent clean builds:** 3-5 minutes -- **Incremental builds:** 10-30 seconds -- **Fast incremental builds:** 5-15 seconds +**Build fails with "cannot find -lgmp" or similar:** +- You didn't install system dependencies. Run Step 1 from "First Time Setup" -## Code Quality Requirements +**TLS/SSL handshake failures:** +- Proxy not configured. Run Step 5 from "First Time Setup" -Before committing: -1. Format with ormolu: `find cli -name '*.hs' -exec ormolu --mode inplace {} \;` -2. Check lint: `hlint cli/` (fix what's reasonable) -3. Tests pass: `stack test` +**"stack: command not found":** +- Run `source ~/.ghcup/env` -GitHub CI will fail if formatting is wrong. +## Before Committing -## Pro Tips +1. Format code: `find cli -name '*.hs' -exec ormolu --mode inplace {} \;` +2. Run tests: `stack test --fast` +3. Verify build: `stack build --fast` -- Use `--fast` during development, full builds only for final testing -- Install ormolu once: `ghcup install ormolu` -- The first Stack command in a new environment is slow (downloads GHC), be patient -- If builds seem stuck, they're probably downloading packages - check with `ps aux | grep stack` -- Stack caches aggressively - if something seems wrong, `stack clean` and rebuild +GitHub CI will reject commits with incorrect formatting.