Skip to content

chrome-devtools-cli v1.4.0

Latest
Latest

Choose a tag to compare

View all tags
@aeroxy aeroxy released this 02 Jul 12:24
1.4.0
b77678a

1. High-Level Summary (TL;DR)

  • Impact: High - Introduces powerful new capabilities for custom automation, allowing users to execute local JavaScript files and domain-specific adapters directly in the browser context.
  • Key Changes:
    • Added run-script command to execute custom JavaScript files inside the page.
    • Added adapter command to run specific functions from domain-aware adapter files.
    • Implemented an injected ctx automation helper object containing utilities like click, fill, and waitForSelector.
    • Added auto-navigation logic driven by JSDoc-style comments (@url, @domain) to ensure scripts run on the correct pages.
    • Introduced comprehensive documentation and examples for these new features.

2. Visual Overview (Code & Logic Map)

graph TD
    subgraph "CLI Layer (src/lib.rs & executor.rs)"
        User["User CLI Command"] -->|run-script / adapter| Executor["script_exec_args()"]
    end
    
    subgraph "Execution Logic (src/commands/evaluate.rs)"
        Executor --> Parser["parse_script_url_marker() / parse_adapter_domains()"]
        Parser -->|Domain Mismatch| Nav["client.navigate()"]
        Parser -->|Domain Match| Context["build_ctx_object()"]
        Nav --> Context
        Context --> Eval["evaluate()"]
    end
    
    classDef default fill:#bbdefb,color:#0d47a1,stroke:#0d47a1,stroke-width:2px;

3. Detailed Change Analysis

CLI Commands & Routing (src/lib.rs, src/commands/executor.rs)

  • What Changed: Added new enum variants RunScript and Adapter to the main CLI commands. Introduced a shared argument parsing logic to handle both named (-a key=val) and positional (-- val) arguments flexibly.
  • New Command Parameters:
    Param Type Required Description
    file_path String Yes Path to the local JS script or adapter file
    function_name String Yes (adapter only) Name of the specific function to run
    --arg / -a String No Named arguments to pass to the script
    raw_args String[] No Positional arguments appended after a literal --
    --output / -o String No Write output to a file instead of stdout
    --track-navigation Boolean No Track URL changes caused by execution

Script Evaluation & Auto-Navigation (src/commands/evaluate.rs)

  • What Changed: Implemented run_script and run_adapter execution flows. The commands now read the target file, parse it for metadata (@url, @navigate, @domain), and automatically navigate the active tab if it's not currently on the target domain.
  • Error Handling Update: Removed verbose hints regarding DOM traversal in the generic evaluate() error output, replacing it with a clean bail string.

Injected Automation Context (src/commands/evaluate.rs, src/constants.rs)

  • What Changed: Introduced build_ctx_object() which constructs a JavaScript snippet that is injected into the evaluation context as an Immediately Invoked Function Expression (IIFE). This exposes a robust set of helpers to user scripts. Added POLL_INTERVAL_MS (100ms) to control polling frequency.
  • Injected ctx API:
    Method Description
    ctx.args Object containing parsed arguments from the CLI
    ctx.wait(ms) Async sleep utility
    ctx.waitForText(text, timeout) Polls the DOM body until text appears
    ctx.waitForSelector(sel, timeout) Polls until a CSS selector exists
    ctx.click(selector) DOM element clicking helper
    ctx.fill(selector, value) Input value setter that correctly overrides native setters to trigger React/Vue/Angular state updates

Documentation & Examples

  • What Changed: Created skill/chrome-devtools/CUSTOM_SCRIPTING.md and added reference wikis (wiki/adapter.md, wiki/run-script.md). Included real-world SPA examples for Hacker News (search_hn.js, hn_adapter.js).

4. Impact & Risk Assessment

  • Breaking Changes: None. The update is purely additive. A minor adjustment was made to the evaluate command's error message format.
  • Risks:
    • Security Injection: The function_name for adapters is directly interpolated into the JS IIFE. However, this is mitigated by is_valid_js_identifier() validation.
    • Auto-Navigation Loops: If a site rapidly redirects after navigation, the domain check might warn about URL mismatches.
Assets 3
Loading