@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.
- package/dist-lib/lib/api/chat.d.ts +3 -1
- package/dist-lib/lib/api/chat.js +6 -2
- package/dist-lib/lib/api/index.d.ts +2 -0
- package/dist-lib/lib/api/index.js +3 -1
- package/dist-lib/lib/api/inference-calls.d.ts +18 -0
- package/dist-lib/lib/api/inference-calls.js +15 -0
- package/dist-lib/lib/api/rag.js +10 -2
- package/dist-lib/lib/assistant/harness.d.ts +1 -0
- package/dist-lib/lib/assistant/history.d.ts +10 -1
- package/dist-lib/lib/assistant/history.js +36 -1
- package/dist-lib/lib/assistant/message.d.ts +2 -0
- package/dist-lib/lib/assistant/message.js +11 -0
- package/dist-lib/lib/assistant/skill-encode.js +27 -1
- package/dist-lib/lib/assistant-tree.d.ts +2 -0
- package/dist-lib/lib/assistant-tree.js +11 -2
- package/dist-lib/lib/assistant.d.ts +19 -3
- package/dist-lib/lib/assistant.js +148 -23
- package/dist-lib/lib/core/chunk.js +5 -0
- package/dist-lib/lib/core/files/rag/build.d.ts +1 -2
- package/dist-lib/lib/core/files/rag/build.js +1 -2
- package/dist-lib/lib/core/files/rag/extract/office-collabora.d.ts +1 -1
- package/dist-lib/lib/core/files/rag/index.d.ts +4 -24
- package/dist-lib/lib/core/files/rag/index.js +3 -17
- package/dist-lib/lib/core/files/rag/load.d.ts +1 -2
- package/dist-lib/lib/core/files/rag/load.js +1 -2
- package/dist-lib/lib/core/files/rag/produce.d.ts +1 -1
- package/dist-lib/lib/core/files/rag/produce.js +1 -3
- package/dist-lib/lib/core/files/rag/retrieval/full-text.d.ts +1 -1
- package/dist-lib/lib/core/files/rag/retrieval/full-text.js +1 -4
- package/dist-lib/lib/core/files/rag/similarity.d.ts +5 -0
- package/dist-lib/lib/core/files/rag/similarity.js +6 -0
- package/dist-lib/lib/core/files/upload.d.ts +1 -1
- package/dist-lib/lib/core/inference-calls-handoff.d.ts +20 -0
- package/dist-lib/lib/core/inference-calls-handoff.js +37 -0
- package/dist-lib/lib/core/inference-calls-receiver.d.ts +14 -0
- package/dist-lib/lib/core/inference-calls-receiver.js +39 -0
- package/dist-lib/lib/core/notification.js +5 -4
- package/dist-lib/lib/core/skill-secrets.js +3 -6
- package/dist-lib/lib/core.d.ts +9 -1
- package/dist-lib/lib/core.js +129 -13
- package/dist-lib/lib/credential-pusher.d.ts +2 -3
- package/dist-lib/lib/credential-pusher.js +67 -39
- package/dist-lib/lib/inference-calls.d.ts +40 -0
- package/dist-lib/lib/inference-calls.js +266 -0
- package/dist-lib/lib/integrations/index.d.ts +1 -2
- package/dist-lib/lib/integrations/index.js +0 -1
- package/dist-lib/lib/integrations/setup-routes.js +0 -15
- package/dist-lib/lib/oauth/flow-core.js +1 -1
- package/dist-lib/lib/oauth/flow.d.ts +4 -2
- package/dist-lib/lib/oauth/flow.js +3 -4
- package/dist-lib/lib/oauth/host.d.ts +3 -1
- package/dist-lib/lib/oauth/host.js +3 -1
- package/dist-lib/lib/oauth/keys.d.ts +21 -20
- package/dist-lib/lib/oauth/keys.js +59 -85
- package/dist-lib/lib/oauth/loopback.d.ts +2 -2
- package/dist-lib/lib/oauth/loopback.js +32 -19
- package/dist-lib/lib/oauth/loopback.stub.d.ts +2 -2
- package/dist-lib/lib/oauth/loopback.stub.js +2 -2
- package/dist-lib/lib/oauth/providers.d.ts +3 -5
- package/dist-lib/lib/oauth/providers.js +20 -67
- package/dist-lib/lib/oauth/redirect-types.d.ts +1 -0
- package/dist-lib/lib/oauth/registry.d.ts +10 -0
- package/dist-lib/lib/oauth/registry.js +25 -0
- package/dist-lib/lib/oauth/resolve.js +1 -1
- package/dist-lib/lib/oauth/token-exchange-core.js +2 -1
- package/dist-lib/lib/oauth/types.d.ts +1 -1
- package/dist-lib/lib/oauth.client.d.ts +3 -1
- package/dist-lib/lib/oauth.client.js +3 -1
- package/dist-lib/lib/oauth.d.ts +4 -7
- package/dist-lib/lib/oauth.js +4 -7
- package/dist-lib/lib/skill-types.d.ts +12 -0
- package/dist-lib/schema/content.js +5 -1
- package/dist-lib/schema/engine.js +63 -2
- package/dist-lib/schema/qvac.js +4 -2
- package/dist-lib/spec/bind.js +3 -0
- package/dist-lib/spec/calls.js +1 -0
- package/dist-lib/spec/capabilities.d.ts +2 -0
- package/dist-lib/spec/hrpc/hrpc.json +13 -0
- package/dist-lib/spec/hrpc/index.js +15 -3
- package/dist-lib/spec/hrpc/messages.js +284 -52
- package/dist-lib/spec/hyperschema/index.js +284 -52
- package/dist-lib/spec/hyperschema/schema.json +210 -1
- package/dist-lib/spec/hyperschema/types.d.ts +51 -1
- package/dist-lib/spec/local/hyperdb/messages.js +64 -128
- package/dist-lib/spec/local/hyperschema/index.js +32 -64
- package/dist-lib/spec/local/hyperschema/schema.json +16 -0
- package/dist-lib/spec/mesh/hyperdb/messages.js +176 -311
- package/dist-lib/spec/mesh/hyperdispatch/messages.js +132 -236
- package/dist-lib/spec/mesh/hyperschema/index.js +132 -236
- package/dist-lib/spec/mesh/hyperschema/schema.json +70 -1
- package/dist-lib/spec/mesh/hyperschema/types.d.ts +3 -1
- package/package.json +15 -18
- package/tui/app.mjs +98 -155
- package/tui/lib/knowledge-import.mjs +1 -1
- package/tui/lib/save-file.mjs +1 -1
- package/.claude/skills/asana/SKILL.md +0 -86
- package/.claude/skills/compaction/SKILL.md +0 -136
- package/.claude/skills/device-mesh-debug/SKILL.md +0 -328
- package/.claude/skills/gh-stack/SKILL.md +0 -181
- package/.claude/skills/gh-stack/references/commands.md +0 -177
- package/.claude/skills/gh-stack/references/stack-design.md +0 -97
- package/.claude/skills/gh-stack/references/troubleshooting.md +0 -159
- package/.claude/skills/js-house-style/SKILL.md +0 -671
- package/.claude/skills/pr-create/SKILL.md +0 -243
- package/.claude/skills/pr-review/SKILL.md +0 -428
- package/.claude/skills/release/SKILL.md +0 -122
- package/CLAUDE.md +0 -48
- package/dist-lib/lib/core/files/rag/artifact/codec.d.ts +0 -3
- package/dist-lib/lib/core/files/rag/artifact/codec.js +0 -172
- package/dist-lib/lib/core/files/rag/artifact/id.d.ts +0 -10
- package/dist-lib/lib/core/files/rag/artifact/id.js +0 -39
- package/dist-lib/lib/core/files/rag/artifact/types.d.ts +0 -24
- package/dist-lib/lib/core/files/rag/artifact/types.js +0 -41
- package/dist-lib/lib/core/files/rag/chunk/chunking.d.ts +0 -12
- package/dist-lib/lib/core/files/rag/chunk/chunking.js +0 -117
- package/dist-lib/lib/core/files/rag/chunk/metadata.d.ts +0 -30
- package/dist-lib/lib/core/files/rag/chunk/metadata.js +0 -89
- package/dist-lib/lib/core/files/rag/chunk/tokenizer.d.ts +0 -7
- package/dist-lib/lib/core/files/rag/chunk/tokenizer.js +0 -18
- package/dist-lib/lib/core/files/rag/extract/csv-text.d.ts +0 -1
- package/dist-lib/lib/core/files/rag/extract/csv-text.js +0 -117
- package/dist-lib/lib/core/files/rag/extract/document-types.d.ts +0 -22
- package/dist-lib/lib/core/files/rag/extract/document-types.js +0 -152
- package/dist-lib/lib/core/files/rag/extract/extract.d.ts +0 -17
- package/dist-lib/lib/core/files/rag/extract/extract.js +0 -81
- package/dist-lib/lib/core/files/rag/extract/html-table-text.d.ts +0 -1
- package/dist-lib/lib/core/files/rag/extract/html-table-text.js +0 -125
- package/dist-lib/lib/core/files/rag/extract/html-text.d.ts +0 -1
- package/dist-lib/lib/core/files/rag/extract/html-text.js +0 -132
- package/dist-lib/lib/core/files/rag/extract/pdf-platform.d.ts +0 -17
- package/dist-lib/lib/core/files/rag/extract/pdf-platform.js +0 -141
- package/dist-lib/lib/core/files/rag/extract/pdf-text.d.ts +0 -12
- package/dist-lib/lib/core/files/rag/extract/pdf-text.js +0 -43
- package/dist-lib/lib/core/files/rag/extract/rtf-text.d.ts +0 -1
- package/dist-lib/lib/core/files/rag/extract/rtf-text.js +0 -15
- package/dist-lib/lib/core/files/rag/extract/text-decoding.d.ts +0 -1
- package/dist-lib/lib/core/files/rag/extract/text-decoding.js +0 -91
- package/dist-lib/lib/core/files/rag/extract/types.d.ts +0 -36
- package/dist-lib/lib/core/files/rag/extract/types.js +0 -12
- package/dist-lib/lib/core/files/rag/extract/utf.d.ts +0 -2
- package/dist-lib/lib/core/files/rag/extract/utf.js +0 -18
- package/dist-lib/lib/core/files/rag/retrieval/citation-match.d.ts +0 -2
- package/dist-lib/lib/core/files/rag/retrieval/citation-match.js +0 -16
- package/dist-lib/lib/core/files/rag/retrieval/coverage.d.ts +0 -4
- package/dist-lib/lib/core/files/rag/retrieval/coverage.js +0 -48
- package/dist-lib/lib/core/files/rag/retrieval/diversity.d.ts +0 -10
- package/dist-lib/lib/core/files/rag/retrieval/diversity.js +0 -37
- package/dist-lib/lib/core/files/rag/retrieval/floor.d.ts +0 -5
- package/dist-lib/lib/core/files/rag/retrieval/floor.js +0 -21
- package/dist-lib/lib/core/files/rag/retrieval/format.d.ts +0 -6
- package/dist-lib/lib/core/files/rag/retrieval/format.js +0 -21
- package/dist-lib/lib/core/files/rag/retrieval/knowledge.d.ts +0 -2
- package/dist-lib/lib/core/files/rag/retrieval/knowledge.js +0 -54
- package/dist-lib/lib/core/files/rag/retrieval/notices.d.ts +0 -16
- package/dist-lib/lib/core/files/rag/retrieval/notices.js +0 -27
- package/dist-lib/lib/core/files/rag/retrieval/scoring.d.ts +0 -8
- package/dist-lib/lib/core/files/rag/retrieval/scoring.js +0 -82
- package/dist-lib/lib/core/files/rag/retrieval/search.d.ts +0 -3
- package/dist-lib/lib/core/files/rag/retrieval/search.js +0 -49
- package/dist-lib/lib/core/files/rag/retrieval/selection.d.ts +0 -11
- package/dist-lib/lib/core/files/rag/retrieval/selection.js +0 -93
- package/dist-lib/lib/core/files/rag/retrieval/source-tag-filter.d.ts +0 -6
- package/dist-lib/lib/core/files/rag/retrieval/source-tag-filter.js +0 -79
- package/dist-lib/lib/core/files/rag/retrieval/sources.d.ts +0 -13
- package/dist-lib/lib/core/files/rag/retrieval/sources.js +0 -20
- package/dist-lib/lib/core/files/rag/retrieval/target.d.ts +0 -13
- package/dist-lib/lib/core/files/rag/retrieval/target.js +0 -89
- package/dist-lib/lib/core/files/rag/retrieval/terms.d.ts +0 -8
- package/dist-lib/lib/core/files/rag/retrieval/terms.js +0 -70
- package/dist-lib/lib/core/files/rag/retrieval/types.d.ts +0 -29
- package/dist-lib/lib/core/files/rag/retrieval/types.js +0 -1
- package/dist-lib/lib/core/files/rag/retrieval/web-sources.d.ts +0 -8
- package/dist-lib/lib/core/files/rag/retrieval/web-sources.js +0 -41
- package/dist-lib/lib/core/files/rag/retrieval/whole-document-query.d.ts +0 -1
- package/dist-lib/lib/core/files/rag/retrieval/whole-document-query.js +0 -96
- package/dist-lib/lib/core/files/rag/vector/memory.d.ts +0 -15
- package/dist-lib/lib/core/files/rag/vector/memory.js +0 -135
- package/dist-lib/lib/core/files/rag/vector/types.d.ts +0 -28
- package/dist-lib/lib/core/files/rag/vector/types.js +0 -1
- package/dist-lib/lib/integrations/oauth-providers.d.ts +0 -14
- package/dist-lib/lib/integrations/oauth-providers.js +0 -116
- package/dist-lib/lib/oauth/asana.d.ts +0 -35
- package/dist-lib/lib/oauth/asana.js +0 -71
- package/dist-lib/lib/oauth/google.d.ts +0 -37
- package/dist-lib/lib/oauth/google.js +0 -77
- package/dist-lib/lib/oauth/notion.d.ts +0 -34
- package/dist-lib/lib/oauth/notion.js +0 -82
- package/dist-lib/lib/oauth/spotify.d.ts +0 -32
- package/dist-lib/lib/oauth/spotify.js +0 -74
- package/dist-lib/lib/oauth/verify.d.ts +0 -8
- 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.
|