Add JS Asset Auditor plugin with Playwright CLI

[ChristianPavilonis]

Summary

• Add JS Asset Auditor as a Claude Code plugin at packages/js-asset-auditor/ with a standalone Playwright CLI that sweeps publisher pages for third-party JS assets
• Auto-detect integrations (GPT, GTM, Didomi, DataDome, Lockr, Permutive, Prebid, APS) from swept URLs and generate trusted-server.toml config with --config flag
• Expanded heuristic filters for Google ad rendering, ad verification, ad fraud detection, and reCAPTCHA to reduce noise
• Auto-include target URL host as first-party, make trusted-server.toml optional with --domain flag for portability
• Browser launches headed by default to avoid bot detection (captchas, DataDome, etc.)

Try it out

1. Check out the branch

git fetch origin
git checkout feature/js-asset-auditor

2. Install dependencies

cd packages/js-asset-auditor && npm install && npx playwright install chromium
cd ../..

3. Run the CLI directly

# Basic audit — opens a browser, sweeps the page, writes js-assets.toml
node packages/js-asset-auditor/lib/audit.mjs https://www.publisher.com

# Also generate trusted-server.toml with detected integrations
node packages/js-asset-auditor/lib/audit.mjs https://www.publisher.com --config

# Custom output paths
node packages/js-asset-auditor/lib/audit.mjs https://www.publisher.com \
  --output /tmp/assets.toml --config /tmp/config.toml

# Headless mode (for CI, may be blocked by bot protection)
node packages/js-asset-auditor/lib/audit.mjs https://www.publisher.com --headless

4. Use as a Claude Code plugin

claude --plugin-dir packages/js-asset-auditor

Then in Claude Code:

/js-asset-auditor:audit-js-assets https://www.publisher.com
/js-asset-auditor:audit-js-assets https://www.publisher.com --config

CLI flags

Flag	Description
--diff	Compare sweep against existing js-assets.toml
--settle <ms>	Settle window after page load (default: 6000)
--first-party <hosts>	Additional first-party hosts (comma-separated)
--domain <host>	Publisher domain (falls back to trusted-server.toml or URL)
--no-filter	Bypass heuristic filtering
--headless	Run browser without UI (default is headed)
--output <path>	Output file for js-assets.toml (default: js-assets.toml)
--config [path]	Generate trusted-server.toml with detected integrations
--force	Overwrite existing config file

Test plan

• Run against a publisher page and verify js-assets.toml output
• Run with --config and verify detected integrations in generated trusted-server.toml
• Run with --diff against an existing js-assets.toml and verify confirmed/new/missing
• Run without trusted-server.toml (e.g., from /tmp) and verify domain inference
• Load as Claude Code plugin and test the skill
• Verify --config without --force errors when file already exists
• Verify bot-protected sites work in headed mode (e.g., autoblog.com)

Closes #631

[aram356]

Summary

Additive Claude Code plugin (packages/js-asset-auditor/) with a Playwright-based CLI for sweeping publisher pages, a processing library, and integration auto-detection. No Rust changes. Review uncovered three blocking issues: the format-docs CI gate is red, the generated trusted-server.toml emits an invalid bidders = "" for Prebid, and the CLI arg parser silently consumes the next flag when a value is omitted. A handful of non-blocking refactor/hardening suggestions follow.

Blocking

🔧 wrench

• format-docs CI failing: prettier wants table column realignment in docs/superpowers/specs/2026-04-01-js-asset-auditor-design.md (heuristic filter table and detection patterns table). Fix: cd docs && npx prettier --write superpowers/specs/2026-04-01-js-asset-auditor-design.md. (inline at line 100)
• Generated bidders = "" is invalid for Rust Prebid config: PrebidConfig::bidders is Vec<String> (crates/trusted-server-core/src/integrations/prebid.rs:69). Users who flip enabled = true on a generated [integrations.prebid] block get a deserialization failure. (inline at detect.mjs:266)
• --first-party / --settle / --output / --domain consume the next flag: passing a value-taking flag without a value silently swallows the following arg. Reproduced. (inline at audit.mjs:84)

Non-blocking

♻️ refactor

• Slug algorithm duplicated in scripts/js-asset-slug.mjs — make it import from packages/js-asset-auditor/lib/process.mjs. Silent drift here breaks KV lookups against the Rust proxy. (inline at scripts/js-asset-slug.mjs:78)
• Stale help block in audit.mjs — references --headed (not implemented; actual flag is --headless) and omits --config, --force, --domain. (inline at audit.mjs:18)

🤔 thinking

• readPublisherDomain conflates parse errors with missing file — a malformed but present trusted-server.toml silently falls through to URL-inferred domain, producing wrong slugs (publisher prefix depends on domain). Distinguish ENOENT from parse failure. (inline at audit.mjs:142)
• --config existence check uses readFileSync — use fs.existsSync. (inline at audit.mjs:238)
• No unit tests for process.mjs / detect.mjs — both have nontrivial logic (wildcard regex, first-party boundary, heuristic filter with two match shapes, integration field extraction). Vitest already runs in crates/js/lib; adding fixtures there (or alongside the plugin) would catch drift, especially for the slug hash that must match the Rust proxy.

⛏ nitpick

