feat(cli,core,cdp): --viewport flag + viewport multi-run orchestration

[aram-devdocs]

Target branch

• This PR targets main

Spec

Fixes #16. Part of #10 Phase 1, Gate 2, Batch 1B (sibling: #15 DOMSnapshot integration).

PRD references: §10.3 (data flow / per-viewport pipeline), §13.3 (exit codes), §15.4 (plumb lint flags).

Summary

• Adds repeatable --viewport <name> flag to plumb lint. Filters the configured viewport set from plumb.toml; absent the flag, every configured viewport runs. Unknown names produce a clear input error (exit 2) listing the available viewports.
• New BrowserDriver::snapshot_all trait method with a default fan-out impl. ChromiumDriver overrides it so Chromium launches exactly once per CLI invocation for the full viewport batch (the per-viewport DOMSnapshot conversion still returns CdpError::NotImplemented until feat(cdp): DOMSnapshot.captureSnapshot integration with style whitelist #15 lands).
• New plumb_core::run_many aggregates rule output across multiple snapshots, re-sorts by (rule_id, viewport, selector, dom_order), and dedups. The existing exit_code_for then computes worst-severity-wins across all viewports (AC chore(roadmap): link phase-2 parent #4).

Crates touched

• plumb-core — new run_many entry point; run is now a thin wrapper.
• plumb-format
• plumb-cdp — BrowserDriver::snapshot_all + viewport-aware FakeDriver.
• plumb-config
• plumb-mcp
• plumb-cli — --viewport flag + orchestrator + LintError (thiserror).
• xtask
• docs/
• .agents/ or .claude/
• .github/

System impact

• New public API item — plumb_core::run_many, BrowserDriver::snapshot_all. Both have full rustdoc with # Determinism notes; both are infallible-or-Result shaped per the existing patterns.
• New MCP tool
• New rule
• CDP / browser surface change — BrowserDriver::snapshot_all added; security-auditor reviewed.
• Config schema change
• Dependency added / bumped — plumb-cli adds thiserror (workspace dep already in tree); tempfile added to [dev-dependencies] only.
• Determinism invariant touched — run_many re-sorts + dedups across snapshots; tested input-order-independent.

Architectural compliance

• Layer discipline holds — plumb-core adds no internal deps; plumb-cdp still depends only on plumb-core; only plumb-cli prints.
• Error shape — LintError is thiserror-derived; anyhow only at the orchestrator boundary.
• No new unwrap/expect/panic! in libraries. The unreachable empty-pop case in ChromiumDriver::snapshot returns a typed CdpError::Driver rather than panicking.
• No new SystemTime::now / Instant::now in plumb-core.
• No new HashMap in observable output paths (IndexMap throughout).
• No new #[allow(...)] annotations.

Test plan

• just validate passes locally (54 tests, 0 failed).
• cargo xtask pre-release (no rule or schema change).
• just determinism-check — three byte-identical runs.
• cargo deny check — advisories ok, bans ok, licenses ok, sources ok.
• New tests added:
  • plumb-core::engine_run_many — 3 cases (collects-from-every, sort order, input-order independence).
  • plumb-cdp::snapshot_all_default::fake_driver_snapshot_all_preserves_target_order_and_viewport — 1 case.
  • plumb-cli::commands::lint::tests — 7 cases on resolve_targets (default fallback, IndexMap order, filter, unknown-name error shape).
  • plumb-cli::tests::cli_integration — 4 new cases covering all four ACs end-to-end.

Documentation

• Rustdoc on every new public item (run_many, snapshot_all, LintError, the new Lint::viewports flag).
• # Errors not needed for run_many (infallible) or snapshot_all (already documented CdpError).
• docs/src/ — no user-facing book changes in this PR. CLI reference docs for --viewport will land alongside the broader CLI docs page in a later PR (humanizer pass deferred to that PR).
• docs/src/rules/ — no new rules.
• CHANGELOG — no entry needed; release-please owns it from PR chore(roadmap): link phase-1 parent #3 onward.
• Humanizer skill — not run (no docs/src/** changes).

Breaking change?

• No

Checklist

• Conventional Commits title
• Branch name: codex/16-feat-cli-viewport-flag-multirun
• All review gates passed: spec → quality → architecture → test (+ security).

Reviewer notes

• The ChromiumDriver real path still returns CdpError::NotImplemented per feat(cdp): DOMSnapshot.captureSnapshot integration with style whitelist #15. This PR's job is the orchestrator + single-launch invariant; the per-viewport DOMSnapshot conversion lands in feat(cdp): DOMSnapshot.captureSnapshot integration with style whitelist #15. The two PRs can land in either order — they don't conflict.
• Config::viewports is empty by default. The default-fallback path (single desktop 1280×800 target) preserves the walking-skeleton quickstart so plumb lint plumb-fake://hello works in a fresh checkout. Once a [viewports.*] section is added to plumb.toml, the bare plumb lint <url> command begins running every configured viewport — that's per PRD §10.3.
• Empty-config + --viewport <name> arg silently falls back to the default desktop target rather than erroring. This is documented in resolve_targets's rustdoc and asserted by empty_config_ignores_viewport_arg_and_returns_default. Erroring would regress the no-config quickstart.
• Unknown-viewport input error returns exit 2 ("CLI / infrastructure failure") per the existing crates/plumb-cli/CLAUDE.md mapping. Spec reviewer flagged this as a divergence from PRD §13.3's literal "exit 3 for input errors" but accepted it as consistent with the established CLI convention; if the PRD is canonical, that reconciliation is a separate ticket.

🤖 Generated with Claude Code