feat(eliminate-frontend-makefile): task 3.3 - update live documentation (11 files)

Removes every live current-fact reference to src/frontend/Makefile
targets or Makefile-specific fixed paths across 11 docs (steering,
frontend/CLAUDE.md, root CLAUDE.md, deployment docs, and two skill
docs), replacing with the Meson-based equivalents established by
tasks 1-3.2: /xce-build apiserver, meson test --suite apiserver,
direct tests/regression/run.sh invocation.

Round-1 review rejected the first pass: xce-deploy-ha/SKILL.md had
over-corrected by deleting all mention of deploy-ha.sh's still-real
/tmp/apiserver legacy fallback (that script's discovery logic is
unchanged, unlike run-resource-verify.sh's, which genuinely lost its
fallback in task 3.1 -- xce-test-resources/SKILL.md's identical-
looking edit was correct for that reason). Fixed by restoring an
accurate, Makefile-free description of the real fallback at all four
touched sites. Re-reviewed and approved.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XYdtrEWWZfKRRGED7raEYg
This commit is contained in:
Rongsong Shen 2026-09-03 14:22:54 +00:00
parent 483cac3dcb
commit f5fbc6bcac
No known key found for this signature in database
GPG key ID: 5BCDAAE0123E9FE2
12 changed files with 56 additions and 48 deletions

View file

@ -67,7 +67,7 @@
- `controllers/queues.go` — `preCheckQueueControlRequest` now returns `(bool, error)`; `ControlQueue` receives allFlag locally
- `controllers/host_control_test.go` — 5 new tests: allFlag true/false, concurrent no-race (50 goroutines), invalid action, comment-too-long
- `controllers/queue_control_test.go` — 5 new tests: same coverage for queues
- All tests passing (`make test`)
- All tests passing (via `/xce-build apiserver`'s test step)
- [x] **#8 P0-2c: Register routes + RBAC for host control/select**
- `router/routers.go` — `POST /xce/v1/hosts/control` → RBAC `host:control` (cluster_admin)
@ -117,7 +117,7 @@
## Final
- [x] **#14 Build and test verification**
- `make test` in `src/frontend/` passes — all backend, controllers, store, utils, xcecli tests green
- `/xce-build apiserver`'s test step passes — all backend, controllers, store, utils, xcecli tests green
- `ninja -C build` for C components passes — required meson reconfigure + CGO val_helpers.h fix
- RBAC verification — `host:control` (cluster_admin) and `host:view` (all authenticated) confirmed in routes + rbac.yaml
- Input safety — comment limit 512 chars; select expression limit 4094 chars (1024 reduction deferred to P1-2b)

View file

@ -240,11 +240,11 @@ apiserver -d /opt/xce/apiserver
Both `app.yaml` and `logger.yaml` are JSON-Schema-validated at startup (fail-fast on malformed config).
### Build gotcha — use the Meson/Nix build, not `make build-server`
### Build gotcha — apiserver needs real CGO flags, not a bare `go build`
`make build-server` (`src/frontend/Makefile`) runs a bare `go build` with **no `CGO_CFLAGS`/`CGO_LDFLAGS` set**. The real controller-connection code (`backend/clib.go`) is CGO and needs those flags to find `libxce`'s headers. Depending on your environment this either fails to compile, or — if `CGO_ENABLED=0` is ambient — silently links `backend/stub.go` instead, producing a binary where every backend call returns `errNoCGO: backend requires CGO`. There is no startup warning; the HTTP server comes up fine and only fails at request time.
A bare `go build` in `src/frontend/apiserver` (no `CGO_CFLAGS`/`CGO_LDFLAGS` set) is not a supported way to produce a working apiserver binary. The real controller-connection code (`backend/clib.go`) is CGO and needs those flags to find `libxce`'s headers. Depending on your environment this either fails to compile, or — if `CGO_ENABLED=0` is ambient — silently links `backend/stub.go` instead, producing a binary where every backend call returns `errNoCGO: backend requires CGO`. There is no startup warning; the HTTP server comes up fine and only fails at request time.
**Use `/xce-build apiserver` (or `nix build .#xcecore`)** for anything that needs to actually talk to a controller — it computes the correct `CGO_CFLAGS`/`CGO_LDFLAGS` from pkg-config and produces `xce_apiserver` under `src/xce.build/frontend/apiserver/` (or the equivalent path for other profiles). Reserve `make build-server`/`make test` for the pure-Go unit-test loop (`CGO_ENABLED=0` is *intentional* there).
**Use `/xce-build apiserver` (or `nix build .#xcecore`)** for anything that needs to actually talk to a controller — it computes the correct `CGO_CFLAGS`/`CGO_LDFLAGS` from pkg-config and produces `xce_apiserver` under `src/xce.build/frontend/apiserver/` (or the equivalent path for other profiles). `/xce-build apiserver` also runs the pure-Go unit-test loop (`CGO_ENABLED=0` is *intentional* there); a manual `go build`/`go test` invocation is not the canonical path.
### Relationship to the controller

View file

@ -11,10 +11,10 @@ Go-based REST API server (Gin) and CLI tool (Cobra) that expose cluster manageme
## Build & Test
```bash
make build-server # → /tmp/apiserver
make build-cli # → /tmp/xce_static (CGO_ENABLED=0, static binary)
make test # unit tests only (no live server required)
make test-all # unit + integration (needs XCE_BIN and SRV_URL env vars)
/xce-build apiserver # → <build_dir>/frontend/apiserver/xce_apiserver, xcecli; runs unit tests (no live server required)
meson test -C <build_dir> --suite apiserver # CGO-backed backend tests
XCE=<build_dir>/frontend/xcecli/xcecli URL=<url> \
tests/regression/run.sh # integration (needs XCE and URL env vars)
```
## API Server Architecture

View file

@ -64,7 +64,7 @@ Live test: `xcecli` against running `apiserver` with builtin test data.
### Infrastructure
- [x] Nix flake dev shell (`nix develop`) — Go 1.25, PAM, OpenSSL, meson, gnumake, swag, gopls, delve
- [x] Root `Makefile`: `make test`, `make test-integration`, `make test-all`
- [x] Meson build/test: `/xce-build apiserver` (unit tests), `meson test -C <build_dir> --suite apiserver` (CGO-backed backend tests), `tests/regression/run.sh` (integration)
- [x] Regression suite: `tests/regression/run.sh` — 29 tests, all pass
- [x] Unit tests across: `apiserver/store`, `apiserver/utils`, `apiserver/controllers`, `xcecli/cmd/auth`, `xcecli/cmd/jobs`, `xcecli/cmd/roles`, `xcecli/cmd/users`, `xcecli/common/request`, `xcecli/models`