• GTM match uses pathname.includes("/gtm.js") — .endsWith("/gtm.js") removes theoretical ambiguity. (inline at detect.mjs:37)
• formatTomlValue doesn't escape " / \ — fine today since inputs are static, but JSON.stringify on the string branch is free escape handling for future patterns. (inline at detect.mjs:226)

🌱 seedling

• Cross-language slug fixture test — the spec claims the JS slug must produce identical output to the Rust proxy's KV key derivation, but the Rust proxy lives on a separate branch. Once it lands, a shared-fixture test (same {domain, url} → same slug in both JS and Rust) is the only reliable guard against silent drift. Worth a follow-up issue.

CI Status

• cargo fmt: PASS
• cargo clippy: PASS
• rust tests: PASS
• vitest (crates/js/lib): PASS
• format-typescript: PASS
• format-docs: FAIL (see 🔧 above)

[prk-Jr]

Summary

This plugin is close, but there are three blocking behavior issues in the CLI/config pipeline that can mislead operators or produce unusable output. CI is green, but these cases need to be fixed before the tool is safe to rely on for onboarding and diff workflows.

Blocking

🔧 wrench

• Generated configs enable integrations before required fields are present (packages/js-asset-auditor/lib/detect.mjs:260)
• Diff mode keeps re-appending the same NEW assets on repeated runs (packages/js-asset-auditor/lib/process.mjs:214)
• --config conflict only logs an error and still exits successfully (packages/js-asset-auditor/lib/audit.mjs:266)

[aram356]

Summary

Re-review against main after 66951b9. That commit cleanly addresses every finding from my prior review (format-docs, bidders = "", arg-parser flag-swallowing, slug duplication, stale help block, existsSync, GTM endsWith, TOML escaping, ENOENT-vs-parse distinction), with focused regression tests for each.

However, the 2026-04-22 review from @prk-Jr is not addressed by the latest push — I confirmed all three of their blockers in the worktree — and I found two additional blocking-class issues while re-reading the 18 changed files.

Blocking

🔧 wrench

• enabled = true for partial / detect_only integrations — generated config boot-fails on missing required fields (server_url, pub_id, app_id). packages/js-asset-auditor/lib/detect.mjs:260 (inline).
• Diff mode re-appends the same NEW assets on repeated runs — reproduced: same asset appears 6× after 3 runs because parseExistingToml ignores commented suggestions. packages/js-asset-auditor/lib/process.mjs:214 (inline).
• --config collision exits 0 with success summary — violates spec, breaks automation. packages/js-asset-auditor/lib/audit.mjs:269 (inline).
• --config default path collides with live trusted-server.toml — with --force, silently overwrites the real publisher config with a TODO skeleton. packages/js-asset-auditor/lib/audit.mjs:136 (inline).
• Plugin unit tests are not wired into CI — .github/workflows/test.yml only runs vitest in crates/js/lib. The 8 regression tests added in 66951b9 (the sole guard against drift on slug algorithm, integration detection, arg parsing) run locally only, so regressions will land on main unnoticed. Add a step that runs cd packages/js-asset-auditor && npm ci && npm test on PRs touching this directory, or unconditionally.

Non-blocking

🤔 thinking

• No diff-idempotence test — processAssets(..., { diff: true }) run twice against its own output should yield summary.new.length === 0. A fixture test in packages/js-asset-auditor/test/process.test.mjs would have caught the re-append regression and will keep catching it.
• SKILL.md still says "headless browser" — packages/js-asset-auditor/skills/audit-js-assets/SKILL.md:24. The CLI has defaulted to headed since e0c7e0c. Misleading for sandbox users.
• data: / blob: script URLs produce "null" origin in slugs — new URL("data:…").origin === "null" so applyWildcards yields null/<pathname>. Rare for <script src>, but one protocol guard is cheap.

♻️ refactor

• readPublisherDomain hand-rolls a TOML scan (lib/audit.mjs:37-61) — rejects single-quoted strings and any non-^domain = "…" shape. A small TOML lib would be more robust. Non-urgent.

⛏ nitpick

• APS pattern uses pathname.includes("/apstag") (lib/detect.mjs:152) — same class of ambiguity as the GTM case tightened in 66951b9. Consider anchoring.

CI Status

• cargo fmt: PASS
• cargo clippy / Analyze (rust): PASS
• cargo test: PASS
• vitest (crates/js/lib): PASS
• format-typescript: PASS
• format-docs: PASS
• browser integration tests: PASS
• CodeQL: PASS
• plugin tests (packages/js-asset-auditor/test): NOT WIRED INTO CI — see blocking #5

[aram356]

🔧 Prints test.publisher.com in place of actual domain because it reads from toml file

🔧 Please add guide documentation

[ChristianPavilonis]

Addressed the remaining review feedback in 00ce787 and replied/resolved the inline threads:

• incomplete integrations are no longer auto-enabled
• diff mode is now idempotent across repeated runs
• --config collisions now fail non-zero before the success summary
• no-arg --config now writes to trusted-server.generated.toml
• plugin tests are wired into CI
• added docs/guide/js-asset-auditor.md
• clarified domain precedence and source selection in the CLI/skill/docs

Validation run after the changes:

• cd packages/js-asset-auditor && npm test
• cd docs && npm run format
• cargo test --workspace
• cargo fmt --all -- --check
• cargo clippy --workspace --all-targets --all-features -- -D warnings

Re-requesting review from @aram356 and @prk-Jr.