feat(codeceptq): CLI to query HTML with CodeceptJS locators

[DavertMik]

Summary

Adds codeceptq — a standalone CLI that takes an HTML stream (stdin or --file) plus a CodeceptJS locator (CSS / XPath / fuzzy / semantic) and prints matched elements with line numbers and outerHTML snippets.

Designed for AI agents iterating on locators against aiTrace's per-step *_page.html snapshots: "would this locator match at step N?" — answered in milliseconds, no browser, no re-run.

# CSS / XPath
cat output/trace_*/0007_*_page.html | npx codeceptq './/input[@required]'
npx codeceptq '#submit' --file output/trace_*/0007_*_page.html

# semantic locators (label / button text / option / checkbox)
npx codeceptq 'Email' --field --file output/trace_*/0003_*_page.html
npx codeceptq 'Save' '.modal' --click --file output/trace_*/0005_*_page.html

# JSON for scripting
npx codeceptq 'Username' --field --json --file output/trace_*/0002_*_page.html

Changes

• New bin/codeceptq.js (registered as codeceptq in package.json#bin).
• New lib/command/query.js — parse5-tracked line numbers + xmldom xpath eval. Reuses Locator for CSS→XPath and semantic builders (Locator.field.byText, Locator.clickable.wide, Locator.checkable.byText, Locator.select.byVisibleText).
• lib/html.js#formatHtml now passes inline: [] to js-beautify so every element in trace HTML lands on its own line — line numbers from codeceptq map 1:1 to elements.
• xpath@0.0.34 promoted from devDependencies → dependencies (already in tree).
• Default --snippet length 500 chars; --full for complete outerHTML; --json for tooling.
• Exit codes: 0 match, 1 no match, 2 invalid input/XPath.

Tests

test/runner/codeceptq_test.js — 45 tests against test/data/{checkout,github,gitlab,app/drag_drop}.html. Each assertion shows the expected { line, snippet } inline so the test source is also a behavior spec:

expect(parsed.matches).toEqual([
  { line: 87, snippet: '<input type="text" class="form-control" id="firstName" placeholder="" value="" required>' },
  { line: 94, snippet: '<input type="text" class="form-control" id="lastName" placeholder="" value="" required>' },
  // ...
])

Coverage: XPath, CSS (id/class/attr/forced), --field, --click/--clickable, --checkable, --select, fuzzy auto-detect, context scoping, stdin vs --file, --limit, --snippet, --full, --json, exit codes, large fixtures.

Test plan

• npx mocha test/runner/codeceptq_test.js → 45 passing
• npx mocha test/unit/html_test.js test/unit/utils/trace_test.js → existing tests still pass with new inline: []
• npx eslint bin/codeceptq.js lib/command/query.js test/runner/codeceptq_test.js → clean
• Smoke against real examples/output/trace_*/*_page.html — finds all 17 inputs with line numbers
• Reviewer: try npx codeceptq 'something' --file output/trace_*/<step>_page.html after a real test run

🤖 Generated with Claude Code