wpt-gen-cli

name	wpt-gen-cli
description	Best practices for CLI infrastructure, outputs, subprocess management, and templating in WPT-Gen.

WPT-Gen CLI Skills

This document outlines the best practices for working with the CLI infrastructure in the wpt-gen repository.

1. CLI Framework: Typer

WPT-Gen uses Typer for building its command-line interface.

• Routing: Define subcommands and groups using @app.command() decorators.
• Type Hints: Rely heavily on Python type hints to automatically generate CLI arguments and options.
• Common Options: Most commands (especially generate) support a standard set of flags:
  • --provider (-p): Override the LLM provider (gemini, openai, anthropic).
  • --wpt-dir (-w): Override the local web-platform-tests repository path.
  • --config (-c): Path to a custom wpt-gen.yml.
  • --show-responses (-s): Display raw LLM-generated responses.
  • --use-lightweight / --use-reasoning: Force a specific model category.

2. Rich Console Output & Abstraction

For displaying information to the user, WPT-Gen utilizes Rich.

• Strict UIProvider Abstraction: Never use the native print() function. You must route all outputs through the injected UIProvider dependency (e.g. ui.print, ui.warning, ui.error).
• Styling: Use rich.print (via UIProvider) for colored and formatted output.
• Panels & Tables: Use rich.panel.Panel to encapsulate related information (like summarizing test plans) and rich.table.Table for structured data, rather than dumping raw JSON or concatenated strings to the CLI.
• Progress Bars: When iterating over long-running LLM calls, use ui.status() wrappers to provide visual rich.progress spinners to the user so they know the command has not hung.

3. Subprocess execution & Wrappers

WPT-Gen heavily relies on executing native binaries (wpt lint, grep) to empower LLM agents.

• Subprocess Stability (Hung Agents): Autonomous agents will hang indefinitely if tools don't return. When using subprocess.run(), you must always provide explicit timeout=... constraints, otherwise a rogue blocking command will freeze the AI forever.
• Environment Context Leaking: Subprocess calls must construct and pass explicit env={**os.environ, "CUSTOM": "VAL"} mappings, rather than lazily mutating the global os.environ which bleeds state across Python threads. Reviewers must actively catch environment leaking.
• Shell Injection & Compat: When wrapping native CLI execution tools (e.g., git grep or grep), scrutinize custom arguments for shell injection vulnerabilities. Force the use of the -- argument separator to securely separate binary options from user-generated patterns.

4. Templating with Jinja2

WPT-Gen uses Jinja2 to template both prompts to the LLM and the final generated output (HTML/JS files).

• Location: Templates are typically stored in the wptgen/templates/ directory.
• Variable Injection: Use standard Jinja2 syntax ({{ variable_name }}) to inject context retrieved via trafilatura or derived from local scans.
• Control Structures: Utilize standard {% if %} and {% for %} loops to dynamically construct test structures based on the suggested test footprint. Ensure large, nullable dependencies are robustly guarded behind {% if %} conditions to avoid causing context bloat.