Skip to content

Commit 5609156

Browse files
thymikeeclaude
andauthored
docs: new-package publish rule, ADR scope, device-claim recipe, find default action (callstack#4161)
* docs(agents): require a new public package on npm before its PR merges Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * docs(adr): record rejected experiments in their issue, not an ADR Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * docs(sessions): add a recipe to hold a device claim around an external command Fixes callstack#3263 Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * docs(find): show the action as optional and default to click in help Co-Authored-By: Claude Sonnet 5.5 <[email protected]> --------- Co-authored-by: Claude Sonnet 5.5 <[email protected]>
1 parent 38fe9b9 commit 5609156

7 files changed

Lines changed: 48 additions & 22 deletions

File tree

‎docs/adr/FORMAT.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,9 +35,11 @@ Do not record these in an ADR. Send each to its owner:
3535

3636
- Implementation inventories and file maps: the registries, types, and gates that own them.
3737
- Measurements: `docs/evidence/`.
38+
- Experiment logs, run details, and measurements of a rejected alternative: the issue that ran the experiment. The ADR keeps the alternative with a one-line reason.
3839
- Rollout and migration plans: the package docs, the help, or the umbrella issue.
3940
- PR logs and status change-logs: the umbrella issue.
4041

42+
Amend an ADR when its decision, its consequences, or its open gaps change.
4143
Do not repeat general repo guidance that `AGENTS.md` already gives.
4244

4345
## The record stays current

‎docs/agents/pull-requests.md‎

Lines changed: 11 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,32 @@
11
# Open or update a PR
22

3-
A request to open or ship a PR authorizes these steps after validation:
4-
5-
- Branch creation.
6-
- Commits.
7-
- Push.
8-
- PR creation.
9-
10-
Apply authorization already given. Merging and releasing need separate authorization.
3+
After validation, a request to open or ship a PR authorizes branch creation, commits, push, and PR creation. Merging and releasing need separate authorization.
114

125
## Validate
136

147
Follow [validation](testing.md).
158
Record the `check:affected --run --head` receipt in the PR body. A serialized gate stage can validate the pushed head instead.
16-
For unresolved failures, follow the blocked-validation table.
179
An authorized incomplete draft can record a blocker. A blocker is not a pass.
1810
Push once per review round. Each push restarts CI. Drafts skip device lanes.
1911

2012
For device-facing changes, follow [device verification](device-verification.md).
21-
Prove the changed route ran live. Fixtures and adjacent routes do not replace this evidence.
2213
Report missing devices or commands.
2314

2415
- Published: the branch is pushed, the PR is open, and validation status is recorded at a named commit.
25-
- Merge-ready: required checks pass at the actual head, with live evidence for device-facing changes.
16+
- Merge-ready: required checks pass at the head, with live evidence for device-facing changes.
2617

2718
Do not wait for CI merely to report publication.
28-
Do not claim that skipped integration or coverage passed.
19+
Do not report skipped integration or coverage as passed.
20+
21+
## New public package
22+
23+
A new public package under `packages/` needs a safe transition on npm before its PR merges.
24+
First, the maintainer publishes an empty placeholder version, for example `0.0.0`, under a dist-tag other than `latest`.
25+
Then the maintainer configures the npm trusted publisher for the release workflow.
26+
Only after these steps does the PR remove `"private": true`.
2927

3028
## Self-review
3129

32-
Commit the change.
3330
Give an independent reviewer the worktree, the merge-base SHA, the head SHA, and the task requirements.
3431
In the first review, do not supply an implementation summary.
3532
Review that SHA range with AGENTS.md and [review guidance](review.md).
@@ -57,7 +54,7 @@ After a rebase, validate the new head. Keep old evidence attributed to its origi
5754

5855
## PR body
5956

60-
Use ready-for-review by default. When requested or intentionally incomplete, use draft.
57+
Use ready-for-review by default. Use draft when requested or incomplete.
6158
Keep the body below 250 words:
6259

6360
- `## Summary`: include:

‎docs/agents/testing.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,8 @@
99

1010
Serialized validation requires macOS or Linux.
1111
On Windows, use plan mode or focused checks.
12-
Both broad commands and heavy `pnpm gate` ids acquire the same host lock.
1312
Wait for the owner to finish.
14-
Do not add lock wrappers. Do not delete lock files.
13+
Do not add lock wrappers.
1514
A wait ends after two hours.
1615
Focused tests do not lock. Avoid subprocess-heavy tests beside a broad gate.
1716

@@ -43,7 +42,6 @@ The receipt lists skipped checks and owners in `results[].reason`.
4342
GitHub owns full coverage, native builds, device lanes, provider integration, and compatibility that uses history.
4443
On a narrowed plan, related tests replace only provider integration.
4544
A production source change also runs the unit suite (about 3 minutes), because some unit gates read sources as text.
46-
Check the Integration Tests and Coverage jobs at the actual PR head.
4745
For docs-only changes, run the selected documentation checks.
4846
Do not add tests that assert prose.
4947

‎packages/command-surface/src/interaction/index.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -350,9 +350,9 @@ const interactionCliSchemas = {
350350
allowedFlags: [...SELECTOR_SNAPSHOT_FLAGS, 'record'],
351351
},
352352
find: {
353-
usageOverride: 'find <locator|text> <action> [value] [--first|--last]',
353+
usageOverride: 'find <locator|text> [action] [value] [--first|--last]',
354354
usageFlags: [],
355-
positionalArgs: ['query', 'action', 'value?'],
355+
positionalArgs: ['query', 'action?', 'value?'],
356356
allowsExtraPositionals: true,
357357
allowedFlags: ['snapshotDepth', 'snapshotRaw', 'findFirst', 'findLast', 'record'],
358358
},

‎packages/command-surface/src/interaction/metadata.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ const interactionCommandDescriptions = {
7777
'Scroll in a direction, or toward the top/bottom edge of scrollable content. Set until to a selector to reach an off-screen target in one command rather than a scroll-and-check loop. The optional amount is the finger-path fraction of the viewport axis, honored up to 0.8 of it; directional scrolls reduce release momentum, while app scroll physics determine the final content offset. A visible keyboard shortens the swiped band instead of being dismissed; when too little is left, the command refuses with scroll_keyboard_occludes_surface. A directional scroll also reports the movement it observed as movement: moved, at-edge, unchanged, or unobserved when the two reads could not back a claim either way; an unchanged surface inside a container that still hides content in that direction refuses with scroll_no_progress rather than repeating the requested distance. The movement field is absent where a tier verifies per pass (top/bottom, until), where the runtime cannot read a screen, or where a settle observation or a replay already owns that observation.',
7878
get: 'Read text or accessibility attributes from a snapshot ref or selector without changing the app. Use format text for visible content or attrs for the element attribute map.',
7979
is: 'Check whether a selector satisfies a UI predicate such as visible, hidden, exists, absent, editable, selected, focused, or text. `absent` passes only when one readable, complete, settled, unscoped, full-depth accessibility capture has zero matches. Use wait when the condition may appear asynchronously.',
80-
find: 'Find by text/label/value/role/id and run action. The role locator matches snapshot kind vocabulary (button, text, text-field, switch, ...); pre-reconciliation leaf spellings (statictext, edittext, textview) stay accepted on the nodes that carried them during a deprecation window.',
80+
find: 'Find by text/label/value/role/id and run action; the action defaults to click. The role locator matches snapshot kind vocabulary (button, text, text-field, switch, ...); pre-reconciliation leaf spellings (statictext, edittext, textview) stay accepted on the nodes that carried them during a deprecation window.',
8181
gesture:
8282
'Perform a structured pan, fling, swipe, pinch, rotate, transform, tap, or drag gesture. Select the gesture kind, then provide only the inputs that apply to that kind. A tap touches 2 to 5 points at once; repeat it with count and pauseMs.',
8383
} as const;

‎website/docs/docs/selectors.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,9 @@ agent-device find "Follow" list
1818

1919
## Find an element
2020

21-
`find <locator> <query> <action>` takes an optional locator (`text`, `label`, `value`, `role`, or
22-
`id`), the query, and an action. Without a locator it searches labels, values, and ids. Text
21+
`find <query> [action]` and `find <locator> <query> [action] [value]` take an optional locator
22+
(`text`, `label`, `value`, `role`, or `id`), the query, and an optional action; the action defaults to
23+
`click`. Without a locator it searches labels, values, and ids. Text
2324
matches ignore case, and a field containing the query matches too; an exact match wins over a
2425
partial one.
2526

‎website/docs/docs/sessions.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -188,6 +188,34 @@ To free a device:
188188
claim, and reports the release in `warnings`. `device release --stale` never checks for a
189189
reboot, so it keeps refusing a claim whose owner is live.
190190

191+
## Hold a device while an external command runs
192+
193+
Tools like `xcrun simctl install` or `expo run:ios` install without going through a session, so they
194+
ignore claims. To keep other sessions off the device while one runs, claim it first with an app-less
195+
`open` on a uniquely named session, and run the command only if the claim succeeds:
196+
197+
```bash
198+
udid=<udid>
199+
claim="build-$$"
200+
agent-device open --platform ios --udid "$udid" --session "$claim" --timeout 600000 || exit
201+
trap 'agent-device close --session "$claim"' EXIT
202+
xcrun simctl install "$udid" ./App.app
203+
```
204+
205+
- `|| exit` stops the script when another session holds the device (`DEVICE_IN_USE`), so the command
206+
never runs unfenced. Add `--wait <ms>` to `open` to queue for the device instead.
207+
- The script exits with the command's status, as long as the command is the last line. To run
208+
more after it, save `status=$?` and finish with `exit "$status"`.
209+
- The `trap` closes the session whether the command succeeds or fails. Add `--shutdown` to `close` to
210+
shut the simulator or emulator down afterwards.
211+
- `open` without an app boots the device if needed and claims it, so the first call on a cold
212+
simulator can take minutes.
213+
- This is a session claim, not a claim owned by your process. If the shell dies without running its
214+
`trap` (for example `kill -9`), the session keeps the device until you run
215+
`agent-device close --session <name>`. Find the name with `agent-device session list`.
216+
The tool itself is not stopped from touching the device; only other agent-device sessions are
217+
fenced off.
218+
191219
## Notes
192220

193221
- `open <app>` in an existing session switches the active app and updates the session's bundle id.

0 commit comments

Comments
 (0)