Files
lora.vegas/TODO.md
clawbot fd3cd4c18c
All checks were successful
check / check (push) Successful in 16s
Add Makefile shims for cibuild and precommit (closes #34)
script/cibuild and script/precommit both existed and were already the
documented CI and pre-commit entrypoints, but neither had a Makefile
target, so the standing rule to drive the repo through make targets
rather than the underlying tool could not be followed for either.

It matters most for the build. A bare `docker build .` fails closed on
the CHECK_EPOCH guard by design, so script/cibuild is one of only three
supported ways to build an image here, and it was the only one of the
three without a target while `make docker` had one.

The two targets are thin shims in the same style as every other target
and change nothing about what the scripts do. .PHONY was already
complete for the targets that existed and now lists both new ones.

README.md's Entrypoints section gains the script-to-target mapping so
the two documents agree, including the two names that do not match:
script/install-precommit is `make hooks`, and script/precommit is
`make precommit`. It also notes that `make cibuild` is the slowest
target, because it is the only one that runs two container builds --
while still taking seconds once the shared script/bootstrap layer is
cached, since Dockerfile.lint's first four instructions are
byte-identical to the main Dockerfile's and the pinned-Hugo compile is
therefore paid once per machine rather than twice.

Two accuracy fixes to text the same section already carried. The
script/install-precommit bullet said the installed hook runs
script/check; the script writes script/precommit into
.git/hooks/pre-commit, and its own header comment says so. And the
Makefile is described as listing the operations you are expected to run
rather than as the authoritative list of everything the repo can do,
which is not literally true: script/projectname is an internal helper
that script/docker calls to compute a tag, and it has no target
deliberately -- a target for it would be noise in the `make<tab>`
listing this change exists to make useful.

TODO.md also loses the stale Future Step asking someone to confirm the
static/_headers file took effect in production. That was confirmed live
on both hostnames on 2026-08-10 and recorded at
#14 , so the item is work
already done. The Status paragraph's matching "unverified in production
until the next deploy" clause is corrected for the same reason: a commit
that edits TODO.md should not leave a known-false statement in it.
2026-08-10 13:57:34 +00:00

350 lines
24 KiB
Markdown

# Workflow
- branch (from `main`)
- do the work in Next Step
- move Next Step to the top of Completed Steps
- move the top item of Future Steps into Next Step
- commit (`TODO.md` changes in the same commit as the work)
- merge to `main` if the branch is not protected, otherwise open a PR
- push
# Status
pre-1.0
No git tags. The site is live and now has the scripts-to-rule-them-all scaffold
(`Makefile`, `script/`, `Dockerfile`, `check.yml`), the canonical policy
dotfiles and `LICENSE`, so the mandated minimum file list is complete. Every
external reference in the repo is now pinned by cryptographic hash (or, for the
wrangler CLI install, an exact version), and the Hugo that builds the published
site is a deliberate pinned version rather than whatever the base image's
package repo serves. The site now ships a Cloudflare Pages `_headers` file, so
its response security headers are declared in the repo instead of being whatever
the edge defaults to, and confirmed live in production on both hostnames. The
lint now runs inside a container and nowhere else: `script/lint` is a build of
`Dockerfile.lint`, with no host path to fall back to. Formatting is not a lint
and stays on the host. Every entrypoint the README documents now has a
`Makefile` target, so the org-wide "use make targets, never the underlying tool"
rule is satisfiable for the CI build as well as for the everyday checks.
# Next Step
Make the prettier scope's exclusion of dot-directories explicit instead of
leaning on `.gitignore` (https://git.eeqj.de/sneak/lora.vegas/issues/33).
# Completed Steps
- 2026-08-10: added the `cibuild` and `precommit` targets to the `Makefile`
(https://git.eeqj.de/sneak/lora.vegas/issues/34). Both scripts already
existed, were already documented, and are the two entrypoints a contributor is
most likely to be told to run — the CI build and what the pre-commit hook runs
— yet neither had a make target, so the standing rule to use make targets
rather than the underlying tool could not be followed for either. It bit
reviewers twice, most recently on
https://git.eeqj.de/sneak/lora.vegas/pulls/32, and it bit hardest for the
build: since https://git.eeqj.de/sneak/lora.vegas/issues/30 a bare
`docker build .` fails closed on the `CHECK_EPOCH` guard, so `script/cibuild`
is one of only three supported ways to build an image and was the only one
without a target. The two targets are thin shims in the existing style and
change nothing about what the scripts do. `.PHONY` was already complete and
now lists both. `README.md`'s Entrypoints section gained the script-to-target
mapping, including the two names that do not match —
`script/install-precommit` is `make hooks`, and `script/precommit` is
`make precommit` — plus a note that `make cibuild` is the slowest target
because it is the only one that runs two container builds, while still taking
seconds once the shared `script/bootstrap` layer is cached. The section's
pre-existing `script/install-precommit` bullet, which claimed the installed
hook runs `script/check`, now says `script/precommit`, which is what the
script actually writes into `.git/hooks/pre-commit`. The stale Future Step
asking for post-deploy confirmation of `static/_headers` is dropped here: it
was confirmed live on both hostnames
(https://git.eeqj.de/sneak/lora.vegas/issues/14). Verified that `make cibuild`
earns its green rather than replaying a warm cache: one invocation ran both
builds for real in sequence, each with its own distinct `CHECK_EPOCH`, with
`RUN script/bootstrap` `CACHED` above and no check layer cached below it — the
`Dockerfile.lint` build echoed its epoch and printed hugo's own build table,
then the main image build echoed a different epoch, ran `script/test` for the
production build and `script/fmt-check` for the formatting check.
`make precommit` passes on a clean tree, and `make check` passes
- 2026-08-10: moved the lint into Docker
(https://git.eeqj.de/sneak/lora.vegas/issues/38). A new root `Dockerfile.lint`
runs `hugo --minify --printPathWarnings` as a build step, so a successful
build is a clean lint, and `script/lint` is nothing but a build of that file —
no host path and deliberately no "already inside a container?" branch, which
would be a host lint path in disguise. The containerisation boundary is lint
only, per the owner ruling of the same day: formatting is not a lint, so
`script/fmt` and `script/fmt-check` stay on the host. `Dockerfile.lint` has
exactly one stage on purpose. A whole-file `docker build -f Dockerfile.lint .`
builds only the file's last stage, and sibling stages off a shared base have
no ordering edge, so any second stage beside the lint would be silently
skipped by the invocation the canonical org-wide `script/lint` uses — a green
that linted nothing. With one stage there is nothing to skip and `script/lint`
needs no `--target`. Its first four instructions are byte-identical to the
main `Dockerfile`'s, so the expensive `RUN script/bootstrap` layer that
compiles Hugo from source is shared between the two images rather than paid
twice. The recursion this creates was resolved by direction, not detection:
`make check` calls `script/lint`, so the main `Dockerfile` can no longer
`RUN make check` — that would attempt a docker build inside a build step, in a
bare Alpine with no docker client and no daemon socket. It runs the individual
non-lint checks instead, `script/test` and `script/fmt-check`, matching the
canonical shape upstream, and `script/cibuild` runs `script/lint` first for
fail-fast feedback before the main image build starts. So CI still covers all
three checks and cannot drift from what a developer runs. Caching is waived
for the lint exactly as the main `Dockerfile` already does it:
`ARG CHECK_EPOCH` with no default, guarded with
`[ -n "$CHECK_EPOCH" ] || exit 1`, and the value expanded into the linted
command as well as the guard, so invalidation never rests on BuildKit's
handling of an unreferenced `ARG`. Every image-building entrypoint generates
and passes it — `script/cibuild`, `script/docker`, `script/lint` — which is
the failure mode this repo already hit once, a Dockerfile guard asserting a
property one entrypoint did not supply. `script/lint` builds with
`--output type=cacheonly`: the build is run for its exit status, not for an
image, and since the lint layer is cache-busted every run an exporting build
would leave one dangling image per lint on a host shared with other work.
Verified rather than assumed: two consecutive `script/lint` runs on an
unchanged tree both executed hugo for real (second run 0.85s wall,
`RUN script/bootstrap` `CACHED`, distinct epochs echoed, real build tables
printed); a whole-file `docker build -f Dockerfile.lint .` with the argument
and no `--target` ran the lint for real, which is the regression test for the
skipped-sibling hazard; a bare build with no argument failed closed on the
guard; a planted template error failed the lint with hugo's own render error
and made `script/cibuild` exit in 0.6s without the main image build starting
at all; a planted over-long line failed the host `script/fmt-check` with
`[warn] README.md`; both violations were reverted and re-run clean. Not
changed here, and still true: the lint fails on hugo build errors but not on
render-target collisions, which `--printPathWarnings` only prints
(https://git.eeqj.de/sneak/lora.vegas/issues/25) — containerising the run
neither fixes nor worsens that
- 2026-08-10: added the `LICENSE` file and made the README say what it says
(closes #10). The repo is public (`private: false` on the Gitea API, verified
rather than assumed), so the owner's standing policy — MIT on any public repo
lacking a license — applies. `LICENSE` is byte-identical to the canonical
`sneak/homoicon` copy, confirmed by git blob hash rather than by eye
(`3274443`), and its body is word-for-word the SPDX MIT text with only the
line wrapping differing. The README's "Content is provided as-is for community
use." — which granted nothing and matched no committed file — is replaced by
`MIT. See [LICENSE](LICENSE).` plus an explicit statement that the licence
covers the content in `content/` as well as the code, since this repo carries
both and MIT names only "the Software". The Description first line now carries
the licence, which `REPO_POLICIES.md` requires and which was the one field it
was missing. Nothing published contradicts the choice: the built `public/`
tree carries no copyright, all-rights-reserved or terms-of-use string
anywhere, in `index.html`, `css/style.css`, `index.xml` or `sitemap.xml` — the
footer `baseof.html` renders names `@sneak` and links the repo but asserts no
reservation of rights, and the content is factual mesh channel data with no
licence claim of its own. The fmt gate cannot reach `LICENSE` and needed no
`.prettierignore` entry: `script/fmt` passes prettier the explicit globs
`'**/*.md'` and `'**/*.css'`, and an extensionless root file matches neither.
Measured, not assumed — a `script/fmt` run leaves the file's hash unchanged,
and a counterfactual `LICENSE.md` copy was reflowed by the same run, which is
the direct evidence that it is the extension and not an ignore rule doing the
excluding. Deliberately not done, per the issue: per-file licence headers and
SPDX identifiers, which no org standard mandates
- 2026-08-09: added `static/_headers` so Cloudflare Pages serves baseline
response security headers (closes #14). Hugo copies `static/` verbatim into
`public/`, which is the deploy root Pages reads the file from; this is the
first root-level `static/` in the repo, and the built tree confirms it unions
with the theme's rather than shadowing it — `public/css/style.css` and
`public/index.html` are byte-identical to the previous build and the static
file count goes 1 to 2. The live "before" was measured, not assumed:
Cloudflare already sends `X-Content-Type-Options` and `Referrer-Policy` by
default, so the substance here is `Strict-Transport-Security`,
`Content-Security-Policy`, `X-Frame-Options` and `Permissions-Policy`. The CSP
is `default-src 'none'` with `style-src 'unsafe-inline'`, which the built page
supports exactly: it has no script, img, link, iframe, form or media element
and no `style=`/`on*=` attribute, only the one inline `<style>` block
`baseof.html` fills by `readFile`. Verified in a headless Chrome against a
local server that parses the committed `_headers` and applies it as real
response headers: zero CSP violations, the inlined stylesheet parses to 17
rules and the computed body padding, tagline colour and link colour all come
from the theme CSS, framing the page from another origin is refused by
`frame-ancestors 'none'` (consistent with `X-Frame-Options: DENY`), and all
five named outbound links still navigate with status 200. HSTS carries neither
`preload` nor `includeSubDomains`: `www.lora.vegas` is the only other name in
DNS and it is served by this same Pages project, so this file sets HSTS on its
responses directly, and `includeSubDomains` would instead bind every future
subdomain for a year with no way to walk it back inside the max-age window
without also dropping the apex protection.
- 2026-08-09: restructured `README.md` into the canonical section set (closes
#11): a Description first line, then Getting Started, Entrypoints, Rationale,
Design, TODO, License, Author. The non-standard About / Contributing /
Technical Details headings are gone, but nothing they held was dropped — the
bullet list of what the site publishes moved under the Description, the
contribute contact and the local-preview instructions moved into Getting
Started. Getting Started was written against the current `Makefile` rather
than the old prose: there is no `make build` target, so the former "Build:
`hugo`" instruction is now `make test`, and the former "Local Development:
`hugo server`" is `make setup` then `make serve`. Two stale claims fixed: the
site is deployed by Gitea Actions to Cloudflare Pages, not "GitHub Actions",
and the Entrypoints bullet for `script/fmt` still described the
top-level-markdown-only scope that #12 replaced with `'**/*.md'` and
`'**/*.css'`. The License section body is deliberately untouched — it is owned
by #10, which is blocked on the owner's choice of license, and the Description
sentence is likewise missing the license clause the policy calls for until #10
lands. Design section claims were verified against the tree, not assumed
- 2026-08-09: widened the prettier gate from top-level markdown to `'**/*.md'`
and `'**/*.css'` (closes #12). `themes/loravega/static/css/style.css` was
never formatted or gated even though it is inlined into every page; it is now
both, and the reformat landed as its own commit ahead of the script change so
no commit in the branch is red. `content/` is excluded in `.prettierignore`,
and that exclusion is measured rather than assumed: with `content/` in scope,
prettier re-wrapped one list item in `content/_index.md` and the rendered
`public/index.html` changed with it (the wrap became a literal newline between
`7 PM at` and the following `<a>`). HTML collapses that newline to a space so
the page looks identical, but the published bytes are not, and this content
carries raw HTML that goldmark passes through verbatim under `unsafe = true`.
`themes/loravega/layouts/` is excluded too, with the reason recorded: those
files are Go templates, not HTML, and prettier has no parser for `{{ ... }}`
covering them would need a plugin and therefore a `package.json`. Verified by
extracting `public/` from the built image before and after: with the final
scope, `index.html`, `index.xml` and `sitemap.xml` are byte-identical and only
the verbatim-copied `public/css/style.css` changes, in whitespace only — the
minified `<style>` block inlined into `index.html` is unchanged, which is the
direct evidence that CSS formatting cannot reach the rendered page
- 2026-08-09: added the canonical policy dotfiles and hardened both ignore files
(closes #8). `REPO_POLICIES.md` is a byte-identical copy of the canonical
`prompts` file, front matter intact; `.editorconfig`, `.prettierrc` and
`.prettierignore` are the canonical contents. `.gitignore` keeps its three
Hugo lines and gains the OS/editor/node/secrets block plus `.claude/`, so a
clean checkout with agent tooling present is `git status`-clean and a stray
key or `.env` can no longer be committed. `.dockerignore` gained the same
coverage but **not** the same syntax: it matches with Go's `filepath.Match`
rules extended with `**`, where `*` does not cross `/` and an unprefixed
pattern is anchored at the context root, so every depth-independent pattern
carries an explicit `**/` prefix and only the genuinely root-anchored entries
(`.git`, `public`, `resources`, `.hugo_build.lock`) go bare. Verified by
planting `.env`, `*.key`, `*.pem` and `node_modules` two directories deep: the
unprefixed form shipped all of them into the image and the `**/` form ships
none. Excluding `.claude/` also takes `worktrees/` — entire additional
checkouts of this repo — out of the build context; #23's two-consecutive-run
proof was re-run against the smaller context, since that issue was validated
against the old one. Note the canonical upstream `REPO_POLICIES.md` is not
clean under this repo's prettier settings, so the reformat is a separate
follow-up commit rather than churn mixed into this one
- 2026-08-09: stopped `script/cibuild` reporting a green it never earned (closes
#23). `COPY . .` is keyed on content, so on an unchanged tree Docker served
`RUN make check` from cache: the checks never executed and the build still
exited 0. Three separate reviewers had already been fooled by it here. The
`Dockerfile` now declares `ARG CHECK_EPOCH` below `COPY . .` with no default
(a default is a constant, and a constant is a stable cache key), guards it
with `RUN [ -n "$CHECK_EPOCH" ] || exit 1`, and expands it into the check
command; `script/cibuild` and `script/docker` both pass
`epoch="$(date +%s%N)$$"` — assigned on its own line, because a failing
command substitution inside an argument does not trip `set -e`, and with `$$`
because busybox `date` drops `%N` silently. This is the canonical shape
settled upstream in `prompts` #26, which has not merged there yet, so it may
need re-syncing. Verified with two consecutive runs on an unchanged tree that
both executed the checks while `RUN script/bootstrap` stayed `CACHED`, a
constant-epoch counterfactual that restored the false green, and a planted
prettier failure that failed the build
- 2026-08-09: disabled the unused `taxonomy` and `term` page kinds in
`hugo.toml` (closes #13). Hugo enables the `tags` and `categories` taxonomies
by default; this single-page site has no taxonomy terms and no taxonomy
templates, so every build emitted
`WARN found no layout file for "html" for kind "taxonomy"` and generated
`categories/index.xml` and `tags/index.xml` that nothing links to. Re-verified
the warning still occurs on the now-pinned hugo v0.164.0 rather than trusting
the issue's text, which predates the version move. `make test` and `make lint`
are now `WARN`-free, so the build's noise floor is zero and the next warning
will be visible. `public/` is otherwise byte-identical — `index.html`,
`css/style.css` and the RSS `index.xml` all unchanged — and `sitemap.xml` is
still generated, now listing only the home page instead of two taxonomy URLs
- 2026-08-09: replaced `hugo.toml`'s deprecated `languageCode` key with `locale`
(closes #18). Hugo deprecated `languageCode` in v0.158.0, so the Hugo pinned
in the preceding commit warns about it; left alone it would become a third
routinely-ignored warning, and a latent breakage when the key is removed.
Deliberately sequenced **after** the Hugo version move and in the same branch:
under the apk hugo 0.139.0 that CI ran until now, `locale` is an unknown key
that is silently ignored, which downgrades the generated RSS from
`<language>en-us</language>` to `<language>en</language>` with no warning and
exit 0. Verified on hugo v0.164.0 that the RSS `<language>` still reads
`en-us`, the `lang` attribute is unchanged, and `public/` is byte-identical to
the preceding commit's output
- 2026-08-09: installed Hugo at a deliberate, hash-verified version instead of
taking whatever alpine ships (closes #26). `script/bootstrap` no longer does
`pkg_install hugo`; it installs `github.com/gohugoio/hugo@v0.164.0` with
`go install`, which verifies the module against `sum.golang.org`. The version
is a commented constant, as is the Go toolchain (`go1.26.5`) — hugo v0.164.0
requires go >= 1.26.0 and alpine 3.21 ships go 1.23.9 with
`GOTOOLCHAIN=local`, so a bare `go install` refuses to run. `CGO_ENABLED=0` is
deliberate: standard Hugo, not extended, because this site has no SCSS, no
`resources.ToCSS`, no PostCSS and no image processing. This moves the build
off apk's hugo 0.139.0, about two years behind, onto the current stable.
Rendered output across the whole `public/` tree is unchanged except the
`meta name=generator` version string
- 2026-08-09: made `script/check` run `script/lint` (closes #9). It previously
ran only `fmt-check` then `test`, so `script/lint` executed nowhere — not in
`make check`, not in the pre-commit hook, and not in CI, even though the
`Dockerfile` runs `make check` and `script/cibuild` builds it. It now runs
`test`, `lint`, `fmt-check` in the canonical order, so the
`hugo --printPathWarnings` render-target-collision signal is no longer
discarded. `README.md`'s Entrypoints line was corrected to match
- 2026-08-09: hash-pinned every external reference in
`.gitea/workflows/deploy.yml` (closes #7): both job container images are
pinned by digest, all three `uses:` are pinned by 40-hex commit SHA, and the
wrangler install is pinned to an exact version. The abandoned
`klakegg/hugo:ext-alpine` image is gone: the build job now runs on the same
pinned `alpine` digest the `Dockerfile` uses, with a pre-checkout
`apk add nodejs git tar` step (the Actions runner needs `node` inside the job
container to execute JavaScript actions), an explicit `shell: sh` default,
then `script/bootstrap` and `script/test`. The `deploy` job is guarded with
`if: github.ref_name == 'main'` so it can never publish from a branch. Also
dropped the dead `feat/initial-site` push trigger and reindented the file to
4-space YAML to match `check.yml`. This is the second attempt; the first broke
the deploy and was reverted, so this one was verified by temporarily
triggering the workflow on the PR branch and iterating until the `build` job
ran green for real
- 2026-07-25: added the scripts-to-rule-them-all scaffold (closes #4): `script/`
entrypoints, `Makefile` shims, a Hugo `Dockerfile` (sha256-pinned alpine) plus
`.dockerignore` that runs `make check`, `.gitea/workflows/check.yml` running
`script/cibuild`, and a README Entrypoints section. `test`/`lint` are a clean
`hugo --minify` build; `fmt`/`fmt-check` run prettier over the repo's own
top-level markdown only
- 2026-02-10: design pass: minimal light theme with inline CSS, grey wells for
mesh channels and signal groups, horizontal overflow fix, body width tuning,
map link update
- 2026-02-10: added README and footer contribute link
- 2026-02-10: added Gitea workflow that builds the site and deploys to
Cloudflare Pages
- 2026-02-08: initial Hugo static site for lora.vegas
# Future Steps
Startable work first. Everything under "Blocked" waits on somebody or something
outside this repo, so nothing there may be picked up as the Next Step.
- Fix the README's SSH-only clone URL, and add the two entrypoints the
Entrypoints section omits, `script/precommit` and `script/projectname`
(https://git.eeqj.de/sneak/lora.vegas/issues/36)
- Drop the Go toolchain and module cache from the check image's final layer;
they are needed to build hugo and dead weight afterwards
(https://git.eeqj.de/sneak/lora.vegas/issues/28)
- Add a timeout guard to `script/test` and `script/lint` so a wedged build fails
instead of hanging (https://git.eeqj.de/sneak/lora.vegas/issues/16)
- Sync the reformat of `REPO_POLICIES.md` back upstream to `prompts` so the
canonical copy is clean under the shared prettier settings and future syncs
are a straight byte copy
- Keep mesh channel and signal group listings current
## Blocked
- Decide whether `script/lint` should fail on render-target collisions rather
than only print them; `--printPathWarnings` exits 0 today, so the signal is
reported and not enforced. Owner call, since it changes what the gate rejects
(https://git.eeqj.de/sneak/lora.vegas/issues/25)
- Move the artifact actions in `.gitea/workflows/deploy.yml` to v4 once this
Gitea Actions instance serves the v4 artifact protocol; they are pinned on the
deprecated v3 line because v4 fails here
(https://git.eeqj.de/sneak/lora.vegas/issues/20). This touches the live deploy
path, so it needs a real workflow run to verify rather than a local check
- Move the deploy container to a pinned node 22 so the wrangler pin can advance
past 4.86.0 (https://git.eeqj.de/sneak/lora.vegas/issues/21)
- Delete the stale remote branches `feat/initial-site` and `security-audit`;
only the owner can remove them
(https://git.eeqj.de/sneak/lora.vegas/issues/15)
- Decide the HSTS `includeSubDomains` and `preload` posture for `lora.vegas`.
Both are owner calls: neither can be walked back inside the max-age window,
and `includeSubDomains` binds hostnames this repo does not control
(https://git.eeqj.de/sneak/lora.vegas/issues/14)
- Verify the Cloudflare Pages deploy still works after the workflow changes