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] slots from a live page's GPT state — reconstructed from the GPT registry (googletag.pubads().getSlots()) and captured gampad/ads requests — and write them into an existing trusted-server.toml in place, preserving every other section. Slots accumulate across pages (--page-pattern unions coverage into re-seen slots), so multi-page pattern sets can be built run-by-run. A --cookie flag carries a valid session past an origin challenge (this tool still does not evade bot detection — it forwards a clearance cookie a human already earned).
• 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> is now a hidden alias for ts audit page <url>; the base branch's draft-artifact generation moved to the explicit ts audit generate <url>.

closes #701

Changes

Area	Change
trusted-server-core/src/creative_opportunities.rs	[creative_opportunities] config types, match_slots, and a shared evaluate_ad_stack_gate runtime gate
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, and the stable JSON model
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
trusted-server-cli/src/commands/audit/generate/{mod,gpt_slots}.rs	ts audit ad-templates generate: reconstruct slots from live GPT (registry + gampad/ads), normalize ephemeral div-id noise (React _R_ hashes, -container, hex UUIDs) to stable prefixes, merge into the existing config in place
trusted-server-cli/src/commands/audit/generate/{browser_collector,collector,analyzer}.rs	Existing draft-config generator moved under generate/; collector scrapes the live GPT registry and supports operator cookies
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/superpowers/{specs,plans}/2026-06-26-server-side-ad-template-cli*	Design spec and implementation plan

Closes

Not yet linked to an issue.

Test plan

• cargo test --workspace
• cargo clippy --workspace --all-targets --all-features -- -D warnings
• cargo fmt --all -- --check
• JS tests: cd crates/trusted-server-js/lib && npx vitest run (393 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)
• Other: host CLI tests cargo test -p trusted-server-cli --target <host-triple> (164, incl. slot reconstruction, div-normalization, merge/union, TOML-escaping/CRLF tests + Chrome-gated browser fixtures for evidence collection and scroll-phase attribution); manual ts audit ad-templates verify against a local fixture — confirmed (exit 0) and --strict on a missing slot (exit 2)

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"

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

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

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

# Bootstrap slots → writes [creative_opportunities] into trusted-server.toml in place
ts audit ad-templates generate https://www.example.com/ --page-pattern '/'

# Add another page's coverage — unions the pattern into shared slots
ts audit ad-templates generate https://www.example.com/news/story --page-pattern '/news/*'

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
ts audit ad-templates generate https://www.example.com/ --cookie 'name=value'  # carry a session past a challenge

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'

# 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 non-zero when a matched slot is missing or only partially confirmed (CI gate). A page-level navigation failure 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, not the article (this tool does not evade bot detection). To exercise the full pipeline reliably, 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"

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]

Automated review: I reviewed the ad-template CLI diagnostics/generate/verify changes against server-side-ad-templates-impl. I found three non-blocking issues around in-place TOML rewriting and generated-slot defaults that should be addressed, but no blocking correctness/security/data-loss issue severe enough to request changes. CI checks currently shown by GitHub are passing (integration tests, Fastly EC lifecycle, browser integration tests, prepare integration artifacts).

[ChristianPavilonis]

Automated review: I reviewed PR #823 against main, focusing on the new ts CLI ad-template diagnostics, browser audit/generate paths, TOML rewriting, and the shared runtime gate. CI is currently green. I did not find a blocking runtime/security issue requiring REQUEST_CHANGES, but I found several high-confidence non-blocking correctness and compatibility issues called out inline. Existing earlier automated comments about inline-commented TOML headers, redirected default page patterns, and DEL escaping appear to have been addressed in the current head, so I did not repeat them.