Skip to content

Commit a792415

Browse files
committed
revert(selectors): keep agent-device/selectors public, behind one AST subpath
The cutover removed the `agent-device/selectors` public subpath as part of tightening the API. It is in use, so the removal is reverted: the subpath ships the same ten symbols v0.20.5 shipped, with the same signatures. That has to coexist with the reason the package façade is string-only, so the AST leaves through one named door instead of the main one: @agent-device/selectors string-in/string-out; every in-repo consumer @agent-device/selectors/ast the published parser surface; one consumer, src/sdk/selectors.ts `packages/selectors/src/ast.ts` re-exports parseSelectorChain, tryParseSelectorChain, isSelectorToken, the AST-taking findSelectorChainMatch and resolveSelectorChain, isNodeVisible, isNodeEditable, and types SelectorChain / SelectorDiagnostics. `formatSelectorFailure` keeps its published `SelectorChain | string` first parameter as a shim here rather than widening internal/resolve.ts back to a union — the compatibility obligation sits at the boundary that owes it. This is strictly narrower than main, where the AST was reachable from anywhere in src/ via src/selectors/*. Two gates hold it there: facade-symbols.ts pins ./ast to exactly the v0.20.5 list, and package-boundaries.test.ts asserts src/sdk/selectors.ts is the only file outside the package that imports it. Restored alongside: the ./selectors export and tsdown entry/chunk group, the .fallowrc.json entry, the package-exports supported-subpath list, and both client-api.md sections. No CHANGELOG entry — nothing is removed any more. pnpm check green: 602 unit files / 5278 tests, smoke 35 passed / 3 live skipped, layering 71/71 (10 packages, 32 subpaths), depgraph 22/22, mutation config 45/45, fallow clean over 129 changed files, package smoke imported all 12 published entry points with publint and attw passing. Verified functionally against the built dist: the doc's parse -> findSelectorChainMatch example returns the same shapes as before, resolveSelectorChain still returns an AST `selector`, and formatSelectorFailure still accepts a chain.
1 parent e93c7df commit a792415

10 files changed

Lines changed: 128 additions & 6 deletions

File tree

‎.fallowrc.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
"src/sdk/install-source.ts",
1212
"src/sdk/android-adb.ts",
1313
"src/sdk/contracts.ts",
14+
"src/sdk/selectors.ts",
1415
"src/sdk/finders.ts",
1516
"src/bin.ts",
1617
"src/client/companion-tunnel.ts",

‎package.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,10 @@
5858
"types": "./dist/src/contracts.d.ts",
5959
"import": "./dist/src/contracts.js"
6060
},
61+
"./selectors": {
62+
"types": "./dist/src/selectors.d.ts",
63+
"import": "./dist/src/selectors.js"
64+
},
6165
"./finders": {
6266
"types": "./dist/src/finders.d.ts",
6367
"import": "./dist/src/finders.js"

‎packages/selectors/package.json‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
"private": true,
55
"sideEffects": false,
66
"type": "module",
7-
"description": "Private shared selector matching, argument, and replay semantics for agent-device.",
7+
"description": "Shared selector matching, argument, and replay semantics for agent-device. `.` is string-only; `./ast` is the published parser surface behind `agent-device/selectors`.",
88
"dependencies": {
99
"@agent-device/ad-script": "workspace:*",
1010
"@agent-device/contracts": "workspace:*",
@@ -14,6 +14,10 @@
1414
".": {
1515
"types": "./src/index.ts",
1616
"default": "./src/index.ts"
17+
},
18+
"./ast": {
19+
"types": "./src/ast.ts",
20+
"default": "./src/ast.ts"
1721
}
1822
}
1923
}

‎packages/selectors/src/ast.ts‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
// The published selector AST surface, and the ONLY way the parser
2+
// representation leaves this package.
3+
//
4+
// `./index.ts` is string-in/string-out on purpose: every in-repo consumer
5+
// names selectors as text, so the AST has no business crossing that façade,
6+
// and `package-boundaries.test.ts` asserts it does not. But `agent-device/selectors`
7+
// has been a public subpath since before the engine moved in here, and it
8+
// ships the AST — `parseSelectorChain` returning a `SelectorChain` IS the
9+
// published contract. Removing it is a breaking change for consumers who
10+
// parse and match selectors against a snapshot themselves.
11+
//
12+
// So the AST stays exported, through one named subpath instead of being
13+
// reachable from anywhere: `src/sdk/selectors.ts` is its only consumer, and
14+
// `facade-symbols.ts` pins this list to exactly what v0.20.5 shipped. Widening
15+
// it means widening the public package, and the gate makes that a deliberate
16+
// edit rather than a side effect.
17+
import type { SelectorChain } from './internal/parse.ts';
18+
import { formatSelectorFailure as formatSelectorFailureFromText } from './internal/resolve.ts';
19+
import type { SelectorDiagnostics } from './internal/public-resolution-types.ts';
20+
21+
export type { SelectorChain } from './internal/parse.ts';
22+
export type { SelectorDiagnostics } from './internal/public-resolution-types.ts';
23+
24+
export { isSelectorToken, parseSelectorChain, tryParseSelectorChain } from './internal/parse.ts';
25+
export { findSelectorChainMatch, resolveSelectorChain } from './internal/resolve.ts';
26+
export { isNodeEditable, isNodeVisible } from './internal/node.ts';
27+
28+
/**
29+
* The published signature takes a parsed chain or the raw text it came from;
30+
* the engine only ever needs the text. Kept here rather than widening
31+
* `internal/resolve.ts` back to a union, so the compatibility obligation sits
32+
* at the boundary that owes it.
33+
*/
34+
export function formatSelectorFailure(
35+
chain: SelectorChain | string,
36+
diagnostics: SelectorDiagnostics[],
37+
options: { unique?: boolean },
38+
): string {
39+
return formatSelectorFailureFromText(
40+
typeof chain === 'string' ? chain : chain.raw,
41+
diagnostics,
42+
options,
43+
);
44+
}

