@goflag/cli 0.2.10 → 0.2.12

package/README.md

@@ -1,9 +1,8 @@
-# Goflag
+# goflag
 
-> **A lean CLI that flags the site problems humans can't catch at scale.**
-> Point it at a URL and get four things: broken links, missing translation pages, a robots.txt that contradicts your pages, and missing or misconfigured SEO metadata. JSON-first.
+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.
 
-[![node](https://img.shields.io/badge/node-%3E%3D22-339933?logo=nodedotjs&logoColor=white)](./package.json)
+[![node](https://img.shields.io/badge/node-%3E%3D22-339933?logo=nodedotjs&logoColor=white)](https://github.com/tancredesimonin/goflag/blob/main/package.json)
 [![license: MIT](https://img.shields.io/badge/license-MIT-green)](#license)
 
 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.
@@ -13,7 +12,24 @@ 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.
 
-## What it checks
+## Getting started
+
+```sh
+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](https://github.com/tancredesimonin/goflag/blob/main/AGENTS.md).
+
+## What it does
 
 - **Broken links** — scrapes every crawled page, dedupes targets globally (a footer link on 500 pages is probed once), 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.
@@ -43,31 +59,11 @@ fails loudly rather than passing quietly. It is also why `--static` is the right
 default in CI: it needs no browser, and it cannot mistake a broken page for a
 fine one.
 
-## Install
-
-Requires Node `>=22`.
-
-```sh
-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.
+## Where it runs
 
-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.
+Two packages ship to npm from a tag, published by GitLab CI over OIDC with no stored credential: `@goflag/cli` (`v*`) and `@goflag/next` (`next-v*`). The documentation site `apps/website` runs at [goflag.tech](https://goflag.tech), with `develop.goflag.tech` alongside it, both deployed with Kamal onto the shared OVH host described in the `infrastructure` repository.
 
-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`:
-
-```sh
-pnpm add -D playwright && pnpm exec playwright install chromium
-```
-
-## Getting started
+## Your first audit
 
 Five steps, in this order. Each one is explained in full further down; this is
 the sequence.
@@ -134,6 +130,19 @@ npx @goflag/cli https://example.com --report report.json      # write JSON to a
 
 The terminal view is just a render of that JSON.
 
+### Four verbs
+
+```sh
+goflag <url> [options]     # audit a site
+goflag preview <url>       # render its share cards, and look at them
+goflag rules               # print the rule catalogue as JSON
+goflag flags               # print the flag reference as JSON
+```
+
+The last two answer a question about goflag rather than about a site, so they
+take no URL and touch no network. `preview` takes one and audits like a normal
+run — [what it writes](#goflag-preview--look-at-the-cards-before-you-ship-them) is further down.
+
 ### The catalogue is data too
 
 ```sh
@@ -141,15 +150,15 @@ npx @goflag/cli rules > rules.json
 ```
 
 `rules` answers a question about goflag rather than about a site: no URL, no
-crawl, no network. Every entry carries its scope, severity and summary; the
-twenty-three page rules and four prose rules also carry a rigor, the documents they
-cite and — where a remedy is a line of code — a fix snippet. Cross-page rules
-may carry them too, and the robots family does; the three hreflang and sitemap
-rules that predate the field still emit `rigor: null` with an empty `sources`,
-because choosing their citations is work nobody has done and inventing an
-authority is worse than admitting the gap. Write your consumer against that. The same document
-ships inside the package as `rules.json`, if you would rather read it than run
-anything.
+crawl, no network. It ships fifty-eight rules — twenty-five page rules,
+twenty-eight site rules and five prose rules — and every entry carries its
+scope, severity and summary. All but one also carry a rigor, the documents they
+cite and, where a remedy is a line of code, a fix snippet. The exception is
+`hreflang.sitemap-mismatch`, which emits `rigor: null` with an empty `sources`
+because no specification says which of the two declarations is wrong; inventing
+an authority there is worse than admitting the gap. Write your consumer against
+that. The same document ships inside the package as `rules.json`, if you would
+rather read it than run anything.
 
 The flag list below is data too:
 
@@ -174,7 +183,8 @@ documentation site came to quote a message the engine had stopped printing.
 --json                 Print the JSON report to stdout (nothing else).
 --summary, -s          Roll findings up (dedup by link/rule/code). Pairs with
                        --json for a compact payload; --report always writes
-                       the full report regardless.
+                       the full report regardless. Not available with
+                       --baseline: there the diff is the answer.
 --report <file>        Write the JSON report to <file>.
 --depth <n>            How far to follow links out of each page (0 = follow
                        none). Sitemap URLs are seeded regardless, so --depth 0
@@ -435,6 +445,30 @@ should boot. In a monorepo audited from the root, point it at the package:
 goflag http://localhost:3000 --start "pnpm start" --start-cwd apps/web
 ```
 
+### `goflag preview` — look at the cards before you ship them
+
+Some things are only settleable by looking. `og.image.representative` asks
+whether the shared image survives being cropped to 1.91:1 — a question the
+catalogue states and refuses to answer, because no rule can.
+
+```sh
+goflag preview http://localhost:3000 --start "pnpm start"
+```
+
+It audits like a normal run, then writes `.goflag/preview.html`: one
+self-contained file showing what Google, Open Graph, X, LinkedIn, Slack, Discord
+and WhatsApp make of each page, with the findings pinned on the cards they
+concern and the page's JSON-LD shown beside them.
+
+Each surface is labelled with how well its geometry is actually documented.
+Three of the seven publish real numbers; Slack calls its own rendering a
+"micro-approximation"; Discord publishes nothing; X's card documentation is not
+reachable, and its shape changed twice since 2023. Drawing all seven with the
+same confidence would be six unearned claims, so the file says which is which.
+
+It never gates — it exits 0 unless the run itself failed — and it prints the
+path it wrote, so `open "$(goflag preview http://localhost:3000)"` opens it.
+
 ### Multilingual sites
 
 Discovery is seeded from the sitemap, not just from links. That matters because
@@ -513,7 +547,7 @@ Three rules, whichever you use:
 stages: [build, deploy, audit]
 
 variables:
-  GOFLAG_VERSION: "0.2.10"
+  GOFLAG_VERSION: "0.2.12"
 
 # Before the merge: build the branch, let goflag boot it, audit that.
 seo:mr:
@@ -565,7 +599,7 @@ jobs:
       - run: corepack enable && pnpm install --frozen-lockfile
       - run: pnpm build
       - run: |
-          npx --yes @goflag/cli@0.2.10 http://localhost:3000 \
+          npx --yes @goflag/cli@0.2.12 http://localhost:3000 \
             --start "pnpm start" --static --no-external \
             --baseline .goflag/baseline.json --regressions-only --max-debt 41 \
             --report goflag-report.json
@@ -612,6 +646,7 @@ console.log(report.summary);
 ```
 packages/cli/      @goflag/cli, the CLI (installs the `goflag` command)
 packages/next/     @goflag/next, the Next.js library (see below)
+packages/og/       @goflag/og, the share cards and the favicon container
 apps/website/      goflag.tech, the landing page and the documentation
 tools/name-holder/ the bare `goflag` name on npm, a signpost to @goflag/cli
 ```
@@ -623,7 +658,7 @@ enforces it rather than trusting memory.
 ## The other half: `@goflag/next`
 
 goflag tells you what is wrong. It does not tell you how to stop writing it
-wrong. [`@goflag/next`](packages/next) is a route registry for the Next.js App
+wrong. [`@goflag/next`](https://github.com/tancredesimonin/goflag/tree/main/packages/next) is a route registry for the Next.js App
 Router that produces the HTML this auditor would have nothing to say about.
 
 ```ts
@@ -641,7 +676,32 @@ held in agreement by vigilance, and their disagreement is what goflag reports as
 `hreflang.sitemap-mismatch`. Projecting both from one registry makes that
 finding unrepresentable. Full documentation at
 [goflag.tech/docs/next](https://goflag.tech/docs/next), and the API reference in
-[`packages/next/README.md`](packages/next/README.md).
+[`packages/next/README.md`](https://github.com/tancredesimonin/goflag/blob/main/packages/next/README.md).
+
+## The picture: `@goflag/og`
+
+Two of this catalogue's rules had no remedy to point at. `og.image.missing`
+fired 24 times on one site and `og.image.alt` 46 times on another, and the fix
+for both is "either an asset or a route you have to write" — which is how a rule
+becomes permanent debt. [`@goflag/og`](packages/og) is that route, written once.
+
+```tsx
+// app/[locale]/opengraph-image.tsx
+const image = ogImage(og, async ({ params }) => {
+  const { locale } = await params;
+  return { title: t("hero.title"), alt: t("meta.ogAlt") };
+});
+
+export const generateImageMetadata = image.generateImageMetadata;
+export default image.render;
+```
+
+The core renders nothing: it returns a JSX tree that `next/og` — which already
+embeds satori — turns into a PNG at build time, so nothing installs a second
+renderer and a card can be unit-tested with no framework build. It also packs
+the `favicon.ico` **no Next convention emits**, guarded so that a generated file
+living in git is not dirtied by every commit. API reference in
+[`packages/og/README.md`](packages/og/README.md).
 
 ## Develop locally
 
@@ -667,8 +727,28 @@ eslint once at the root and then fans out to any package that defines its own
 across workspace packages with `pnpm -r`. To work on one package, filter:
 `pnpm --filter @goflag/cli test`.
 
-The engine is framework-agnostic and lives in [`packages/cli/src/lib/core/`](packages/cli/src/lib/core) (crawl, fetch/extract, link audit, i18n) and [`packages/cli/src/lib/rules/`](packages/cli/src/lib/rules) (SEO checks). The CLI shell — orchestration, the `GoflagReport` schema, and rendering — lives in [`packages/cli/src/report/`](packages/cli/src/report) and [`packages/cli/src/cli.ts`](packages/cli/src/cli.ts).
+The engine is framework-agnostic and lives in [`packages/cli/src/lib/core/`](https://github.com/tancredesimonin/goflag/tree/main/packages/cli/src/lib/core) (crawl, fetch/extract, link audit, i18n) and [`packages/cli/src/lib/rules/`](https://github.com/tancredesimonin/goflag/tree/main/packages/cli/src/lib/rules) (SEO checks). The CLI shell — orchestration, the `GoflagReport` schema, and rendering — lives in [`packages/cli/src/report/`](https://github.com/tancredesimonin/goflag/tree/main/packages/cli/src/report) and [`packages/cli/src/cli.ts`](https://github.com/tancredesimonin/goflag/blob/main/packages/cli/src/cli.ts).
+
+## Contributing
+
+GitHub is a read-only mirror; the canonical repository and the CI are on GitLab,
+so a pull request opened here cannot be merged. **Issues are the useful thing to
+open on GitHub** — a wrong finding especially, which is the class of bug handled
+first. [CONTRIBUTING.md](https://github.com/tancredesimonin/goflag/blob/main/CONTRIBUTING.md)
+has the whole story, including what makes a report reproducible and what a rule
+proposal needs. Vulnerabilities go to <hello@goflag.tech> rather than to an
+issue — see
+[SECURITY.md](https://github.com/tancredesimonin/goflag/blob/main/SECURITY.md).
 
 ## License
 
 MIT.
+
+## Learn more
+
+- Strategy and goals: [STRATEGY.md](https://github.com/tancredesimonin/goflag/blob/main/STRATEGY.md)
+- What comes next: [ROADMAP.md](https://github.com/tancredesimonin/goflag/blob/main/ROADMAP.md)
+- Working in this repository (human or agent): [AGENTS.md](https://github.com/tancredesimonin/goflag/blob/main/AGENTS.md)
+- The overall development plan: [docs/spec-and-lib-plan.md](https://github.com/tancredesimonin/goflag/blob/main/docs/spec-and-lib-plan.md)
+- The rule catalogue and its architecture: [docs/rules-catalog-plan.md](https://github.com/tancredesimonin/goflag/blob/main/docs/rules-catalog-plan.md)
+- Publishing `@goflag/next`: [docs/publishing.md](https://github.com/tancredesimonin/goflag/blob/main/docs/publishing.md)