Files
archie/Taskfile.yml
T
sam 0311eb74a7 fix(ui,gateway): load the served lifecycle vocabulary, and make the page registry match the routes (#890)
* fix(ui): make the served lifecycle vocabulary actually load

base/task-meta.jsx documents the backend as the source of truth: /api/task-meta
returns the statuses (label, pill severity, "needs you") and the operator
actions, and loadTaskMeta() replaces the freeze-dried defaults with that
catalog. Nothing called it. Every pill, status filter and action control read
the snapshot, so a catalogue change on the server never reached the browser --
the module's first paragraph was simply not true.

main.jsx now asks for the catalog once at boot, alongside the capabilities read
it already does for the same reason: the shell paints immediately and upgrades a
moment later.

The two vocabularies the dashboard mirrors rather than serves -- FILE_STATUS
(ids owned by internal/domain/workflow/task/changes.go) and CONFIG_SCHEMA
(events.ConfigCapturedSchema) -- are now documented as the deliberate second
tier, with their two-sided pins named, so the tree stops telling two stories
about where a vocabulary comes from. Both degrade to a raw id or the verbatim
payload rather than rendering something wrong, which is why mirroring is
tolerable there and not for a presentation catalog.

RED before (loader never called):

    x booting the dashboard replaces the freeze-dried vocabulary with the served catalog
      actual: 'custom_status', expected: 'Custom status'

Also repairs a drifted LAW asset. A fresh build of pristine main dirties both
ui/dist/assets/index.css and index.js: 04d4d8f1 (#889, memory unification slice
5) changed ui/src without rebuilding ui/dist, and task check runs task ui --
which repairs dist instead of verifying it -- so a stale dist is invisible to
the gate. Rebuilding here restores the invariant; a dist-freshness gate is filed
as follow-up.

* fix(ui,gateway): restore the search focus the port dropped, and the page registry truth

An adversarial review of the port (278b7fc6) found three things worth acting on.

1. Topbar search -- a regression the port introduced. The el() version focused
   the input when the narrow-layout toggle opened it, and blurred it after a
   successful jump; the port kept neither. That layout hides the field with
   width:0/pointer-events:none until .is-open or :focus-within, so without
   focus() the caret was not in the field the operator had just opened, and
   without blur() :focus-within left it expanded across the topbar after the
   jump. Both calls are back, with the ref they need.

2. dashboard_tools.go advertised a page that does not exist and omitted two that
   do. The registry calls itself "the single source of truth for what the
   dashboard exposes", but it is a hand-copy of the route table in
   ui/src/main.jsx: /memory stayed after the page was deleted (that deletion
   also left ui/dist stale -- archie-core-1vhh), and /bindings and /curators
   were never added. So the agent could hand the operator a chip to a route that
   now falls back to the dashboard, and could not answer "where do I go for
   playbook bindings?".

3. TestDashboardPagesRegistryCoversEveryRoute did not test that. It asserted
   three hardcoded paths and passed while the registry listed a deleted page. It
   now reads the route table back out of ui/src/main.jsx and compares in both
   directions, which is what makes the registry's claim holdable. RED before:

     route "/bindings" is a dashboard page the registry does not list, so the agent cannot point at it
     route "/curators" is a dashboard page the registry does not list, so the agent cannot point at it
     registry lists "/memory" (Memory), which is not a dashboard route: the agent would send the operator somewhere that does not exist

Also deletes the dead .chat-page rules the deleted chatPage() bridge left
behind: nothing renders .chat-page any more (chat.jsx renders
.chat-page-content, and the drawer sizes it from layout.css).

Not changed: the unreachable `soon` path, which predates the port and was
reported rather than acted on.

* fix(build): verify ui/dist is fresh instead of never looking at it

ui/dist is committed because the Go build embeds it, so it is a generated
source file. Nothing in the gate read it: task check does not run task ui, and
nothing else compares the bundle with ui/src. So when 04d4d8f1 (#889) changed
ui/src without rebuilding, the committed bundle went on serving the Memory page
whose source had been deleted -- with the gate green throughout.

task ui:check (tools/uidist.sh) rebuilds into a temporary directory and compares,
never rewriting the committed artifact. That is the rule docs:check already
states for the contract reference -- a gate that silently rewrote the artifact
would bless an unintended change with no reviewer ever seeing it -- and it
matters more now that several agents work in their own worktrees, where each
could otherwise pass while producing a different bundle.

Evidence:
  fresh tree                            exit 0, matches
  hand-staled bundle                    exit 1, names the differing file
  the #889 drift replayed               exit 1, names BOTH index.css and index.js
  (pre-#889 bundle, post-#889 sources)
  git status after a run                unchanged: the check never writes ui/dist

Cost: ui:check declares ui:deps like ui and test:ui do, so the gate runs npm
install once per dependent. Task's sources/generates up-to-date check does not
apply to a node_modules directory (measured: it ran on every invocation), so the
target does not claim otherwise; guarding that is follow-up work.

Gate: task check exit 0, UI suite 230/230, all Go packages ok.

* fix(ui): make the served vocabulary reach an already-painted page

Greptile's finding on the first cut of this fix, and it was right: loadTaskMeta()
resolves after a page has painted and only mutated module state. The route tree
renders into its own root, so App re-rendering cannot reach it, and a painted
page kept the freeze-dried labels it read on the way up.

show() is split so the page render can be repeated on its own: renderRoute()
mounts the current route into the outlet without the teardown/chrome side
effects, and the catalog effect calls it once the catalog lands. The key is
unchanged, so Preact re-renders the mounted page in place and keeps its state.

Deeper instance of the same defect, found while fixing that one:
task-filters.jsx captured the vocabulary in module-level constants at import
(ATTENTION_STATUSES/TASK_STATUSES), so the task filter could never see a served
status, no matter when or how correctly the catalog landed. Both are read at
call time now.

Tests, and what they actually cover:
  - the task-filter test has teeth: with the source fix stashed it fails, with
    the fix it passes.
  - task-meta-late-catalog.test.js guards the boot fetch end to end (it fails
    when loadTaskMeta is never called), but it does NOT isolate the re-render:
    a page also re-renders for its own reasons, so the assertion holds without
    renderRoute too. Said plainly here rather than implied as coverage -- the
    fix makes the re-render deterministic instead of incidental, and this
    harness cannot tell those apart.
  - it lives in its own file because main.jsx boots once per process; a second
    test in the same file would assert against a detached tree.

UI suite 232/232, task check exit 0.
2026-09-19 23:38:19 +10:00

453 lines
19 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:
# -extra must match the gofumpt formatter's extra-rules in
# .golangci.yml. Without it `task fmt` cannot produce what `task lint`
# demands -- e.g. func f(a int, b int) -> func f(a, b int) -- so a
# contributor has no command that satisfies the gate.
- gofumpt -extra -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.
Two report sections, because a dead whole package and a dead symbol
inside a live one are different failure modes: "unreachable-*" is a
package no shipped binary imports at all; "in-package-*" is a symbol
dead inside a package that IS shipped -- the ChatCourier/Dispatch
shape, where the feature is wired everywhere except its own call site.
Both carry the same tracked/untracked/dynamic classification.
--refresh re-runs the analysis. Without it the tool reuses
/tmp/reachaudit-deadcode-<sha>.txt with no staleness check beyond HEAD
and a dirty-tree check, which will happily report last week's tree
against today's code if HEAD hasn't moved.
--json PATH and --md PATH write the same findings as structured data or
a Markdown report, in addition to the terminal summary.
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
ui:check:
desc: Rebuild the dashboard into a temporary directory and reject a stale ui/dist
summary: |
ui/dist is committed because the Go build embeds it, so it is a generated
source file. Nothing else in the gate reads it and `task ui` rewrites it
in place, so before this a change to ui/src that landed without the
rebuilt bundle was invisible -- and two agents in two worktrees could each
"pass" while producing different dashboards.
Builds somewhere temporary and compares, never rewriting the committed
artifact, which is the rule docs:check already follows for the contract
reference. A gate that rebuilt ui/dist in place would bless an unintended
UI change with no reviewer ever seeing it.
Fix a failure with `task ui`, then commit the rebuilt bundle in the same
commit as the source change that caused it.
Declares ui:deps like `ui` and `test:ui` do, so a fresh clone works; that
means the gate runs `npm install` once for each dependent. Task's
sources/generates up-to-date check does not apply to a node_modules
directory, so the guard against that is a follow-up, not a claim here.
deps: [ui:deps]
cmds:
- bash tools/uidist.sh check
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
The gRPC ports come from [services.state].listen and [services.gateway].listen in
deployments/dev.toml, each paired with the target that dials it. Move them there
when the host already owns one: cockpit binds 9090 by default.
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-messaging"
- "{{.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 -o {{.BIN_DIR}}/archie-messaging ./cmd/archie-messaging
- 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 and bundle"
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
# ...and so is the bundle that suite is built from. ui/dist is committed
# and embedded; nothing else checks it against ui/src, and `task ui`
# rewrites it in place, so a forgotten rebuild used to leave no trace in
# the gate at all.
- task: ui:check
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