From 83f00a2c66e604359134aa26520d979f3682c702 Mon Sep 17 00:00:00 2001 From: xarmian Date: Mon, 7 Sep 2026 12:51:54 -0400 Subject: [PATCH] docs: a fresh worktree has no web/build, and that breaks the Go gates (#1279) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit embed.go embeds a generated directory a new worktree does not have, so make test and make lint fail with 'pattern all:web/build: no matching files found' before a single test runs. go build ./... dies first and two packages report [setup failed], which reads as a broken tree rather than a missing generated directory — it cost two confused minutes twice in one day. The sibling trap (.svelte-kit) is already documented one bullet up; this is the same class and belongs beside it. Claude-Session: https://claude.ai/code/session_01Xk9M5UVPdc84xL5E1mZkm8 --- CLAUDE.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 592057df..7a01afd3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -39,6 +39,8 @@ Agent sessions take a `git worktree` per task rather than sharing the main check - **Symlinking `web/node_modules` to the main checkout's copy is fine** (and fast). Vitest, `vite build`, and `npm run check` all work through the symlink. - **A fresh worktree has no `web/.svelte-kit`** (gitignored, generated). Run `npx svelte-kit sync` in `web/` before any vitest/vite command — or `npm run check`, which syncs first. Without it, vitest fails with `Failed to load tsconfig '.svelte-kit/tsconfig.json': Tsconfig not found` regardless of how `node_modules` was set up. (This missing generated dir was historically misdiagnosed as a symlink problem — `npm ci` "fixed" it only because its `prepare` script runs `svelte-kit sync`.) +- **A fresh worktree has no `web/build` either**, and that one breaks the GO gates rather than the web ones. `embed.go` does `//go:embed all:web/build`, so `make test` and `make lint` fail with `pattern all:web/build: no matching files found` before a single test runs — `go build ./...` dies first, two packages report `[setup failed]`, and it reads as a broken tree rather than a missing generated directory. `npx vite build` in `web/` fixes it (`make web` would too, and is FORBIDDEN here — see the next rule). + - **Never run `npm ci` in a worktree whose `web/node_modules` is a symlink — including via make.** `npm ci` lives in the `web` target, so every target whose dependency chain reaches it is off-limits too: currently `web`, `build`, `install`, `serve`, `web-check`, and `check` (via `web-check`). Everything else — `build-go`, `dev`, `restart`, `test`, `test-pg`, `lint`, `vuln`, `web-test`, `web-audit`, `dev-web`, `clean` — never reaches `npm ci`. `npm ci` deletes through the symlink into the shared tree, breaking every other worktree and session at once with a confusing `vitest: not found`. If you want a real, isolated `node_modules` instead of a symlink, `npm ci` in an un-symlinked `web/` is ~5s on a warm cache and regenerates `.svelte-kit` as a side effect. - **`make test-pg` is safe to run from several worktrees at once** (TASK-2708). It used to bind the Postgres test container to a fixed host port, so a second worktree failed with `port is already allocated` and a stack orphaned by a removed worktree blocked the port for everyone. Docker now assigns the port and the Makefile reads it back, so each worktree gets its own container on its own port under its own compose project. If you have been starting a private container by hand to avoid the collision, you no longer need to. Two other things that target now does: it REFUSES to run, with a `NO TESTS EXECUTED` banner, when the database is unreachable — `go test` exiting 2 with zero FAIL lines had already been mistaken for a pass once — and it says so explicitly when the database dies mid-run, so the failures read as infrastructure rather than as evidence about the code. To reap a stack whose worktree was deleted before teardown: `docker ps --filter name=padtest-` lists them and the container name carries the compose project, so `docker compose -p down -v` reaps it from anywhere. From inside the worktree, `make test-pg-project` prints the name and `make test-pg-down` does it for you. (The project is `padtest--` — NOT the bare directory name, which would collide between two checkouts sharing a basename.)