Files
archie/Taskfile.yml
T
sam 6fd76ae550 fix(tools): stop testing on the text of other files, and ungate contractaudit
Six tests asserted on the wording and formatting of source and config files
rather than on behaviour: four injected text into fixtures and checked that a
regex noticed, and two asserted on api.jsx's contents. They break on an extra
space, a newline, a rename, or a comment that merely mentions the token -- the
single-fetch check had already false-positived on a comment, and I patched it
with a comment-stripper instead of deleting it. A test that cannot tell "the
code is wrong" from "the file is formatted differently" tests the wrong thing,
and the maintenance cost is permanent.

Deleted: tools/contractaudit/negative_test.go in full, and the source-scanning
"api.jsx holds exactly one fetch call" check with its stripComments helper. The
dashboard suite still asserts the browser mutation contract behaviourally, per
method, by inspecting the request each one makes -- which is where the real
defect was found. 142 UI tests pass; the 45 methods remain fully covered by the
two inventories and the completeness check.

The tool's own decoding is now testable without a file: parseDeclarations takes
an io.Reader, so its rules are exercised with in-memory input, and only the
absent-file branch still touches a path (which is never created).

contractaudit is no longer part of task check. Its surfaces are discovered by
scanning source text, so a rename or reformat elsewhere can change its output
with nothing actually wrong -- it reported 16 live routes as unconsumed once,
when the dashboard's request helper was renamed. A check that can fail for
reasons unrelated to what it measures must not be able to break a build. It now
matches tools/reachaudit: advisory, run by hand, --strict available on request.

Also removes five unused indirect requires from tools/go.mod (go mod tidy).
They were residue from the reflection-based first implementation of the RPC
scan, which was replaced by text scanning without tidying. -mod=readonly cannot
catch a superfluous require, so nothing would ever have found them.

Rewrites docs/prds/contract-conformance-audit.md, which claimed RPC coverage was
derived by reflection over the exported client type -- it never was -- listed
surface sizes of 43/12/52 against real counts of 45/21/49, described three
classification classes where the code has four, invented a five-surface Shape
with files that were never written, and blamed raw fetch calls for a 401 defect
that did not exist. Each false claim is now recorded in an errata section rather
than quietly dropped, and the document states plainly that the audit has found
nothing actionable: the 415 refusals and the duplicated client plumbing were
both found by reading the handler and reproducing the request.

Testing rule added to the document, since this is the second time: assert on the
observable effect, never on the content or formatting of generated or
hand-authored text and config files.
2026-09-15 14:17:53 +10:00

318 lines
12 KiB
YAML

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