‎scripts/layering/facade-symbols.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,21 @@ export const FACADE_SYMBOLS: readonly (readonly [string, readonly string[]])[] =
8585
'validateSelectorExpression',
8686
],
8787
],
88+
[
89+
'@agent-device/selectors/ast',
90+
[
91+
'SelectorChain',
92+
'SelectorDiagnostics',
93+
'findSelectorChainMatch',
94+
'formatSelectorFailure',
95+
'isNodeEditable',
96+
'isNodeVisible',
97+
'isSelectorToken',
98+
'parseSelectorChain',
99+
'resolveSelectorChain',
100+
'tryParseSelectorChain',
101+
],
102+
],
88103
[
89104
'@agent-device/ad-script',
90105
[

‎scripts/layering/package-boundaries.test.ts‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import assert from 'node:assert/strict';
66
import fs from 'node:fs';
77
import path from 'node:path';
88
import { test } from 'node:test';
9+
import { listSourceFiles } from './check.ts';
910
import { readFacadeExports, readNamedExports } from './facade-exports.ts';
1011
import { FACADE_SYMBOLS } from './facade-symbols.ts';
1112
import {
@@ -316,7 +317,14 @@ test('the real tree parses, declares, and passes R11', () => {
316317
);
317318
const selectorsPackage = packages.find((pkg) => pkg.name === '@agent-device/selectors');
318319
assert.ok(selectorsPackage, 'selectors package must exist');
319-
assert.deepEqual([...selectorsPackage.exportTargets.keys()], ['@agent-device/selectors']);
320+
// Two subpaths, and the split is the point: `.` is the string-only façade
321+
// every in-repo consumer uses, `./ast` is the published parser surface that
322+
// `agent-device/selectors` has shipped since before the engine moved into
323+
// this package. A third subpath, or the AST leaking into `.`, fails here.
324+
assert.deepEqual([...selectorsPackage.exportTargets.keys()].sort(), [
325+
'@agent-device/selectors',
326+
'@agent-device/selectors/ast',
327+
]);
320328
assert.deepEqual([...selectorsPackage.workspaceDependencies].sort(), [
321329
'@agent-device/ad-script',
322330
'@agent-device/contracts',
@@ -331,6 +339,17 @@ test('the real tree parses, declares, and passes R11', () => {
331339
[],
332340
'selectors façade keeps AST and grammar internals private',
333341
);
342+
// The AST subpath's one in-repo consumer is the published SDK re-export.
343+
// Anything else importing it means the string-only façade was bypassed.
344+
assert.deepEqual(
345+
listSourceFiles()
346+
.filter((file) => !file.startsWith('packages/selectors/'))
347+
.filter((file) =>
348+
fs.readFileSync(path.join(repoRoot, file), 'utf8').includes('@agent-device/selectors/ast'),
349+
),
350+
['src/sdk/selectors.ts'],
351+
'only the published SDK subpath may import the selector AST',
352+
);
334353
const providerWebDriverPackage = packages.find(
335354
(pkg) => pkg.name === '@agent-device/provider-webdriver',
336355
);

‎src/__tests__/package-exports.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ const supportedSubpaths = [
3131
'./android-adb',
3232
'./limrun',
3333
'./contracts',
34+
'./selectors',
3435
'./finders',
3536
];
3637
const typeOnlySubpaths = new Set(['./remote-config']);
@@ -66,7 +67,6 @@ test('package exports only supported public subpaths', () => {
6667

6768
assert.equal(pkg.exports['./android-apps'], undefined);
6869
assert.equal(pkg.exports['./daemon'], undefined);
69-
assert.equal(pkg.exports['./selectors'], undefined);
7070
});
7171

7272
test('every public subpath is backed by a configured tsdown build entry', () => {

‎src/sdk/selectors.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
export type { SelectorChain, SelectorDiagnostics } from '@agent-device/selectors/ast';
2+
3+
export {
4+
findSelectorChainMatch,
5+
formatSelectorFailure,
6+
isNodeEditable,
7+
isNodeVisible,
8+
isSelectorToken,
9+
parseSelectorChain,
10+
resolveSelectorChain,
11+
tryParseSelectorChain,
12+
} from '@agent-device/selectors/ast';

‎tsdown.config.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ const publicSdkChunkGroups = [
5050
/src[\\/]remote[\\/]remote-config-schema\.d\.[cm]?ts$/,
5151
/src[\\/]remote[\\/]remote-config-schema\.ts$/,
5252
],
53+
['sdk-selectors', /src[\\/]sdk[\\/]selectors\.d\.[cm]?ts$/, /src[\\/]sdk[\\/]selectors\.ts$/],
5354
] as const;
5455

5556
export default defineConfig({
@@ -64,6 +65,7 @@ export default defineConfig({
6465
'android-adb': 'src/sdk/android-adb.ts',
6566
limrun: 'src/sdk/limrun.ts',
6667
contracts: 'src/sdk/contracts.ts',
68+
selectors: 'src/sdk/selectors.ts',
6769
finders: 'src/sdk/finders.ts',
6870
'internal/bin': 'src/bin.ts',
6971
'internal/companion-tunnel': 'src/client/companion-tunnel.ts',

‎website/docs/docs/client-api.md‎

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,16 @@ Supported public entry points for Node consumers:
5454
- `centerOfRect(rect)`
5555
- `defaultHintForCode(code)`, `normalizeError(error)`
5656
- types: `DaemonError`, `DaemonInstallSource`, `DaemonRequest`, `DaemonResponse`, `DaemonResponseData`, `JsonRpcId`, `JsonRpcRequestEnvelope`, `LeaseBackend`, `SessionRuntimeHints`
57+
- `agent-device/selectors`
58+
- `parseSelectorChain(expression)`
59+
- `tryParseSelectorChain(expression)`
60+
- `resolveSelectorChain(nodes, chain, options)`
61+
- `findSelectorChainMatch(nodes, chain, options)`
62+
- `formatSelectorFailure(chain, diagnostics, options)`
63+
- `isNodeVisible(node)`
64+
- `isSelectorToken(token)`
65+
- `isNodeEditable(node, platform)`
66+
- types: `SelectorChain`, `SelectorDiagnostics`
5767
- `agent-device/finders`
5868
- `findBestMatchesByLocator(nodes, locator, query, requireRectOrOptions)`
5969
- `parseFindArgs(args)`
@@ -429,6 +439,17 @@ Use `agent-device/remote-config` for profile loading and path resolution, `agent
429439

430440
## Selector helpers
431441

432-
Selector parsing and matching are internal to the CLI/daemon runtime. Consumer code should use the
433-
typed client methods or CLI commands such as `find`, `click`, `fill`, and `wait`; the former
434-
`agent-device/selectors` AST-exporting subpath is no longer part of the public package.
442+
Use `agent-device/selectors` when a remote daemon or bridge needs to parse and match selector expressions without deep-importing daemon internals. Matching is platform-aware because role normalization and editability checks differ by backend.
443+
444+
```ts
445+
import { findSelectorChainMatch, parseSelectorChain } from 'agent-device/selectors';
446+
447+
const chain = parseSelectorChain('role=button label="Continue" visible=true');
448+
449+
const match = findSelectorChainMatch(snapshot.nodes, chain, {
450+
platform: 'android',
451+
requireRect: true,
452+
});
453+
454+
if (!match) {
455+
// Build a daemon-shaped error with formatSelectorFailure(...) if needed.

0 commit comments

Comments
 (0)