0 Fork 0

Files

T

fix: preserve tracked dist/.gitkeep across clean cycles

Commit 6472890 accidentally deleted the committed dist/.gitkeep: the
clean-state test ran 'rm -rf dist' (which contains the tracked .gitkeep)
and the following 'git add -A' recorded the deletion. Fresh clones then
had no dist/ and 'go build'/'just check' failed before the first shiroa
run ('pattern all:dist: no matching files found').

- Justfile: 'clean' now recreates dist/.gitkeep, so the tracked file
  survives clean/build cycles.
- AGENT.md: clean-state procedure uses 'just clean' and requires a clean
  'git status' after test cycles, with the reason documented.
- Verified: with dist/ holding only .gitkeep, 'go build' and 'go vet'
  succeed (fresh-clone state).

2026-10-10 18:58:45 +02:00

4.0 KiB

Raw Blame History

AGENT.md — operating rules for agents working on Yggdrasil

Personal knowledge base: Typst sources (docs/, a shiroa book) compiled to a static site, embedded into a Go binary that enforces per-page OIDC group permissions (Authentik). README.md is the human-facing documentation; this file is the working rulebook. Follow it; when it conflicts with the user, the user wins.

Commands

just — shows the command overview (bare just never builds anything).
just build — parse ACL, compile the book, build ./server.
just run — build everything, then serve on :8080.
just check — go vet, go test, gofmt. Run it before every commit.
just clean — removes dist/ and server (keeps tools/ and restores the committed dist/.gitkeep).
The shiroa toolchain is pinned and self-bootstrapped into tools/ by the tools recipe. Never assume a global shiroa/typst install exists; do not install shiroa globally; do not bump the pin casually (see Traps).

Layout

docs/ — shiroa book. book.typ lists every built page; files not listed there are not part of the site. Categories are = part headers in the summary, pages are # chapter("path.typ")[Title] entries. Final URL = source path with .typ replaced by .html.
cmd/parser — build step: scans docs/ for #let access-groups = (..) tags and emits acl.json. Untagged pages are public.
cmd/server + embed.go (repo root) — //go:embed of dist/ and acl.json into a single binary.
internal/acl — ACL loading and page-key normalization (security critical).
internal/oidc — OIDC authorization-code client.
internal/middleware — sessions, login/callback/logout, access gate.
legacy_docs/ — frozen previous site. Never modify or migrate it unless the user asks explicitly.

Security invariants — do not break

Fail closed: a malformed acl.json aborts startup; protected pages with no configured IdP answer 503, never the content.
Page keys: shiroa pages keep their rendered content in sibling <page>.<theme>.multi.sir.in files fetched by client-side JS. acl.PageKey reduces any URL to a page key so those files inherit the page's protection. If the shiroa output format changes, re-verify this mapping: content in any new sidecar file must be covered or blocked.
/searchindex.json contains the text of protected pages: blocked at the router, always.
Session cookies: HttpOnly, SameSite=Lax, Secure unless COOKIE_SECURE=false. OAuth2 states are random and single use; post-login redirect targets are sanitized (open-redirect guard).

Traps

Shiroa version pairing: the CLI and the @preview/shiroa:* typst package must match (CLI v0.4.0-rc2 pairs with package 0.4.0; the v0.3.0 release CLI rejects 0.4.0 books). Bump both together and rebuild.
Typst call syntax: no space between ) and the trailing content block — #chapter("x.typ")[Title], not #chapter("x.typ") [Title].
dist/ and acl.json are embedded at Go build time; there is no runtime reload. After changing docs or ACL, rebuild the binary.
go build needs dist/ and acl.json to exist: fresh clones carry dist/.gitkeep and a committed acl.json for exactly this reason. Never gitignore those two.

Testing expectations

Test what the user runs, not a proxy for it: from a clean state (rm -rf tools && just clean), just build and just run must succeed with no global shiroa on PATH. Test the bare just output too. After any clean/test cycle, git status must be clean: dist/.gitkeep is tracked, and committing a worktree where it is missing breaks fresh clones (go:embed needs dist/).
Server behavior: curl a public page (200), a protected page (503 without OIDC env; it must never serve protected content), and /searchindex.json (404). Extend the unit tests in internal/acl and internal/middleware whenever touching those paths.
A live OIDC round trip needs a real IdP and is not testable here. Say that explicitly when reporting what was verified.

4.0 KiB Raw Blame History