@qvac/core 0.3.0 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (191) hide show
  1. package/dist-lib/lib/api/chat.d.ts +3 -1
  2. package/dist-lib/lib/api/chat.js +6 -2
  3. package/dist-lib/lib/api/index.d.ts +2 -0
  4. package/dist-lib/lib/api/index.js +3 -1
  5. package/dist-lib/lib/api/inference-calls.d.ts +18 -0
  6. package/dist-lib/lib/api/inference-calls.js +15 -0
  7. package/dist-lib/lib/api/rag.js +10 -2
  8. package/dist-lib/lib/assistant/harness.d.ts +1 -0
  9. package/dist-lib/lib/assistant/history.d.ts +10 -1
  10. package/dist-lib/lib/assistant/history.js +36 -1
  11. package/dist-lib/lib/assistant/message.d.ts +2 -0
  12. package/dist-lib/lib/assistant/message.js +11 -0
  13. package/dist-lib/lib/assistant/skill-encode.js +27 -1
  14. package/dist-lib/lib/assistant-tree.d.ts +2 -0
  15. package/dist-lib/lib/assistant-tree.js +11 -2
  16. package/dist-lib/lib/assistant.d.ts +19 -3
  17. package/dist-lib/lib/assistant.js +148 -23
  18. package/dist-lib/lib/core/chunk.js +5 -0
  19. package/dist-lib/lib/core/files/rag/build.d.ts +1 -2
  20. package/dist-lib/lib/core/files/rag/build.js +1 -2
  21. package/dist-lib/lib/core/files/rag/extract/office-collabora.d.ts +1 -1
  22. package/dist-lib/lib/core/files/rag/index.d.ts +4 -24
  23. package/dist-lib/lib/core/files/rag/index.js +3 -17
  24. package/dist-lib/lib/core/files/rag/load.d.ts +1 -2
  25. package/dist-lib/lib/core/files/rag/load.js +1 -2
  26. package/dist-lib/lib/core/files/rag/produce.d.ts +1 -1
  27. package/dist-lib/lib/core/files/rag/produce.js +1 -3
  28. package/dist-lib/lib/core/files/rag/retrieval/full-text.d.ts +1 -1
  29. package/dist-lib/lib/core/files/rag/retrieval/full-text.js +1 -4
  30. package/dist-lib/lib/core/files/rag/similarity.d.ts +5 -0
  31. package/dist-lib/lib/core/files/rag/similarity.js +6 -0
  32. package/dist-lib/lib/core/files/upload.d.ts +1 -1
  33. package/dist-lib/lib/core/inference-calls-handoff.d.ts +20 -0
  34. package/dist-lib/lib/core/inference-calls-handoff.js +37 -0
  35. package/dist-lib/lib/core/inference-calls-receiver.d.ts +14 -0
  36. package/dist-lib/lib/core/inference-calls-receiver.js +39 -0
  37. package/dist-lib/lib/core/notification.js +5 -4
  38. package/dist-lib/lib/core/skill-secrets.js +3 -6
  39. package/dist-lib/lib/core.d.ts +9 -1
  40. package/dist-lib/lib/core.js +129 -13
  41. package/dist-lib/lib/credential-pusher.d.ts +2 -3
  42. package/dist-lib/lib/credential-pusher.js +67 -39
  43. package/dist-lib/lib/inference-calls.d.ts +40 -0
  44. package/dist-lib/lib/inference-calls.js +266 -0
  45. package/dist-lib/lib/integrations/index.d.ts +1 -2
  46. package/dist-lib/lib/integrations/index.js +0 -1
  47. package/dist-lib/lib/integrations/setup-routes.js +0 -15
  48. package/dist-lib/lib/oauth/flow-core.js +1 -1
  49. package/dist-lib/lib/oauth/flow.d.ts +4 -2
  50. package/dist-lib/lib/oauth/flow.js +3 -4
  51. package/dist-lib/lib/oauth/host.d.ts +3 -1
  52. package/dist-lib/lib/oauth/host.js +3 -1
  53. package/dist-lib/lib/oauth/keys.d.ts +21 -20
  54. package/dist-lib/lib/oauth/keys.js +59 -85
  55. package/dist-lib/lib/oauth/loopback.d.ts +2 -2
  56. package/dist-lib/lib/oauth/loopback.js +32 -19
  57. package/dist-lib/lib/oauth/loopback.stub.d.ts +2 -2
  58. package/dist-lib/lib/oauth/loopback.stub.js +2 -2
  59. package/dist-lib/lib/oauth/providers.d.ts +3 -5
  60. package/dist-lib/lib/oauth/providers.js +20 -67
  61. package/dist-lib/lib/oauth/redirect-types.d.ts +1 -0
  62. package/dist-lib/lib/oauth/registry.d.ts +10 -0
  63. package/dist-lib/lib/oauth/registry.js +25 -0
  64. package/dist-lib/lib/oauth/resolve.js +1 -1
  65. package/dist-lib/lib/oauth/token-exchange-core.js +2 -1
  66. package/dist-lib/lib/oauth/types.d.ts +1 -1
  67. package/dist-lib/lib/oauth.client.d.ts +3 -1
  68. package/dist-lib/lib/oauth.client.js +3 -1
  69. package/dist-lib/lib/oauth.d.ts +4 -7
  70. package/dist-lib/lib/oauth.js +4 -7
  71. package/dist-lib/lib/skill-types.d.ts +12 -0
  72. package/dist-lib/schema/content.js +5 -1
  73. package/dist-lib/schema/engine.js +63 -2
  74. package/dist-lib/schema/qvac.js +4 -2
  75. package/dist-lib/spec/bind.js +3 -0
  76. package/dist-lib/spec/calls.js +1 -0
  77. package/dist-lib/spec/capabilities.d.ts +2 -0
  78. package/dist-lib/spec/hrpc/hrpc.json +13 -0
  79. package/dist-lib/spec/hrpc/index.js +15 -3
  80. package/dist-lib/spec/hrpc/messages.js +284 -52
  81. package/dist-lib/spec/hyperschema/index.js +284 -52
  82. package/dist-lib/spec/hyperschema/schema.json +210 -1
  83. package/dist-lib/spec/hyperschema/types.d.ts +51 -1
  84. package/dist-lib/spec/local/hyperdb/messages.js +64 -128
  85. package/dist-lib/spec/local/hyperschema/index.js +32 -64
  86. package/dist-lib/spec/local/hyperschema/schema.json +16 -0
  87. package/dist-lib/spec/mesh/hyperdb/messages.js +176 -311
  88. package/dist-lib/spec/mesh/hyperdispatch/messages.js +132 -236
  89. package/dist-lib/spec/mesh/hyperschema/index.js +132 -236
  90. package/dist-lib/spec/mesh/hyperschema/schema.json +70 -1
  91. package/dist-lib/spec/mesh/hyperschema/types.d.ts +3 -1
  92. package/package.json +15 -18
  93. package/tui/app.mjs +98 -155
  94. package/tui/lib/knowledge-import.mjs +1 -1
  95. package/tui/lib/save-file.mjs +1 -1
  96. package/.claude/skills/asana/SKILL.md +0 -86
  97. package/.claude/skills/compaction/SKILL.md +0 -136
  98. package/.claude/skills/device-mesh-debug/SKILL.md +0 -328
  99. package/.claude/skills/gh-stack/SKILL.md +0 -181
  100. package/.claude/skills/gh-stack/references/commands.md +0 -177
  101. package/.claude/skills/gh-stack/references/stack-design.md +0 -97
  102. package/.claude/skills/gh-stack/references/troubleshooting.md +0 -159
  103. package/.claude/skills/js-house-style/SKILL.md +0 -671
  104. package/.claude/skills/pr-create/SKILL.md +0 -243
  105. package/.claude/skills/pr-review/SKILL.md +0 -428
  106. package/.claude/skills/release/SKILL.md +0 -122
  107. package/CLAUDE.md +0 -48
  108. package/dist-lib/lib/core/files/rag/artifact/codec.d.ts +0 -3
  109. package/dist-lib/lib/core/files/rag/artifact/codec.js +0 -172
  110. package/dist-lib/lib/core/files/rag/artifact/id.d.ts +0 -10
  111. package/dist-lib/lib/core/files/rag/artifact/id.js +0 -39
  112. package/dist-lib/lib/core/files/rag/artifact/types.d.ts +0 -24
  113. package/dist-lib/lib/core/files/rag/artifact/types.js +0 -41
  114. package/dist-lib/lib/core/files/rag/chunk/chunking.d.ts +0 -12
  115. package/dist-lib/lib/core/files/rag/chunk/chunking.js +0 -117
  116. package/dist-lib/lib/core/files/rag/chunk/metadata.d.ts +0 -30
  117. package/dist-lib/lib/core/files/rag/chunk/metadata.js +0 -89
  118. package/dist-lib/lib/core/files/rag/chunk/tokenizer.d.ts +0 -7
  119. package/dist-lib/lib/core/files/rag/chunk/tokenizer.js +0 -18
  120. package/dist-lib/lib/core/files/rag/extract/csv-text.d.ts +0 -1
  121. package/dist-lib/lib/core/files/rag/extract/csv-text.js +0 -117
  122. package/dist-lib/lib/core/files/rag/extract/document-types.d.ts +0 -22
  123. package/dist-lib/lib/core/files/rag/extract/document-types.js +0 -152
  124. package/dist-lib/lib/core/files/rag/extract/extract.d.ts +0 -17
  125. package/dist-lib/lib/core/files/rag/extract/extract.js +0 -81
  126. package/dist-lib/lib/core/files/rag/extract/html-table-text.d.ts +0 -1
  127. package/dist-lib/lib/core/files/rag/extract/html-table-text.js +0 -125
  128. package/dist-lib/lib/core/files/rag/extract/html-text.d.ts +0 -1
  129. package/dist-lib/lib/core/files/rag/extract/html-text.js +0 -132
  130. package/dist-lib/lib/core/files/rag/extract/pdf-platform.d.ts +0 -17
  131. package/dist-lib/lib/core/files/rag/extract/pdf-platform.js +0 -141
  132. package/dist-lib/lib/core/files/rag/extract/pdf-text.d.ts +0 -12
  133. package/dist-lib/lib/core/files/rag/extract/pdf-text.js +0 -43
  134. package/dist-lib/lib/core/files/rag/extract/rtf-text.d.ts +0 -1
  135. package/dist-lib/lib/core/files/rag/extract/rtf-text.js +0 -15
  136. package/dist-lib/lib/core/files/rag/extract/text-decoding.d.ts +0 -1
  137. package/dist-lib/lib/core/files/rag/extract/text-decoding.js +0 -91
  138. package/dist-lib/lib/core/files/rag/extract/types.d.ts +0 -36
  139. package/dist-lib/lib/core/files/rag/extract/types.js +0 -12
  140. package/dist-lib/lib/core/files/rag/extract/utf.d.ts +0 -2
  141. package/dist-lib/lib/core/files/rag/extract/utf.js +0 -18
  142. package/dist-lib/lib/core/files/rag/retrieval/citation-match.d.ts +0 -2
  143. package/dist-lib/lib/core/files/rag/retrieval/citation-match.js +0 -16
  144. package/dist-lib/lib/core/files/rag/retrieval/coverage.d.ts +0 -4
  145. package/dist-lib/lib/core/files/rag/retrieval/coverage.js +0 -48
  146. package/dist-lib/lib/core/files/rag/retrieval/diversity.d.ts +0 -10
  147. package/dist-lib/lib/core/files/rag/retrieval/diversity.js +0 -37
  148. package/dist-lib/lib/core/files/rag/retrieval/floor.d.ts +0 -5
  149. package/dist-lib/lib/core/files/rag/retrieval/floor.js +0 -21
  150. package/dist-lib/lib/core/files/rag/retrieval/format.d.ts +0 -6
  151. package/dist-lib/lib/core/files/rag/retrieval/format.js +0 -21
  152. package/dist-lib/lib/core/files/rag/retrieval/knowledge.d.ts +0 -2
  153. package/dist-lib/lib/core/files/rag/retrieval/knowledge.js +0 -54
  154. package/dist-lib/lib/core/files/rag/retrieval/notices.d.ts +0 -16
  155. package/dist-lib/lib/core/files/rag/retrieval/notices.js +0 -27
  156. package/dist-lib/lib/core/files/rag/retrieval/scoring.d.ts +0 -8
  157. package/dist-lib/lib/core/files/rag/retrieval/scoring.js +0 -82
  158. package/dist-lib/lib/core/files/rag/retrieval/search.d.ts +0 -3
  159. package/dist-lib/lib/core/files/rag/retrieval/search.js +0 -49
  160. package/dist-lib/lib/core/files/rag/retrieval/selection.d.ts +0 -11
  161. package/dist-lib/lib/core/files/rag/retrieval/selection.js +0 -93
  162. package/dist-lib/lib/core/files/rag/retrieval/source-tag-filter.d.ts +0 -6
  163. package/dist-lib/lib/core/files/rag/retrieval/source-tag-filter.js +0 -79
  164. package/dist-lib/lib/core/files/rag/retrieval/sources.d.ts +0 -13
  165. package/dist-lib/lib/core/files/rag/retrieval/sources.js +0 -20
  166. package/dist-lib/lib/core/files/rag/retrieval/target.d.ts +0 -13
  167. package/dist-lib/lib/core/files/rag/retrieval/target.js +0 -89
  168. package/dist-lib/lib/core/files/rag/retrieval/terms.d.ts +0 -8
  169. package/dist-lib/lib/core/files/rag/retrieval/terms.js +0 -70
  170. package/dist-lib/lib/core/files/rag/retrieval/types.d.ts +0 -29
  171. package/dist-lib/lib/core/files/rag/retrieval/types.js +0 -1
  172. package/dist-lib/lib/core/files/rag/retrieval/web-sources.d.ts +0 -8
  173. package/dist-lib/lib/core/files/rag/retrieval/web-sources.js +0 -41
  174. package/dist-lib/lib/core/files/rag/retrieval/whole-document-query.d.ts +0 -1
  175. package/dist-lib/lib/core/files/rag/retrieval/whole-document-query.js +0 -96
  176. package/dist-lib/lib/core/files/rag/vector/memory.d.ts +0 -15
  177. package/dist-lib/lib/core/files/rag/vector/memory.js +0 -135
  178. package/dist-lib/lib/core/files/rag/vector/types.d.ts +0 -28
  179. package/dist-lib/lib/core/files/rag/vector/types.js +0 -1
  180. package/dist-lib/lib/integrations/oauth-providers.d.ts +0 -14
  181. package/dist-lib/lib/integrations/oauth-providers.js +0 -116
  182. package/dist-lib/lib/oauth/asana.d.ts +0 -35
  183. package/dist-lib/lib/oauth/asana.js +0 -71
  184. package/dist-lib/lib/oauth/google.d.ts +0 -37
  185. package/dist-lib/lib/oauth/google.js +0 -77
  186. package/dist-lib/lib/oauth/notion.d.ts +0 -34
  187. package/dist-lib/lib/oauth/notion.js +0 -82
  188. package/dist-lib/lib/oauth/spotify.d.ts +0 -32
  189. package/dist-lib/lib/oauth/spotify.js +0 -74
  190. package/dist-lib/lib/oauth/verify.d.ts +0 -8
  191. package/dist-lib/lib/oauth/verify.js +0 -58
