Adds an mkdocs.yml, a landing page, and `task docs:site` / `task docs:serve`. Deliberately hosting-agnostic: MkDocs is the same input Backstage TechDocs consumes, so choosing where this lands later costs nothing. exclude_docs holds back four subtrees, since everything under docs/ would otherwise be published. archive/ is superseded design and would compete with the current architecture for a reader's attention; inspiration/ discusses other products by name; prds/ are open decisions rather than settled design; github-token.md is credential setup. One PRD is let back through because architecture/migration-decisions.md links to it three times, and a page excluded out from under a live link is just a 404 with extra steps. No nav block. MkDocs derives it from the directory layout, so a new page under docs/architecture/ publishes without a second edit, and there is no hand-maintained tree to drift against the repository. Builds --strict, so a dead internal link fails rather than ships.
402 lines
16 KiB
YAML
402 lines
16 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
|
|
|
|
docs:generate:
|
|
desc: Regenerate the committed contract reference from Archie-owned types
|
|
summary: |
|
|
Writes docs/data/generated/contracts.json. The output is committed, so
|
|
this dirties the tree deliberately: review the diff and commit it with
|
|
the code change that shifted the contract surface. Never hand-edit the
|
|
artifact.
|
|
|
|
-mod=readonly is mandatory on every `go -C tools` command; see
|
|
task test:tools for why.
|
|
cmds:
|
|
- go -C tools run -mod=readonly ./docsgen --repo-root ..
|
|
|
|
docs:check:
|
|
desc: Verify the committed contract reference matches Archie-owned types
|
|
summary: |
|
|
Implements Step 6 of docs/architecture/generated-documentation.md:
|
|
generates into a temporary directory, compares it with the committed
|
|
output, names the authoritative Go definition behind each mismatch, and
|
|
exits non-zero without modifying the working tree.
|
|
|
|
Fix a failure with `task docs:generate`, then commit the result in the
|
|
same commit as the code change that shifted the contract surface. This
|
|
checks rather than regenerates on purpose: a gate that silently rewrote
|
|
the artifact would bless an unintended contract change with no reviewer
|
|
ever seeing it, which Step 9 explicitly forbids.
|
|
cmds:
|
|
- go -C tools run -mod=readonly ./docsgen check --repo-root ..
|
|
|
|
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 ./...
|
|
|
|
deadcode:
|
|
desc: "Report functions no shipped binary can reach (whole-program RTA from ./cmd/...). Not part of task check: it reports a standing backlog, so gating on it would fail every run until that backlog is zero."
|
|
summary: |
|
|
Answers "is this reachable in production", which no linter does:
|
|
golangci-lint's unused check is package-scoped, so anything exported
|
|
and called from a sibling package looks live even when no binary
|
|
reaches it.
|
|
|
|
Run via `go run ...@latest` deliberately. A locally installed deadcode
|
|
built against an older Go than this module exits non-zero and prints
|
|
NOTHING, which reads as "no dead code" instead of "analysis failed".
|
|
Building it against the repo toolchain makes that failure impossible.
|
|
|
|
-test=false is the point of the report: a function reached only by its
|
|
own tests is not reachable in production.
|
|
|
|
Read the output in one direction only. RTA over-approximates what is
|
|
reachable, so "unreachable func" is sound and worth acting on, while
|
|
silence proves nothing: interface dispatch and any address-taken
|
|
function (every reflect.ValueOf entry in the *extract tables) is
|
|
assumed reachable whether or not it is ever called.
|
|
cmds:
|
|
- go run golang.org/x/tools/cmd/deadcode@latest -test=false ./cmd/...
|
|
|
|
reachaudit:
|
|
desc: "Classify unreachable code as tracked / untracked / dynamic (tools/reachaudit). Wraps task deadcode with provenance and tracker status."
|
|
summary: |
|
|
deadcode says a function is unreachable. reachaudit says whether that
|
|
is a known gap, a forgotten one, or an artifact of runtime loading
|
|
(yaegi, reflection) that must never be deleted.
|
|
|
|
--refresh re-runs the analysis. Without it the tool reuses
|
|
/tmp/reachaudit-deadcode.txt with no staleness check, which will
|
|
happily report last week's tree against today's code.
|
|
cmds:
|
|
- python3 tools/reachaudit/reachaudit.py --repo . {{.CLI_ARGS}}
|
|
docs:site:
|
|
desc: "Build the documentation site into ./site (MkDocs). --strict, so a dead internal link fails the build."
|
|
summary: |
|
|
Publishes docs/ minus the subtrees held back in mkdocs.yml's
|
|
exclude_docs. Requires mkdocs-material:
|
|
|
|
pip install --user mkdocs-material
|
|
|
|
Distinct from docs:check, which verifies the generated contract data
|
|
rather than the site.
|
|
cmds:
|
|
- mkdocs build --strict
|
|
|
|
docs:serve:
|
|
desc: "Serve the documentation site locally with live reload on :8000."
|
|
cmds:
|
|
- mkdocs serve
|
|
|
|
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, docs, vet, lint, build, test, tools tests, ui tests"
|
|
cmds:
|
|
- task: fmt
|
|
- go fix ./...
|
|
- task: proto:lint
|
|
- task: proto:check
|
|
- task: docs: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
|