Add ts CLI ad-template config diagnostics and browser audit

[prk-Jr]

Summary

• Adds operator tooling to verify server-side ad-template ([creative_opportunities]) configuration: static path/slot diagnostics via ts config ad-templates …, and browser-backed live verification via ts audit … (local Chrome/Chromium over CDP).
• Adds ts audit ad-templates generate <url> to bootstrap [creative_opportunities] from a live site. One run crawls the publisher's sections (sitemap via robots.txt, else navigation links), samples a landing page and an article per section, reconciles each slot across the pages it appeared on, and writes the result into an existing trusted-server.toml in place, preserving every other section and comment.
• Where the evidence proves it, the run infers a {network_id}/{section} ad-unit template plus the section_root/section_segment policy it depends on, instead of pinning each slot to the one literal path it happened to be scraped from. A wrong template makes a publisher bid against inventory that does not exist, so inference refuses rather than guesses — see the table below.
• Everything the run writes is validated before it replaces the file: the candidate goes through Settings::from_toml, the same load path the runtime uses at startup, on the --dry-run path too. An unloadable trusted-server.toml is a full-site outage once pushed, not a degraded ad stack.
• Lets publishers catch slot/config drift before deploy — match a path to configured slots, assert expected slots in CI, explain runtime ad-stack gating, and confirm configured slots actually render (DOM/GPT/APS evidence) on live pages.
• Keeps the CLI host-only: browser deps (chromiumoxide) are excluded from the wasm32-wasip1 build, and the runtime ad-stack gate is shared with publisher.rs so the CLI cannot drift from server behavior.

Stacks on the EdgeZero CLI base (server-side-ad-templates-impl). After merging the base back in, the diff against it is feature-only.

Behavior change: bare ts audit <url> remains a hidden alias for ts audit generate <url>; the base branch's draft-artifact generation moved to the explicit ts audit generate <url>.

Deploy ordering — read before pushing generated config. A config carrying section_root or section_segment is not rollback-safe. CreativeOpportunitiesConfig is deny_unknown_fields, so a binary predating ad-unit templating (cee1e20e) rejects the entire Settings load — not just the ad-template section — and every route serves an error. Deploy the template-aware binary first, then push, and do not roll that binary back while the config is live. A run that did not template writes neither key and leaves the config exactly as rollback-safe as it was. The command prints this warning itself.

closes #701

Changes

