@goflag/cli 0.2.11 → 0.2.13

package/README.md

@@ -5,6 +5,12 @@ A CLI that audits a site for broken links, missing translation pages, a robots.t
 [![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)
 
+[![A goflag run against a site with findings: a red verdict over the crawl counts, a COVERAGE line saying how many pages of the sitemap were audited, the tally of broken links, missing translations and SEO issues, then the broken links listed under the page that references them.](https://goflag.tech/assets/hero.png)](https://goflag.tech/docs/report)
+
+<sub>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.</sub>
+
 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
@@ -61,7 +67,7 @@ fine one.
 
 ## Where it runs
 
-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.
+Three packages ship to npm from a tag, published by GitLab CI over OIDC with no stored credential: `@goflag/cli` (`v*`), `@goflag/next` (`next-v*`) and `@goflag/og` (`og-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.
 
 ## Your first audit
 
@@ -130,6 +136,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
@@ -137,7 +156,7 @@ npx @goflag/cli rules > rules.json
 ```
 
 `rules` answers a question about goflag rather than about a site: no URL, no
-crawl, no network. It ships fifty-six rules — twenty-three page rules,
+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
@@ -170,7 +189,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
@@ -431,6 +451,35 @@ 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.
+
+An example of what it writes — a real audit, frozen, so its footer names the date it was
+taken — is served at <https://goflag.tech/assets/example-preview.html>. The URL is absolute
+because `prepack` copies this file into the package and npm renders it, where a relative link
+is dead.
+
 ### Multilingual sites
 
 Discovery is seeded from the sitemap, not just from links. That matters because
@@ -509,7 +558,7 @@ Three rules, whichever you use:
 stages: [build, deploy, audit]
 
 variables:
-  GOFLAG_VERSION: "0.2.11"
+  GOFLAG_VERSION: "0.2.13"
 
 # Before the merge: build the branch, let goflag boot it, audit that.
 seo:mr:
@@ -561,7 +610,7 @@ jobs:
       - run: corepack enable && pnpm install --frozen-lockfile
       - run: pnpm build
       - run: |
-          npx --yes @goflag/cli@0.2.11 http://localhost:3000 \
+          npx --yes @goflag/cli@0.2.13 http://localhost:3000 \
             --start "pnpm start" --static --no-external \
             --baseline .goflag/baseline.json --regressions-only --max-debt 41 \
             --report goflag-report.json
@@ -583,6 +632,25 @@ Audit external links on a schedule instead, where nobody is waiting.
 
 ### Reading a red build
 
+A red build says what moved, not what is wrong. The diff lists rule ids and
+absolute page URLs; the messages and the fixes are in the report:
+
+<!-- goflag:transcript gate -->
+
+```plaintext
+goflag --regressions-only
+REGRESSION  1 new · 13 known findings NOT gating this build · 1 resolved
+baseline https://example.com/ — taken 2026-07-21T09:14:02.881Z (14 days ago)
+
+New findings
+  + error seo  canonical.absolute on https://example.com/pricing
+
+Resolved
+  - warn  seo  og.image.missing on https://example.com/about
+```
+
+<!-- /goflag:transcript -->
+
 The report artefact is the thing to open. It is the same JSON as `--json`, and
 it is kept whether the job passed or failed, because it is most wanted when it
 is red.
@@ -645,7 +713,7 @@ finding unrepresentable. Full documentation at
 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.
+becomes permanent debt. [`@goflag/og`](https://github.com/tancredesimonin/goflag/tree/main/packages/og) is that route, written once.
 
 ```tsx
 // app/[locale]/opengraph-image.tsx
@@ -663,7 +731,7 @@ 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).
+[`packages/og/README.md`](https://github.com/tancredesimonin/goflag/blob/main/packages/og/README.md).
 
 ## Develop locally