@forsvn/metaprev 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+## 0.5.0 — 2026-08-23
+
+### Added
+- Responsive local repair workspace with separate Open Graph and X input resolution, representative platform cards, source-fallback labels, and cover-versus-fit crop inspection.
+- Actionable issue objects with stable `code`, `impact`, `evidence`, and `fix` fields. Existing `level`, `field`, and `message` JSON keys remain compatible.
+- Reviewable, copy-ready metadata starting point, repair brief, and guarded coding-agent prompt. Missing facts remain explicit comments instead of invented values.
+- `og:type`, `og:image:alt`, and `twitter:image:alt` parsing, plus validation for required Open Graph fields and image alternative text.
+- Focused local HTTP, CLI exit-code, fallback, render, crop, and injection regression coverage.
+
+### Changed
+- Removed generic title and description length advice. metaprev now reports observed breakage and compatibility risk instead of encouraging padded copy.
+- Image guidance now cites first-party Open Graph and LinkedIn requirements. File-size warnings use LinkedIn's documented 5 MB sharing-module limit.
+- A distinct `twitter:image` is fetched only for the interactive preview. Scoped and JSON commands keep the single-image, non-base64 path.
+- Full-preview `--json` now follows the CI exit contract (`1` when the report contains errors), and JSON paths flush stdout before returning so large reports stay complete.
+- Non-success and explicitly non-HTML page responses are runtime failures (exit `2`) instead of producing misleading missing-tag reports.
+- Platform cards are labeled as representative because experiments, viewport differences, and caches can change the final unfurl.
+
+### Security
+- Generated reports use a per-report Content Security Policy nonce, escape all page-controlled values, admit only strict raster data URIs into image styles, and never embed SVG.
+- Image probes reject non-HTTP(S) protocols before fetching. Repair snippets leave localhost and private-network URLs as review comments instead of presenting them as public metadata.
+- Multi-image parsing keeps structured width, height, and alt evidence attached to the selected first `og:image`.
+
+## 0.4.1 — 2026-05-29
+
+### Changed
+- Upgraded `image-size` to v2 (ESM, smaller); the named `imageSize(buf)` import is unchanged.
+- Bundled agent skill (`skills/metaprev/`) updated for 0.4.0 — light/dark toggle, content-type / SVG checks, 2026-accurate platform mocks.
+
+### Docs
+- Rewrote the README around the tool's value propositions ("What you get"), with a numbered quick-start, a Troubleshooting section (bun-missing, self-signed TLS, timeouts), and a Contributing & release section.
+
+## 0.4.0 — 2026-05-29
+
+### Added
+- **Light / dark preview toggle** in the HTML report — see how the card renders in each platform's actual light *and* dark theme (Facebook, X, LinkedIn, Discord).
+- `og:image` content-type checks: warns when the image is an **SVG** (Facebook, X, and LinkedIn don't render SVG share images) and errors when a **non-image** response also fails to decode as an image (catches an `og:image` pointing at an HTML/error page that returns 200; a real image served as `application/octet-stream` still passes).
+- "Copy" on the parsed-meta panel, alongside the existing issues copy.
+- Test suite (`bun test`) covering parsing, validation, and rendering.
+
+### Fixed
+- **Entity decoding** now handles numeric (`’`), hex (`❤`), and common named (`—`, `…`) references. Char-count validation was previously inflated by raw entities (e.g. `Ben & Jerry’s` measured 19 chars instead of 13) and cards/facts showed raw entity text.
+- **Double-escaped** values in the parsed-meta panel (`&`) now render correctly.
+- **Hardened the preview against CSS injection** — only the validated, locally-fetched image data URI is ever placed into a CSS `url()`; a failed image probe shows a placeholder instead of injecting the remote (page-controlled) URL into inline styles.
+
+### Changed
+- Redesigned the HTML preview: OKLCH design tokens, sharper type hierarchy, platform-accurate card mocks updated for 2026 (X shows image + domain overlay with no body text; LinkedIn drops the in-feed description; Discord auto-embeds render without a color bar), full mobile responsiveness, and `prefers-reduced-motion` support.
+- Faster non-preview runs: `issues` / `facts` / `--json` no longer base64-encode the image. Page (4 MB) and image (32 MB) downloads are now size-capped against hostile/misconfigured responses, and timeouts report a clear `timed out after Ns` message.
+
+## 0.3.2 — 2026-05-12
+
+### Fixed
+- `metaprev --version` now matches the published package version.
+- Shared byte formatting between terminal and HTML output so image byte display stays consistent.
+
+### Compared to 0.3.1
+- Publish-ready maintenance release for the cleanup pass.
+
+## 0.3.0 — 2026-05-11
+
+### Fixed
+- `og:image:width`/`og:image:height` now validates against actual image dimensions. Warns when declared dimensions don't match real file dimensions — Slack and Discord trust the declared values for first-paint and will mis-crop when they don't match.
+
+### Compared to 0.2.0
+- `src/validate.ts`: +18 lines — new dimension consistency check
+
+## 0.2.0 — 2025-11-19
+
+### Added
+- `issues` subcommand — CI-friendly, exits 1 on errors, no browser
+- `facts` subcommand — raw parsed meta, plain or JSON
+- `data-URI` cache-bust — og:image embedded as base64 so regenerating the asset always shows the fresh image
+- Auto-relax TLS for `*.localhost` / `*.test` / `127.0.0.1` (`--insecure` still available)
+- Framework-agnostic defaults (no hardcoded og:type)
+
+## 0.1.0 — 2025-09-27
+
+### Added
+- Core preview: fetches URL, parses og:* / twitter:* meta, validates char counts and image dimensions, opens side-by-side mock for Facebook, X, LinkedIn, Discord/Slack
+- `-o, --output` flag to write preview HTML to a specific path
+- `--no-open` and `--json` flags
+- `image-size` dep for PNG/JPEG/WebP dimension reading

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Le Vinh Hung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# metaprev
+
+[![skills.sh](https://skills.sh/b/forsvn-labs/metaprev)](https://skills.sh/forsvn-labs/metaprev)
+
+![metaprev demo](https://github.com/forsvn-labs/metaprev/raw/main/demo.gif)
+
+**Inspect how your share metadata is likely to render — locally, before you ship.**
+
+Broken share cards are invisible until they're live. The page looks fine; the link looks broken — a blank thumbnail, the wrong image, or a damaging crop — and you only find out after sharing it. metaprev fetches your URL, parses its Open Graph and X metadata, validates the selected asset, and opens a local repair workspace with representative **Facebook**, **X**, **LinkedIn**, and **Discord** cards. Its fallback inspection also covers the common Open Graph and X metadata used by [Slack classic unfurls](https://api.slack.com/reference/messaging/link-unfurling).
+
+No account, no upload, no copy-pasting into a third-party debugger. Point it at your local dev server (any framework — Next, Astro, Vite, SvelteKit, Bun.serve, Rails, Django…) or a deployed page.
+
+```bash
+npx @forsvn/metaprev https://your-site.com
+npx @forsvn/metaprev http://localhost:3000   # your dev server, whatever the port
+```
+
+## What you get
+
+- **Platform-aware, without fake certainty.** The workspace separates Open Graph values from X-specific overrides and labels every fallback it used. The mocks are representative: platform experiments, viewport changes, and cached unfurls can still differ.
+- **Light and dark inspection.** A toggle lets you check the same inputs against representative light and dark card treatments.
+- **Crop evidence, not guesswork.** Cover and fit views place the fetched asset in the same 1.91:1 frame, show decoded dimensions and byte size, and estimate which edges a centered cover crop hides.
+- **What you validated is what you saw.** The `og:image` is fetched and embedded as a data URI in the preview, so regenerating your asset never shows a stale, browser-cached image.
+- **Catches silent breaks.** A relative `og:image` such as `/og.png` is not a valid Open Graph URL and can fail when a crawler fetches the asset. metaprev flags that plus broken or missing images, harmful crops, oversized files, non-image or SVG responses, and declared dimensions that do not match the decoded file.
+- **Runs where you work.** Against `localhost` on any framework and port, before you deploy — somewhere OpenGraph.xyz, metatags.io, and the Facebook Debugger can't reach.
+- **CI-ready.** Exit codes (`0` clean / `1` error / `2` fetch failure) plus `--json` and scoped `issues` / `facts` subcommands let you fail a build the moment a share card breaks.
+- **Actionable findings.** Every issue has a stable code plus impact, observed evidence, and a concrete fix. Errors come first; warnings and notes cannot bury them.
+- **Copy-ready repair output.** Review and copy a safe metadata starting point, an evidence-led repair brief, or a guarded prompt for a coding agent. Missing facts and local-only URLs stay explicit comments instead of becoming invented public metadata.
+- **Safer local reports.** Page values are escaped, image probes accept only HTTP(S), only validated raster data URIs enter image styles, SVG is never embedded, and a per-report CSP nonce limits script execution.
+- **Tiny and fast.** One dependency, no network round-trip to a third party, instant open.
+- **Teaches your AI agent.** Ships a [skill](#agent-skill) so coding agents reach for metaprev (not a third-party validator) and know which warnings to ignore.
+
+## Quick start
+
+1. **Run it against your page** — a local dev server or a deployed URL:
+   ```bash
+   npx @forsvn/metaprev http://localhost:3000
+   ```
+   Requires `bun` on PATH ([install](https://bun.sh/install)); the package ships TypeScript and runs it via Bun.
+2. **Read the terminal summary.** You get the resolved title, description, `og:image`, image dimensions, and the issues found — errors first, then warnings, then info.
+3. **Open the workspace.** Compare platform inputs, cover-versus-fit crop, prioritized validation, parsed facts, resolved fallbacks, and repair output in one responsive report.
+4. **Fix what's flagged and re-run.** The exit code stays `1` while any error remains and drops to `0` once the card is clean — so the same command works as a pre-ship check.
+
+## What it checks
+<!-- synced: 2026-08-23 -->
+
+| Check | Why |
+|---|---|
+| Share title and description | Errors only when no usable value exists; metaprev does not pad copy to generic SEO character targets |
+| Required Open Graph fields | Flags a missing `og:title`, `og:type`, `og:image`, or canonical share URL with the exact fallback observed |
+| `og:image` is absolute URL | Crawlers fetch the URL standalone and fail on relative paths |
+| `og:image` returns a successful response | Catches stale or wrong URLs |
+| `og:image` content-type | Errors when a non-image response cannot be decoded; warns on SVG and never embeds it in the report |
+| Image dimensions and crop | Uses a 1200×630 (1.91:1) workspace target; LinkedIn documents 1200×627 for its sharing module |
+| Image file size | Warns above LinkedIn's documented 5 MB sharing-module limit |
+| `og:image:width` / `:height` | Shows whether declared dimensions match the decoded asset |
+| `og:image:alt` | Notes when the image lacks the description recommended by the Open Graph protocol |
+| `twitter:card` | Distinguishes `summary_large_image` from the compact `summary` treatment |
+| `og:url` / canonical | Helps platforms dedupe shares |
+
+Three severity levels: **error** (broken input), **warn** (real compatibility or presentation risk), and **info** (standards or resilience improvement). Each issue in text and JSON includes `level`, `code`, `field`, `message`, `impact`, `evidence`, and `fix`. The original `level` / `field` / `message` keys remain available for existing scripts.
+
+The rules use the [Open Graph protocol](https://ogp.me/) and current [LinkedIn sharing requirements](https://www.linkedin.com/help/linkedin/answer/a521928) for factual requirements. The report says when a card is representative rather than presenting a mock as a guaranteed platform screenshot.
+
+## Install
+
+Run via `npx` (no install):
+
+```bash
+npx @forsvn/metaprev <url>
+```
+
+Or install globally for instant repeat runs:
+
+```bash
+bun add -g @forsvn/metaprev
+# or
+npm install -g @forsvn/metaprev
+```
+
+Requires `bun` on PATH ([install](https://bun.sh/install)) — the package ships TypeScript source and runs it via Bun.
+
+## Usage
+
+```bash
+metaprev                                 # no URL → show help
+metaprev http://localhost:3000           # check your local dev server (any port, any framework)
+metaprev https://forsvn.com              # check a deployed page
+metaprev https://forsvn.com --json       # CI-friendly JSON output
+metaprev https://forsvn.com --no-open    # don't auto-open the preview
+metaprev https://forsvn.com -o ./og.html # write the preview to a specific path
+
+# Subcommands — same data, no browser, scoped output
+metaprev issues http://localhost:3000    # just the issue list (exits 1 on errors — CI-friendly)
+metaprev facts  https://forsvn.com       # just the parsed meta facts (title, dims, bytes, etc.)
+metaprev facts  https://forsvn.com --json # pipe parsed meta into another tool
+```
+
+## Options
+
+| Flag | Effect | Default |
+|---|---|---|
+| `-o, --output <file>` | Write preview HTML to `<file>` (preview command only) | a temp file |
+| `--no-open` | Don't auto-open the preview in your browser | opens |
+| `--json` | Print machine-readable JSON to stdout (implies `--no-open`) | off |
+| `-k, --insecure` | Skip TLS verification | auto-on for `*.localhost` / `*.test` / `127.0.0.1` |
+| `-v, --version` | Print version | — |
+| `-h, --help` | Show help | — |
+
+## Exit codes
+<!-- synced: 2026-08-23 -->
+
+- `0` — no errors (warnings allowed)
+- `1` — at least one error-level issue (broken image, missing `og:image`, etc.)
+- `2` — fetch/runtime failure or usage error (unknown flags fail instead of being ignored)
+
+Exception: `facts` always exits `0` once a report was produced. It is a diagnostic
+dump for pipelines, not a CI gate — use `issues` or the default command when you
+need the exit code to reflect findings.
+
+Useful in CI — fail the build when a share card breaks:
+
+```bash
+npx @forsvn/metaprev issues https://staging.example.com --json || exit 1
+```
+
+## Troubleshooting
+
+- **`metaprev: requires bun on PATH` (exit 127).** The package runs its TypeScript via Bun. Install Bun: `curl -fsSL https://bun.sh/install | bash`, then re-run.
+- **`failed to fetch … self-signed certificate` (exit 2).** A staging server with a self-signed cert. Re-run with `--insecure`. (It's auto-on for `*.localhost`, `*.test`, and `127.0.0.1`.)
+- **`timed out after 10s` (exit 2).** The page or image didn't respond in time — check the server is up and the URL is reachable from your machine.
+- **The card looks right in metaprev but stale on a platform.** metaprev validates the source response, not platform caches. Use the platform's own refresh or inspection tool where one exists, such as the [Facebook Sharing Debugger](https://developers.facebook.com/tools/debug/) or [LinkedIn Post Inspector](https://www.linkedin.com/post-inspector/).
+
+## Agent skill
+
+This repo ships a skill at [`skills/metaprev/`](./skills/metaprev/) that teaches coding agents to run the local validator, interpret impact/evidence/fix findings, respect metadata fallbacks, and reject generic SEO padding or invented calls to action.
+
+Install via the [skills](https://skills.sh) CLI:
+
+```bash
+# Globally — available across all projects
+npx skills add forsvn-labs/metaprev -g
+
+# Or per-project — committed with your repo, shared with your team
+npx skills add forsvn-labs/metaprev
+```
+
+Works with Claude Code, Cursor, Codex, OpenCode, and other agents supported by the [skills CLI](https://github.com/vercel-labs/skills#supported-agents).
+
+## Contributing & release
+<!-- synced: 2026-08-23 -->
+
+```bash
+bun install
+bun test            # parse / validate / render regressions
+bun run typecheck   # bunx tsc --noEmit
+bun run dev <url>   # run the CLI from source
+```
+
+Before publishing, sync `version` in `package.json` with `VERSION` in `bin/metaprev.ts`, then:
+
+```bash
+bun run typecheck
+npm pack --dry-run
+npm publish --access public
+```
+
+If npm 11 reports `Invalid time value` / `before=null`, check that any user-level `min-release-age` config is numeric seconds, not shorthand like `3d`.
+
+## License
+
+MIT © Le Vinh Hung

package/bin/metaprev.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// Thin shim: npm needs a recognized extension for `bin` entries, so this .mjs
+// stub launches the actual Bun-based TypeScript entry (bin/metaprev.ts).
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const entry = resolve(here, "metaprev.ts");
+const bun = process.env.METAPREV_BUN || "bun";
+
+const child = spawn(bun, [entry, ...process.argv.slice(2)], { stdio: "inherit" });
+
+child.on("error", (err) => {
+  if (err && err.code === "ENOENT") {
+    console.error("metaprev: requires `bun` on PATH (https://bun.sh/install).");
+    process.exit(127);
+  }
+  console.error("metaprev: failed to spawn bun:", err.message);
+  process.exit(1);
+});
+child.on("exit", (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 1);
+});

package/bin/metaprev.ts

@@ -0,0 +1,353 @@
+#!/usr/bin/env bun
+import { spawn } from 'node:child_process'
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fetchPage, isLocalUrl, probeImage } from '../src/fetch.ts'
+import { resolvePrimaryInput } from '../src/inputs.ts'
+import { formatBytes } from '../src/format.ts'
+import { parseMeta } from '../src/parse.ts'
+import { renderHtml } from '../src/render.ts'
+import type { ImageProbe, Report } from '../src/types.ts'
+import { validate } from '../src/validate.ts'
+
+type Cmd = 'preview' | 'issues' | 'facts'
+type Issue = Report['issues'][number]
+type IssueLevel = Issue['level']
+
+type Opts = {
+  cmd: Cmd
+  url: string
+  output?: string
+  open: boolean
+  json: boolean
+  help: boolean
+  insecure: boolean
+}
+
+const VERSION = '0.5.0'
+const SUBCOMMANDS = new Set<Cmd>(['issues', 'facts'])
+const ISSUE_TAGS: Record<IssueLevel, string> = {
+  error: 'ERR',
+  warn: 'WRN',
+  info: 'INF',
+}
+
+function parseArgs(argv: string[]): Opts {
+  const opts: Opts = {
+    cmd: 'preview',
+    url: '',
+    open: true,
+    json: false,
+    help: false,
+    insecure: false,
+  }
+  const positional: string[] = []
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    switch (a) {
+      case '-h':
+      case '--help':
+        opts.help = true
+        break
+      case '-v':
+      case '--version':
+        console.log(VERSION)
+        process.exit(0)
+        break
+      case '--no-open':
+        opts.open = false
+        break
+      case '--json':
+        opts.json = true
+        opts.open = false
+        break
+      case '-k':
+      case '--insecure':
+        opts.insecure = true
+        break
+      case '-o':
+      case '--output':
+        opts.output = argv[++i]
+        break
+      default:
+        if (a && !a.startsWith('-')) {
+          positional.push(a)
+          break
+        }
+        // Unknown flags are user errors — fail loudly instead of silently ignoring.
+        console.error(`metaprev: unknown option '${a}'`)
+        console.error('  run `metaprev --help` to see available options')
+        process.exit(2)
+    }
+  }
+  if (positional[0] && SUBCOMMANDS.has(positional[0] as Cmd)) {
+    opts.cmd = positional.shift() as Cmd
+  }
+  if (positional[0]) opts.url = positional[0]
+  if (opts.url && !/^https?:\/\//i.test(opts.url)) opts.url = `http://${opts.url}`
+  return opts
+}
+
+function help(): void {
+  console.log(`metaprev v${VERSION} — preview your OpenGraph cards locally
+
+Usage:
+  metaprev <url> [options]              # full preview + browser open
+  metaprev issues <url> [options]       # print just the issues
+  metaprev facts  <url> [options]       # print just the parsed meta facts
+
+Arguments:
+  url                URL to fetch (e.g. https://example.com or http://localhost:3000)
+
+Options:
+  -o, --output FILE  Write the preview HTML to FILE (preview command only)
+  --no-open          Don't auto-open the preview in your browser
+  --json             Print machine-readable JSON to stdout (implies --no-open)
+  -k, --insecure     Skip TLS cert verification (auto-on for *.localhost / *.test / 127.0.0.1)
+  -v, --version      Print version and exit
+  -h, --help         Show this help
+
+Examples:
+  metaprev http://localhost:3000            # check your local dev server
+  metaprev https://hungv.io                 # check a deployed page
+  metaprev issues http://localhost:3000     # quick issue check, no browser
+  metaprev facts https://hungv.io --json    # pipe parsed meta into another tool
+`)
+}
+
+function reportColor(level: IssueLevel): string {
+  if (!process.stdout.isTTY) return ''
+  return level === 'error' ? '\x1b[31m' : level === 'warn' ? '\x1b[33m' : '\x1b[36m'
+}
+
+function reset(): string {
+  return process.stdout.isTTY ? '\x1b[0m' : ''
+}
+
+function bold(s: string): string {
+  return process.stdout.isTTY ? `\x1b[1m${s}\x1b[22m` : s
+}
+
+function dim(s: string): string {
+  return process.stdout.isTTY ? `\x1b[2m${s}\x1b[22m` : s
+}
+
+function green(s: string): string {
+  return process.stdout.isTTY ? `\x1b[32m${s}\x1b[0m` : s
+}
+
+function printTerminal(report: Report): void {
+  const m = report.meta
+  const title = resolvePrimaryInput(m, 'title').value ?? '(none)'
+  const desc = resolvePrimaryInput(m, 'description').value ?? '(none)'
+  console.log()
+  console.log(bold(`metaprev — ${report.finalUrl}`))
+  console.log(dim(`HTTP ${report.status} · fetched ${report.fetchedAt}`))
+  console.log()
+  console.log(`  ${dim('title')}        ${title} ${dim(`(${title.length} chars)`)}`)
+  console.log(`  ${dim('description')}  ${truncate(desc, 100)} ${dim(`(${desc.length} chars)`)}`)
+  console.log(`  ${dim('og:image')}     ${m.ogImage ?? '(none)'}`)
+  if (report.image?.width && report.image?.height) {
+    console.log(`  ${dim('image dims')}   ${report.image.width}×${report.image.height}px`)
+  } else if (report.image?.error) {
+    console.log(`  ${dim('image dims')}   ${reportColor('error')}failed: ${report.image.error}${reset()}`)
+  }
+  console.log()
+  if (report.issues.length === 0) {
+    console.log(`  ${green('✓ no issues — your card is clean.')}`)
+  } else {
+    for (const i of report.issues) {
+      printIssue(i, '  ')
+    }
+  }
+  console.log()
+}
+
+function printIssuesOnly(report: Report): void {
+  if (report.issues.length === 0) {
+    console.log(green('✓ no issues — your card is clean.'))
+    return
+  }
+  for (const i of report.issues) {
+    printIssue(i)
+  }
+}
+
+function printIssue(issue: Issue, indent = ''): void {
+  const tag = ISSUE_TAGS[issue.level]
+  console.log(`${indent}${reportColor(issue.level)}${tag}${reset()} ${dim(issue.field.padEnd(12))} ${issue.message}`)
+  const detailIndent = `${indent}    `
+  console.log(`${detailIndent}${dim('impact')}   ${issue.impact}`)
+  console.log(`${detailIndent}${dim('evidence')} ${issue.evidence}`)
+  console.log(`${detailIndent}${dim('fix')}      ${issue.fix}`)
+}
+
+function printFactsOnly(report: Report): void {
+  const m = report.meta
+  const title = resolvePrimaryInput(m, 'title').value
+  const desc = resolvePrimaryInput(m, 'description').value
+  const rows: Array<[string, string]> = [
+    ['source', report.source],
+    ['final url', report.finalUrl],
+    ['http', String(report.status)],
+    ['title', fmt(title, true)],
+    ['description', fmt(desc, true)],
+    ['og:image', m.ogImage ?? '(none)'],
+    ['image dims', report.image?.width && report.image?.height ? `${report.image.width}×${report.image.height}px` : report.image?.error ? `failed: ${report.image.error}` : '(unknown)'],
+    ['image bytes', report.image?.byteLength != null ? formatBytes(report.image.byteLength) : '(unknown)'],
+    ['twitter:card', m.twitterCard ?? '(none)'],
+    ['og:site_name', m.ogSiteName ?? '(none)'],
+    ['canonical', m.canonical ?? m.ogUrl ?? '(none)'],
+  ]
+  const labelWidth = Math.max(...rows.map((r) => r[0].length))
+  for (const [label, value] of rows) {
+    console.log(`${dim(label.padEnd(labelWidth))}  ${value}`)
+  }
+}
+
+function fmt(s: string | undefined, withCount = false): string {
+  if (!s) return '(none)'
+  return withCount ? `${s} ${dim(`(${s.length} chars)`)}` : s
+}
+
+function truncate(s: string, n: number): string {
+  return s.length > n ? `${s.slice(0, n - 1)}…` : s
+}
+
+function openInBrowser(file: string): void {
+  const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'explorer.exe' : 'xdg-open'
+  try {
+    spawn(cmd, [file], { stdio: 'ignore', detached: true }).unref()
+  } catch {}
+}
+
+// Strip the embedded image bytes from --json output. They're only useful for the
+// HTML preview and would otherwise bloat piped output by ~100KB+.
+function stripDataUri(report: Report): Report {
+  const clean = (probe: ImageProbe | undefined): ImageProbe | undefined => {
+    if (!probe?.dataUri) return probe
+    const image = { ...probe }
+    delete image.dataUri
+    return image
+  }
+  return { ...report, image: clean(report.image), twitterImage: clean(report.twitterImage) }
+}
+
+async function buildReport(opts: Opts): Promise<Report> {
+  const fetchedAt = new Date().toISOString()
+  const page = await fetchPage(opts.url, { insecure: opts.insecure })
+  const meta = parseMeta(page.html)
+  const imageRef = meta.ogImage
+  // The base64 data URI is only embedded in the HTML preview. Skip building it for
+  // issues / facts / --json, where it would be stripped or unused anyway.
+  const withDataUri = opts.cmd === 'preview' && !opts.json
+  const imagePromise = imageRef
+    ? probeImage(imageRef, page.finalUrl, { insecure: opts.insecure, withDataUri })
+    : Promise.resolve(undefined)
+  // A distinct twitter:image affects only the visual X preview. Probe it only for the
+  // browser workspace; scoped and JSON commands keep their original single request.
+  const twitterImagePromise = withDataUri && meta.twitterImage && meta.twitterImage !== meta.ogImage
+    ? probeImage(meta.twitterImage, page.finalUrl, { insecure: opts.insecure, withDataUri: true })
+    : Promise.resolve(undefined)
+  const [image, twitterImage] = await Promise.all([imagePromise, twitterImagePromise])
+  const issues = validate(meta, image)
+  return {
+    source: opts.url,
+    fetchedAt,
+    finalUrl: page.finalUrl,
+    status: page.status,
+    meta,
+    image,
+    twitterImage,
+    issues,
+  }
+}
+
+async function main(): Promise<void> {
+  const opts = parseArgs(process.argv.slice(2))
+  if (opts.help) {
+    help()
+    return
+  }
+  if (!opts.url) {
+    // Subcommand with no URL is a user error — scripts that forget to interpolate $URL
+    // should fail loudly, not silently exit 0.
+    if (opts.cmd !== 'preview') {
+      console.error(`metaprev: '${opts.cmd}' needs a URL argument`)
+      console.error(`  example: metaprev ${opts.cmd} https://example.com`)
+      process.exitCode = 2
+      return
+    }
+    help()
+    return
+  }
+  if (opts.output && opts.cmd !== 'preview') {
+    console.error(`metaprev: --output is ignored for '${opts.cmd}' (no preview HTML is generated)`)
+  }
+
+  let report: Report
+  try {
+    report = await buildReport(opts)
+  } catch (err) {
+    const msg = (err as Error).message
+    console.error(`metaprev: failed to fetch ${opts.url}`)
+    console.error(`  ${msg}`)
+    if (/self[ -]?signed|certificate|unable to verify/i.test(msg) && !opts.insecure && !isLocalUrl(opts.url)) {
+      console.error(`  hint: rerun with --insecure to skip TLS verification (auto-on for *.localhost / *.test / 127.0.0.1)`)
+    }
+    process.exitCode = 2
+    return
+  }
+
+  const hasError = report.issues.some((i) => i.level === 'error')
+
+  if (opts.cmd === 'issues') {
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(report.issues, null, 2) + '\n')
+    } else {
+      printIssuesOnly(report)
+    }
+    process.exitCode = hasError ? 1 : 0
+    return
+  }
+
+  if (opts.cmd === 'facts') {
+    if (opts.json) {
+      const facts = {
+        source: report.source,
+        finalUrl: report.finalUrl,
+        status: report.status,
+        meta: report.meta,
+        image: stripDataUri(report).image,
+      }
+      process.stdout.write(JSON.stringify(facts, null, 2) + '\n')
+    } else {
+      printFactsOnly(report)
+    }
+    return
+  }
+
+  // default: full preview
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(stripDataUri(report), null, 2) + '\n')
+    process.exitCode = hasError ? 1 : 0
+    return
+  }
+
+  printTerminal(report)
+
+  const html = renderHtml(report)
+  const outFile = opts.output ?? join(mkdtempSync(join(tmpdir(), 'metaprev-')), 'preview.html')
+  writeFileSync(outFile, html, 'utf8')
+  console.log(`  ${dim('preview →')} ${outFile}`)
+  if (opts.open) openInBrowser(outFile)
+
+  process.exitCode = hasError ? 1 : 0
+}
+
+main().catch((err) => {
+  console.error('metaprev: unexpected error')
+  console.error(err)
+  process.exitCode = 2
+})