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.

[aram356]

Summary

Re-review against main after 5b3481a. Every prior blocker from the 2026-04-22 (prk-Jr) and 2026-04-23 (aram356) reviews is cleanly addressed in 00ce787 + 5b3481a, with focused regression tests for each fix and the plugin test job now wired into PR CI. CI is green (14 checks). I verified all 16 plugin tests pass locally and prettier is clean on the new docs files.

Two issues warrant changes before merge:

• data: / blob: script URLs produce garbage TOML entries that look like real [[js_assets]] blocks but reference unfetchable origins. Reproduced both cases through processAssets(). Inline below.
• Spec example for Lockr now contradicts the implementation — the doc shows enabled = true for an integration that the (corrected) generator now emits as enabled = false. Inline below.

Plus two non-blocking suggestions: replace the hand-rolled TOML scan in readPublisherDomain with a real parser (carried over — the new test now locks in the strict-double-quote-only limitation), and tighten the loose pathname.includes(\"/apstag\") APS pattern the same way GTM was tightened in 66951b9.

Blocking

🔧 wrench

• data: / blob: URLs produce garbage TOML (packages/js-asset-auditor/lib/process.mjs:321, inline)
• Spec example contradicts implementation (docs/superpowers/specs/2026-04-01-js-asset-auditor-design.md:284, inline)

Non-blocking

♻️ refactor

• readPublisherDomain hand-rolled TOML scan (packages/js-asset-auditor/lib/audit.mjs:39-63, inline)

🤔 thinking

• Integration detection runs against unfiltered URLs — lib/audit.mjs:305 calls detectIntegrations(scriptUrls, …) on the raw network capture, not the post-first-party set. If a publisher self-hosts their prebid bundle at cdn.publisher.com/prebid.js, a [integrations.prebid] block lands in the generated config. Not strictly wrong (publisher does run prebid), but it bypasses the first-party boundary the asset pipeline carefully enforces. Consider passing the third-party-filtered URL set instead.

⛏ nitpick

• APS pattern is loose (packages/js-asset-auditor/lib/detect.mjs:170, inline)
• --first-party accepts unvalidated values (packages/js-asset-auditor/lib/audit.mjs:163) — splits on , with no normalization, so --first-party https://www.example.com silently no-ops because stripWww doesn't strip the protocol. Either reject non-hostname values or normalize via new URL(value).hostname.

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
• js-asset-auditor tests: PASS (newly wired into CI in this PR)

[ChristianPavilonis]

I will use the generate docs skill

[aram356]

Summary

Re-review of feature/js-asset-auditor against main at head dd859bfa. The PR has been through three earlier review passes and Christian has cleanly addressed every prior blocker — fixes landed with focused regression tests, parseExistingToml now recognizes commented suggestions, --config collisions exit non-zero, integrations with TODO fields no longer auto-enable, data: / blob: URLs are rejected, and the plugin test job is wired into PR CI. 20/20 plugin tests pass locally.

One blocker: format-docs CI is failing on the new docs files. Same class of issue that landed in the original review (fixed in 66951b9); the doc additions in dd859bfa reintroduced it. Reproduced locally — see inline. Everything else is non-blocking polish.

Blocking

🔧 wrench

• format-docs CI is failing — Prettier wants column-aligned tables in docs/guide/js-asset-auditor.md (L100–105 and L227–238) and docs/superpowers/specs/implemented/2026-04-01-js-asset-auditor-design.md (L122–130 and L208–212). Inline.

Non-blocking

🤔 thinking

• Init mode silently overwrites an existing js-assets.toml — audit-js-assets <url> with no --diff writes args.output unconditionally at packages/js-asset-auditor/lib/audit.mjs:314. Inconsistent with --config, which fails loudly via ensureConfigPathWritable() unless --force is passed. If an operator re-runs init forgetting --diff, hand-curated entries are lost silently. Consider applying ensureConfigPathWritable(args.output, args.force) symmetrically (or at least when output is the default path).
• inject_in_head first-seen-wins on wildcard collapse — see inline at packages/js-asset-auditor/lib/process.mjs:340.

♻️ refactor

• Lockr hostname.includes is loose — see inline at packages/js-asset-auditor/lib/detect.mjs:88.
• readPublisherDomain hand-rolled TOML scan — see inline at packages/js-asset-auditor/lib/audit.mjs:39.

🌱 seedling

• formatTomlEntry doesn't escape strings — packages/js-asset-auditor/lib/process.mjs:185-196 uses raw interpolation for slug, path, origin_url. detect.mjs's formatTomlValue does escape via JSON.stringify. All three values today come from URL-encoded ASCII so the inconsistency is harmless, but it's a footgun if anyone later adds a non-URL-derived field.
• Missing direct unit tests for applyWildcards, matchesHeuristicFilter, extractAssetStem, normalizeUrl, isFirstParty — All exercised only indirectly through processAssets. Direct tests would catch regressions in the wildcard semver/hex/mixed-hash heuristics and in the dot-boundary suffix logic (e.g., a regression where evil-googletagmanager.com starts matching).
• page.waitForTimeout is "discouraged" in Playwright — packages/js-asset-auditor/lib/audit.mjs:264. For an audit tool a fixed-window settle is reasonable, but page.waitForLoadState('networkidle', { timeout: args.settle }) is the documented alternative.
• Permutive omits commented cache_ttl_seconds / rewrite_sdk defaults — packages/js-asset-auditor/lib/detect.mjs:126-129 lists only api_endpoint and secure_signals_endpoint. The Permutive Rust struct also defines cache_ttl_seconds and rewrite_sdk with serde defaults, and GPT lists analogous defaults in the generator. Inconsistent operator visibility into available overrides.

📌 out of scope

• Unrelated chrome-devtools MCP permissions in root .claude/settings.json — .claude/settings.json:27-32 adds navigate_page, list_network_requests, close_page. The auditor uses Playwright, not chrome-devtools-mcp. These additions look orthogonal to this PR's scope and would be cleaner in a separate "expand harness permissions" change so the diff stays focused on the auditor.

CI Status

• cargo fmt: PASS
• cargo clippy / Analyze (rust): PASS
• cargo test: PASS
• vitest (crates/js/lib): PASS
• format-typescript: PASS
• format-docs: FAIL
• browser integration tests: PASS
• CodeQL: PASS
• js-asset-auditor tests: PASS

[aram356]

🔧 wrench — format-docs CI is failing on this file.

Reproduced locally with cd docs && npm run format: Prettier wants column-aligned tables here (the Field / Description table) and again at lines ~227–238 (the Common options table), plus the matching tables in docs/superpowers/specs/implemented/2026-04-01-js-asset-auditor-design.md (asset-entry table at L122–130 and diff-mode condition table at L208–212).

This is the same class of failure that landed in the original review and was fixed in 66951b9; the doc additions in dd859bfa reintroduced it. CI run: https://github.com/IABTechLab/trusted-server/actions/runs/25353966443/job/74339283778

Fix:

cd docs && npm run format:write

then commit the resulting whitespace-only changes. cd docs && npm run format should then pass.

[aram356]

🤔 thinking — inject_in_head is determined from the pre-wildcard URL on a first-seen-wins basis.

injectInHead = normalizedHead.has(url) uses the original URL, but the dedup at L335 keys on the wildcarded URL. If a publisher's page loads …/prod/1.19.8/raven.js from <body> and …/prod/1.19.9/raven.js from <head> in the same sweep, both collapse to the same wildcard but inject_in_head reflects only whichever URL the iteration saw first.

Not common in practice (a single page sweep usually loads one version), but worth flagging — when a wildcarded entry is generated, inject_in_head should arguably be true if any of the originals appeared in head.

Suggested approach:

const injectInHead = [...normalizedHead].some((headUrl) => {
  const { wildcarded: headWildcarded } = applyWildcards(headUrl);
  return headWildcarded === wildcarded;
});

or track the OR across originals collapsed into the same wildcard during the dedup loop.

[aram356]

♻️ refactor — Lockr hostname match uses String.prototype.includes, which is looser than every other pattern in this file.

url.hostname.includes("aim.loc.kr") matches notaim.loc.kr and aim.loc.kr.attacker.com. Combined with the identity-lockr substring + .js suffix requirements (and the fact that partial integrations are emitted with enabled = false), the practical blast radius is limited to a noisy false positive in the generated config — but the test is still wrong, and inconsistent with how GTM / Datadome / Didomi / GPT / APS / Permutive all use === or endsWith.

Fix:

const { hostname } = url;
const hostMatch =
  hostname === "aim.loc.kr" ||
  hostname.endsWith(".aim.loc.kr") ||
  hostname === "identity.loc.kr" ||
  hostname.endsWith(".identity.loc.kr");
if (!hostMatch) return false;
const href = url.href.toLowerCase();
return href.includes("identity-lockr") && href.endsWith(".js");

Worth covering with a regression test that asserts notaim.loc.kr/identity-lockr-foo.js does not match.

[aram356]

♻️ refactor — Carry-over from the 2026-04-29 review: readPublisherDomain is still a hand-rolled TOML scan that only matches domain = "…" (double-quoted basic strings).

Author explicitly deferred adding a TOML dependency in this pass, and the new test in audit.test.mjs locks in the strict-double-quote-only behavior — a single-quoted domain = 'publisher.com' is treated as missing and the CLI errors out, which is at least consistent. Re-flagging as non-blocking so the follow-up stays on the list: an actual TOML parser (e.g., smol-toml, ~6 KB) would gracefully accept literal strings and multi-line strings, and would future-proof against operators copy-pasting examples from the wider TOML ecosystem.

[aram356]

⛏ nitpick — Frontmatter verified_against_commit: 4773d13b is stale.

Latest commit on this branch is dd859bfa (Update docs for JS Asset Auditor), which itself touches this file. Either bump the value to the current head or drop the field if it's not meant to track every doc edit.