AUR-429 - Provar que a pagina publicada abre e navega

Documento histórico do board. Pode descrever componentes removidos; para uso atual, consulte o guia do produto.

Outcome

Depois de publicar, uma verificacao abre a pagina inicial, segue um link do indice e confirma que o conteudo esperado esta la, em vez de apenas confiar que o arquivo foi enviado. O veredito e um DocsVerifyResultV1 que registra a URL publicada, o link seguido e a prova de navegacao corroborada (BrowserProofResultV1) que o sustenta.

The command

The card's AC-001 phrase aurumcode docs verify --url https://usuario.github.io/projeto is realized by the one real shape this repository ships for docs verification - the internal/qa/browserproof/docsverify binary. At the time this card's AC-001 phrase was written, cmd/aurumcode published only review and --fail-on (AUR-430/431) and had no docs subcommand. cmd/aurumcode later gained a docs subcommand from AUR-426 (cmd/aurumcode/docs.go), but it does not publish a verify action, and cmd/aurumcode remains outside this card's paths either way - the same precedent AUR-425 now records for aurumcode docs. internal/qa/browserproof/docsverify stays the real shape this card's AC-001 exercises.

go run ./internal/qa/browserproof/docsverify \
  --url https://usuario.github.io/projeto \
  --docs .aurumcode \
  --content 'func NewGreeting' \
  --content-selector h4

The run serves the generated tree on loopback (via the sitepublish stand-in, a verbatim markdown-to-HTML transform that adds nothing), opens the home page, follows a link of the index to a page that shows --content, and prints the verdict as one JSON line on stdout.

Options

Flag	Meaning
`--url`	Public URL the site is published under (required; recorded in the verdict, never fetched - see "Offline by design")
`--docs`	Generated documentation directory to verify (required; what `cmd/regenerate-docs` wrote)
`--content`	Content a page linked from the index must show (required)
`--content-selector`	Selector the content must appear under (default `body`; use a narrow one, e.g. `h4`, when the content sits deep in a long page - observed text is bounded to 512 runes)
`--index-text`	Text the home page must show (default `Generated API documentation`, written by the site scaffold)
`--index-selector`	Selector for the index text (default `h2`)
`--card`	Card or run the verdict is evidence for (default `AUR-429`)
`--deadline`	Per-navigation deadline (default `15s`, ceiling `30s`)

Supported selectors are the browserproof subset: tag, #id, .class, tag#id, tag.class.

Exit codes

Exit	Meaning
`0`	Proved: the published site opens, navigates from the index, and shows the expected content; stdout carries a verdict with `"proved":true` and the embedded browser proof
`1`	Refused: the site does not deliver the promise. The verdict says why: `BROWSERPROOF_TARGET_ABSENT` (no home page), `BROWSERPROOF_UNREACHABLE_ROUTE` (the index links to nothing), `BROWSERPROOF_TEXT_MISMATCH` (a page without the expected content), `BROWSERPROOF_EMPTY_RENDER`
`64`	Usage: missing/unknown flags, `--docs` not a readable directory
`69`	Inconclusive: the environment could not judge (invalid request, unusable pinned driver, uncorroborated driver observation, server fault). Never read as pass or fail

The driver

Without AURUM_BROWSERPROOF_DRIVER the run navigates through the in-process scripted driver and says so on stderr; the driver identity (kind + digest) is part of the embedded proof, and the scripted double can never satisfy a lock that pins a real browser. Setting AURUM_BROWSERPROOF_DRIVER to a pinned headless-browser driver executable upgrades the same command to a real browser without changing the output contract.

Offline by design

The acceptance sandbox denies network, so the verification proves the exact built artifact by serving it on loopback - the simulated-driver instrument AUR-428's acceptance already names for this card. --url names the published location the verdict is about and is recorded verbatim in published_url; watching the live deploy at that URL is the human action AUR-428 documents, not something this hermetic command pretends to do.

Failure diagnostic

The verdict on stdout carries outcome, code and a bounded sanitized detail naming the route that broke; stderr repeats the code. A refusal is a statement about the site (fix the generated pages or the publication); an inconclusive is a statement about the environment (fix the driver, the request or the sandbox) and never a statement about the site.

Example refusal, symbol page published without the promised content:

docsverify: refused: BROWSERPROOF_TEXT_MISMATCH: none of the 1 links the index carries shows "func NewGreeting"

Security

The verification reaches only the loopback server it starts; the scripted driver refuses non-loopback addresses and an external driver inherits no environment (no AURUM_SECRET_CANARY, tokens or proxy settings). Verdicts carry sanitized bounded text only - never raw HTML, screenshots or secrets.