version: "3" vars: BIN_DIR: "bin" tasks: default: desc: List available tasks cmds: - task --list fmt: desc: Format and fix Go source (gofumpt, go fix) cmds: - gofumpt -w . - go fix ./... proto:install: desc: Install the pinned Buf and protobuf Go generators cmds: - bash tools/proto.sh install proto:generate: desc: Generate and format committed grpc-go service contracts cmds: - bash tools/proto.sh generate proto:lint: desc: Lint protobuf contracts and check compatibility with main cmds: - bash tools/proto.sh lint proto:check: desc: Regenerate contracts and reject uncommitted generated differences cmds: - bash tools/proto.sh check vet: desc: Run go vet cmds: - go vet ./... lint: desc: Run golangci-lint cmds: - golangci-lint run ./... lint:playbooks: desc: "Lint playbook binding dirs for collisions (standalone tool, cmd/archie-playbooks)" summary: | Runs the standalone playbook linter (archie-playbooks lint) against ./playbooks by default. It validates playbook YAML binding files against the same loaders the daemon uses at startup, so a pre-merge check can never disagree with runtime validation. Exit non-zero on any collision / malformed file / invalid binding. Lint a different set of directories directly: go run ./cmd/archie-playbooks lint -dir ./a -dir ./b cmds: - go run ./cmd/archie-playbooks lint -dir ./playbooks vuln: desc: "Scan for known stdlib/dependency CVEs (govulncheck). Not part of task check: it needs network access to the vuln DB and is not build/test-blocking; run it explicitly or in CI." cmds: - govulncheck ./... ui:deps: desc: Install the dashboard's node dependencies (ui/node_modules is gitignored) internal: true dir: ui cmds: - npm install --no-audit --no-fund ui: desc: Build the dashboard into ui/dist (committed; the Go build embeds it) dir: ui deps: [ui:deps] cmds: - npm run build test:ui: desc: Run the dashboard's node tests (DOM-building primitives) dir: ui # Without this, a fresh clone fails the gate on a missing jsdom rather # than a real test failure: ui/node_modules is gitignored and nothing # else in `task check` installs it. deps: [ui:deps] cmds: - npm test dev: desc: "Develop: archied live-reload + archie-gateway + archie-state-store + archie-ui + Vite HMR together. Open http://localhost:5173" summary: | Runs the dev loop in one terminal: * air rebuilds and restarts archied on Go changes * archie-gateway serves ChatContract on 127.0.0.1:8585 (archied and archie-ui dial it; neither embeds a gateway) * archie-state-store owns archie.db on 127.0.0.1:9090, loopback, no token (deployments/dev.toml); archied, archie-gateway and archie-ui dial it -- none owns the DB in-process (docs/prds/state-store-contract.md ยง12 step 7) * archie-ui serves the dashboard on 127.0.0.1:8484 from the embedded dist (deployments/dev.toml). After the UI cutover (archie-core-8cda.5.4) archied runs no dashboard listener: this is what :8484 is. * vite serves the dashboard with hot reload on :5173, proxying /api and /events through to archie-ui on :8484 Open http://localhost:5173 -- not :8484. The Vite server is the one with hot reload; :8484 serves the last built dist/ and will look stale. Ctrl-C stops all five. deps: [dev:daemon, dev:gateway, dev:state-store, dev:dashboard, dev:ui] dev:daemon: desc: archied only, live-reloading via air (prefer `task dev`) cmds: - air -build.args_bin="-config-overlay,deployments/dev.toml" dev:dashboard: desc: archie-ui only, no live-reload (prefer `task dev`) cmds: - go run ./cmd/archie-ui -config-overlay deployments/dev.toml dev:state-store: desc: archie-state-store only, no live-reload (prefer `task dev`) cmds: - go run ./cmd/archie-state-store -config-overlay deployments/dev.toml dev:gateway: desc: archie-gateway only, no live-reload (prefer `task dev`) # The overlay carries [services.state].target, which archie-gateway # requires (openStateStoreAdapter fails closed on an empty target). # Without it `task dev` leaves the gateway dialling whatever the # developer's installed config names, or unable to start at all, while # archied, archie-ui and the state store all dial 127.0.0.1:9090. cmds: - go run ./cmd/archie-gateway -config-overlay deployments/dev.toml dev:ui: desc: Vite dev server only, expects archie-ui already running (prefer `task dev`) dir: ui cmds: - npm install --no-audit --no-fund - npm run dev dev:mobile: desc: Serve the dashboard on your LAN (token-protected) for phone viewing summary: | Starts archie-ui with a LAN-reachable [web] bind and a minted dashboard token, printing the URL (LAN IP + token) and a QR code to scan. After the UI cutover the dashboard is archie-ui's process: this task starts archie-ui only. Run the daemon separately (task dev, or archied) for actual archie operation -- two daemons sharing the bot identity would double-poll the forge. The frontend served is the embedded dist, so run `task ui` if you changed the frontend. The token file is the path archied used to mint before the cutover, so an existing phone setup keeps its token. deps: - ui cmds: - cmd: | IP=$(hostname -I | awk '{print $1}') TOKEN_FILE="${XDG_DATA_HOME:-$HOME/.local/share}/archie/web-token" go run ./cmd/archie-ui -listen 0.0.0.0:8484 -token-file "$TOKEN_FILE" & UI_PID=$! sleep 2 TOKEN=$(cat "$TOKEN_FILE" 2>/dev/null) URL="http://$IP:8484/?t=$TOKEN" echo "Phone URL: $URL" echo "$URL" | qrencode -t ANSIUTF8 trap "kill $UI_PID 2>/dev/null" EXIT wait $UI_PID build: desc: Build archie services and agent binaries # Version stamping used to live only in Dockerfile.archied, so any build # from source -- including a host deployment -- reported "dev" for # both components and /version was useless there. Derive the same # -X values from the release tags so a source build is stamped too. # git describe (without --abbrev=0) yields 1.7.0-2-gbb54786 when HEAD is # past the tag, which is the honest answer for a mid-cycle build. vars: GATEWAY_VERSION: sh: git describe --tags --match 'archied/v*' 2>/dev/null | sed 's|^archied/v||' || echo dev RUNTIME_VERSION: sh: git describe --tags --match 'archie/v*' 2>/dev/null | sed 's|^archie/v||' || echo dev sources: - "**/*.go" - go.mod - go.sum generates: - "{{.BIN_DIR}}/archied" - "{{.BIN_DIR}}/archie-gateway" - "{{.BIN_DIR}}/archie-state-store" - "{{.BIN_DIR}}/archie-ui" - "{{.BIN_DIR}}/archie-agent" cmds: - go build -ldflags "-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion={{.GATEWAY_VERSION}} -X github.com/samcharles93/archie-core/internal/app/archied.runtimeVersion={{.RUNTIME_VERSION}} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archied ./cmd/archied - go build -ldflags "-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion={{.GATEWAY_VERSION}} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-gateway ./cmd/archie-gateway - go build -o {{.BIN_DIR}}/archie-state-store ./cmd/archie-state-store - go build -o {{.BIN_DIR}}/archie-ui ./cmd/archie-ui - go build -ldflags "-X github.com/samcharles93/archie-core/internal/app/agentworker.version={{.RUNTIME_VERSION}} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-agent ./cmd/archie-agent test: desc: Run the Go test suite cmds: - go test ./... -count=1 test:tools: desc: Run the nested tools module suite, refusing to rewrite its go.mod summary: | tools/go.mod replaces the root module, so its build list must satisfy the root module's requirements. When the root moves on, the tools module goes stale and any plain go command there rewrites tools/go.mod and tools/go.sum to catch up, leaving an unrelated dirty diff. -mod=readonly is explicit because a developer's global GOFLAGS=-mod=mod overrides the toolchain default and re-enables the silent rewrite. Fix a failure here with: go -C tools mod tidy cmds: - go -C tools test -mod=readonly ./... -count=1 check: desc: "Full quality gate: fmt, go fix, proto, vet, lint, build, test, tools tests, ui tests" cmds: - task: fmt - go fix ./... - task: proto:lint - task: proto:check - task: vet - task: lint - task: build - task: test # The tools module is not covered by ./... from the root; without this # its dependency drift is only ever discovered by a command that # silently repairs it. - task: test:tools # The dashboard's suite runs here too. Left out of the gate it rots # silently: nothing else executes it, so a broken DOM primitive ships. - task: test:ui contract: desc: "Report contract conformance: declared surfaces, their consumers, and the drift between them" summary: | Walks every declared contract surface -- the two gRPC services, the dashboard HTTP API -- and classifies each subject as consumed, declared-unconsumed, undeclared, or a stale declaration. ADVISORY, and deliberately NOT part of `task check`, matching tools/reachaudit. The surfaces are discovered by scanning source text: the .proto files, the adapter bodies that call the generated client, the route registrations in internal/webui, and the path literals under ui/src. That makes it useful for a periodic survey and unsafe as a gate -- a rename or a reformat elsewhere in the tree can change its output without anything being wrong, and it has already produced a batch of false "unconsumed" readings once when the dashboard's request helper was renamed. Read the findings as a prompt to go and check, not as a verdict. To make it fail on an undeclared or stale entry, pass --strict by hand: go -C tools run ./contractaudit --repo-root .. --strict See docs/prds/contract-conformance-audit.md. cmds: - go -C tools run ./contractaudit --repo-root .. release:preview: desc: "Show the release notes that would be generated (VERSION=1.2.0, or GATEWAY=/RUNTIME= to version the two components separately)" cmds: - tools/release.sh --gateway {{.GATEWAY | default .VERSION}} --runtime {{.RUNTIME | default .VERSION}} --dry-run requires: vars: [VERSION] release:prepare: desc: "Write the generated notes into the changelogs, uncommitted, for editing (VERSION=1.2.0)" cmds: - tools/release.sh --gateway {{.GATEWAY | default .VERSION}} --runtime {{.RUNTIME | default .VERSION}} --prepare requires: vars: [VERSION] release: desc: "Freeze the edited changelogs into a release commit and tags (VERSION=1.2.0). Run release:prepare first." cmds: - tools/release.sh --gateway {{.GATEWAY | default .VERSION}} --runtime {{.RUNTIME | default .VERSION}} --tag requires: vars: [VERSION] clean: desc: Remove build artifacts cmds: - rm -rf {{.BIN_DIR}} docker-build: desc: Build the archie-agent sandbox image cmds: - docker compose build agent docker-up: desc: Start the optional external NATS service via docker compose cmds: - docker compose up -d nats docker-down: desc: Stop the docker compose stack cmds: - docker compose down docker-logs: desc: Follow the NATS container logs cmds: - docker compose logs -f nats