Skip to content

development.md

Latest commit

 

History

History
140 lines (101 loc) · 3.18 KB

development.md

File metadata and controls

140 lines (101 loc) · 3.18 KB
Raw

Development

Bootstrap

In a fresh clone, start with:

bash scripts/setup-agent-links.sh
bash scripts/check-agent-links.sh

Then start the checkout-local stack:

uv run bash scripts/dev.sh start --random-ports
uv run bash scripts/dev.sh urls

Stack Lifecycle

Main commands:

uv run bash scripts/dev.sh start --random-ports
uv run bash scripts/dev.sh status
uv run bash scripts/dev.sh urls
uv run bash scripts/dev.sh stop
uv run bash scripts/dev.sh restart
uv run bash scripts/dev.sh down
uv run bash scripts/dev.sh recreate --random-ports
uv run bash scripts/dev.sh cleanup

Semantics:

  • start creates or resumes the checkout-local stack
  • status shows the saved stack state
  • urls prints the saved host ports
  • stop stops the stack without deleting local state
  • restart force-recreates the same stack on the same ports
  • down removes the stack and the saved local state
  • recreate --random-ports rebuilds on fresh ports
  • cleanup removes stale local state when the stack no longer exists

Each checkout keeps its own .devstack.env, Compose project name, and host port allocation, so multiple worktrees can run side by side.

Worktrees

Create new worktrees through the repository wrapper:

bash scripts/wt-switch.sh --create <feature-name>

Useful variants:

bash scripts/wt-switch.sh --create <feature-name> -x codex
bash scripts/wt-switch.sh --create <feature-name> -x claude
wt switch <feature-name>
wt switch -
wt list
wt remove

Containers

Backend development container:

  • runs uv sync --frozen --package app
  • starts fastapi run --reload app/main.py
  • reloads on backend source changes

Frontend development container:

  • runs bun install --frozen-lockfile --ignore-scripts
  • starts bun run dev --host 0.0.0.0 --port 5173
  • reloads on frontend source changes

Mounted sources:

  • backend mounts ./backend, root pyproject.toml, and uv.lock
  • frontend mounts ./frontend, root package.json, and bun.lock

Normal code edits do not require image rebuilds. Rebuild only for Dockerfile or base image changes.

Host Commands

Backend:

uv sync --frozen --package app
uv run pytest
uv run bash backend/scripts/lint.sh

Frontend:

bun install --frozen-lockfile --ignore-scripts
cd frontend && bun run lint
cd frontend && bun run test

The host .venv does not conflict with the backend container, which uses a Docker-managed /app/.venv.

Testing

Against a running dev stack:

set -a; source .devstack.env; set +a
docker compose exec -T backend sh -c 'cd /app/backend && bash scripts/tests-start.sh'

Full containerized cycle:

bash scripts/test.sh

Useful checks:

set -a; source .devstack.env; set +a
docker compose logs -f backend taskiq-worker frontend
curl "http://localhost:${HOST_BACKEND_PORT}/api/v1/utils/health-check/"
curl "http://localhost:${HOST_FRONTEND_PORT}"

Notes

  • Source .devstack.env before raw docker compose commands.
  • Regenerate the frontend client when backend API contracts change.
  • Keep generated frontend files out of manual edits.
  • For realtime event work, apply .agents/skills/realtime-events/SKILL.md before implementation.