goflag

A CLI that audits a site for broken links, missing translation pages, a robots.txt that contradicts your pages, and missing or misconfigured SEO metadata — and a Next.js library that produces the HTML it would have nothing to say about.

_{The first eleven lines of a real run. Rendered from the same transcript the documentation site paints, which is compared to the renderers byte for byte — so this picture cannot drift from what the command prints.}

Goflag crawls a site once and judges what it found. It is deliberately small: no dashboard, no config system, no social-preview gallery. Just the findings, as a machine-readable report you can pipe, diff, or gate CI on.

It is built for the mistakes that are invisible while browsing and expensive in search: a hreflang that points at a 404, a canonical that silently de-indexes a page, a robots.txt that contradicts every <meta name="robots"> on the site. A human cannot check those on 400 pages. That is the whole job.

Getting started

npx @goflag/cli https://example.com          # one-off, nothing installed
pnpm add -D @goflag/cli                      # then: pnpm goflag https://example.com

Install it as a dev dependency once you run it more than once — in a script, in CI, in a git hook. npx is for trying it. The package is @goflag/cli; the command it installs is goflag. Everything under the brand lives in the @goflag scope; the bare goflag name on npm is a deprecated signpost pointing here and carries no code.

• Node >=22.
• Nothing else for a static audit. Headless rendering needs Chromium, which is not installed with goflag — playwright is an optional peer dependency. Add it only if you audit client-rendered pages without --static: pnpm add -D playwright && pnpm exec playwright install chromium.
• Working in this repository instead of consuming it: pnpm install, then see AGENTS.md.

What it does

• Broken links — reads the links of every crawled page from the copy the crawl kept, dedupes targets globally (a footer link on 500 pages is probed once, and a link to a page the crawl fetched without a redirect is judged from that answer rather than asked again), and checks each with HEAD→GET fallback, redirect-chain/loop detection, soft-404 and anti-bot (403/429) triage. Broken links are mapped back to the pages that reference them.
• Missing translation pages — builds a route × locale matrix and flags every route that exists in one locale but is missing in another, plus hreflang reciprocity gaps (A → B with no B → A), missing x-default, and locale tags naming a language, script or region that does not exist. Rows are keyed by pathname, unless the site declares its translation clusters — either with xhtml:link in the sitemap, or with reciprocal hreflang between two crawled pages' <head>. Then those declarations decide which URLs are one page, whatever their slugs, and the run reports diagnostics.declaredClusters. The sitemap source survives --coverage structural, where the two locales of a slug-translating family are rarely both sampled; the <head> source needs both pages in hand and is what fixes the common site that declares properly there and nothing in its sitemap.
• robots.txt policy — the file is parsed to RFC 9309, not scanned: every grou

... View full README on GitHub