ssrwire 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/CHANGELOG.md +45 -1
  2. package/CONTRIBUTING.md +8 -5
  3. package/PUBLISHING.md +92 -78
  4. package/README.md +117 -28
  5. package/SECURITY.md +8 -4
  6. package/dist/analyze.d.ts.map +1 -1
  7. package/dist/analyze.js +162 -6
  8. package/dist/analyze.js.map +1 -1
  9. package/dist/audit.d.ts.map +1 -1
  10. package/dist/audit.js +82 -7
  11. package/dist/audit.js.map +1 -1
  12. package/dist/cli.d.ts.map +1 -1
  13. package/dist/cli.js +6 -1
  14. package/dist/cli.js.map +1 -1
  15. package/dist/config.d.ts +1 -0
  16. package/dist/config.d.ts.map +1 -1
  17. package/dist/config.js +11 -0
  18. package/dist/config.js.map +1 -1
  19. package/dist/http-probe.d.ts.map +1 -1
  20. package/dist/http-probe.js +4 -0
  21. package/dist/http-probe.js.map +1 -1
  22. package/dist/index.d.ts +1 -1
  23. package/dist/index.d.ts.map +1 -1
  24. package/dist/index.js.map +1 -1
  25. package/dist/redact.d.ts.map +1 -1
  26. package/dist/redact.js +17 -0
  27. package/dist/redact.js.map +1 -1
  28. package/dist/reporters.d.ts.map +1 -1
  29. package/dist/reporters.js +69 -2
  30. package/dist/reporters.js.map +1 -1
  31. package/dist/social.d.ts +14 -0
  32. package/dist/social.d.ts.map +1 -0
  33. package/dist/social.js +88 -0
  34. package/dist/social.js.map +1 -0
  35. package/dist/stability.d.ts +9 -0
  36. package/dist/stability.d.ts.map +1 -0
  37. package/dist/stability.js +326 -0
  38. package/dist/stability.js.map +1 -0
  39. package/dist/stream-parser.d.ts.map +1 -1
  40. package/dist/stream-parser.js +21 -1
  41. package/dist/stream-parser.js.map +1 -1
  42. package/dist/types.d.ts +47 -0
  43. package/dist/types.d.ts.map +1 -1
  44. package/examples/github-actions.yml +2 -2
  45. package/examples/ssrwire.config.yml +8 -0
  46. package/package.json +5 -2
  47. package/src/analyze.ts +208 -7
  48. package/src/audit.ts +116 -8
  49. package/src/cli.ts +7 -1
  50. package/src/config.ts +12 -0
  51. package/src/http-probe.ts +4 -0
  52. package/src/index.ts +6 -0
  53. package/src/redact.ts +17 -0
  54. package/src/reporters.ts +97 -2
  55. package/src/social.ts +116 -0
  56. package/src/stability.ts +475 -0
  57. package/src/stream-parser.ts +31 -1
  58. package/src/types.ts +62 -0
package/CHANGELOG.md CHANGED
@@ -5,6 +5,48 @@ All notable changes to SSRWire are documented here. The project follows
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [0.3.0] - 2026-08-28
9
+
10
+ ### Added
11
+
12
+ - Streamed capture for core Open Graph and Twitter Card metadata with arrival
13
+ time, observed byte position, document location, bounded repeated values, and
14
+ report redaction.
15
+ - Opt-in `require.openGraph` and `require.twitterCard` target contracts with
16
+ missing-field, invalid-URL, duplicate/conflict, and head/body delivery
17
+ findings.
18
+ - A terminal social-preview readiness table and public social metadata signal
19
+ types in JSON and the programmatic API.
20
+
21
+ ### Changed
22
+
23
+ - Enabled social contracts now participate in required-signal timing,
24
+ cross-agent comparison, and repeated-sample stability analysis.
25
+ - Twitter Card readiness prefers native Twitter metadata and falls back to the
26
+ corresponding Open Graph title, description, and image.
27
+ - Multiple `og:image` values are retained in document order without being
28
+ treated as conflicting scalar metadata.
29
+
30
+ ## [0.2.0] - 2026-08-24
31
+
32
+ ### Added
33
+
34
+ - Bounded `repeat` configuration and `--repeat` CLI sampling for 1–10 requests
35
+ per target-agent pair.
36
+ - Per-agent minimum, median, nearest-rank p95, maximum, and spread summaries for
37
+ response-header, first-byte, required-signal, and completion timings.
38
+ - Response and streamed-HTML stability findings across repeated samples.
39
+ - Sample attribution in terminal and JSON reports.
40
+
41
+ ### Changed
42
+
43
+ - Added an npm package badge to the README.
44
+ - Samples for one target-agent pair run sequentially while independent pairs
45
+ retain bounded concurrency.
46
+ - Repeated policy findings are coalesced with occurrence and sample evidence.
47
+ - Exact body-fingerprint variation alone is informational; timing variation
48
+ alone remains evidence rather than a policy failure.
49
+
8
50
  ## [0.1.0] - 2026-08-22
