Skip to content

makefile-reference.md

Latest commit

 

History

History
122 lines (83 loc) · 5.59 KB

makefile-reference.md

File metadata and controls

122 lines (83 loc) · 5.59 KB
Raw

Makefile Reference

The Makefile is for local development and pre-release verification. Every Docker target builds from your local checkout. End users install via curl | bash and run decepticon — they don't use make.

Run make help for a quick summary. Full reference below.

Pre-release Verification

The primary purpose of this Makefile. Run these before tagging a release.

Target Description
make dogfood Full OSS UX on local code: builds the Go launcher + every service image (:dev tag), wires up an isolated $DECEPTICON_HOME under .dogfood/, then runs the launcher. The onboard wizard, engagement picker, compose up, health checks, and CLI all execute exactly as a curl | bash install.
make smoke Compose-only smoke (no launcher, no onboard wizard) — fastest possible release-shape check. Replicates only the launcher's compose up step: clean → build images locally → up -d --no-build --wait → health checks. Use when you only changed the compose stack.
make launcher Build the Go launcher binary at clients/launcher/bin/decepticon. Embedded version is dev, which skips release update notices and versioned config sync inside the launcher. Invoked automatically by make dogfood.

make dogfood runs against an isolated .dogfood/ directory so the user's real ~/.decepticon is never touched. make clean purges both the compose volumes and .dogfood/ when you want a fresh onboard.

Development

Target Description
make dev Build all Docker images and start with hot-reload (docker compose watch) — source changes sync into containers automatically
make cli-dev Open the interactive terminal UI locally with hot-reload (Node) — backend stays in Docker
make web-dev Run the Next.js dev server locally with infra services in Docker

Typical contributor workflow:

# Day-to-day iteration: hot-reload
make dev

# Before opening a PR
make quality

# Before tagging a release
make smoke      # fast check
make dogfood    # full OSS UX

The Web dashboard is part of the default Compose stack; after make dev it's reachable at http://localhost:3000.

Quality Gates

Target Description
make quality Run all quality gates: Python lint + tests + CLI typecheck/build/test + Web lint/build
make lint Python lint + type-check (ruff check + ruff format --check + basedpyright)
make lint-fix Auto-fix Python lint and formatting
make quality-cli CLI typecheck + build + test (vitest)

Testing

Target Description
make test [ARGS=...] Run Python tests (pytest) inside the Docker container
make test-local [ARGS=...] Run Python tests locally (requires uv sync --dev)

CLI tests are part of make quality-cli. To run them in isolation: npm run test --workspace=@decepticon/cli.

Web Dashboard

Target Description
make web-dev Start the Next.js dev server locally; brings up infra in Docker
make web-build Build the web dashboard (also generates the Prisma client)
make web-lint Lint the web dashboard (ESLint)
make web-migrate [NAME=name] Run a Prisma dev migration

To regenerate just the Prisma client (without a full build): cd clients/web && npx prisma generate.

Operations

Target Description
make status Show running service status (docker compose ps)
make logs [SVC=service] Follow logs (default: langgraph). Override: make logs SVC=litellm
make health KG backend + Neo4j + Web health checks (broader than decepticon kg-health, which only checks the KG)
make clean Full teardown: stop services, remove volumes, and remove .dogfood/. Use this when you want the next make dogfood to start from a fresh onboard wizard.

Benchmark

Target Description
make benchmark [ARGS="--level 1"] Run the benchmark suite locally

Versioning (no manual step)

There is no make sync-version or pre-tag commit. Source-tree version fields carry a "0.0.0" sentinel in pyproject.toml, clients/cli/package.json, and clients/web/package.json. The release workflow stamps the real tag into the images at Docker build time via --build-arg VERSION=<tag>. The Go launcher is similarly stamped via GoReleaser ldflags.

Release channel policy (see update-channels.md for the user-facing view):

  • vX.Y.Z Git tags are the source of truth for releases.
  • GHCR version tags (X.Y.Z) are immutable release artifacts and should be used by installed deployments.
  • Two moving channel tags (Claude-Code-style soak model — both final-only):
    • GHCR latest → moved to the newest final release immediately, by the publish-release job (after all version-tagged images exist and the GitHub release is undrafted).
    • GHCR stable → moved to the newest final release baked ≥ the soak window (default 7 days), by the scheduled promote-stable.yml workflow — not on release. The conservative default; the ${DECEPTICON_VERSION:-stable} compose fallback resolves here.
  • Pre-releases use SemVer suffixes such as v1.1.0-rc.1, stay marked as GitHub pre-releases, and move neither channel tag (the channels never auto-select them).
  • Bug fixes ship as new patch releases. Do not rebuild or rewrite an existing version tag.

To cut a release:

make quality && make smoke && make dogfood
git tag v1.0.16 && git push origin v1.0.16