Skip to content

Commit db08548

Browse files
authored
refactor: enforce src/utils retirement (#2149) (#2229)
1 parent 947582a commit db08548

23 files changed

Lines changed: 220 additions & 81 deletions

‎.fallowrc.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
"src/bin.ts",
1818
"src/client/companion-tunnel.ts",
1919
"src/daemon.ts",
20-
"src/utils/png-worker.ts",
20+
"packages/capture-kit/src/png-worker.ts",
2121
"scripts/patch-xcuitest-runner-icon.ts",
2222
"scripts/runner-request-count/run.ts",
2323
"packages/capture-kit/src/ios-snapshot-engine/replay.ts",

‎docs/adr/0012-interactive-replay.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1251,7 +1251,7 @@ both `.ad` and Maestro paths) grounds the same conclusions from the caller's sea
12511251
`--json`. Structurally: replay's success payload (`{ replayed, healed, session, artifactPaths }`,
12521252
`session-replay-runtime.ts:186-195`) has no `message` field, so the generic CLI success path prints
12531253
nothing (`writeGenericCliOutput` → `readCommandMessage` → `writeCommandOutput`,
1254-
`src/cli/commands/generic.ts:68-71`, `src/utils/success-text.ts:12-14`,
1254+
`src/cli/commands/generic.ts:68-71`, `packages/kernel/src/success-text.ts:12-14`,
12551255
`src/cli/commands/shared.ts:4-15`). An agent pays a verification turn just to learn what happened.
12561256
- **Failure output today is step + action + selector + a generic hint — no screen evidence.** The live
12571257
divergence hit was pure app state: the RN example app persists navigation state, so relaunch+deeplink

‎docs/adr/0018-unified-event-journal.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,8 @@ Normative summary of the proposal; contracts and rationale below.
5252
The codebase has grown four parallel event vocabularies, each with its own emit call, shape,
5353
redaction discipline, and sink (inventoried 2026-07-24):
5454