9
51
 
10
52
  ### Added
@@ -16,5 +58,7 @@ All notable changes to SSRWire are documented here. The project follows
16
58
  - Terminal, JSON, and SARIF reports with CI-safe exit codes.
17
59
  - YAML configuration, one-off URL checks, Docker support, and GitHub Actions examples.
18
60
 
19
- [Unreleased]: https://github.com/lame13/ssrwire/compare/v0.1.0...HEAD
61
+ [Unreleased]: https://github.com/lame13/ssrwire/compare/v0.3.0...HEAD
62
+ [0.3.0]: https://github.com/lame13/ssrwire/compare/v0.2.0...v0.3.0
63
+ [0.2.0]: https://github.com/lame13/ssrwire/compare/v0.1.0...v0.2.0
20
64
  [0.1.0]: https://github.com/lame13/ssrwire/releases/tag/v0.1.0
package/CONTRIBUTING.md CHANGED
@@ -28,7 +28,9 @@ Keep each change narrow. Include tests for behavior changes, especially for:
28
28
  - response chunk boundaries and elements split across chunks;
29
29
  - redirects, timeouts, aborted bodies, and size limits;
30
30
  - malformed, duplicated, late, or body-located metadata;
31
+ - Open Graph and Twitter Card requirements, fallbacks, arrays, and URL values;
31
32
  - user-agent differences and comparison findings;
33
+ - repeated-sample ordering, aggregation, and instability classification;
32
34
  - redaction of configured header values;
33
35
  - terminal, JSON, SARIF, and exit-code behavior.
34
36
 
@@ -39,11 +41,12 @@ positions instead.
39
41
 
40
42
  ## Scope
41
43
 
42
- SSRWire is an HTTP stream observer, not a browser, crawler, packet capture,
43
- performance benchmark, or framework plugin. New features should preserve that
44
- boundary. In particular, avoid conclusions that claim to reveal the server's
45
- original flush calls: proxies, compression, TLS, HTTP stacks, and client
46
- buffering can coalesce data before SSRWire sees it.
44
+ SSRWire is an HTTP stream observer and bounded consistency sampler, not a
45
+ browser, crawler, packet capture, load generator, performance benchmark, or
46
+ framework plugin. New features should preserve that boundary. In particular,
47
+ avoid conclusions that claim to reveal the server's original flush calls:
48
+ proxies, compression, TLS, HTTP stacks, and client buffering can coalesce data
49
+ before SSRWire sees it.
47
50
 
48
51
  By contributing, you agree that your contribution is licensed under the MIT
49
52
  License.
package/PUBLISHING.md CHANGED
@@ -1,109 +1,124 @@
1
- # Publish SSRWire from a local machine
1
+ # Publish SSRWire 0.3.0 from a local machine
2
2
 
3
- This repository intentionally includes no npm publishing workflow. Every npm
4
- release is published from a local interactive terminal after GitHub CI passes.
5
- Do not configure an `NPM_TOKEN`, trusted publisher, OIDC identity, or automated
6
- release workflow for npm publication.
3
+ This repository intentionally includes no npm publishing workflow. Publish from
4
+ a foreground local terminal only after the GitHub `CI` workflow passes. Do not
5
+ configure an `NPM_TOKEN`, trusted publisher, OIDC identity, or automated npm
6
+ release job.
7
7
 
