BE-M0-31 · pnpm docs:reference and the generated reference pages

ID BE-M0-31 · Level L0 · Pack Pack E · Logins, types and the acceptance check · Run order row 22 · Issue #14

Goal

pnpm docs:reference writes the generated pages under apps/docs reference/ from the local database, and the docs sidebar shows them under Reference (D27). There are nine pages: tables, row-level security, views, enums and types, functions, error keys, roles and permissions, and storage, plus an index. Pack E is merged into main.

Before

BE-M0-27 is Done. You are on the branch tools/e2e-types-reference in ~/opleet-v2/opleet, git status --short prints nothing, and the stack is running with every migration and the seed applied.

Run

1 · This step's file, the root script and the sidebar entry

The sidebar helper comes with the pack and is never committed; it adds the entry once and writes nothing if the config isn't as expected.

cp -R ~/opleet-v2/packs/be-pack-e/BE-M0-31/. .
pnpm pkg set 'scripts["docs:reference"]=node tools/db/gen-reference.mjs'
node ~/opleet-v2/packs/be-pack-e/add-reference-sidebar.mjs
git status --short

2 · Write the pages

pnpm docs:reference
ls apps/docs/src/content/docs/reference

3 · Build the docs site with them, and run the rule check

pnpm --filter docs build
pnpm docs:rules

4 · Commit

git add tools/db/gen-reference.mjs package.json apps/docs
git commit -m "feat(tools): generated reference pages in apps/docs (D27)"

5 · Push, open the pull request and wait for its checks

git push -u origin tools/e2e-types-reference
gh pr create --title "feat(tools): E2E logins, generated types and reference pages" --body "BE pack E (BE-M0-25 to BE-M0-27, BE-M0-31), timeline row 22. Closes #14."
gh pr checks --watch

6 · Log the run on #14, then merge

Comment on #14 with the date, what you ran in BE-M0-25 to BE-M0-31, the output of BE-M0-26's block 3 and BE-M0-27's three blocks. Then:

gh pr merge --squash --delete-branch
git switch main
git pull

Expect

Block 1: apps/docs/astro.config.mjs: the Reference section added before Contributing., then M apps/docs/astro.config.mjs, M package.json and ?? tools/db/gen-reference.mjs.
Block 2: apps/docs/src/content/docs/reference: 9 pages from 70 tables, 4 views, … with the number of functions last, then enums.md, error-keys.md, functions.md, index.md, policies.md, roles.md, storage.md, tables.md and views.md.
Block 3: the build ends with “Complete!” and lists the /reference/ pages; the warnings about i18n, 404 and the sitemap are old and harmless. The rule check prints one “Rules: …” line and nothing under it.
Block 4: ✔️ biome and ✔️ commitlint, then the commit line.
Block 5: the pull request's URL; checks and pr-title pass.
Block 6: “✓ Squashed and merged pull request #…”, and main moves to that commit.

Check

pnpm docs:reference && git diff --exit-code apps/docs/src/content/docs/reference && echo "reference pages are current"
git log --oneline -1

“reference pages are current”, then “feat(tools): E2E logins, generated types and reference pages (#…)” on main.

If it fails

Block 1 prints “Stopped, nothing written”: the sidebar config isn't what the helper expects. Paste the output and don't edit the config by hand.
Block 2 fails with “No such container: supabase_db_opleet”: the stack isn't running. Run pnpm supabase start, then block 2 again.
Block 3's build fails: paste the error lines. Don't commit.
A check fails on the pull request: paste the failing job's log.

Undo

Before merging: gh pr close --delete-branch, then git switch main. After merging: revert it with a new pull request. The generated pages are rewritten in full on every run, so a later run fixes a stale page.

Runs

Not run yet. Log each run as a comment on #14.