Skip to content

Commit c2c7d56

Browse files
committed
docs: update guidance references to kernel/{device,errors} after the move
Follow-up to the path move in this PR: AGENTS.md (Apple-family sync rule + normalizeError), ADR-0009, and plans/apple-platform-consolidation.md still named the old src/utils/{device,errors}.ts paths. Point them at src/kernel/ so future agents do not follow stale paths. plans/perfect-shape.md's utils/device.ts mention is left as-is — it describes the pre-move diagnosis.
1 parent 97509fa commit c2c7d56

3 files changed

Lines changed: 4 additions & 4 deletions

File tree

‎AGENTS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,7 @@ Command-only flags (like `find --first`) that do not flow to the platform layer
139139
- Use `keyboard dismiss` for iOS keyboard dismissal; it may tap safe native controls such as `Done` but must not fall back to system back navigation.
140140
- Do not remove shared snapshot/session model behavior without full migration.
141141
- Command/device support must come from `src/core/capabilities.ts`.
142-
- Apple-family target changes must keep `src/utils/device.ts`, `src/core/capabilities.ts`, `src/core/dispatch-resolve.ts`, `src/platforms/ios/devices.ts`, and `src/platforms/ios/runner-xctestrun.ts` in sync.
142+
- Apple-family target changes must keep `src/kernel/device.ts`, `src/core/capabilities.ts`, `src/core/dispatch-resolve.ts`, `src/platforms/ios/devices.ts`, and `src/platforms/ios/runner-xctestrun.ts` in sync.
143143
- iOS simulator-set scoping is iOS-specific: do not let `iosSimulatorDeviceSet` hide the host macOS desktop target when `--platform macos` or `--target desktop` is requested.
144144
- If Swift runner code changes, run `pnpm build:xcuitest`.
145145
- Use `inferFillText` and `uniqueStrings` from `src/daemon/action-utils.ts`.
@@ -157,7 +157,7 @@ Command-only flags (like `find --first`) that do not flow to the platform layer
157157
- Request diagnostics belong in `sessions/<effective-session>/requests/<request-id>.ndjson` once the effective session is resolved. The top-level daemon log is for daemon lifecycle/startup and pre-session failures.
158158
- Session artifact paths are centralized in `src/daemon/session-store.ts`; do not hand-build session log paths in handlers.
159159
- Do not add ad-hoc stderr/file logging where diagnostics helpers apply.
160-
- Normalize user-facing failures via `src/utils/errors.ts` (`normalizeError`).
160+
- Normalize user-facing failures via `src/kernel/errors.ts` (`normalizeError`).
161161
- Failure payload contract: `code`, `message`, `hint`, `diagnosticId`, `logPath`, `details`.
162162
- User-facing errors should be short and actionable: say what failed, why when known, and how to recover. Put recovery steps in `hint` when the action is not obvious, for example restart/retry, use plain screenshot when AX state is unavailable, navigate with coordinates, or inspect logs.
163163
- If an interaction unexpectedly takes 5+ seconds, inspect the relevant daemon log before attributing it to the app. Check the session `--state-dir` `daemon.log` or the failure `logPath` for runner restart, stale session recovery, AX failure, transport retry, or command timeout evidence.

‎docs/adr/0009-apple-platform-consolidation.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Accepted
99
Apple support is modeled asymmetrically and is physically smeared across an `ios` directory that is really
1010
the shared Apple engine. `Platform` carries `ios` and `macos` as separate literals, but tvOS is not a
1111
platform at all — it is `platform: 'ios' + target: 'tv'`, with the OS name reconstructed late and lossily by
12-
`resolveApplePlatformName` (`src/utils/device.ts`). Meanwhile ~697 LOC of macOS code lives inside
12+
`resolveApplePlatformName` (`src/kernel/device.ts`). Meanwhile ~697 LOC of macOS code lives inside
1313
`src/platforms/ios/`, `src/platforms/macos/devices.ts` is a 19-line stub that the iOS discovery imports (the
1414
dependency arrow points backwards), and the Apple interactor in `src/core/interactors/apple.ts` reaches into
1515
`platforms/ios`. A four-investigator survey found that ~85% of `platforms/ios` (the runner stack,

‎plans/apple-platform-consolidation.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ each OS to its own `Platform` literal. Reasons from the code:
2828
BEFORE — Apple support is smeared across an "iOS" folder that is really the Apple engine
2929
─────────────────────────────────────────────────────────────────────────────────────────
3030
31-
DeviceInfo (src/utils/device.ts)
31+
DeviceInfo (src/kernel/device.ts)
3232
platform: ios | macos | android | linux | web ← macOS is its OWN literal …
3333
kind: simulator | emulator | device
3434
target?: mobile | tv | desktop ← … but tvOS = ios + target:'tv' (asymmetric!)

0 commit comments

Comments
 (0)