8
- ## 1. Prepare and verify
8
+ The `main` branch is protected. Land every release change through a pull
9
+ request, and do not use an administrator bypass or a direct push to `main`.
9
10
 
10
- From the extracted archive:
11
+ ## 1. Update the existing repository
12
+
13
+ Work from a clean clone of the existing public repository. Copy the 0.3.0
14
+ source files into that clone while preserving its `.git` directory.
11
15
 
12
16
  ```bash
13
- unzip ssrwire.zip # skip when already inside a source checkout
14
17
  cd ssrwire
18
+ git switch main
19
+ git pull --ff-only origin main
20
+ git status --short
21
+ git switch -c release/0.3.0
22
+ ```
23
+
24
+ `git status --short` must be empty before creating the release branch and
25
+ applying the release files.
26
+
27
+ ## 2. Verify the release locally
28
+
29
+ ```bash
15
30
  nvm use 24
16
31
  node --version
17
32
  npm --version
18
33
  npm ci
19
34
  npm run check
20
35
  npm pack --dry-run
36
+ node dist/bin.js --version
21
37
  ```
22
38
 
23
- Install and authenticate GitHub CLI if needed:
24
-
25
- ```bash
26
- brew install gh
27
- gh auth login -h github.com --web
28
- gh auth status -h github.com
29
- ```
39
+ The final command must print `0.3.0`. Inspect the dry-run file list. It must not
40
+ contain `.env`, `.github`, `node_modules`, `test`, ZIP files, or tarballs.
30
41
 
31
- ## 2. Create the Git history
42
+ Review the release diff and version references:
32
43
 
33
44
  ```bash
34
- git init -b main
35
- git add -- \
36
- .dockerignore .editorconfig .env.example .github .gitignore \
37
- CHANGELOG.md CONTRIBUTING.md Dockerfile LICENSE PUBLISHING.md README.md SECURITY.md \
38
- biome.json examples package.json package-lock.json scripts src test \
39
- tsconfig.build.json tsconfig.json vitest.config.ts
40
- git commit -m "Initial SSRWire release"
45
+ git diff --check
46
+ git diff --stat
47
+ git diff -- package.json package-lock.json CHANGELOG.md README.md PUBLISHING.md
48
+ rg '0\.2\.0' README.md examples package.json package-lock.json scripts src test
41
49
  ```
42
50
 
43
- ## 3. Create and push the public repository
51
+ The final search should return nothing. Historical entries in `CHANGELOG.md`
52
+ are excluded intentionally.
53
+
54
+ ## 3. Commit, push the release branch, and open a pull request
44
55
 
45
56
  ```bash
46
- gh repo create lame13/ssrwire \
47
- --public \
48
- --source=. \
49
- --remote=origin \
50
- --push \
51
- --description "Inspect streamed SSR HTML, metadata timing, and crawler-specific delivery from the command line." \
52
- --homepage "https://nikom.work"
57
+ gh auth status -h github.com || gh auth login -h github.com --web
58
+ git add --all
59
+ git diff --cached --check
60
+ git diff --cached --stat
61
+ git commit -m "feat: release SSRWire 0.3.0"
62
+ git push --set-upstream origin release/0.3.0
63
+ gh pr create --base main --head release/0.3.0 --fill
64
+ PR_NUMBER="$(gh pr view release/0.3.0 --json number --jq .number)"
65
+ test -n "$PR_NUMBER"
66
+ gh pr checks "$PR_NUMBER" --watch --fail-fast
53
67
  ```
54
68
 
55
- ## 4. Add repository topics
69
+ Do not merge while any Node, package-smoke, or Docker job is failing. Satisfy
70
+ all review and branch-protection requirements, then merge with GitHub's allowed
71
+ strategy. Running `gh pr merge "$PR_NUMBER"` without a strategy flag lets the
72
+ CLI prompt for one of the repository's permitted methods. Do not select an
73
+ administrator bypass.
56
74
 
57
75
  ```bash
58
- gh repo edit lame13/ssrwire \
59
- --add-topic technical-seo \
60
- --add-topic seo \
61
- --add-topic ssr \
62
- --add-topic streaming-html \
63
- --add-topic nextjs \
64
- --add-topic nuxt \
65
- --add-topic astro \
66
- --add-topic crawler \
67
- --add-topic typescript \
68
- --add-topic cli \
69
- --add-topic seo-tools \
70
- --add-topic github-actions \
71
- --add-topic sarif
76
+ gh pr merge "$PR_NUMBER"
72
77
  ```