55-
1. **Diagnostics** (`src/utils/diagnostics.ts`). ~155 distinct stringly-typed `phase` values across
55+
1. **Diagnostics** (`packages/host-kit/src/internal/diagnostics.ts`).
56+
~155 distinct stringly-typed `phase` values across
5657
~70 files, an `AsyncLocalStorage` request scope entered in exactly three places (CLI pre-parse,
5758
daemon per-request in `request-router.ts`, daemon fatal catch-all), an in-memory buffer plus a
5859
`phaseCounts` tally, and debug-mode live streaming to the per-request ndjson file (after
@@ -134,9 +135,9 @@ Consumers derive kind sets from traits: `RUNNER_ROUND_TRIP_PHASES` becomes
134135
deliberately do not, preserving today's cost semantics). A parity test pins the derived sets so a
135136
trait edit is a reviewed decision, not a drift.
136137

137-
The catalog lives in `contracts` (ranked, kernel-adjacent) so every zone — including unranked
138-
peripherals and `utils` — may import it without a layering back-edge. The journal runtime evolves
139-
in place in `src/utils/diagnostics.ts`, keeping all existing import directions legal.
138+
The catalog lives in `contracts` (ranked, kernel-adjacent) so every zone may import it without a
139+
layering back-edge. The journal runtime evolves in place in
140+
`packages/host-kit/src/internal/diagnostics.ts`, keeping all existing import directions legal.
140141

141142
### 2. One journal, explicit sinks, defined scope model
142143

@@ -361,7 +362,7 @@ gets built.
361362
field is either numeric, an enum imported from the owning registry (command names, error codes,
362363
flag keys), or a hash — and that no open-string field exists; adding one is a failing gate, not
363364
a review comment.
364-
- Layering: `scripts/layering/check.ts` stays green — catalog in `contracts`, runtime in `utils`,
365+
- Layering: `scripts/layering/check.ts` stays green — catalog in `contracts`, runtime in `host-kit`,
365366
no new back-edges.
366367

367368
## Migration plan

‎docs/adr/0019-request-bound-platform-runtime.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -635,8 +635,8 @@ The final gates passed:
635635
- `pnpm check:layering` passed 131 structural/model tests and scanned 1,157 production source files.
636636
R11 owns 17 workspace packages behind 39 exported subpaths with no root back-imports; R13 keeps six
637637
private implementation-lazy platform packages above capture-kit behind one canonical composition
638-
root and its single private provider-composition implementation submodule; R14
639-
and R15 retain one typed route for `logs` and `network` with no legacy route.
638+
root and its single private provider-composition implementation submodule; the historical R14
639+
and R15 rules retained one typed route for `logs` and `network` with no legacy route.
640640
- Six local inventory/runtime owners, all enumerated Apple leaf/kind cells, and the production
641641
BrowserStack, AWS Device Farm, and Limrun provider modes remain covered. Provider ownership and
642642
inventory are fail-closed; exact-owner recovery and provider-authoritative tests prove there is no

‎docs/agents/testing.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,7 @@ whether tests distinguish changed decision logic. Do not infer redundancy from l
129129
Run `pnpm depgraph affected` before touching a high-fan-in module:
130130

131131
```sh
132-
pnpm depgraph affected packages/capture-kit/src/exec.ts
132+
pnpm depgraph affected packages/host-kit/src/command.ts
133133
pnpm depgraph affected src/daemon/ref-frame.ts --json --limit 25
134134
```
135135

‎docs/dependency-graph-findings.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,8 +56,9 @@ raw edge count reads higher.
5656

5757
What moved: the platform-plugin contract and its four facet tags, `NetworkEntry`, the
5858
click-button / recording-export-quality / interactor-types / runner-lease-context vocabularies,
59-
and 16 internal modules out of `(root)`; `utils` joined the spine at rank 1 after its two upward
60-
files moved to the zones they were reaching for. Three new gate scopes keep it: R6 ratchets
59+
and 16 internal modules out of `(root)`; the historical audit reported that `utils` joined the
60+
spine at rank 1 after its two upward files moved to the zones they were reaching for. Three new
61+
gate scopes keep it: R6 ratchets
6162
type-only inversions, R7 pins SessionState field ownership, and the shared selector checks in
6263
`selectors/` are covered by their own tests.
6364

‎fallow-baselines/health.json‎

Lines changed: 5 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -466,11 +466,6 @@
466466
"count": 1
467467
}
468468
},
469-
"src/utils/exec.ts": {
470-
"complexity_moderate": {
471-
"count": 1
472-
}
473-
},
474469
"src/commands/output/snapshot.ts": {
475470
"crap_moderate": {
476471
"count": 1
@@ -481,24 +476,11 @@
481476
"count": 1
482477
}
483478
},
484-
"src/utils/retry.ts": {
485-
"complexity_high": {
486-
"count": 1
487-
}
488-
},
489479
"src/snapshot/scroll-edge-state.ts": {
490480
"crap_moderate": {
491481
"count": 1
492482
}
493483
},
494-
"src/utils/source-value.ts": {
495-
"complexity_high": {
496-
"count": 1
497-
},
498-
"crap_moderate": {
499-
"count": 1
500-
}
501-
},
502484
"src/snapshot/snapshot-presentation/text-surface.ts": {
503485
"crap_high": {
504486
"count": 1
@@ -570,14 +552,13 @@
570552
"src/daemon/handlers/session-state.ts:complexity",
571553
"src/commands/cli-grammar/common.ts:high impact",
572554
"src/snapshot/snapshot-presentation/tree.ts:high impact",
573-
"src/utils/success-text.ts:high impact",
555+
"packages/kernel/src/success-text.ts:high impact",
574556
"src/cli.ts:complexity",
575-
"src/utils/timeouts.ts:high impact",
576557
"src/commands/interaction/output.ts:high impact",
577558
"src/snapshot/snapshot-lines.ts:high impact",
578-
"src/utils/rect-center.ts:high impact",
559+
"packages/kernel/src/rect-center.ts:high impact",
579560
"packages/platform-apple/src/core/app-launch.ts:complexity",
580-
"src/utils/parsing.ts:high impact",
561+
"packages/kernel/src/record.ts:high impact",
581562
"src/daemon/daemon-command-registry.ts:high impact",
582563
"src/replay/script.ts:complexity",
583564
"src/daemon/handlers/session-doctor-output.ts:high impact",
@@ -593,14 +574,13 @@
593574
"packages/platform-linux/src/snapshot.ts:high impact",
594575
"src/core/interaction-targeting.ts:high impact",
595576
"packages/maestro/src/internal/runtime-targets.ts:high impact",
596-
"src/utils/source-value.ts:high impact",
577+
"packages/kernel/src/source-value.ts:high impact",
597578
"src/request/cancel.ts:high impact",
598579
"src/commands/interaction/selectors.ts:untested risk",
599580
"packages/selectors/src/internal/build.ts:high impact",
600581
"src/kernel/redaction.ts:high impact",
601-
"src/utils/rect-visibility.ts:high impact",
602582
"packages/provider-webdriver/src/webdriver-utils.ts:high impact",
603-
"src/utils/keyed-lock.ts:high impact",
583+
"packages/kernel/src/keyed-lock.ts:high impact",
604584
"src/daemon/request-progress-protocol.ts:high impact",
605585
"src/cli/replay-test/reporters/format.ts:high impact",
606586
"src/daemon/replay/internal/session-test-infrastructure.ts:high impact",

‎packages/platform-android/src/__tests__/adb-executor.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -485,8 +485,8 @@ test('the local adb executor flags transient transport failures retriable', asyn
485485

486486
test('the local adb executor classifies exec-layer timeouts as a wedged adb server', async () => {
487487
mockRunCmd.mockClear();
488-
// Shape of createTimeoutError in utils/exec.ts: no stderr to classify, the
489-
// structured `timeoutMs` detail is the signal.
488+
// Shape of `createTimeoutError` in `packages/host-kit/src/internal/exec.ts`: no
489+
// stderr to classify, the structured `timeoutMs` detail is the signal.
490490
mockRunCmd.mockRejectedValueOnce(
491491
new AppError('COMMAND_FAILED', 'adb timed out after 10000ms', {
492492
cmd: 'adb',

‎packages/platform-apple/src/runner/__tests__/runner-lease-recycled-pid.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,8 @@ import {
4141
* pinning the read is the point rather than a workaround.
4242
*/
4343

44-
// Process execution goes through utils/exec.ts, never node:child_process
45-
// directly (AGENTS.md hard rule) — including in tests.
44+
// Process execution goes through @agent-device/host-kit/command, never node:child_process
45+
// directly — including in tests.
4646
let child: ExecBackgroundResult | undefined;
4747
let previousLeaseDir: string | undefined;
4848

‎packages/selectors/src/internal/parse.ts‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -58,9 +58,8 @@ export const SELECTOR_KEY_NAMES: readonly SelectorKey[] = [...ALL_KEYS];
5858
// `button` in `button="Push Article"`). Superset of the ROLE_LABELS vocabulary in
5959
// src/snapshot/snapshot-lines.ts (plus a few common role words like list/tab/alert/dialog/header,
6060
// minus valid selector keys such as `text`, which ALL_KEYS short-circuits before this set is
61-
// consulted), kept as a local copy to avoid a utils/ -> snapshot/ layering dependency
62-
// (scripts/layering/check.ts). Drifts silently if ROLE_LABELS grows; that's fine here since this
63-
// is only used to sharpen a hint, not to validate anything.
61+
// consulted), kept locally to avoid a selectors -> snapshot layering dependency. Drifts silently
62+
// if ROLE_LABELS grows; that's fine here since this only sharpens a hint, not validates anything.
6463
const ROLE_HINT_WORDS = new Set([
6564
'button',
6665
'imagebutton',

0 commit comments

Comments
 (0)