@@ -1,328 +0,0 @@
1
- ---
2
- name: device-mesh-debug
3
- description: Diagnose, reproduce, fix and verify mobile + mesh bugs on a device or iOS simulator, driving a real phone against a scriptable bare mesh peer built on this repo's Core. Pairs adb/idb (launch, logs, screenshots, UI driving, and creating a simulator when none exists) with a peer that mints/joins a mesh and grows its oplog on command, so "the phone is behind" states can be produced deliberately. Use for on-device hangs, slow boots, sync gaps, or anything that only shows up against a busy mesh.
4
- ---
5
-
6
- # On-device mobile + mesh debugging
7
-
8
- Mesh bugs cannot be reproduced from a unit test alone: they need a real device
9
- and a real peer that is _ahead_ of it. `adb` and `idb` give you the device. This
10
- repo's `examples/` give you the other side.
11
-
12
- The mesh peer is a real `Core` from this repo on the **public DHT** — the same
13
- class the app runs — driven over stdin. Not a mock, not a testnet.
14
-
15
- > The **app** under test is built from `tetherto/qvac-app` (Expo/React Native),
16
- > which is where the build commands below run. The **peer, the device driver and
17
- > the scenarios** are here. That split is the only reason a section below talks
18
- > about a directory this repo does not contain.
19
-
20
- Both platforms go through one interface. `QVAC_TARGET=android` (default) uses
21
- `adb`; `QVAC_TARGET=ios` uses `idb` plus `simctl`, and **provisions a simulator
22
- when there is none** — a machine whose `~/Library/Developer/CoreSimulator/Devices`
23
- has been pruned lists dozens of devices that all fail to boot with "The device's
24
- data is no longer present", so `ensureTarget()` prunes and creates one.
25
-
26
- ## The loop
27
-
28
- 1. **Reproduce on device first**, and capture the log window that brackets the
29
- symptom. Do not theorise from source before you have a timestamped trace.
30
- 2. **Narrow to a unit test.** Once you can name the blocking call, reproduce it
31
- in `test/basic/` — a device repro is evidence, a test is a regression guard.
32
- The sharpest shape is one that parks `Mesh._open`, so anything that secretly
33
- needs the mesh hangs instead of passing slowly.
34
- 3. **Prove the test catches it** by reverting the fix. A test that passes both
35
- before and after is worthless.
36
- 4. **Verify on device again**, same package, same load.
37
-
38
- ## Tools
39
-
40
- From the repo root:
41
-
42
- ```bash
43
- bun run mesh-peer # the peer alone, stdin-driven
44
- bun run mesh-lab <scenario> # peer + phone, orchestrated
45
- ```
46
-
47
- `examples/mesh-peer.mjs` — runs under `bare`. Prints `STORAGE`, `DEVICE`,
48
- `INVITE`, then `READY`. Commands, one per line, answered on stdout:
49
-
50
- | command | answer | notes |
51
- | ------------------------------- | ---------------------------------- | ------------------------------------------------------------ |
52
- | `invite` | `INVITE qvac://mesh/…` | this peer's mesh |
53
- | `devices` | `DEVICES aabbccdd,…` | 8-char device id prefixes |
54
- | `join <invite>` | `JOINED` | switch onto the phone's mesh |
55
- | `chats` | `CHATS <n>` | what this peer can see |
56
- | `seed [chats] [chunks] [title]` | `SEED i/n` … `SEEDED` | grows the oplog |
57
- | `state` | `STATE members=… devices=… live=…` | one parseable line of membership |
58
- | `members` / `rows` / `activity` | listings | membership is mesh-internal; no RPC carries it |
59
- | `ourmember` | `OURMEMBER aabbccdd` | this peer's member id |
60
- | `align` | `ALIGN flushes=…` | `host.clock`, the number the phone's debug panel shows |
61
- | `ff` | `FF <n>` | gaps crossed by adopting a head instead of replaying into it |
62
- | `len <deviceprefix>` | `LEN <n>` | a writer's oplog length |
63
- | `kick <deviceprefix>` | `KICKED aabbccdd` | revoke on demand |
64
- | `write [title]` | `WROTE <chatId>` | one cheap op |
65
- | `quit` | — | closes cleanly |
66
-
67
- Commands are serialised, so a piped script is safe.
68
-
69
- `examples/device.mjs` — the platform-neutral surface: `ensureTarget`, `launch`,
70
- `stop`, `deepLink`, `installed`, `resetApp`, `clearLogs`, `logs`, `timeBoot`,
71
- `timeBootUntil`, `launchTiming`, `bootTrace`, `bootReport`, `bootPhase`,
72
- `screenshot`, `typeText`, `swipe`, `setAirplaneMode` (Android only), plus UI
73
- driving (`nodes`, `ids`, `strings`, `find`, `waitFor`, `tap`, `tapUntil`,
74
- `tapIfPresent`, `tapNode`, and `byId`/`byText`/`byTextStart`/`byExactText`). It
75
- picks a backend and nothing above it is platform-aware.
76
-
77
- `examples/device-adb.mjs` / `examples/device-idb.mjs` — the backends. Both
78
- return the same normalized node: `{ id, strings, bounds: [x1,y1,x2,y2], raw }`.
79
- `id` is the `testID` either way (`resource-id` on Android, `AXUniqueId` on iOS),
80
- and `strings` collects every textual value on the node (`text` +
81
- `content-desc`; `AXLabel` + `AXValue` + `title`) so one matcher works on both.
82
-
83
- `examples/boot-report-parse.mjs` — `parseBootReport`, `filterBootLines` and
84
- `checkBootConcurrency`, kept separate from the backends so the boot assertions
85
- are unit-testable without a device.
86
-
87
- `examples/mesh-lab.mjs` — scenarios: `pair`, `grow`, `boot-timing`, `converge`,
88
- `chaos` (membership under kill/reboot/kick/interrupted-rejoin), `trio` (the
89
- phone owns the member and two peers join at once), `partition` (airplane mode
90
- under a running app). `chaos` onboards a fresh install itself (Get Started →
91
- name → "Run QVAC on this device" → model → shell; nothing waits on the download),
92
- and pairs in whichever direction the platform allows: Android takes the invite as
93
- a deep link, iOS has the peer join the phone's mesh, so there the phone owns the
94
- member and its own pass attests the peer.
95
-
96
- Env: `QVAC_TARGET`, `QVAC_PKG`, `MESH_STORAGE`, `MESH_CHATS`, `MESH_CHUNKS`,
97
- `MESH_TITLE`, `MESH_DEVICE`, `MESH_INVITE`, `QVAC_LOG_WINDOW`; iOS also takes
98
- `QVAC_SIM` (device name, default `qvac-mesh-lab`) and `QVAC_SIM_DEVICE` (e.g.
99
- `iPhone-17-Pro`).
100
-
101
- ```bash
102
- QVAC_TARGET=ios QVAC_PKG=io.tether.qvac bun run mesh-lab boot-timing
103
- ```
104
-
105
- The app id is the same string on both platforms (`io.tether.qvac`,
106
- `.development`, `.staging`).
107
-
108
- `MESH_STORAGE` defaults to a stable path so the peer keeps its identity across
109
- runs. Only set it to run two independent peers, and do not hand-write the
110
- default — `os.tmpdir()` is not `/tmp` on macOS, so a guessed path mints a _new_
111
- mesh and the phone is no longer on it. `mesh-lab` refuses to run a scenario
112
- against a mesh the phone has not joined; run `pair` deliberately.
113
-
114
- Pairing a phone onto successive throwaway meshes leaves it a writer in a mesh
115
- with no surviving peers, and its autobee dies with `No local nodes` — the app
116
- then shows "Core v2 mesh reported an error". Recover with
117
- `adb shell pm clear <pkg>` and pair once.
118
-
119
- ## Producing "the phone is behind"
120
-
121
- This is the state most mesh bugs need, and the order matters:
122
-
123
- ```bash
124
- QVAC_PKG=io.tether.qvac MESH_CHATS=15 MESH_CHUNKS=40 bun run mesh-lab boot-timing
125
- ```
126
-
127
- Pair → kill the phone → grow the mesh while it is gone → relaunch and time it.
128
- Growing _before_ the kill just replicates normally and reproduces nothing.
129
-
130
- ## Boot timing
131
-
132
- Measure the tight window, not wall-clock. The app prints its whole boot timeline
133
- as one `[BOOT]` block when the splash hides, and `bootReport()` parses it into
134
- `{ phases, note, totalMs, unmeasured, late }`; `bootPhase('harness', 'entry')`
135
- picks one out. `bootTrace()` still returns the raw lines.
136
-
137
- Both worklets forward their marks to the host over the ipc they already hold, so
138
- the whole timeline is one `console.log` that cannot interleave with the two
139
- worklets logging concurrently. **`grep ':boot]'` finds the block's boundaries —
140
- its header, its `BOOT total:` and any `BOOT late:` line — and nothing else;** the
141
- phase lines, `[DEVICE]` and `note:` carry no tag, so `bootReport()` is what reads
142
- the interior. Separately the app's own splash, error boundary and fresh-install
143
- guard print bare `[boot]` _failure_ messages with no timings, and on a wedged
144
- boot those are the only lines there are — `bootTrace()` matches them, so use it
145
- before concluding the app printed nothing.
146
-
147
- `mesh-lab boot-timing` asserts the concurrency, not just a wall-clock number:
148
- `checkBootConcurrency(report)` requires the two `worklet boot` marks to start
149
- within 200ms of each other and no harness phase to land after the gate, and it
150
- throws when a hard check fails. Both launch marks are stamped where the work
151
- happens, so moving the prestart below the assistant worklet's start drifts them
152
- apart rather than leaving a green assertion behind. Do **not** assert that the
153
- harness reaches a later phase before the assistant does: the assistant
154
- legitimately wins that race once its own graph shrinks, which is why the ready
155
- margin is soft.
156
-
157
- Phases are concurrent, so read `startOffset` rather than summing durations. A
158
- component still running when the gate closed renders `(open)`; a phase that
159
- lands after the gate gets its own `BOOT late:` line, which is exactly how a
160
- deferred child creeping back onto the critical path shows up.
161
-
162
- `totalMs` starts at the first JS the app can reach, so it excludes the native
163
- process start and RN init that `unmeasured` names — around 650–850ms on a Pixel
164
- 6 Pro. Never quote it against `launchTiming` or an `am start` figure.
165
-
166
- ## A fast splash proves nothing on its own
167
-
168
- If the fix defers work, show the work still lands — otherwise "fast" may mean
169
- "never saw the mesh". `mesh-lab converge` seeds a titled batch and then asserts
170
- those chats render on the phone. Use a distinctive `MESH_TITLE`.
171
-
172
- ## Reading the boot chain
173
-
174
- Mobile blocks its splash on the whole worklet tree, so anything slow inside it
175
- _is_ splash time:
176
-
177
- ```
178
- splash ← the app's root boot ← await ipc.ready
179
- ← stowEntry ready() ← await sup.ready() (bare-supervisor/entry)
180
- ← Supervisor._boot() starts children SERIALLY: core → engine → harness → assistant
181
- ← QvacAssistant._open()
182
- ```
183
-
184
- `await ipc.ready` happens _before_ the app's store is built, so a slow child is
185
- not "slow after load" — it is a blank screen.
186
-
187
- Corollary worth internalising: **`mesh.dispatch()` awaits a full mesh drain.**
188
- `autobee.append()` returns `_bump()`, the shared drain promise, and `update()`
189
- is the same call. So any mesh write on a boot path waits out replication. The
190
- write itself is a RAM enqueue; durability comes from `flushLocal` inside the
191
- drain.
192
-
193
- ## Getting your Core change onto the phone
194
-
195
- The app builds from `tetherto/qvac-app`; these are its traps, and they are how a
196
- Core change silently fails to ship.
197
-
198
- - **Verify the APK carries your change.** `expo run:android --variant release`
199
- reuses a cached JS bundle. Delete
200
- `android/app/build/generated/assets/react/release` and
201
- `android/app/build/intermediates/assets/release` first, then confirm:
202
- `unzip -p <apk> res/<x>.bundle | grep <your-symbol>`. The bundles are
203
- resource-renamed inside the APK (`res/Ie.bundle`), so match them by byte size
204
- against the worklet build output.
205
- - **`mobile:android` does not rebuild the worklets.** Only `mobile:prebuild`
206
- runs `build:all`. Gradle rebundles the RN JS, so an app-side change appears
207
- while a Core change silently ships stale — the app runs the previous Core and
208
- every symptom points at your code being wrong rather than absent. Run the
209
- app repo's `rebuild:native` first for any Core change, and grep the bundle
210
- before believing a result.
211
- - **`.env.local` may set `EXPO_PUBLIC_QVAC_WORKLET_SMOKE`**, which boots a smoke
212
- screen instead of the app. Build with `EXPO_NO_DOTENV=1`; do not edit the file.
213
- - **`android/app/build.gradle` bakes `applicationId` at prebuild time**, so
214
- `APP_VARIANT` at gradle time does not change the package. A release build of
215
- the dev variant can still install as `io.tether.qvac`.
216
-
217
- ## Device gotchas that cost real time
218
-
219
- - **`adb install` can report `Success` and leave no launchable activity.** Check
220
- `adb shell cmd package resolve-activity --brief -c
221
- android.intent.category.LAUNCHER <pkg>`; uninstall + reinstall fixes it.
222
- `mesh-lab` refuses to start in this state.
223
- - **Deep-link pairing needs a matching scheme.** The invite is `qvac://mesh/…`;
224
- the production variant registers `qvac` (works), the `development` variant
225
- registers `qvac-dev` and `meshInviteFromUrl` rejects it. For a dev build, read
226
- the invite off the phone (Settings → My Devices → Pair New Device → Show QR
227
- Code) and `join` it from the peer instead.
228
- - **A deep link pairs even during onboarding**, but does not complete
229
- onboarding — the phone rejoins onboarding on the next launch and has no chat
230
- shell, so UI assertions fail. Onboard first (name → "Run QVAC on this device"
231
- → model download) when a scenario needs the chat list.
232
- - **`uiautomator` taps get swallowed** by the RN drawer on first press; use
233
- `tapUntil`, which retries until the next screen appears. A stray tap can land
234
- you in Android Settings — assert on a `resource-id` before continuing.
235
- - **The Electron desktop peer is the wrong tool.** The bare peer is lighter and
236
- does not depend on a desktop build.
237
- - Screenshots: `screenshot(path)` on either backend, then read the file. Cheaper
238
- than a UI dump when you just need to see what is on screen.
239
-
240
- ## iOS specifics
241
-
242
- Verified working: provisioning a simulator from nothing, `installed`, `launch`,
243
- `stop`, accessibility dump and normalisation, text matching, in-app `tap`,
244
- `logs`, `screenshot`. These do **not** carry over from Android:
245
-
246
- - **The invite deep link is blocked.** iOS gates a scheme handoff behind a
247
- SpringBoard "Open in …?" alert. It is not the app's own UI, so `idb ui tap`
248
- cannot press it and `simctl openurl` raises the same alert — only Appium's
249
- alert API reaches it. `deepLink` throws with that explanation rather than
250
- stranding the dialog. Pair the other way on iOS: read the invite off the app
251
- and `join <invite>` from the peer, which needs the app past onboarding.
252
- - **`testID` does not surface.** RN maps it to the accessibility identifier, but
253
- `AXUniqueId` came back empty for every app node in a Release build, so `byId`
254
- finds nothing. Drive iOS with `byText` / `byTextStart` / `byExactText`.
255
- - **Core's logs do surface, in the system log.** `simctl spawn <udid> log show
256
- --last 15m --info` carries the `(BareKit) [qvac-app-core:…]` lines, contract
257
- ops included — which is what `device.logs()` reads. They are absent from the
258
- `expo run:ios` console, which only carries the host's forwarded `[BOOT]`
259
- marks, so a `grep contract` there returns nothing and reads as "iOS does not
260
- log". Verified on a Debug simulator build.
261
- - **A camera-less device cannot join a mesh at all.** "Pair to another device"
262
- goes straight to a QR scanner with no manual-entry or paste path, so a
263
- simulator can never join an existing mesh. Give it "Run QVAC on this device",
264
- then read its own invite and `join` that from the peers — the simulator owns
265
- the mesh and everything else joins it.
266
- - **The invite is plain text**, beside the QR under "or share an invite link"
267
- (Settings → My Devices → Pair New Device → Show QR Code). No decoding needed,
268
- on either platform, which is what makes phone-owns-the-mesh scriptable.
269
- - **A simulator dev-client build needs Metro** and stops on its launcher until
270
- told which bundle to load. `device-idb.launch` handles it: the app's _own_
271
- scheme raises no SpringBoard alert, so
272
- `simctl openurl 'exp+qvac-mobile://expo-development-client/?url=…'` skips the
273
- launcher; the developer-menu primer's Continue then opens the full menu, which
274
- needs its own Close, and `dumpNodes` clears either whenever it sees one.
275
- `expo run:ios` never exits on its own after "Opening on …" — it tails the log —
276
- so a scripted build kills it. The route form `…/--/settings/my-devices` does
277
- **not** load ("Failed to open app").
278
- - **The simulator keychain survives an uninstall**, so a "fresh install" keeps
279
- debug mode and the old recovery phrase, and the debug bar then sits over the
280
- header. `xcrun simctl keychain <udid> reset` before reinstalling is what makes
281
- it fresh. The drawer is opened with an edge swipe on iOS, because the debug bar
282
- and the dev-client gear both cover its button.
283
- - **The simulator's swarm shows `Conns 0`.** Join, attestation and the wakeup
284
- fast-forward still arrive, but a kick issued by the lab peer never reached the
285
- simulator in two 90s windows and a further 100s with the peer held open — the
286
- lab peer configures no blind peers, so with no direct connection there is no
287
- path. `chaos` therefore stops being meaningful at the kick on iOS; the same
288
- step passes on the Pixel. Treat the simulator as a join/fast-forward target,
289
- not a revocation one, until the lab peer is given a blind peer.
290
- - **Addressing nodes on iOS is by label** (`NODES` in `mesh-lab`: `Open chats`,
291
- `Settings`, `My Devices`, `Pair New Device`, `Debug`, `Recovery phrase`, `✕`),
292
- and a row folds its values into the label after a comma, so match the lead.
293
- - **Debug mode is unlocked by ten taps on the Settings title** within 1.5s each.
294
- On a fresh install neither the Debug row nor the stats panel exists until you
295
- do it, and the scenarios that read either have to establish it first.
296
- - **iOS collapses a row into one accessibility label**, values included, so
297
- `byExactText('Recovery phrase')` misses and the phrase arrives inside the
298
- row's own label. Use `byTextStart` and read the value out of that string.
299
- - **The Expo dev-client menu intercepts taps** on a Debug simulator build, often
300
- right after a relaunch. Dismiss "Close"/"Continue" before asserting, or a
301
- healthy app reads as a wedged one.
302
- - **No log marker has ever been seen on an iOS Release build.** `timeBoot`
303
- returned null there, so use `timeBootUntil`, which measures launch until a UI
304
- node appears — platform-neutral, and the metric a user actually sees. This may
305
- be a tooling bug rather than a routing one: `log show` omits info-level entries
306
- unless asked, and every line the app emits is info. `device-idb.mjs` now passes
307
- `--info`. That cannot be validated here: `device-idb.mjs` is `simctl spawn`
308
- throughout, a **simulator-only** path that never reads a physical device, so
309
- the whole iOS side of `[BOOT]` is unverified against real hardware.
310
- - **`idb` is not on PATH.** It installs via pip as `fb-idb`, landing in
311
- `~/Library/Python/3.9/bin/idb`, with `idb_companion` from brew.
312
- `device-idb.mjs` resolves that path itself; override with `IDB_BIN`. Do not
313
- conclude it is missing because `command -v idb` is empty.
314
- - **The system log cannot be truncated**, so `clearLogs()` records a timestamp
315
- and `logs()` runs `simctl spawn <udid> log show --start <mark>`. On a real
316
- device that path does not apply — the simulator is what this backend targets.
317
- - **A simulator boots before its springboard is ready**; the first
318
- `ui describe-all` returns one all-zero element. `waitFor` handles it; a bare
319
- `nodes()` immediately after boot will look empty.
320
- - iOS needs a simulator build of the app before `launch` and the invite deep
321
- link have anything to target. `installed()` fails fast when the app is absent.
322
-
323
- ## Placement
324
-
325
- Device and mesh repro drivers live in `examples/` and run under `bare`. Their
326
- regression tests go in `test/`. Appium-based end-to-end coverage is a different
327
- stack in `tetherto/qvac-app`; this one deliberately is not that, so do not grow
328
- it in that direction.
@@ -1,181 +0,0 @@
1
- ---
2
- name: gh-stack
3
- description: >
4
- Manages stacked PRs and splits multi-part work into reviewable branches with gh-stack.
5
- Use for stack creation, viewing, edits, push, submit, sync, rebase, merge, or checkout;
6
- when asked to split or isolate work for review; whenever a user mentions a stack,
7
- branch layers, dependent PRs, or gh stack; or when a stack is checked out.
8
- metadata:
9
- author: github
10
- version: '0.1.0'
11
- ---
12
-
13
- # gh-stack
14
-
15
- `gh stack` is a [GitHub CLI](https://cli.github.com/) extension for stacked branches and pull
16
- requests. A stack is an ordered chain of branches rooted on a trunk, where each branch has one PR
17
- based on the branch below it, so a reviewer sees only that layer's diff.
18
-
19
- `gh stack` prints a stack trunk-first, left to right:
20
-
21
- ```
22
- (main) <- auth <- api <- frontend
23
- ```
24
-
25
- Left is the **bottom**, right is the **top**. `auth` is based on `main` and merges first;
26
- `frontend` merges last. `up` moves toward the top, away from trunk; `down` moves toward it.
27
- Foundational work belongs at the bottom, code that depends on it above. For how to choose the
28
- layers, read `references/stack-design.md`.
29
-
30
- ## Setup
31
-
32
- ```bash
33
- gh extension install github/gh-stack
34
- git config rerere.enabled true # remember conflict resolutions
35
- git config remote.pushDefault origin # required if the repo has more than one remote
36
- ```
37
-
38
- ## Non-interactive use
39
-
40
- `gh stack` branches on whether **stdout is a TTY**. Piped, most commands error cleanly or print
41
- static text; under a PTY the same commands open a prompt or a full-screen TUI and block forever.
42
- Agent harnesses differ, so always pass the flags below instead of relying on that detection.
43
-
44
- **Multiple remotes:** never run `push`, `submit`, `sync`, `rebase`, or `link` without
45
- `--remote <name>` unless `remote.pushDefault` is configured. `checkout` and `trunk` have no
46
- `--remote` flag and require the config.
47
-
48
- | Always run | Never run bare | Why |
49
- | ----------------------------------------- | ------------------- | --------------------------------------------- |
50
- | `gh stack view --json` | `gh stack view` | opens a TUI under a PTY |
51
- | `gh stack submit --auto` | `gh stack submit` | prompts for a title per new PR |
52
- | `gh stack merge <target> --yes` | `gh pr merge` | `gh pr merge` cannot merge a stack |
53
- | `gh stack init <branch>...` | `gh stack init` | prompts for branch names |
54
- | `gh stack add <branch>` | `gh stack add` | prompts for a name, and fails even when piped |
55
- | `gh stack checkout <target>` | `gh stack checkout` | opens a selection menu |
56
- | `gh stack up` / `down` / `top` / `bottom` | `gh stack switch` | `switch` is menu-only |
57
- | — | `gh stack modify` | TUI-only, no non-interactive path |
58
-
59
- - `view --short` is safe in both modes, but it is formatted for humans. Use `--json` to parse.
60
- - **`checkout <pr>` when a different local stack already covers those branches** cannot be forced.
61
- Run `gh stack unstack --local` first (this keeps the stack on GitHub), then retry.
62
-
63
- ## Branch placement
64
-
65
- - **Starting multi-part work:** create the stack before writing files. Do not implement every
66
- concern on trunk and split it later. Put one dependent concern in each layer, bottom to top.
67
- - **Editing an existing stack:** check out the layer that owns the change before editing. Never
68
- commit a lower layer's concern on the current top branch. Run `gh stack view --json`; if
69
- ownership is unclear, inspect `git log --all -- <path>`. Then check out the owner, edit, commit,
70
- rebase upstack, and return to top.
71
-
72
- ```bash
73
- gh stack down # or: gh stack checkout api
74
- git add ... && git commit -m "Add get-user endpoint"
75
- gh stack rebase --upstack # replay every branch above onto the change
76
- gh stack top # return to where you were
77
- gh stack push
78
- ```
79
-
80
- ## Core loop
81
-
82
- ```bash
83
- gh stack init auth # create the stack and check out its branch
84
- git add ... && git commit -m "Add auth middleware"
85
- gh stack add api # next layer, branched from the current one
86
- git add ... && git commit -m "Add API routes"
87
- gh stack submit --auto # push every branch and open draft PRs
88
- gh stack view --json # confirm
89
- ```
90
-
91
- Add `--open` to `submit` to create PRs ready for review instead of drafts. Branch names are
92
- verbatim — `gh stack add refactor/foo` creates `refactor/foo`.
93
-
94
- ## Staying in sync
95
-
96
- ```bash
97
- gh stack sync # fetch, reconcile with GitHub, rebase, push, refresh PR state
98
- gh stack sync --prune # also delete local branches for merged PRs
99
- ```
100
-
101
- Pruning never happens without `--prune` when non-interactive. If the local and remote stacks have
102
- diverged, `sync` prints both chains, makes no changes, and exits 0 with `Sync aborted` — see
103
- `references/troubleshooting.md`.
104
-
105
- ## Merging
106
-
107
- Scope the merge with an argument:
108
-
109
- ```bash
110
- gh stack merge 42 --yes # PR #42 plus every unmerged PR below it
111
- gh stack merge 7 --yes # every unmerged PR in stack #7
112
- gh stack merge 42 --yes --squash # or --merge, --rebase, --merge-method <method>
113
- ```
114
-
115
- Pass a PR number to merge that PR and every unmerged PR below it, or a stack number to merge every
116
- unmerged PR in that stack. The operation is all-or-nothing: if any PR in that set cannot merge,
117
- none do.
118
-
119
- Without a method flag the last-used method is reused. If the base branch uses a merge queue, the
120
- stack is queued instead and the queue picks the method, ignoring any flag you passed with a
121
- warning; queued PRs may land in separate groups.
122
-
123
- ## Reading state
124
-
125
- `gh stack view --json` writes JSON to **stdout**. Status messages go to **stderr** — do not parse
126
- them, branch on exit codes instead.
127
-
128
- ```
129
- trunk string
130
- currentBranch string
131
- branches[] name, head, base, isCurrent, isMerged, isQueued, needsRebase
132
- branches[].pr number, url, state ("OPEN" | "MERGED" | "QUEUED"); absent when no PR exists
133
- ```
134
-
135
- `base` is the saved SHA of the parent branch that this branch was last known to contain. It may be
136
- older than the parent's current tip. `needsRebase` is true when the current parent tip is no longer
137
- an ancestor of the branch.
138
-
139
- ## Exit codes
140
-
141
- | Code | Meaning | Recovery |
142
- | ---- | -------------------------- | ---------------------------------------------------------- |
143
- | 0 | Success | — |
144
- | 1 | Generic error | Read stderr |
145
- | 2 | Not in a stack | `gh stack init`, or `gh stack checkout <target>` |
146
- | 3 | Rebase conflict | Follow the Exit 3 recovery below |
147
- | 4 | GitHub API failure | Check `gh auth status`, retry |
148
- | 5 | Invalid arguments | Fix the invocation; see `<command> --help` |
149
- | 6 | Disambiguation required | Branch is in several stacks; check out a non-shared branch |
150
- | 7 | Rebase already in progress | `gh stack rebase --continue` or `--abort` |
151
- | 8 | Stack file locked | Another `gh stack` process is writing; retry after ~5s |
152
- | 9 | Stacked PRs unavailable | Not enabled on the repository; tell the user |
153
- | 10 | Modify recovery required | `gh stack modify --abort` |
154
-
155
- **Exit 3 recovery:**
156
-
157
- - After `gh stack rebase`: resolve the files, run `git add`, then
158
- `gh stack rebase --continue`; use `gh stack rebase --abort` to restore the stack.
159
- - After `gh stack sync`: the stack has already been restored. Run `gh stack rebase` to recreate the
160
- conflict, then resolve and continue as above.
161
-
162
- ## Constraints
163
-
164
- - Stacks are strictly linear: one parent, at most one child. Use separate stacks for parallel work.
165
- - There is no non-interactive reorder or removal. Errors may suggest `gh stack modify`, but it is
166
- TUI-only — restructure with `unstack` then `init` instead.
167
- - PR titles and bodies are auto-generated. Use `gh pr edit` afterwards to change them.
168
-
169
- ## More detail
170
-
171
- `gh stack <command> --help` is authoritative for flags and arguments. Note that
172
- `gh stack help <command>` does **not** work — it prints the top-level help.
173
-
174
- Open the reference whose trigger matches the task; no need to preload all three.
175
-
176
- - `references/stack-design.md` — read before creating a stack, when deciding how many layers to
177
- use, what belongs in each one, or whether work belongs in a new stack.
178
- - `references/commands.md` — read when a command fails unexpectedly or you need its preconditions,
179
- side effects, atomicity, or ordering guarantees.
180
- - `references/troubleshooting.md` — read on a rebase conflict, after a squash-merge, on local and
181
- remote divergence, when restructuring a stack, or when driving stacks from another tool.