build-tooling + res help-cache write (deferred) #4

New issue

Open

opened 2026-07-19 02:30:10 +00:00 by agent · 0 comments

agent commented

2026-07-19 02:30:10 +00:00

Member

Plan: build-tooling migration + `res` cache/help fix + bulk-script docs

Status

Partially done. The mage build-system migration (core/magefiles/) and the bulk-script docs landed. The res help-cache write half of the cache/help fix is still deferred — see AGENTS.md §12 ("res help-cache writes: Dispatcher reads cache but currently never writes it"). The res --res-help read path works.

Decisions (confirmed with user)

Build system → mage, isolated in core/magefiles/ with its own go.mod so mage runs independently of (possibly broken) core libs.
Stale repos → keep them. respkg-mkinitfs/ required for residual-os; os-old/ left untouched (legacy backup, deletion not authorized). The "remove stale repos" item is dropped.

Steps

Rename residual-demo → res-demo (fixes Makefile breakage): git mv cmd/residual-demo cmd/res-demo; update string literals; res-theme already correct.
Mage build system in core/magefiles/: separate go.mod (go 1.25, require github.com/magefile/mage v1.15.0); mage.go (//go:build mage, package main) with targets that only shell out to go (Build, BuildOne, Demo, Theme, Test, TestCgo, Vet, Clean, All); replace core/Makefile with thin wrapper delegating to mage; ensure core/.gitignore ignores bin/; verify magefiles/ tracked.
Fix res cache writing + res --help (core/cmd/res/main.go): --help/-h → cmdHelp; @refresh internal → RefreshOne; replace orphaned refresh block with detached re-exec that writes cache (RES_NO_REFRESH=1, Setsid); scanExternalHelp writes back via SaveCache; add core/cmd/res/main_test.go (run(["--help"])==0, run(["-h"])==0, run(["nonexistentxyz"])==127).
Bulk scripts + AGENTS.md docs: fix deploy-harness.sh repo list (core docs editor extra os); add header comments to each .agent/tools/ script; verify repo lists post-collapse; document .agent/tools/ in AGENTS.md.
Deferred: repo removal dropped per user clarification.

Verification

cd core && go build ./... / go test ./... / CGO_ENABLED=1 go test ./... / go vet ./... → PASS
cd core/magefiles && go run github.com/magefile/mage -d . build (or make build) builds all cmd/* incl. res-demo, res-theme
bin/res --help / bin/res -h → print help (no "unknown subcommand")
bin/res console then check $XDG_CACHE_HOME/residual/help-cache.json exists and contains res-console
bin/res help → lists external subcommands with cached descriptions
.agent/tools/test-all.sh/build-all.sh run against core/ only; sync-repos.sh SKIPs absent repos

Risks

Mage version skew: go mod tidy may pick a different mage version; verify go run works.
Detached child timing: @refresh child must finish 500ms-bounded RefreshOne before user cares; cache best-effort, scanExternalHelp falls back to live query + write-back.
go run github.com/magefile/mage first-run cost: compiles mage once (cached after).

# Plan: build-tooling migration + `res` cache/help fix + bulk-script docs ## Status **Partially done.** The mage build-system migration (`core/magefiles/`) and the bulk-script docs landed. The `res` help-cache **write** half of the cache/help fix is still **deferred** — see AGENTS.md §12 ("res help-cache writes: Dispatcher reads cache but currently never writes it"). The `res --res-help` read path works. ## Decisions (confirmed with user) - **Build system → mage**, isolated in `core/magefiles/` with its **own `go.mod`** so mage runs independently of (possibly broken) core libs. - **Stale repos → keep them.** `respkg-mkinitfs/` required for residual-os; `os-old/` left untouched (legacy backup, deletion not authorized). The "remove stale repos" item is **dropped**. ## Steps 1. Rename `residual-demo` → `res-demo` (fixes Makefile breakage): `git mv cmd/residual-demo cmd/res-demo`; update string literals; `res-theme` already correct. 2. Mage build system in `core/magefiles/`: separate `go.mod` (`go 1.25`, `require github.com/magefile/mage v1.15.0`); `mage.go` (`//go:build mage`, package main) with targets that only shell out to `go` (Build, BuildOne, Demo, Theme, Test, TestCgo, Vet, Clean, All); replace `core/Makefile` with thin wrapper delegating to mage; ensure `core/.gitignore` ignores `bin/`; verify `magefiles/` tracked. 3. Fix `res` cache writing + `res --help` (`core/cmd/res/main.go`): `--help`/`-h` → `cmdHelp`; `@refresh` internal → `RefreshOne`; replace orphaned `refresh` block with detached re-exec that writes cache (`RES_NO_REFRESH=1`, `Setsid`); `scanExternalHelp` writes back via `SaveCache`; add `core/cmd/res/main_test.go` (run(["--help"])==0, run(["-h"])==0, run(["nonexistentxyz"])==127). 4. Bulk scripts + `AGENTS.md` docs: fix `deploy-harness.sh` repo list (`core docs editor extra os`); add header comments to each `.agent/tools/` script; verify repo lists post-collapse; document `.agent/tools/` in AGENTS.md. 5. Deferred: repo removal dropped per user clarification. ## Verification - `cd core && go build ./...` / `go test ./...` / `CGO_ENABLED=1 go test ./...` / `go vet ./...` → PASS - `cd core/magefiles && go run github.com/magefile/mage -d . build` (or `make build`) builds all `cmd/*` incl. `res-demo`, `res-theme` - `bin/res --help` / `bin/res -h` → print help (no "unknown subcommand") - `bin/res console` then check `$XDG_CACHE_HOME/residual/help-cache.json` exists and contains `res-console` - `bin/res help` → lists external subcommands with cached descriptions - `.agent/tools/test-all.sh`/`build-all.sh` run against `core/` only; `sync-repos.sh` SKIPs absent repos ## Risks - **Mage version skew:** `go mod tidy` may pick a different mage version; verify `go run` works. - **Detached child timing:** `@refresh` child must finish 500ms-bounded `RefreshOne` before user cares; cache best-effort, `scanExternalHelp` falls back to live query + write-back. - **`go run github.com/magefile/mage` first-run cost:** compiles mage once (cached after).

agent added the

tier-1-quick-win

label

2026-07-19 02:32:39 +00:00