feat(harness): agent-drivable dev harness and CI that gates
A coding agent could develop this repo's Go packages and could not develop the application: every path to running YellowJacket ended in a blocking GTK window, so 265 bound methods, 46 events, 33 component directories and 13 stores had exactly one form of verification available — `tsc --noEmit`. The unlock is that `wails dev`'s dev server on :34115 serves the real frontend with the real generated bindings against the same Go backend a desktop window attaches to, so a plain Chromium under Xvfb gets a fully functional app. Four test tiers now exist, cheapest first: - `make ui-test` — 313 Vitest tests in a real browser in ~2 s, no app, no backend, no display. Works because `frontend/wailsjs/` is a pure passthrough to `window.go`/`window.runtime`, so faking just those two globals runs the real bindings and the real store code. - `make test` — services in-process, asserting on the payload the frontend would receive, via a new `events.Emit` wrapper. - `make dev-headless` + `playwright-cli` — the real app, driven interactively, with an event bridge on `window.__yjEvents` and a dev-only control surface at `/__test/`. - `make e2e` — 19 of those flows frozen as Playwright specs. `events.Emit(ctx, …)` replaces all 35 direct `runtime.EventsEmit` call sites: wails' `getEvents` `log.Fatalf`s on any context without its runtime, so those paths could not run under test and a background worker could take the app down. Four packages had each hand-rolled the same guard; nine more guarded on `ctx != nil`, which does not help. `TestNoDirectRuntimeEmits` fails the build on a new one. Fixtures are generated, not committed (`make testdata`), and seeds are built by *running the app* — never by hand-writing config and DB rows, which would be a second description of a valid YJ_HOME. `.gitea/workflows/ci.yml` is the first workflow here that tests anything; the other three only package, so `gitea_ci` reported only packaging jobs and misled anyone asking whether a push was healthy. Both jobs were prototyped to green in a bare ubuntu:24.04 container before the YAML was written, which immediately caught `make lint` linting three configurations that nothing builds: all three passes omitted `webkit2_41`, so wails resolved webkit2gtk-4.0 — which Arch still ships and Ubuntu 24.04 dropped. Operational instructions live in `.pi/skills/yellowjacket-dev/`, measured discoveries in `.planning/NOTES.md`, and architecture in `CLAUDE.md` — split by tense, not by topic, because a topical split gives every new fact two plausible homes. `make skill-check` fails a commit if the skill cites a make target that does not exist.
This commit is contained in:
Executable
+43
@@ -0,0 +1,43 @@
|
||||
#!/usr/bin/env bash
|
||||
#
|
||||
# Fails when frontend/wailsjs/ is stale against the bound Go structs.
|
||||
#
|
||||
# frontend/wailsjs/ is generated by `wails`, not by `go generate`, so the
|
||||
# pre-commit codegen check does not cover it at all. Without this, a
|
||||
# renamed Go struct field or a changed method signature first shows up at
|
||||
# runtime, inside a window, as a binding that never settles.
|
||||
#
|
||||
# `wails generate module` builds the app with the `bindings` tag and runs
|
||||
# it to dump the bindings — about three seconds, so it is cheap enough to
|
||||
# gate a commit on.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
cd "$(dirname "$0")/.."
|
||||
|
||||
TARGET="frontend/wailsjs"
|
||||
|
||||
if [ -n "$(git status --porcelain -- "$TARGET")" ]; then
|
||||
echo "bindings-check: $TARGET has uncommitted changes; stage or stash them first" >&2
|
||||
git status --short -- "$TARGET" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
go tool wails generate module -tags webkit2_41 >/dev/null 2>&1
|
||||
|
||||
# `wails generate module` rewrites the three runtime files as 755 every
|
||||
# time. That is not drift, so compare content only.
|
||||
if ! git -c core.fileMode=false diff --quiet -- "$TARGET"; then
|
||||
echo "bindings-check: $TARGET is out of date with the Go bindings." >&2
|
||||
echo "Run 'make bindings' and stage the result." >&2
|
||||
git -c core.fileMode=false diff --stat -- "$TARGET" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Restore the modes the generator churned, so the tree is left clean.
|
||||
chmod 644 \
|
||||
frontend/wailsjs/runtime/runtime.js \
|
||||
frontend/wailsjs/runtime/runtime.d.ts \
|
||||
frontend/wailsjs/runtime/package.json
|
||||
|
||||
echo "bindings-check: frontend/wailsjs is current"
|
||||
Executable
+197
@@ -0,0 +1,197 @@
|
||||
#!/usr/bin/env bash
|
||||
#
|
||||
# Start YellowJacket headless, in the background, and return.
|
||||
#
|
||||
# `wails dev` binds an HTTP + WebSocket dev server on :34115 that serves
|
||||
# the real frontend with the real generated bindings on `window.go` and
|
||||
# bridges every call and every runtime.EventsEmit to the *same* Go
|
||||
# backend the desktop window uses. A browser pointed at it is not a
|
||||
# mock. That is what makes this app drivable by a coding agent.
|
||||
#
|
||||
# Three details are load-bearing:
|
||||
#
|
||||
# * We run the dev *binary*, not `wails dev`. app_dev.go parses
|
||||
# -devserver / -assetdir / -loglevel straight from os.Args, so a
|
||||
# `go build -tags "dev webkit2_41"` binary serves the identical
|
||||
# devserver with no file watcher, no rebuild supervisor and no
|
||||
# reload broadcast: one process, one PID, deterministic startup.
|
||||
#
|
||||
# * Xvfb is not optional. devserver.Run ends in Frontend.Run(ctx),
|
||||
# which opens the GTK window and blocks; no flag suppresses it.
|
||||
#
|
||||
# * dbus-run-session is not incidental. A private session bus makes
|
||||
# backend/mediacontrols register MPRIS for real, so it becomes
|
||||
# assertable with busctl. It replaces the bus, not /run/user, so
|
||||
# PulseAudio still works and InitSpeaker succeeds.
|
||||
#
|
||||
# Usage:
|
||||
# scripts/dev-headless.sh [--seed NAME|--fresh] [--port N] [--no-build]
|
||||
#
|
||||
set -euo pipefail
|
||||
|
||||
cd "$(dirname "$0")/.."
|
||||
|
||||
REPO_ROOT="$PWD"
|
||||
RUN_DIR="$REPO_ROOT/.dev"
|
||||
PID_FILE="$RUN_DIR/app.pid"
|
||||
LOG_FILE="$RUN_DIR/app.log"
|
||||
HOME_FILE="$RUN_DIR/app.home"
|
||||
SEED_DIR="$RUN_DIR/seeds"
|
||||
BIN="$REPO_ROOT/build/bin/yj-dev"
|
||||
|
||||
PORT=34115
|
||||
SEED=""
|
||||
FRESH=0
|
||||
BUILD=1
|
||||
LOG_LEVEL="${YJ_LOG_LEVEL:-debug}"
|
||||
STARTUP_TIMEOUT=60
|
||||
|
||||
usage() {
|
||||
sed -n '3,28p' "$0" | sed 's/^# \{0,1\}//'
|
||||
exit "${1:-0}"
|
||||
}
|
||||
|
||||
while [ $# -gt 0 ]; do
|
||||
case "$1" in
|
||||
--seed)
|
||||
SEED="${2:?--seed needs a name}"
|
||||
shift 2
|
||||
;;
|
||||
--fresh)
|
||||
FRESH=1
|
||||
shift
|
||||
;;
|
||||
--port)
|
||||
PORT="${2:?--port needs a number}"
|
||||
shift 2
|
||||
;;
|
||||
--no-build)
|
||||
BUILD=0
|
||||
shift
|
||||
;;
|
||||
-h | --help) usage 0 ;;
|
||||
*)
|
||||
echo "dev-headless: unknown argument: $1" >&2
|
||||
usage 2
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
mkdir -p "$RUN_DIR"
|
||||
|
||||
# ── Refuse to stack instances ────────────────────────────────────────
|
||||
# Two backends on one port fails obscurely; two backends on one YJ_HOME
|
||||
# corrupts a SQLite database. Check the saved PID, not the port.
|
||||
if [ -f "$PID_FILE" ] && kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then
|
||||
echo "dev-headless: already running (pid $(cat "$PID_FILE")); " \
|
||||
"run 'make dev-stop' first" >&2
|
||||
exit 1
|
||||
fi
|
||||
rm -f "$PID_FILE"
|
||||
|
||||
# ── Choose the YJ_HOME ───────────────────────────────────────────────
|
||||
# A seed is a YJ_HOME that a previous run of the app produced, tarred
|
||||
# up (see scripts/seed-sandbox.sh). Restoring it means starting *in*
|
||||
# the app instead of on the first-run wizard, which intercepts every
|
||||
# pointer event until a library exists.
|
||||
if [ -n "$SEED" ] && [ "$FRESH" = 1 ]; then
|
||||
echo "dev-headless: --seed and --fresh are mutually exclusive" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
if [ -n "$SEED" ]; then
|
||||
SEED_TAR="$SEED_DIR/$SEED.tar"
|
||||
if [ ! -f "$SEED_TAR" ]; then
|
||||
echo "dev-headless: no seed '$SEED' at $SEED_TAR" >&2
|
||||
echo " build one with: make sandbox-seed NAME=$SEED" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
YJ_HOME="$RUN_DIR/home-$SEED"
|
||||
rm -rf "$YJ_HOME"
|
||||
mkdir -p "$YJ_HOME"
|
||||
tar -xf "$SEED_TAR" -C "$YJ_HOME"
|
||||
echo "dev-headless: restored seed '$SEED'"
|
||||
elif [ "$FRESH" = 1 ]; then
|
||||
# Deliberately empty: the first-run wizard is itself a surface
|
||||
# that needs testing.
|
||||
YJ_HOME="$RUN_DIR/home-fresh"
|
||||
rm -rf "$YJ_HOME"
|
||||
mkdir -p "$YJ_HOME"
|
||||
echo "dev-headless: fresh YJ_HOME (expect the first-run wizard)"
|
||||
else
|
||||
YJ_HOME="${YJ_HOME:-$RUN_DIR/home}"
|
||||
mkdir -p "$YJ_HOME"
|
||||
fi
|
||||
|
||||
export YJ_HOME
|
||||
echo "$YJ_HOME" >"$HOME_FILE"
|
||||
|
||||
# ── Build ────────────────────────────────────────────────────────────
|
||||
if [ "$BUILD" = 1 ]; then
|
||||
echo "dev-headless: building frontend + dev binary..."
|
||||
(cd frontend && pnpm install --silent && pnpm build >/dev/null)
|
||||
go build -tags "dev webkit2_41" -o "$BIN" .
|
||||
fi
|
||||
|
||||
if [ ! -x "$BIN" ]; then
|
||||
echo "dev-headless: $BIN missing; drop --no-build" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# ── Launch ───────────────────────────────────────────────────────────
|
||||
# setsid puts the app in its own process group so dev-stop can kill the
|
||||
# whole tree (xvfb-run, dbus-daemon, the app) by group id. Never
|
||||
# `pkill -f`: the pattern matches the invoking shell's own command line
|
||||
# and silently drops the rest of the chain.
|
||||
: >"$LOG_FILE"
|
||||
|
||||
# YJ_TESTCTL mounts backend/testctl's /__test/ endpoints. It is opt-in
|
||||
# rather than implied by the dev build so that a human's `make dev` does
|
||||
# not carry an arbitrary-SQL endpoint on a listening port.
|
||||
YJ_TESTCTL=1 \
|
||||
YJ_LOG_LEVEL="$LOG_LEVEL" setsid dbus-run-session -- xvfb-run -a \
|
||||
"$BIN" \
|
||||
-devserver "localhost:$PORT" \
|
||||
-assetdir "$REPO_ROOT/frontend/dist" \
|
||||
-loglevel Debug \
|
||||
>>"$LOG_FILE" 2>&1 &
|
||||
|
||||
APP_PID=$!
|
||||
echo "$APP_PID" >"$PID_FILE"
|
||||
|
||||
# ── Wait for the dev server ──────────────────────────────────────────
|
||||
deadline=$((SECONDS + STARTUP_TIMEOUT))
|
||||
until curl -sf -o /dev/null "http://localhost:$PORT/"; do
|
||||
if ! kill -0 "$APP_PID" 2>/dev/null; then
|
||||
echo "dev-headless: app exited during startup; last log lines:" >&2
|
||||
tail -n 30 "$LOG_FILE" >&2
|
||||
rm -f "$PID_FILE"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [ "$SECONDS" -ge "$deadline" ]; then
|
||||
echo "dev-headless: :$PORT did not answer within ${STARTUP_TIMEOUT}s" >&2
|
||||
tail -n 30 "$LOG_FILE" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
sleep 0.25
|
||||
done
|
||||
|
||||
cat <<EOF
|
||||
dev-headless: up
|
||||
url http://localhost:$PORT
|
||||
pid $APP_PID
|
||||
YJ_HOME $YJ_HOME
|
||||
log ${LOG_FILE#"$REPO_ROOT"/} (make dev-logs)
|
||||
|
||||
Drive it with:
|
||||
playwright-cli -s=yj open http://localhost:$PORT
|
||||
playwright-cli -s=yj snapshot
|
||||
playwright-cli -s=yj eval "() => window.__yjEvents.call('queue.Queue.GetState', [], 5000)"
|
||||
|
||||
A binding call that never settles means wrong argument types: the
|
||||
backend logs 'error parsing arguments' and never fires the callback.
|
||||
The app log is the only place that shows up, so always use a timeout.
|
||||
EOF
|
||||
Executable
+49
@@ -0,0 +1,49 @@
|
||||
#!/usr/bin/env bash
|
||||
#
|
||||
# Stop the headless app started by scripts/dev-headless.sh.
|
||||
#
|
||||
# Kills the saved process group, never `pkill -f`: a pkill pattern that
|
||||
# appears in the invoking compound command's own command line matches
|
||||
# the invoking shell, kills it, and silently drops everything after it.
|
||||
#
|
||||
# SIGTERM first, so OnBeforeClose / OnShutdown run and player and queue
|
||||
# state are persisted — a seed built from an SIGKILLed app is a seed
|
||||
# missing exactly the state those hooks write.
|
||||
#
|
||||
set -euo pipefail
|
||||
|
||||
cd "$(dirname "$0")/.."
|
||||
|
||||
PID_FILE=".dev/app.pid"
|
||||
GRACE=10
|
||||
|
||||
if [ ! -f "$PID_FILE" ]; then
|
||||
echo "dev-stop: nothing running (no $PID_FILE)"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
PID="$(cat "$PID_FILE")"
|
||||
|
||||
if ! kill -0 "$PID" 2>/dev/null; then
|
||||
echo "dev-stop: pid $PID already gone"
|
||||
rm -f "$PID_FILE"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# setsid made the app a process group leader, so -PID reaches the app,
|
||||
# xvfb-run and the private dbus-daemon together.
|
||||
kill -TERM -- "-$PID" 2>/dev/null || kill -TERM "$PID"
|
||||
|
||||
deadline=$((SECONDS + GRACE))
|
||||
while kill -0 "$PID" 2>/dev/null; do
|
||||
if [ "$SECONDS" -ge "$deadline" ]; then
|
||||
echo "dev-stop: pid $PID ignored SIGTERM after ${GRACE}s, killing"
|
||||
kill -KILL -- "-$PID" 2>/dev/null || kill -KILL "$PID"
|
||||
break
|
||||
fi
|
||||
|
||||
sleep 0.2
|
||||
done
|
||||
|
||||
rm -f "$PID_FILE"
|
||||
echo "dev-stop: stopped $PID"
|
||||
Executable
+174
@@ -0,0 +1,174 @@
|
||||
#!/usr/bin/env bash
|
||||
#
|
||||
# Build a seeded YJ_HOME snapshot by RUNNING THE APP.
|
||||
#
|
||||
# The point of a seed is to start a harness run *inside* the app rather
|
||||
# than on the first-run wizard, which intercepts every pointer event
|
||||
# until a library exists. The wizard's dismissal condition is not a
|
||||
# config file — it is `GetAllLibrariesWithTrackCounts()` returning a
|
||||
# non-empty list — so the only honest way to produce that state is to
|
||||
# call the real AddLibrary binding and let the real scanner finish.
|
||||
#
|
||||
# Hand-writing a config.toml and DB rows would be a second description
|
||||
# of a valid YJ_HOME, free to drift from what the app actually writes.
|
||||
# That is the failure mode .planning/NOTES.md records for the old
|
||||
# migration chain, and it is not worth repeating for seeds.
|
||||
#
|
||||
# Usage:
|
||||
# scripts/seed-sandbox.sh [--name NAME] [--port N] [--no-build]
|
||||
#
|
||||
set -euo pipefail
|
||||
|
||||
cd "$(dirname "$0")/.."
|
||||
|
||||
REPO_ROOT="$PWD"
|
||||
RUN_DIR="$REPO_ROOT/.dev"
|
||||
SEED_DIR="$RUN_DIR/seeds"
|
||||
LOG_FILE="$RUN_DIR/app.log"
|
||||
MANIFEST="$REPO_ROOT/test_data/music_library_test.manifest.json"
|
||||
|
||||
NAME="default"
|
||||
PORT=34115
|
||||
SESSION="yj-seed"
|
||||
BUILD_ARGS=()
|
||||
SCAN_TIMEOUT=180
|
||||
|
||||
while [ $# -gt 0 ]; do
|
||||
case "$1" in
|
||||
--name)
|
||||
NAME="${2:?--name needs a value}"
|
||||
shift 2
|
||||
;;
|
||||
--port)
|
||||
PORT="${2:?--port needs a number}"
|
||||
shift 2
|
||||
;;
|
||||
--no-build)
|
||||
BUILD_ARGS+=(--no-build)
|
||||
shift
|
||||
;;
|
||||
*)
|
||||
echo "seed-sandbox: unknown argument: $1" >&2
|
||||
exit 2
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
need() {
|
||||
command -v "$1" >/dev/null 2>&1 || {
|
||||
echo "seed-sandbox: $1 not found in PATH" >&2
|
||||
exit 1
|
||||
}
|
||||
}
|
||||
need playwright-cli
|
||||
need jq
|
||||
|
||||
if [ ! -f "$MANIFEST" ]; then
|
||||
echo "seed-sandbox: fixtures missing; run 'make testdata'" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
LIBRARY_DIR="$REPO_ROOT/$(jq -r .libraryRoot "$MANIFEST")"
|
||||
WANT_TRACKS="$(jq '.tracks | length' "$MANIFEST")"
|
||||
FIXTURE_HASH="$(jq -r .hash "$MANIFEST")"
|
||||
|
||||
cleanup() {
|
||||
playwright-cli -s="$SESSION" close >/dev/null 2>&1 || true
|
||||
./scripts/dev-stop.sh >/dev/null 2>&1 || true
|
||||
}
|
||||
trap cleanup EXIT
|
||||
|
||||
echo "seed-sandbox: building '$NAME' from $WANT_TRACKS fixture tracks"
|
||||
|
||||
# Start on an empty YJ_HOME: seeding must exercise the same first-run
|
||||
# path a real install takes.
|
||||
#
|
||||
# YJ_CORE_INDEX_URL points at a dead address on purpose. A seed must
|
||||
# not reach for the real explore artifact — that is a minute of network
|
||||
# per seed, and it makes the result depend on what the artifact server
|
||||
# happened to be serving that day.
|
||||
YJ_CORE_INDEX_URL="http://127.0.0.1:1/none.tar.zst" \
|
||||
./scripts/dev-headless.sh --fresh --port "$PORT" "${BUILD_ARGS[@]}"
|
||||
|
||||
YJ_HOME="$(cat "$RUN_DIR/app.home")"
|
||||
|
||||
playwright-cli -s="$SESSION" open "http://localhost:$PORT" >/dev/null
|
||||
|
||||
# Every binding call gets a timeout. A call with wrong argument types
|
||||
# makes the backend log 'error parsing arguments' and never fire the
|
||||
# callback, so the in-page promise never settles and a naive await
|
||||
# hangs forever.
|
||||
call() {
|
||||
playwright-cli -s="$SESSION" eval "async () => {
|
||||
const timeout = new Promise((_, reject) =>
|
||||
setTimeout(() => reject(new Error('binding timeout')), 15000));
|
||||
return await Promise.race([(async () => { $1 })(), timeout]);
|
||||
}"
|
||||
}
|
||||
|
||||
echo "seed-sandbox: registering library $LIBRARY_DIR"
|
||||
|
||||
if ! call "return await window.go.library.Library.AddLibrary(
|
||||
${LIBRARY_DIR@Q});" >/dev/null; then
|
||||
echo "seed-sandbox: AddLibrary failed; app log:" >&2
|
||||
tail -n 40 "$LOG_FILE" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Wait on the observable outcome — the track count the app itself
|
||||
# reports — rather than on a fixed sleep or a scan event. This also
|
||||
# validates the manifest against the real scanner: if the two disagree,
|
||||
# a fixture is not being ingested and the seed is wrong.
|
||||
echo "seed-sandbox: waiting for the scan to reach $WANT_TRACKS tracks"
|
||||
|
||||
# The result is tagged rather than scraped for bare digits:
|
||||
# playwright-cli echoes the evaluated source back, and that source
|
||||
# contains numbers of its own (the binding timeout, for one).
|
||||
deadline=$((SECONDS + SCAN_TIMEOUT))
|
||||
got=0
|
||||
|
||||
while [ "$SECONDS" -lt "$deadline" ]; do
|
||||
got="$(call "const libs =
|
||||
await window.go.library.Library.GetAllLibrariesWithTrackCounts();
|
||||
const total = (libs ?? []).reduce(
|
||||
(n, l) => n + (l.trackCount ?? 0), 0);
|
||||
return 'YJTRACKS' + '=' + total;" |
|
||||
grep -oE 'YJTRACKS=[0-9]+' | head -n 1 | cut -d= -f2)"
|
||||
got="${got:-0}"
|
||||
|
||||
[ "$got" = "$WANT_TRACKS" ] && break
|
||||
|
||||
sleep 1
|
||||
done
|
||||
|
||||
if [ "$got" != "$WANT_TRACKS" ]; then
|
||||
echo "seed-sandbox: scan settled at $got/$WANT_TRACKS tracks" >&2
|
||||
echo " (a fixture the scanner rejects, or a scan still running)" >&2
|
||||
tail -n 40 "$LOG_FILE" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
playwright-cli -s="$SESSION" close >/dev/null 2>&1 || true
|
||||
|
||||
# SIGTERM, so OnBeforeClose / OnShutdown persist window, player and
|
||||
# queue state. A seed built from a killed app is missing exactly the
|
||||
# state those hooks write.
|
||||
./scripts/dev-stop.sh
|
||||
|
||||
mkdir -p "$SEED_DIR"
|
||||
tar -cf "$SEED_DIR/$NAME.tar" -C "$YJ_HOME" .
|
||||
|
||||
cat >"$SEED_DIR/$NAME.json" <<EOF
|
||||
{
|
||||
"name": "$NAME",
|
||||
"tracks": $WANT_TRACKS,
|
||||
"libraryRoot": "$LIBRARY_DIR",
|
||||
"fixtureHash": "$FIXTURE_HASH",
|
||||
"createdAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
|
||||
}
|
||||
EOF
|
||||
|
||||
trap - EXIT
|
||||
|
||||
echo "seed-sandbox: wrote $SEED_DIR/$NAME.tar ($WANT_TRACKS tracks)"
|
||||
echo " use it with: make dev-headless SEED=$NAME"
|
||||
Executable
+48
@@ -0,0 +1,48 @@
|
||||
#!/usr/bin/env bash
|
||||
#
|
||||
# Every command in .pi/ is a `make` target on purpose: the Makefile is
|
||||
# the source of truth for *how* to invoke something, and the skill only
|
||||
# decides *which* and *in what order*. This check keeps that honest —
|
||||
# a renamed or deleted target turns into a failing commit rather than
|
||||
# into an agent confidently running a command that no longer exists.
|
||||
#
|
||||
# It extracts every `make <target>` mentioned under .pi/ and asserts the
|
||||
# target exists. Usage: scripts/skill-check.sh
|
||||
set -euo pipefail
|
||||
|
||||
cd "$(dirname "$0")/.."
|
||||
|
||||
[ -d .pi ] || exit 0
|
||||
|
||||
# `make -pq` prints the database including every rule, without running
|
||||
# anything. It exits non-zero when a target is out of date, and under
|
||||
# `pipefail` that would sink the whole assignment, so swallow it.
|
||||
targets="$({ make -pqRr 2>/dev/null || true; } |
|
||||
awk '/^[a-zA-Z0-9][^$#\/\t=]*:([^=]|$)/ {sub(/:.*/, "", $0); print}' |
|
||||
sort -u)"
|
||||
|
||||
# A mention counts only when it is code: backticked (`make ui-test`) or
|
||||
# the first thing on a line, as in a fenced block. Bare prose is not
|
||||
# scanned, because English says things like "a renamed make target".
|
||||
mentioned="$(grep -rhoE '(`|^)make [a-z][a-z0-9-]*' .pi --include='*.md' |
|
||||
sed 's/^`//' | awk '{print $2}' | sort -u)"
|
||||
|
||||
missing=""
|
||||
|
||||
for t in $mentioned; do
|
||||
if ! printf '%s\n' "$targets" | grep -qx -- "$t"; then
|
||||
missing="$missing $t"
|
||||
fi
|
||||
done
|
||||
|
||||
if [ -n "$missing" ]; then
|
||||
echo "skill-check: .pi/ documents make targets that do not exist:" >&2
|
||||
for t in $missing; do
|
||||
echo " make $t" >&2
|
||||
grep -rln "make $t" .pi --include='*.md' | sed 's/^/ /' >&2
|
||||
done
|
||||
echo "Fix the docs, or restore the target." >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "skill-check: $(printf '%s\n' "$mentioned" | wc -w) documented make targets, all present"
|
||||
Reference in New Issue
Block a user