73
78
 
74
- Enable the private vulnerability-reporting channel referenced by
75
- `SECURITY.md` (this requires repository admin permission):
79
+ After GitHub reports the pull request as merged, update local `main` and wait
80
+ for the CI run on the exact merged commit:
76
81
 
77
82
  ```bash
78
- gh api --method PUT repos/lame13/ssrwire/private-vulnerability-reporting
83
+ git switch main
84
+ git pull --ff-only origin main
85
+ git status --short
86
+ gh pr view "$PR_NUMBER" --json state,mergedAt,mergeCommit
87
+ COMMIT_SHA="$(git rev-parse HEAD)"
88
+ RUN_ID="$(gh run list --workflow CI --branch main --commit "$COMMIT_SHA" \
89
+ --limit 1 --json databaseId --jq '.[0].databaseId')"
90
+ test -n "$RUN_ID"
91
+ gh run watch "$RUN_ID" --exit-status
79
92
  ```
80
93
 
81
- Alternatively, enable **Private vulnerability reporting** in the repository's
82
- Settings → Security settings before publishing the first release.
94
+ `git status --short` must be empty. Do not publish until the merged-commit CI
95
+ run succeeds.
83
96
 
84
- Recommended repository description:
97
+ ## 4. Verify npm state
85
98
 
86
- > Inspect streamed SSR HTML, metadata timing, and crawler-specific delivery from the command line.
99
+ ```bash
100
+ npm view ssrwire version dist-tags homepage keywords repository.url --json
101
+ npm config get registry
102
+ npm config get provenance
103
+ ```
87
104
 
88
- Wait for the repository's `CI` workflow to pass before publishing.
105
+ The published version and `latest` tag must still be `0.2.0`. If npm already
106
+ reports `0.3.0`, stop: never reuse a version that npm accepted.
89
107
 
90
- ## 5. Publish version 0.1.0 to npm locally
108
+ In the npm package settings, select **Require two-factor authentication and
109
+ disallow tokens**. npm documents this as the strongest package publishing
110
+ setting:
91
111
 
92
- Verify the release from a clean checkout before starting npm's short-lived
93
- authenticated session:
112
+ - <https://docs.npmjs.com/requiring-2fa-for-package-publishing-and-settings-modification/>
113
+ - <https://docs.npmjs.com/about-two-factor-authentication/>
94
114
 
95
- ```bash
96
- npm ci
97
- npm run check
98
- npm pack --dry-run
99
- npm view ssrwire
100
- ```
115
+ ## 5. Publish interactively
101
116
 
102
- For the first release, `npm view` returning a 404 means the name is not
103
- currently published. Start authentication only after verification so the
104
- session remains fresh for publication:
117
+ Remove inherited automation credentials before starting the interactive
118
+ session:
105
119
 
106
120
  ```bash
121
+ unset NODE_AUTH_TOKEN NPM_TOKEN NPM_CONFIG_OTP npm_config_otp
107
122
  npm login --auth-type=web --registry=https://registry.npmjs.org
108
123
  npm whoami --registry=https://registry.npmjs.org
109
124
  npm publish --access public --registry=https://registry.npmjs.org
@@ -111,24 +126,23 @@ npm view ssrwire version dist-tags homepage keywords repository.url --json
111
126
  npm logout --registry=https://registry.npmjs.org
112
127
  ```
113
128
 
114
- Run login and publish in a foreground interactive terminal. Complete npm's
115
- browser, passkey, or two-factor-authentication challenge when prompted. Never
116
- put an OTP in a command argument, and do not add an `NPM_TOKEN` to this
117
- repository.
129
+ Complete npm's browser, passkey, or two-factor-authentication challenge when
130
+ prompted. Do not use a token with bypass 2FA, put an OTP in a command argument,
131
+ or add an npm credential to the repository or GitHub Actions. The package-level
132
+ "disallow tokens" setting ensures that publication remains interactive.
118
133
 
