Reachability (tools/reachaudit, epic archie-core-06ag) answers "is this code in a shipped binary?". It cannot answer the complementary question: "does every declared contract surface have a consumer, or a declaration that it has none?". ratelimit was in the binary closure and called by nothing, which reachability could not see. tools/contractaudit classifies each subject of each declared surface as CONSUMED, DECLARED-UNCONSUMED, UNDECLARED-UNCONSUMED, or STALE-DECLARATION, and only the last two are findings. The declaration allowlist must match reality exactly: a missing entry fails and so does an entry that outlived its subject, because a stale allowlist is how a gate quietly stops checking anything. Surfaces: the two gRPC services, whose consumption is derived by scanning adapter bodies for calls through the generated client, and the dashboard HTTP API, matched between the registerXRoutes call sites and the path literals the bundled client calls. Findings on the current tree, all deliberate and now declared: ListCaptures and ListUndispatchedCaptures are superseded by their streaming variants -- staterpc's client calls StreamCaptures -- so no production client reaches the unary RPCs. Three bugs this tool found in itself, each recorded because each is the class of error that makes a conformance check worse than none: - Joining RPCs to adapter methods by name silently reported live RPCs as unconsumed, because adapters do not map one-to-one: StoreClient.Get calls GetSession, List calls ListSessions. - Reflecting over the client value rather than the pointer reported zero methods, hence the whole surface unconsumed. - Treating the asset mount and the health probes as dashboard API routes reported four healthy routes as undeclared; they have different consumers and are out of scope for this surface. The consumer extractor fails loudly on a call shape it cannot parse rather than under-reporting, and every check is negative-tested: a route, an RPC, and a removed consumer are each injected, confirmed to fail for the right reason, and reverted. The declaration staleness rule is tested too. Advisory when run directly; task check runs it -strict. See docs/prds/contract-conformance-audit.md.
309 lines
12 KiB
YAML
309 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`)
|
|
cmds:
|
|
- go run ./cmd/archie-gateway
|
|
|
|
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, contract"
|
|
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 conformance. Static and dependency-light, so it belongs with
|
|
# the per-edit checks rather than next to the end-to-end suite. It runs
|
|
# -strict here: every unconsumed surface must be declared in
|
|
# docs/contract-declarations.json with a reason and a tracker, and a
|
|
# stale declaration fails the same way an undeclared one does.
|
|
- task: contract
|
|
|
|
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 when run directly; `task check` runs it with -strict so an
|
|
undeclared or stale entry fails the gate. Declare an intentionally
|
|
unconsumed surface in docs/contract-declarations.json with a reason
|
|
that states the consequence and the tracker that owns the work.
|
|
|
|
See docs/prds/contract-conformance-audit.md.
|
|
cmds:
|
|
- go -C tools run ./contractaudit --repo-root .. --strict
|
|
|
|
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
|