Area	Change
trusted-server-core/src/creative_opportunities.rs	[creative_opportunities] config types, match_slots, shared evaluate_ad_stack_gate; compile_page_pattern as the single glob definition; derive_section made public so tooling checks inference against the runtime's own derivation rather than a second implementation
trusted-server-core/src/publisher.rs	Route should_run_server_side_ad_stack through the shared gate (behavior-preserving)
trusted-server-cli/src/commands/config/ad_templates.rs	ts config ad-templates {lint,match,check,explain} static diagnostics
trusted-server-cli/src/app_config.rs	Shared effective app-config loader for the config + audit commands
trusted-server-cli/src/ad_templates/{expected,compare,output}.rs	Pure expected-slot projection, DOM/GPT/APS evidence comparison, stable JSON model, terminal-safe text escaping
trusted-server-cli/src/commands/audit/{mod,page,collector,browser,ad_templates}.rs, commands/audit/ad_template_collector.js	ts audit page + ts audit ad-templates verify: chromiumoxide collector, read-only GPT/APS/DOM init script, verifier orchestration, cross-origin refusal
trusted-server-cli/src/commands/audit/generate/crawl_plan.rs	New. Turns links and sitemap entries into a bounded page set — one landing page and one article per section, ranked by nav/sitemap corroboration, capped by section and page budgets, same-origin enforced on both sources
trusted-server-cli/src/commands/audit/generate/evidence.rs	New. Cross-page slot evidence: formats unioned, divergent unit paths retained, network ids required to agree, and detection of one placement fragmented across per-render div ids
trusted-server-cli/src/commands/audit/generate/unit_template.rs	New. {network_id}/{section} inference with positional network binding, a single-varying-segment rule, the witness rule, and replay through the runtime's own renderer
trusted-server-cli/src/commands/audit/generate/page_patterns.rs	New. Expands observed paths into per-section glob pairs (/news and /news/*) without extrapolating past a witnessed section
trusted-server-cli/src/commands/audit/generate/validate.rs	New. Write-side gate: the candidate config must load through Settings::from_toml before it replaces the file; a pre-existing failure downgrades to a warning so an already-broken config can still be updated
trusted-server-cli/src/commands/audit/generate/{mod,gpt_slots}.rs	Crawl orchestration, challenge-rate refusal, per-page diagnostics; slot reconstruction from live GPT plus normalization of ephemeral div-id noise (React _R_/_r_ ids, -container, hex UUIDs)
trusted-server-cli/src/commands/audit/generate/{browser_collector,collector,analyzer}.rs	Batch collection on one reused browser, hydrated-DOM link extraction, in-page sitemap fetch, device profiles, request pacing, consent answering, proxy support
trusted-server-cli/src/run.rs, src/lib.rs	Command wiring and parser tests for the audit namespace
trusted-server-cli/Cargo.toml	Host-only edgezero-core + serde_json deps (cfg-gated off wasm, like the existing browser deps)
docs/guide/cli.md	ts audit ad-templates generate documented: crawl behavior, refusal table, consent platforms, proxy auditing, and the deploy-ordering contract
docs/superpowers/{specs,plans}/2026-06-26-server-side-ad-template-cli*	Design spec and implementation plan

Test plan

Per CLAUDE.md, a bare cargo test/cargo clippy --workspace fails at the workspace root — the repo has multiple wasm runtimes with runtime-specific SDKs, so the target-matched aliases are the real gate.

• cargo fmt --all -- --check
• cargo clippy-fastly && cargo clippy-axum && cargo clippy-cloudflare && cargo clippy-cloudflare-wasm && cargo clippy-spin-native && cargo clippy-spin-wasm
• cargo clippy -p trusted-server-cli --target <host-triple> --all-targets --all-features -- -D warnings
• cargo test-fastly && cargo test-axum && cargo test-cloudflare && cargo test-spin
• cargo test --manifest-path crates/trusted-server-integration-tests/Cargo.toml --test parity (13 passed)
• Host CLI tests: cargo test -p trusted-server-cli --target <host-triple> — 347 passed
• JS tests: cd crates/trusted-server-js/lib && npx vitest run (829 passed)
• JS format: cd crates/trusted-server-js/lib && npm run format
• Docs format: cd docs && npm run format
• WASM build: cargo build --package trusted-server-adapter-fastly --release --target wasm32-wasip1 (plus cargo build -p trusted-server-cli --target wasm32-wasip1 — browser deps stay out of wasm)
• Chrome-gated browser fixtures (./scripts/test-cli.sh) for evidence collection and scroll-phase attribution
• Manual: full crawl against a live publisher through ts dev proxy — template and section policy inferred, per-render div-id fragments refused, generated config loads through Settings::from_toml

Notable fixture-based coverage, all offline: crawl planning (cross-origin rejection on links and sitemap entries, utility/asset filtering, query/fragment collapsing, budget truncation), evidence reconciliation (format union, network-id conflict, fragment detection with a co-occurrence false-positive guard), and one test per template-inference refusal case.

How to use

Static ts config ad-templates … commands only read local effective config (no browser). Browser-backed ts audit … commands launch a local Chrome/Chromium.

Configure slots

In your (gitignored) trusted-server.toml — fictional values shown:

[creative_opportunities]
gam_network_id = "123"
section_root = "homepage"     # required when a template uses {section}

[[creative_opportunities.slot]]
id = "atf"
gam_unit_path = "/{network_id}/news/{section}"   # or a literal path
div_id = "ad-atf-"            # treated as a prefix; matches e.g. ad-atf-0
page_patterns = ["/", "/news", "/news/*"]
formats = [{ width = 300, height = 250 }]

# optional provider hints
[creative_opportunities.slot.providers.aps]
slot_id = "atf"

Generate slots from a live site (needs local Chrome/Chromium)

# Crawl the site's sections and write [creative_opportunities] in place
ts audit ad-templates generate https://www.example.com/

ts audit ad-templates generate https://www.example.com/ --dry-run    # preview, no write
ts audit ad-templates generate https://www.example.com/ --replace    # overwrite instead of merge

# Bound the crawl
ts audit ad-templates generate https://www.example.com/ --max-sections 20 --max-pages 41
ts audit ad-templates generate https://www.example.com/ --max-pages 1   # single page, as before

# Set the patterns yourself; disables pattern inference
ts audit ad-templates generate https://www.example.com/ \
  --page-pattern '/' --page-pattern '/news' --page-pattern '/news/*'

# Check whether the publisher splits ad units by device
ts audit ad-templates generate https://www.example.com/ --profiles desktop,mobile

# Behind bot protection: carry a session, pace the crawl, or use a visible browser
ts audit ad-templates generate https://www.example.com/ \
  --cookie '<NAME>=<VALUE>' --page-delay-ms 1500
ts audit ad-templates generate https://www.example.com/ --headful

Re-running merges: a slot seen again keeps its hand-tuned fields and gains this run's patterns and newly observed formats, and a hand-written gam_unit_path template is preserved. --replace discards existing slots, including any template written by hand.

Consent platforms. Publishers gate slot definition behind their consent platform, and the audit runs in a throwaway profile with no consent cookie — so such a site would define no slots at all and look identical to a site with no ad stack. The crawl therefore answers the two IAB interfaces every compliant platform exposes (TCF v2 and US Privacy) as a consenting, out-of-scope reader, before any page script runs. This changes only what the audit browser sees. --no-assume-consent observes the un-consented page instead.

Auditing a production hostname served locally. ts dev proxy serves a production hostname from a local Trusted Server; auditing through it keeps the page's origin, cookie scope, and any origin checks in the ad stack matching production rather than localhost:

ts dev proxy --map www.example.com=127.0.0.1:7676 --upstream-plaintext --rewrite-host

ts audit ad-templates generate https://www.example.com/ \
  --browser-proxy 127.0.0.1:18080 --danger-accept-invalid-certs

Note that a local Trusted Server injects its own configured slots, so a run through the proxy can rediscover config it already has; slot ids absent from the current config are the publisher's own.

When generation keeps literal paths, and when it refuses

Situation	Result
Only one page was crawled	Literal path — one observation cannot distinguish a literal from a template
The ad unit never varied by section	Literal path
A section's slug is not derivable from its URL	Refused slot omitted; the failed round-trip is reported
No root page was seen, so section_root is unknown	Refused slot omitted rather than guessing a fallback
Two path segments could both be the section	No template; the ambiguity is reported
The unit varies by device, geo, or anything the URL cannot supply	Refused slot omitted with the conflicting evidence reported
Several slots are one placement under per-render div ids	Fragments reported and skipped, with the stable prefix they share
Crawled pages report different GAM network ids	Run fails — the pages are not one property
More than a quarter of crawled pages return no slots	Run fails — the signature of bot protection serving challenge pages

Static diagnostics (no browser)

# Summarize config + deploy-time implications
ts config ad-templates lint

# Which configured slots match a path (or full URL)
ts config ad-templates match /news/story --details

# CI assertion: exact expected slot set
ts config ad-templates check /news/story --expected-slot atf
ts config ad-templates check /weather --expect-no-slots
ts config ad-templates check /news/story --expected-slot atf --allow-extra-slots

# Explain the runtime ad-stack gates for a modeled request
ts config ad-templates explain /news/story --bot --consent-denied --prefetch

Browser-backed audit (needs local Chrome/Chromium)

# Generic read-only page summary
ts audit page https://www.example.com/

# Verify configured slots render on live pages (DOM/GPT/APS evidence)
ts audit ad-templates verify https://www.example.com/news/story
ts audit ad-templates verify https://www.example.com/news/story --json
ts audit ad-templates verify https://www.example.com/ --strict --scroll

# Carry a session past an origin challenge (repeatable)
ts audit ad-templates verify https://www.example.com/ --cookie '<NAME>=<VALUE>'

# Allow a known redirect between your own properties (e.g. apex → www)
ts audit ad-templates verify https://example.com/ --allow-cross-origin-redirect

# Point at a specific browser / tune settle timing
ts audit ad-templates verify https://www.example.com/ \
  --chrome /path/to/chrome --settle-quiet-ms 1000 --settle-max-ms 15000

Shared config flags (all of the above)

--app-config <path>     # default: <app.name>.toml beside edgezero.toml
--manifest <path>       # default: edgezero.toml
--no-env                # skip the app-config environment overlay

Exit behavior

• Default verify is auditor-assist: exits 0 even with missing/partial evidence.
• --strict exits 1 when a confirmable matched slot is missing or partially confirmed; video, native, and out-of-page slots are unconfirmable and do not fail the gate. A page-level navigation failure, or a redirect that leaves the requested origin, also exits non-zero.
• Runtime gates (e.g. [auction].enabled = false) mark a page "skipped" so --strict does not fail it.

Local live test (deterministic, no external site)

Many large ad publishers block headless/non-evasive browsers, so verify against them sees a challenge page rather than the article (this tool does not evade bot detection — --cookie forwards a clearance a human already earned, and --headful runs a visible browser). When a page comes back without slots, the run now reports GPT's observable state — whether the library reached apiReady, how many queued commands never drained, how many scripts ran — which distinguishes "the library never loaded" from "this page has no ads".

To exercise the full pipeline reliably without an external site, serve a local fixture:

# 1. Fixture page that stubs just enough GPT (no network), served over HTTP
mkdir -p demo/news
cat > demo/news/story.html <<'HTML'
<!doctype html><html><head><meta charset="utf-8">
<div id="ad-atf-0"></div>
<script>
(function(){var s=[];var gt={cmd:[]};
gt.defineSlot=function(p,z,d){var o={getAdUnitPath:function(){return p},getSlotElementId:function(){return d},getSizes:function(){return z.map(function(x){return {getWidth:function(){return x[0]},getHeight:function(){return x[1]}}})}};s.push(o);return o};
gt.pubads=function(){return {getSlots:function(){return s}}};var op=gt.cmd.push.bind(gt.cmd);gt.cmd.push=function(c){op(c);c()};
window.googletag=gt;googletag.cmd.push(function(){googletag.defineSlot('/123/news/atf',[[300,250]],'ad-atf-0')});})();
</script></head><body></body></html>
HTML
(cd demo && python3 -m http.server 8771 &)

# 2. Verify against it (config from the example above, with page_patterns ["/news/*"])
ts audit ad-templates verify http://127.0.0.1:8771/news/story.html --json
#   => slots[0].status == "confirmed"

For a realistic end-to-end generation run, ts dev proxy in front of a local Trusted Server is the reliable path — see the proxy example above.

Checklist

• Changes follow CLAUDE.md conventions
• No unwrap() in production code — use expect("should ...")
• No println!/eprintln! in library code (CLI output uses writeln!; errors use log)
• New code has tests
• No secrets or credentials committed

[ChristianPavilonis]

Summary

Reviewed the locked head revision 4c9777d14bf1f541f25cedd37770aa800e8668c6. CI and local validation pass. I found two medium-priority correctness issues in generation/merge behavior and one documentation-policy issue; details are inline.

[aram356]

Summary

Round-6 re-review at fec84adef. Round 5 is fully resolved — every finding closed, two beyond what was asked (cli_definition_is_valid, the ErrorKind upgrade), and the borrowed-root precision question settled by a disjointness argument that was independently verified. The two new feature series are largely sound: the scroll pass is genuinely unified rather than tripled, the div-id reconciliation is order-independent and idempotent, the round-3 prefix hazard is confirmed not reintroduced (every runtime consumer resolves exact/longest-first), and HEAD passes the real-world token sweep. Requesting changes for two reproduced false positives in the new stale-slot diagnostic — an ambiguity-refused placement and a live broad prefix are both reported "not observed during this crawl" with advice that cannot help — plus a set of doc-accuracy and hardening items, most with one-click fixes.

12 of the inline comments below carry a one-click GitHub suggestion. Every suggestion was verified in a scratch worktree, in isolation and as a batch: cargo fmt --all -- --check, cargo clippy -p trusted-server-cli --target aarch64-apple-darwin --all-targets -- -D warnings, the CLI test suites, and docs prettier, all clean with byte-exact drift checks (the Chrome-gated fixture behind the timing-margin suggestion was not executed; that one is arithmetic-derived). The remaining comments describe fixes in prose because the change spans non-adjacent regions or is a design call.

Blocking

🔧 wrench

• Ambiguity-refused placements reported "not observed", with advice that cannot help — see inline at crates/trusted-server-cli/src/commands/audit/generate/mod.rs:746
• A live broad prefix is reported unobserved when its exact sibling is configured — see inline at crates/trusted-server-cli/src/commands/audit/generate/slot_toml.rs:378

Non-blocking

♻️ refactor / 🤔 thinking / ⛏ nitpick

• ♻️ Split-off siblings silently lose the parent's hand-tuned fields — see inline at crates/trusted-server-cli/src/commands/audit/generate/slot_toml.rs:353
• 🤔 The 8+8 token rule refuses stable date-plus-word div ids — see inline at crates/trusted-server-cli/src/commands/audit/generate/gpt_slots.rs:285
• ♻️ ScrollFailure duplicates eval_discard's warning vocabulary — see inline at crates/trusted-server-cli/src/commands/audit/browser_scroll.rs:8
• ♻️ The Linux build fix papers over derive_more's macOS-only gating; ScrollFailure lacks impl Error — see inline at crates/trusted-server-cli/src/commands/audit/browser_scroll.rs:11
• ⛏ collect_open_page still takes 7 positionals after the grouping commit — see inline at crates/trusted-server-cli/src/commands/audit/generate/browser_collector.rs:574
• ⛏ Refusal table missing the new cross-origin page skip — see inline at docs/guide/cli.md:243 (suggestion)
• ⛏ Merge paragraph still describes pre-round-6 identity rules — see inline at docs/guide/cli.md:277 (suggestion)
• ⛏ "Not by recognising token shapes" contradicted by the shape recognizer — see inline at docs/guide/cli.md:386 (suggestion)
• ⛏ Shared-flag list omits --scroll — see inline at docs/guide/cli.md:455 (suggestion)
• ⛏ Broken HOST_TARGET shell snippet, six occurrences — see inline at docs/superpowers/plans/2026-08-24-ad-template-generate-scroll-staleness.md:61 (suggestion)
• ⛏ Ragged wrap left by the token scrub — see inline at docs/superpowers/specs/2026-08-24-ad-template-generate-scroll-staleness-design.md:96 (suggestion)
• ⛏ Dead filter predicate in the observation seed — see inline at crates/trusted-server-cli/src/commands/audit/generate/slot_toml.rs:231 (suggestion)
• ⛏ Staleness note's --replace guidance understates what it discards — see inline at crates/trusted-server-cli/src/commands/audit/generate/mod.rs:759 (suggestion)
• ⛏ observed_div_ids superset contract undocumented — see inline at crates/trusted-server-cli/src/commands/audit/generate/slot_toml.rs:208 (suggestion)
• ⛏ Bare assertions on the wording-split test and scroll default — see inline at crates/trusted-server-cli/src/commands/audit/generate/mod.rs:2254 and crates/trusted-server-cli/src/run.rs:520 (suggestions)
• ⛏ Chrome fixture's ~250 ms timing margin — see inline at crates/trusted-server-cli/src/commands/audit/generate/browser_collector.rs:1133 (suggestion)

Cross-cutting / body-level findings

• 📝 --scroll is unreachable from ts audit generate and the legacy alias — both build the collector with no .with_scroll(...). This matches the design doc's scope statement, so it reads as intentional; recording the asymmetry since the collector now carries a knob one of its two callers cannot reach.
• 📝 "Autoblog" survives in branch history — HEAD is clean (verified across every added line), but the name exists in commits 28881e053, f4f9a6e66, and 11b013005 before the 2f5cae6da scrub. If the repository policy extends to history, squash-merge this PR rather than merge-committing it.

CI Status

• Analyze (actions): PASS
• Analyze (javascript-typescript): PASS (×2)
• Analyze (rust): PASS
• CodeQL: PASS
• browser integration tests: PASS
• cargo check (cloudflare native + wasm32-unknown-unknown): PASS
• cargo check/build/test (spin native + wasm32-wasip1): PASS
• cargo fmt: PASS (required)
• cargo test: PASS (required)
• cargo test (axum native): PASS
• cargo test (cross-adapter parity): PASS
• cargo test (ts CLI, native): PASS
• format-docs: PASS (required)
• format-typescript: PASS (required)
• integration tests: PASS
• integration tests (Fastly EC lifecycle): PASS
• prepare integration artifacts: PASS
• vitest: PASS

Local verification at fec84adef: CLI suites 251 + 217 + 30 audit/generate/run-scoped tests passed, full crate green; clippy -D warnings clean; fmt clean; docs prettier clean.

[prk-Jr]

Round-six review follow-up:

• --scroll remains intentionally scoped to ts audit ad-templates generate, matching the approved design; no separate legacy CLI surface was added.
• HEAD is scrubbed, but intermediate commits retain the historical hostname. If the repository policy applies to all reachable history, this PR should be squash-merged.
• All 19 inline findings are addressed in fccfcd48, with focused regressions. The local CLI suite, full adapter test/clippy matrix, parity suite, Vitest/type checks, formatting, docs lint, and docs build are green.