Stabilize CLI contracts and cut 0.2.0 (#13)

* Restore post-rc3 CLI contracts for search and interaction flows

This commit lands the contract fixes that were validated against the
browser-backed harness and the manual 4310 scenario set. It wires
`node search --limit` through the CLI/runtime boundary, restores
structured truncation metadata, and makes `interact type` /
`interact press` honor `--target-text` and `--role` instead of
silently falling back or failing on selector-only assumptions.

Constraint: Must preserve the published click/source contracts while extending type/press targeting
Constraint: `.omx/` and PERF_VALIDATION.md are local-only and intentionally excluded
Rejected: Patch only the runtime search response | CLI still ignored --limit and invalid limit 0 still succeeded
Rejected: Add null-target guards only | would mask the missing targeting support instead of fixing it
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Keep the browser-backed harness aligned with the manual PR-check scenario set whenever interaction contracts change
Tested: npm run build; npm test; npm run test:integration; manual 4310 session open/search/source/click/type/press validation
Not-tested: Cross-platform manual interaction behavior outside the local Chromium-backed open-session path

* Clarify untargeted press compatibility without widening the API surface

The remaining risk after the contract-restoration pass was not a
broken code path but an ambiguous one: untargeted `interact press`
was still supported for compatibility, yet its response copy implied
selector-based targeting and it was not locked by explicit harness
coverage. This commit makes that compatibility behavior explicit in
responses, help text, and docs while adding regression checks for
page-level press and invalid strict/nth usage without a target.

Constraint: Keep untargeted press backward compatible instead of making press target-only
Constraint: Follow the existing public response shape rather than inventing new target sentinel values
Rejected: Require a target for every press action | higher safety, but a breaking change to an existing compatibility path
Rejected: Leave untargeted press undocumented | keeps the risk of future accidental regression and misleading output
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: If untargeted press is ever removed, update help/docs/harness in the same change and treat it as a breaking CLI contract change
Tested: npm run build; npm test; npm run test:integration
Not-tested: Manual untargeted press behavior on non-Chromium browsers or non-open transports

* Promote the CLI surface from prerelease to 0.2.0

The search and interaction contracts are now validated through unit,
integration, docs-build, pack, and publish dry-run lanes, so this
version bump marks the first stable cut after the rc series. The bug
report template is updated alongside the package metadata so the
reported version examples match the released channel.

Constraint: Publish workflow requires the GitHub release tag to match package.json exactly
Constraint: Stable versions publish to the npm latest tag instead of next
Rejected: Keep shipping rc builds | the CLI contracts are now stable enough to make the next stable line the source of truth
Rejected: Bump only package.json | would leave package-lock and issue template inconsistent with the release line
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Future stable releases should update package metadata, release tag, and user-facing version examples in the same change
Tested: npm run build; npm test; npm run test:integration; npm run docs:build; npm pack --dry-run; npm publish --dry-run
Not-tested: End-to-end npm publish from GitHub release until the release is actually created from main

Author: Ring-wdr

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -13,7 +13,7 @@ body:
     attributes:
       label: react-devtool-cli version
       description: Output of `rdt --version`
-      placeholder: 0.1.34
+      placeholder: 0.2.0
     validations:
       required: true
   - type: textarea

README.md

@@ -159,13 +159,16 @@ rdt profiler export --session demo --compress
 - Use built-in `interact` commands before reaching for external Playwright helper scripts.
 - Current supported actions:
   - `rdt interact click --session <name> (--selector <css> | --text <value> | --role <role>) [--nth <index>] [--strict] [--delivery auto|playwright|dom]`
-  - `rdt interact type --session <name> --selector <css> --text <value>`
-  - `rdt interact press --session <name> --key <name> [--selector <css>]`
+  - `rdt interact type --session <name> (--selector <css> | --target-text <label> | --role <role>) [--nth <index>] [--strict] --text <value>`
+  - `rdt interact press --session <name> --key <name> [--selector <css> | --target-text <label> | --role <role>] [--nth <index>] [--strict]`
   - `rdt interact wait --session <name> --ms <n>`
 - These commands execute through the same Playwright session that owns the current `rdt` browser page.
 - `interact click` can resolve targets by CSS selector, visible text, or ARIA role.
+- `interact type` and targeted `interact press` can resolve controls by CSS selector, label text, or ARIA role.
+- `interact press` without a target remains a page-level keyboard action for compatibility; use a target when focus ambiguity would make the result nondeterministic.
 - `--nth` selects one match from a broader result set, and `--strict` requires exactly one match.
-- Responses now include `targetingStrategy`, `matchCount`, and `resolvedNth` alongside the delivery metadata.
+- For `interact type` and targeted `interact press`, `--strict` and `--nth` only make sense when one of `--selector`, `--target-text`, or `--role` is present.
+- Responses now include `targetingStrategy`, `targetingResolution`, `matchCount`, and `resolvedNth` alongside the delivery metadata.
 - `interact click` defaults to `--delivery auto`.
 - In `auto`, profiler-active clicks fall back to DOM dispatch and report `requestedDelivery`, `effectiveDelivery`, `profilerActive`, and `fallbackApplied`.
 - Use `--delivery playwright` to force Playwright pointer input, or `--delivery dom` to force DOM dispatch.
@@ -281,7 +284,8 @@ Use `node pick` when the agent knows the visible element but not the component n
 - `source reveal --structured` returns `status`, `available`, `mode`, `reason`, and `source` so automation can distinguish unavailable source data from a successful source payload.
 - `source reveal` without `--structured` preserves the raw legacy behavior and may return literal `null`.
 - `dom` is the first host element summary used for CLI highlight and DOM-oriented inspection.
-- `node search --structured` wraps search results in `{ items, query, snapshotId, matchCount, runtimeWarnings }`.
+- `node search --structured` wraps search results in `{ items, query, snapshotId, matchCount, returnedCount, truncated, runtimeWarnings }`.
+- `node search --limit <n>` trims the returned items to the requested count while preserving the full `matchCount`.
 - When `node search --structured` returns `matchCount: 0`, `runtimeWarnings` explains that the component may be absent from the current snapshot rather than absent from the codebase.
 - Profiler summary fields are commit-oriented CLI metrics, not the full DevTools profiler session schema.
 - `profiler summary` and exported summaries explicitly report:

docs/workflows.md

@@ -48,7 +48,7 @@ rdt source reveal <nodeId> --session demo --snapshot <snapshotId> --structured
 ```
 
 - `tree stats` is the lightweight summary path when `tree get --format json` is too heavy.
-- `node search --structured` keeps the default array-returning behavior opt-in while adding `matchCount` and `runtimeWarnings`.
+- `node search --structured` keeps the default array-returning behavior opt-in while adding `matchCount`, `returnedCount`, `truncated`, and `runtimeWarnings`.
 - `source reveal --structured` returns availability metadata instead of only raw `null`.
 
 Recovery flow:
@@ -79,22 +79,25 @@ Built-in interactions keep the investigation inside the same session instead of
 
 ```bash
 rdt interact click --session demo --role button --nth 0 --delivery auto
-rdt interact type --session demo --selector 'input[name="query"]' --text hello
+rdt interact type --session demo --target-text 'Filter inventory' --text hello
 rdt interact wait --session demo --ms 500
 ```
 
 - `interact click --delivery auto` uses Playwright pointer input by default.
 - When the profiler is active, `auto` may fall back to DOM dispatch and reports the applied delivery in the response payload.
 - Use one targeting mode per click: `--selector`, `--text`, or `--role`.
+- `interact type` and targeted `interact press` accept `--selector`, `--target-text`, or `--role`.
+- `interact press --key <name>` without a target remains a page-level keyboard action and depends on the browser's current focus state.
 - Add `--nth` to choose one match from a broader result set, or `--strict` to require exactly one match.
+- For `interact type` and targeted `interact press`, `--strict` and `--nth` require an explicit target.
 
 After interaction, verify the app settled by collecting a fresh tree or reading profiler output instead of assuming the UI state changed correctly.
 
 ## Profile a real update
 
 ```bash
 rdt profiler start --session demo
-rdt interact type --session demo --selector 'input[name="query"]' --text hello
+rdt interact type --session demo --target-text 'Filter inventory' --text hello
 rdt profiler stop --session demo
 rdt profiler summary --session demo
 rdt profiler ranked <commitId> --session demo --limit 10

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "react-devtool-cli",
-  "version": "0.1.35-rc.3",
+  "version": "0.2.0",
   "description": "Agent-first CLI for React component tree inspection, snapshot-aware node debugging, and profiler analysis through a Playwright-managed browser session.",
   "license": "MIT",
   "type": "module",

package.json

@@ -345,6 +345,33 @@ async function main() {
     );
     ensure(Array.isArray(searchPayload.items) && searchPayload.matchCount >= 1, "node-search-structured did not return any App matches");
 
+    const limitedSearchPayload = parseJsonResult(
+      "node-search-limit",
+      await runRdt([
+        "node",
+        "search",
+        "ResultRow",
+        "--session",
+        sessionName,
+        "--snapshot",
+        statsPayload.snapshotId,
+        "--structured",
+        "--limit",
+        "5",
+        "--format",
+        "json",
+      ]),
+    );
+    ensure(Array.isArray(limitedSearchPayload.items) && limitedSearchPayload.items.length === 5, "node-search-limit did not truncate items to 5");
+    ensure(limitedSearchPayload.returnedCount === 5, "node-search-limit did not report returnedCount 5");
+    ensure(limitedSearchPayload.matchCount > limitedSearchPayload.returnedCount, "node-search-limit did not report a truncated result set");
+    ensure(limitedSearchPayload.truncated === true, "node-search-limit did not report truncated=true");
+    ensure(
+      Array.isArray(limitedSearchPayload.runtimeWarnings)
+        && limitedSearchPayload.runtimeWarnings.some((warning) => warning.includes("--limit 5")),
+      "node-search-limit did not report the limit warning",
+    );
+
     const zeroMatchPayload = parseJsonResult(
       "node-search-zero-match",
       await runRdt([
@@ -362,6 +389,21 @@ async function main() {
     );
     ensure(zeroMatchPayload.matchCount === 0, "node-search-zero-match did not return matchCount 0");
     ensure(Array.isArray(zeroMatchPayload.runtimeWarnings) && zeroMatchPayload.runtimeWarnings.length > 0, "node-search-zero-match did not return runtimeWarnings");
+
+    const invalidSearchLimitResult = await runRdt([
+      "node",
+      "search",
+      "ResultRow",
+      "--session",
+      sessionName,
+      "--structured",
+      "--limit",
+      "0",
+      "--format",
+      "json",
+    ]);
+    ensure(invalidSearchLimitResult.code !== 0, "node-search-invalid-limit unexpectedly succeeded");
+    ensure(invalidSearchLimitResult.stderr.includes("--limit"), "node-search-invalid-limit did not explain the limit failure");
     logScenarioOk("tree-stats-and-structured-search");
 
     const appNodeId = searchPayload.items[0]?.id;
@@ -488,6 +530,157 @@ async function main() {
       "profiler-stop",
       await runRdt(["profiler", "stop", "--session", sessionName, "--format", "json"]),
     );
+
+    const targetTextType = parseJsonResult(
+      "type-target-text",
+      await runRdt([
+        "interact",
+        "type",
+        "--session",
+        sessionName,
+        "--target-text",
+        "Filter inventory",
+        "--text",
+        "billing",
+        "--format",
+        "json",
+      ]),
+    );
+    ensure(targetTextType.targetingStrategy === "target-text", "type-target-text did not use target-text targeting");
+    ensure(targetTextType.targetingResolution === "label-control", "type-target-text did not resolve through label-control");
+    ensure(targetTextType.target?.tagName === "input", "type-target-text did not resolve to an input");
+    ensure(targetTextType.textLength === 7, "type-target-text did not report the expected text length");
+
+    const targetTextPress = parseJsonResult(
+      "press-target-text",
+      await runRdt([
+        "interact",
+        "press",
+        "--session",
+        sessionName,
+        "--key",
+        "Enter",
+        "--target-text",
+        "Filter inventory",
+        "--format",
+        "json",
+      ]),
+    );
+    ensure(targetTextPress.targetingStrategy === "target-text", "press-target-text did not use target-text targeting");
+    ensure(targetTextPress.targetingResolution === "label-control", "press-target-text did not resolve through label-control");
+    ensure(targetTextPress.target?.tagName === "input", "press-target-text did not resolve to an input");
+
+    const roleType = parseJsonResult(
+      "type-role-targeting",
+      await runRdt([
+        "interact",
+        "type",
+        "--session",
+        sessionName,
+        "--role",
+        "textbox",
+        "--strict",
+        "--text",
+        "analytics",
+        "--format",
+        "json",
+      ]),
+    );
+    ensure(roleType.action === "type", "type-role-targeting did not report type action");
+    ensure(roleType.targetingStrategy === "role", "type-role-targeting did not use role targeting");
+    ensure(roleType.strict === true, "type-role-targeting did not report strict=true");
+
+    const rolePress = parseJsonResult(
+      "press-role-targeting",
+      await runRdt([
+        "interact",
+        "press",
+        "--session",
+        sessionName,
+        "--key",
+        "Enter",
+        "--role",
+        "textbox",
+        "--strict",
+        "--format",
+        "json",
+      ]),
+    );
+    ensure(rolePress.action === "press", "press-role-targeting did not report press action");
+    ensure(rolePress.targetingStrategy === "role", "press-role-targeting did not use role targeting");
+    ensure(rolePress.strict === true, "press-role-targeting did not report strict=true");
+    ensure(rolePress.effectiveDelivery === "keyboard", "press-role-targeting did not use keyboard delivery");
+
+    const untargetedPress = parseJsonResult(
+      "press-page-keyboard",
+      await runRdt([
+        "interact",
+        "press",
+        "--session",
+        sessionName,
+        "--key",
+        "Escape",
+        "--format",
+        "json",
+      ]),
+    );
+    ensure(untargetedPress.action === "press", "press-page-keyboard did not report press action");
+    ensure(untargetedPress.targetingStrategy === null, "press-page-keyboard unexpectedly reported a targetingStrategy");
+    ensure(untargetedPress.target === null, "press-page-keyboard unexpectedly resolved a target");
+    ensure(
+      Array.isArray(untargetedPress.runtimeWarnings)
+        && untargetedPress.runtimeWarnings.some((warning) => warning.includes("active page keyboard focus")),
+      "press-page-keyboard did not warn about page-level keyboard focus",
+    );
+
+    const invalidClickResult = await runRdt([
+      "interact",
+      "click",
+      "--session",
+      sessionName,
+      "--selector",
+      "button.counter",
+      "--text",
+      "Count is",
+    ]);
+    ensure(invalidClickResult.code !== 0, "invalid-click-targeting unexpectedly succeeded");
+    ensure(invalidClickResult.stderr.includes("Use exactly one"), "invalid-click-targeting did not explain the conflicting target failure");
+
+    const invalidTypeResult = await runRdt([
+      "interact",
+      "type",
+      "--session",
+      sessionName,
+      "--text",
+      "hello",
+    ]);
+    ensure(invalidTypeResult.code !== 0, "invalid-type-targeting unexpectedly succeeded");
+    ensure(invalidTypeResult.stderr.includes("Missing type target"), "invalid-type-targeting did not explain the missing target failure");
+
+    const invalidPressResult = await runRdt([
+      "interact",
+      "press",
+      "--session",
+      sessionName,
+      "--key",
+      "Enter",
+      "--strict",
+    ]);
+    ensure(invalidPressResult.code !== 0, "invalid-press-targeting unexpectedly succeeded");
+    ensure(invalidPressResult.stderr.includes("Missing press target"), "invalid-press-targeting did not explain the missing target failure");
+
+    const invalidPressNthResult = await runRdt([
+      "interact",
+      "press",
+      "--session",
+      sessionName,
+      "--key",
+      "Enter",
+      "--nth",
+      "0",
+    ]);
+    ensure(invalidPressNthResult.code !== 0, "invalid-press-nth-targeting unexpectedly succeeded");
+    ensure(invalidPressNthResult.stderr.includes("Missing press target"), "invalid-press-nth-targeting did not explain the missing target failure");
     logScenarioOk("click-targeting-and-delivery");
   } finally {
     await closeSession(sessionName);