119
- If the package is not immediately visible after `npm publish` succeeds, wait
120
- for npm's publish-time scanning to finish instead of publishing the same
121
- version again.
134
+ If npm's publish-time scanning delays package visibility, wait. Do not publish
135
+ `0.3.0` again or change the tag to work around propagation.
122
136
 
123
- After npm confirms `0.1.0`, create the matching source release:
137
+ ## 6. Tag the exact published commit
124
138
 
125
139
  ```bash
126
140
  node scripts/clean.mjs
127
141
  rm -rf node_modules/.vite
128
142
  git status --short
129
- git tag -a v0.1.0 -m "SSRWire v0.1.0"
130
- git push origin v0.1.0
131
- gh release create v0.1.0 --generate-notes --title "SSRWire v0.1.0"
143
+ git tag -a v0.3.0 -m "SSRWire v0.3.0"
144
+ git push origin v0.3.0
145
+ gh release create v0.3.0 --generate-notes --title "SSRWire v0.3.0"
132
146
  ```
133
147
 
134
- `git status --short` must print nothing before tagging the release.
148
+ `git status --short` must print nothing before tagging.
package/README.md CHANGED
@@ -1,16 +1,17 @@
1
1
  # SSRWire
2
2
 
3
3
  [![CI](https://github.com/lame13/ssrwire/actions/workflows/ci.yml/badge.svg)](https://github.com/lame13/ssrwire/actions/workflows/ci.yml)
4
+ [![npm version](https://img.shields.io/npm/v/ssrwire.svg)](https://www.npmjs.com/package/ssrwire)
4
5
  [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
5
6
 
6
- Inspect streamed SSR HTML, metadata timing, and crawler-specific delivery from
7
- the command line.
7
+ Inspect streamed SSR HTML, SEO and social metadata timing, and crawler-specific
8
+ delivery from the command line.
8
9
 
9
10
  SSRWire makes a real HTTP request for each selected user-agent profile, reads
10
- the response incrementally, and records when important SEO signals become
11
- observable to its parser. It reports their elapsed time, observed byte
12
- position, and document location without launching a browser or executing
13
- JavaScript.
11
+ the response incrementally, and records when important SEO and social-preview
12
+ signals become observable to its parser. It reports their elapsed time,
13
+ observed byte position, and document location without launching a browser or
14
+ executing JavaScript.
14
15
 
15
16
  ```bash
16
17
  npx ssrwire https://example.com/product
@@ -24,7 +25,9 @@ Modern SSR output is not always one complete HTML document delivered at once:
24
25
  - a framework may intentionally stream metadata into `<body>` for a capable
25
26
  crawler while blocking for an HTML-limited bot;
26
27
  - browser, search-crawler, and social-crawler user agents may receive different
27
- titles, canonicals, robots directives, redirects, or statuses;
28
+ titles, canonicals, social-preview metadata, robots directives, redirects, or
29
+ statuses;
30
+ - the same URL and user agent may receive inconsistent SSR output between requests;
28
31
  - an interrupted or oversized stream may never deliver the expected elements;
29
32
  - a working hydrated page can hide thin or incomplete source HTML.
30
33
 
@@ -84,13 +87,13 @@ form of `npx ssrwire check URL`.
84
87
 
85
88
  ## What it observes
86
89
 
87
- For each target and agent, SSRWire captures:
90
+ For each target, agent, and configured sample, SSRWire captures:
88
91
 
89
92
  - response status, final URL, redirect chain, and an allowlisted response-header snapshot;
90
93
  - time to response headers, first response-body bytes, and completed body;
91
94
  - total bytes delivered to the stream parser and a body fingerprint;
92
- - title, meta description, canonical, meta robots, H1, first main-content
93
- text, and JSON-LD blocks;
95
+ - title, meta description, canonical, meta robots, Open Graph, Twitter Card,
96
+ H1, first main-content text, and JSON-LD blocks;
94
97
  - elapsed arrival time, observed byte position, and `head`/`body` location for
95
98
  each signal;
96
99
  - clean completion, timeout, network failure, invalid response, or configured
@@ -105,10 +108,15 @@ It then checks:
105
108
  | Missing title | Error |
106
109
  | Missing description, canonical, H1, or main text | Warning |
107
110
  | Duplicate or conflicting title, description, canonical, or robots values | Warning |
111
+ | Missing an enabled Open Graph or Twitter Card contract | Warning |
112
+ | Invalid social metadata URL or conflicting scalar social metadata | Warning |
108
113
  | Invalid JSON-LD | Warning |
109
114
  | JSON-LD block/count exceeds the bounded analysis budget | Warning |
110
- | Critical metadata in `<body>` for a profile that requires head metadata | Error |
111
- | Status, final URL, title, canonical, or robots drift between profiles | Warning |
115
+ | Critical or enabled social metadata in `<body>` for a profile that requires head metadata | Error |
116
+ | Status, final URL, title, canonical, robots, or enabled social metadata drift between profiles | Warning |
117
+ | Completion, status, final URL, or redirect-chain drift between samples | Warning |
118
+ | Metadata value or document-location drift between complete samples | Warning |
119
+ | Exact body fingerprint drift without metadata drift | Information |
112
120
  | First byte or required-signal arrival over a configured limit | Warning |
113
121
  | Timeout, truncation, network error, or another incomplete probe | Error / incomplete run |
114
122
 
@@ -157,6 +165,41 @@ agents:
157
165
  requiresHeadMetadata: true
158
166
  ```
159
167
 
168
+ ## Social preview metadata
169
+
170
+ Every probe captures these bounded, ordered metadata signals when they arrive
171
+ before completion or termination:
172
+
173
+ - Open Graph: `og:title`, `og:type`, `og:url`, `og:image`, and
174
+ `og:description`;
175
+ - Twitter Card: `twitter:card`, `twitter:title`, `twitter:description`, and
176
+ `twitter:image`.
177
+
178
+ SSRWire accepts either the conventional `property` attribute or a `name`
179
+ attribute for those keys. Each captured value carries the same arrival time,
180
+ observed byte position, and document location as the existing metadata
181
+ signals. The terminal report shows a compact readiness table whenever social
182
+ metadata is observed or required, while JSON retains every captured value.
183
+
184
+ Social policy is opt-in per target. `openGraph: true` requires the four basic
185
+ [Open Graph protocol](https://ogp.me/) properties: title, type, URL, and image.
186
+ The `twitterCard: true` option requires `twitter:card` plus a usable title,
187
+ description, and image; SSRWire prefers the corresponding `twitter:*` value
188
+ and falls back to `og:title`, `og:description`, or `og:image`. These are
189
+ explicit SSRWire audit contracts, not a claim that a social platform will
190
+ render a particular preview.
191
+
192
+ Enabled contracts also participate in critical-signal timing, head/body
193
+ policy, cross-agent drift, and repeated-sample stability checks. URL-valued
194
+ fields must be absolute HTTP or HTTPS URLs. Open Graph permits multiple images,
195
+ so SSRWire retains them in order without treating the array as a scalar
196
+ conflict; the first non-empty image satisfies readiness.
197
+
198
+ When both options are false, SSRWire still records and reports raw social
199
+ signals but emits no social-policy or social-drift findings. It does not fetch
200
+ images, verify dimensions or media types, execute JavaScript, or simulate a
201
+ platform's rendered preview.
202
+
160
203
  ## Configuration
161
204
 
162
205
  SSRWire automatically looks for `ssrwire.config.yml`,
@@ -174,6 +217,8 @@ targets:
174
217
  canonical: true
175
218
  h1: true
176
219
  mainText: true
220
+ openGraph: true
221
+ twitterCard: true
177
222
  maxFirstByteMs: 1200
178
223
  maxCriticalMs: 2500
179
224
 
@@ -185,6 +230,8 @@ targets:
185
230
  canonical: false
186
231
  h1: true
187
232
  mainText: true
233
+ openGraph: false
234
+ twitterCard: false
188
235
 
189
236
  agents:
190
237
  - browser
@@ -198,6 +245,7 @@ headers:
198
245
  timeoutMs: 15000
199
246
  maxBytes: 10485760
200
247
  maxRedirects: 10
248
+ repeat: 1
201
249
  ```
202
250
 
203
251
  A target can also be a plain URL string when defaults are sufficient:
@@ -212,10 +260,12 @@ Defaults:
212
260
 
213
261
  - expected status: `200`;
214
262
  - title, description, canonical, H1, and main text: required;
263
+ - Open Graph and Twitter Card contracts: disabled;
215
264
  - agents: `browser`, `googlebot`, `bingbot`, and `twitterbot`;
216
265
  - timeout: 15 seconds per probe;
217
266
  - response limit: 10 MiB;
218
- - redirect limit: 10.
267
+ - redirect limit: 10;
268
+ - samples per target and agent: 1, with an allowed range of 1–10.
219
269
 
220
270
  Unknown configuration keys are rejected. URLs must be absolute HTTP or HTTPS
221
271
  URLs and cannot contain embedded credentials.
@@ -255,11 +305,11 @@ The final response must declare `text/html` or `application/xhtml+xml` as its
255
305
  sniff headerless, JSON, text, or binary responses for HTML-looking fragments.
256
306
 
257
307
  To keep hostile or accidentally huge pages bounded, SSRWire retains at most
258
- 256 signals of each repeated metadata kind, analyzes at most 64 JSON-LD blocks,
259
- and captures at most 1,048,576 characters from one JSON-LD block. Exceeding a
260
- JSON-LD analysis budget produces a dedicated warning rather than being
261
- mislabeled as invalid JSON. The configured response-byte limit remains the
262
- outer bound.
308
+ 256 signals of each repeated metadata kind, including each supported social
309
+ property, analyzes at most 64 JSON-LD blocks, and captures at most 1,048,576
310
+ characters from one JSON-LD block. Exceeding a JSON-LD analysis budget produces
311
+ a dedicated warning rather than being mislabeled as invalid JSON. The
312
+ configured response-byte limit remains the outer bound.
263
313
 
264
314
  ## Timing interpretation
265
315
 
@@ -276,6 +326,40 @@ transfer-size or packet-boundary evidence. They count bytes delivered by the
276
326
  Fetch implementation to SSRWire; those bytes are post-content-decoding when a
277
327
  server ignores SSRWire's `Accept-Encoding: identity` request.
278
328
 
329
+ ## Repeated sampling
330
+
331
+ Use repeated sampling when one successful request does not prove that SSR output
332
+ is stable:
333
+
334
+ ```bash
335
+ npx ssrwire check --repeat 3
336
+ ```
337
+
338
+ `repeat` is the total number of samples, not a retry count. SSRWire retains
339
+ failures instead of replacing them with a later success. Samples for one
340
+ target-agent pair run sequentially; different target-agent pairs may still run
341
+ concurrently. SSRWire does not add delays, cache-busting parameters, or special
342
+ cache headers.
343
+
344
+ The request count is `targets × agents × repeat`, plus redirect hops. Configured
345
+ same-origin headers are sent for every sample and retain the existing
346
+ cross-origin stripping and report-redaction behavior.
347
+
348
+ For repeated runs, terminal reports include individual sample numbers and a
349
+ per-agent timing table. JSON retains every probe and adds per-agent stability
350
+ summaries. The summaries report sample count, minimum, median, nearest-rank p95,
351
+ maximum, and spread for available header, first-byte, required-signal, and
352
+ completion timings. With small sample counts, nearest-rank p95 will often equal
353
+ the maximum.
354
+
355
+ Timing spread alone is evidence, not a failure. Network and cache variation can
356
+ change timings without changing the response contract. SSRWire warns when HTTP
357
+ response evidence or streamed metadata changes across samples. Enabled social
358
+ contracts are included in metadata stability; observed social tags remain
359
+ evidence-only when their contracts are disabled. Exact body-hash variation by
360
+ itself is informational because timestamps, nonces, and other legitimate
361
+ dynamic values commonly change source HTML.
362
+
279
363
  ## CLI reference
280
364
 
281
365
  ```text
@@ -294,6 +378,7 @@ Check options:
294
378
  | `--timeout <ms>` | Override request timeout |
295
379
  | `--max-bytes <bytes>` | Override response-body limit |
296
380
  | `--max-redirects <count>` | Override redirect limit |
381
+ | `--repeat <count>` | Run 1–10 sequential samples per URL and agent |
297
382
  | `-f, --format <format>` | `terminal`, `json`, or `sarif` |
298
383
  | `-o, --output <path>` | Write the report to a file |
299
384
  | `--fail-on <level>` | `error`, `warning`, or `never` |
@@ -304,9 +389,10 @@ removed.
304
389
 
305
390
  ## Reports and exit codes
306
391
 
307
- - `terminal`: compact tables and findings for local use.
392
+ - `terminal`: compact sample, social-readiness, aggregate-timing, and finding
393
+ tables for local use.
308
394
  - `json`: structured machine-readable evidence, including every probe and timing
309
- signal.
395
+ signal plus repeated-run stability summaries.
310
396
  - `sarif`: findings suitable for GitHub Code Scanning and other SARIF 2.1.0
311
397
  consumers.
312
398
 
@@ -369,7 +455,7 @@ by the CLI:
369
455
  ```ts
370
456
  import { loadConfig, renderJson, runAudit } from "ssrwire";
371
457
 
372
- const config = await loadConfig({ urls: ["https://example.com/"] });
458
+ const config = await loadConfig({ urls: ["https://example.com/"], repeat: 3 });
373
459
  const audit = await runAudit(config);
374
460
  process.stdout.write(renderJson(audit));
375
461
  ```
@@ -380,15 +466,18 @@ versions.
380
466
 
381
467
  ## Scope
382
468
 
383
- SSRWire does not execute JavaScript, inspect a hydrated DOM, measure Core Web
384
- Vitals, discover URLs, validate indexing, bypass access controls, or emulate a
385
- crawler's rendering pipeline. Use [RoutePlay](https://github.com/lame13/routeplay)
386
- when the question is server HTML versus a cold browser versus real client-side
387
- navigation.
469
+ SSRWire does not execute JavaScript, inspect a hydrated DOM, render social
470
+ previews, fetch social images, measure Core Web Vitals, discover URLs, validate
471
+ indexing, bypass access controls, perform load testing, or emulate a crawler's
472
+ rendering pipeline. Use
473
+ [RoutePlay](https://github.com/lame13/routeplay) for server HTML versus a cold
474
+ browser versus real client-side navigation. Use
475
+ [RouteLint](https://github.com/lame13/routelint) for route discovery,
476
+ indexability, and technical SEO policy.
388
477
 
389
478
  Run SSRWire only against targets you are authorized to inspect. Keep target
390
- lists intentionally small; one run starts one probe per target/profile pair,
391
- with additional requests for redirect hops.
479
+ lists and repeat counts intentionally small. It is a consistency sampler, not a
480
+ load generator.
392
481
 
393
482
  ## Development
394
483
 
package/SECURITY.md CHANGED
@@ -20,7 +20,11 @@ report. You should receive an initial response within seven days.
20
20
  ## Operational safety
21
21
 
22
22
  SSRWire sends real HTTP requests to every configured target for every selected
23
- agent profile. Run it only against systems you are authorized to test. Treat
24
- custom headers as secrets, prefer environment-variable interpolation, and do
25
- not commit populated `.env` files or generated reports containing private
26
- URLs.
23
+ agent profile and sample. The base request count is
24
+ `targets × agents × repeat`, plus redirect hops. Samples for one target-agent
25
+ pair are sequential, but different pairs may run concurrently. Keep `repeat`
26
+ bounded and use SSRWire only against systems you are authorized to test.
27
+
28
+ Treat custom headers as secrets and remember that they are sent on every
29
+ same-origin sample. Prefer environment-variable interpolation, and do not
30
+ commit populated `.env` files or generated reports containing private URLs.
@@ -1 +1 @@
1
- {"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EAEX,OAAO,EACP,WAAW,EAIX,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAgepB,wBAAgB,aAAa,CAC3B,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,SAAS,WAAW,EAAE,GAC7B,SAAS,OAAO,EAAE,CAuGpB;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,GAAG,YAAY,CA6BlF"}
1
+ {"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EAEX,OAAO,EACP,WAAW,EAMX,iBAAiB,EAClB,MAAM,YAAY,CAAC;AA2pBpB,wBAAgB,aAAa,CAC3B,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,SAAS,WAAW,EAAE,GAC7B,SAAS,OAAO,EAAE,CAwGpB;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,GAAG,YAAY,CA6BlF"}