johba/harb

openhands 58c3e62f3d fix: refactor AGENTS.md into progressive-disclosure structure (#184 )

- Root AGENTS.md: 350+ lines → 68 lines (map, not encyclopedia)
- New docs/dev-environment.md (67 lines): Docker, dev.sh, ports, pitfalls
- New docs/ci-pipeline.md (73 lines): Woodpecker setup, monitoring, debugging
- New docs/testing.md (41 lines): Foundry, E2E, version validation
- New docs/codeberg-api.md (32 lines): .netrc auth, API usage
- Updated stale model refs in .claude-code-supervisor.yml files
- Sub-component AGENTS.md files unchanged
- Context docs (PRODUCT-TRUTH, ARCHITECTURE, UX-DECISIONS) unchanged

2026-02-23 09:46:35 +00:00

3.5 KiB

Raw Blame History

Dev Environment

Prerequisites

Docker Engine (Linux) or Colima (Mac). See docs/docker.md for installation.

Quick Start

nohup ./scripts/dev.sh start &    # start (takes ~3-6 min first time)
tail -f nohup.out                  # watch progress
./scripts/dev.sh health            # verify all services healthy
./scripts/dev.sh stop              # stop and clean up

Do not launch services individually — dev.sh enforces phased startup with health gates.

Restart Modes

./scripts/dev.sh restart --light — Fast (~10-20s): only webapp + txnbot, preserves Anvil/Ponder state. Use for frontend changes.
./scripts/dev.sh restart --full — Full (~3-6min): redeploys contracts, fresh state. Use for contract changes.

Environments

Supported: BASE_SEPOLIA_LOCAL_FORK (default Anvil fork), BASE_SEPOLIA, and BASE. Match contract addresses and RPCs accordingly.

Ports

The stack uses these ports:

Port	Service
8545	Anvil
5173	webapp
5174	landing
42069	Ponder
43069	txnBot
5100	Otterscan
8081	Caddy

Check with lsof -i :<port> if startup fails.

Docker Topology

docker-compose.yml has NO depends_on. Service ordering is handled by scripts/dev.sh.
Startup phases: anvil+postgres → bootstrap → ponder → webapp/landing/txn-bot → caddy → smoke test.
Shared bootstrap: scripts/bootstrap-common.sh (sourced by both local dev and CI).
20GB disk limit enforced. dev.sh stop auto-prunes. Named volumes for node_modules.
All services have log rotation (30MB max per container) and PostgreSQL WAL limits configured.

kraiken-lib Build

Run ./scripts/build-kraiken-lib.sh before docker-compose up so containers mount a fresh kraiken-lib/dist from the host.
scripts/watch-kraiken-lib.sh rebuilds on file changes (requires inotify-tools) and restarts dependent containers automatically.
The dev script runs the build automatically on start, but manual rebuilds are needed if you change kraiken-lib while the stack is already running.

Common Pitfalls

Docker disk full: dev.sh start refuses to run if Docker disk usage exceeds 20GB. Fix: ./scripts/dev.sh stop (auto-prunes) or docker system prune -af --volumes.
Stale Ponder state: If Ponder fails with schema errors after contract changes, delete its state: rm -rf services/ponder/.ponder/ then ./scripts/dev.sh restart --full.
kraiken-lib out of date: If services fail with import errors or missing exports, rebuild: ./scripts/build-kraiken-lib.sh.
Container not found errors: dev.sh expects Docker Compose v2 container names (harb-anvil-1, hyphens not underscores). Verify with docker compose version.
Port conflicts: See Ports table above. Check with lsof -i :<port> if startup fails.
npm ci failures in containers: Named Docker volumes cache node_modules/. If dependencies change and installs fail, remove the volume: docker volume rm harb_webapp_node_modules (or similar), then restart.

Handy Commands

foundryup                          # update Foundry toolchain
anvil --fork-url https://sepolia.base.org  # manual fork for diagnosing outside dev.sh

# inspect services while stack is running
curl http://localhost:8081/api/txn/status
curl -X POST http://localhost:8081/api/graphql \
  -d '{"query":"{ stats(id:\"0x01\"){kraikenTotalSupply}}"}'
cast call <POOL> "slot0()"         # inspect pool state
PONDER_NETWORK=BASE_SEPOLIA_LOCAL_FORK npm run dev  # focused Ponder debugging (inside services/ponder/)

3.5 KiB Raw Blame History