This repository has no description
1{
2 "issue": "at://did:plc:zmjoeu3stwcn44647rhxa44o/sh.tangled.repo.issue/3lvzel2uo3a22",
3 "version": 2,
4 "introduction": {
5 "project": "AtomicXR is a Nushell-based CLI (`axr`) for managing XR hardware on Linux — SteamVR lighthouse tracking, calibration, and device tooling. Commands live in `.nu` modules served from the repo knot. The README notes the project is deprecated in favor of Homebrew-XR and Envision-OCI, but the codebase is still a useful reference for CLI patterns.",
6 "issue": "The issue requests a new `axr lh pair` command so users can pair SteamVR Lighthouse devices without manually running `lighthouse_console`. Today lighthouse workflows live under `steamvr-lh.nu` (`axr steamvr-lh calibrate`, `axr steamvr-lh console`), while the issue asks for the shorter `lh` namespace — an intentional mismatch we must resolve first.",
7 "approach": "This questionnaire walks from namespace and backend choice through UX, error handling, and shared concerns (tests, docs). Each question's context builds on prior answers; branch follow-ups only appear when your chosen path needs extra detail. Together the answers define a concrete PR plan contributors can consensus on."
8 },
9 "items": [
10 {
11 "id": "command_namespace",
12 "prompt": "The issue requests `axr lh pair`, but the existing lighthouse module is `steamvr-lh.nu` (commands are `axr steamvr-lh calibrate`, `axr steamvr-lh console`). How should the new pair command be namespaced?",
13 "context": "We start here because the issue title says `axr lh pair` but the repo still exposes `axr steamvr-lh …`. Every later decision assumes a command path.",
14 "explanation": "The module file `steamvr-lh.nu` registers subcommands via Nushell's module system. Renaming affects import paths, help text, and user muscle memory. Adding `pair` only to the old module is least disruptive; renaming to `lh` matches the issue verbatim.",
15 "options": [
16 {
17 "label": "Rename module to `lh.nu` so commands become `axr lh pair`, `axr lh calibrate`, etc.",
18 "followups": [
19 {
20 "id": "rename_deprecation",
21 "prompt": "Should the old `steamvr-lh` name be preserved as a deprecated alias?",
22 "context": "Because you chose to rename the module to `lh.nu`, we need to decide whether old scripts using `steamvr-lh` keep working.",
23 "explanation": "A thin alias module costs little and prevents breaking existing docs/scripts. Skipping the alias is simpler but contradicts semver expectations if anyone still depends on the old name.",
24 "options": [
25 {
26 "label": "Yes, keep a thin `steamvr-lh.nu` wrapper that re-exports `lh.nu` with a deprecation warning"
27 },
28 {
29 "label": "No, just rename — the project is marked as no longer maintained anyway"
30 }
31 ]
32 }
33 ]
34 },
35 {
36 "label": "Add `pair` to the existing `steamvr-lh.nu` module (command becomes `axr steamvr-lh pair`)"
37 },
38 {
39 "label": "Create a new separate `lh.nu` module for pairing only, keep `steamvr-lh.nu` for calibrate/console"
40 }
41 ]
42 },
43 {
44 "id": "backend_tool",
45 "prompt": "Which backend tool should the pair command use?",
46 "context": "With the command namespace settled, we pick which external tool wraps the actual pairing protocol.",
47 "explanation": "`lighthouse_console` ships with SteamVR today but is slow and script-hostile. `lhctl` is the intended successor but may not be available on all systems yet. Dual mode adds complexity but future-proofs.",
48 "options": [
49 {
50 "label": "Use `lighthouse_console` now (available today via SteamVR, slower but works)",
51 "followups": [
52 {
53 "id": "lhctl_future_proofing",
54 "prompt": "Should the implementation be structured to make switching to `lhctl` easier later?",
55 "context": "Because you chose `lighthouse_console` today, we decide whether to structure code for a future `lhctl` swap.",
56 "explanation": "This decision affects how the lighthouse pair command is implemented in the Nushell CLI. Contributors may disagree because the repo already has patterns that could conflict with the issue wording.",
57 "options": [
58 {
59 "label": "Yes, abstract the pairing logic behind a helper function so the backend can be swapped"
60 },
61 {
62 "label": "No, just call lighthouse_console directly — refactor when lhctl is available"
63 }
64 ]
65 }
66 ]
67 },
68 {
69 "label": "Wait for `lhctl` to be publicly released and implement with that"
70 },
71 {
72 "label": "Support both: detect if `lhctl` is available and prefer it, fall back to `lighthouse_console`",
73 "followups": [
74 {
75 "id": "dual_backend_flag",
76 "prompt": "Should the user be able to force a specific backend?",
77 "context": "Because you chose dual-backend auto-detection, we clarify whether advanced users can override the choice.",
78 "explanation": "This decision affects how the lighthouse pair command is implemented in the Nushell CLI. Contributors may disagree because the repo already has patterns that could conflict with the issue wording.",
79 "options": [
80 {
81 "label": "Yes, add a `--backend` flag (e.g. `axr lh pair --backend lhctl`)"
82 },
83 {
84 "label": "No, auto-detect only — simpler UX"
85 }
86 ]
87 }
88 ]
89 }
90 ]
91 },
92 {
93 "id": "pairing_workflow",
94 "prompt": "How should the pairing workflow work from the user's perspective?",
95 "context": "Regardless of backend, users experience pairing differently — interactive scan vs args vs wizard.",
96 "explanation": "This decision affects how the lighthouse pair command is implemented in the Nushell CLI. Contributors may disagree because the repo already has patterns that could conflict with the issue wording.",
97 "options": [
98 {
99 "label": "Fully interactive: scan for devices, present a list, user selects which to pair",
100 "followups": [
101 {
102 "id": "interactive_multi_select",
103 "prompt": "Should the user be able to pair multiple devices in one session?",
104 "context": "Because you chose a fully interactive scan flow, we decide single vs multi device per session.",
105 "explanation": "This decision affects how the lighthouse pair command is implemented in the Nushell CLI. Contributors may disagree because the repo already has patterns that could conflict with the issue wording.",
106 "options": [
107 {
108 "label": "Yes, allow multi-select from discovered devices"
109 },
110 {
111 "label": "No, pair one device at a time (simpler, matches lighthouse_console behavior)"
112 }
113 ]
114 }
115 ]
116 },
117 {
118 "label": "Semi-interactive: user provides device serial/ID as argument, command handles the rest"
119 },
120 {
121 "label": "Guided wizard: step-by-step prompts (put device in pairing mode, confirm, etc.)"
122 }
123 ]
124 },
125 {
126 "id": "device_types",
127 "prompt": "Which lighthouse-tracked device types should the pair command support?",
128 "context": "Now we narrow which hardware categories the first implementation supports.",
129 "explanation": "This decision affects how the lighthouse pair command is implemented in the Nushell CLI. Contributors may disagree because the repo already has patterns that could conflict with the issue wording.",
130 "options": [
131 {
132 "label": "All lighthouse devices (base stations, controllers, trackers, HMDs)"
133 },
134 {
135 "label": "Controllers and trackers only (most common pairing need)"
136 },
137 {
138 "label": "Start with controllers only, add other device types in follow-up PRs"
139 }
140 ]
141 },
142 {
143 "id": "lh_console_discovery",
144 "prompt": "The existing `lh-console` helper in `steamvr-lh.nu` checks multiple paths (PATH, Flatpak Steam, native Steam). Should the pair command reuse this helper?",
145 "context": "The existing `steamvr-lh.nu` already locates `lighthouse_console` across Steam installs — reuse affects maintainability.",
146 "explanation": "This decision affects how the lighthouse pair command is implemented in the Nushell CLI. Contributors may disagree because the repo already has patterns that could conflict with the issue wording.",
147 "options": [
148 {
149 "label": "Yes, reuse the existing `lh-console` helper as-is"
150 },
151 {
152 "label": "Reuse but refactor `lh-console` to also support piping input/capturing output (needed for scripted pairing)"
153 },
154 {
155 "label": "Write a new helper specifically for pairing that handles the async job pattern lighthouse_console needs"
156 }
157 ]
158 },
159 {
160 "id": "error_handling",
161 "prompt": "How should the command handle common failure cases (no Bluetooth, SteamVR not installed, device not found)?",
162 "context": "These concerns apply no matter which namespace/backend/workflow you picked above.",
163 "explanation": "This decision affects how the lighthouse pair command is implemented in the Nushell CLI. Contributors may disagree because the repo already has patterns that could conflict with the issue wording.",
164 "options": [
165 {
166 "label": "Pre-flight checks: verify prerequisites before attempting pairing, with actionable error messages"
167 },
168 {
169 "label": "Attempt pairing and surface errors from lighthouse_console/lhctl with minimal wrapping"
170 },
171 {
172 "label": "Pre-flight checks plus a `--force` flag to skip them for advanced users"
173 }
174 ]
175 },
176 {
177 "id": "timeout_handling",
178 "prompt": "Pairing can take a while (especially with lighthouse_console). How should timeouts be handled?",
179 "context": "Pairing duration varies by backend; this shapes UX for all paths.",
180 "explanation": "This decision affects how the lighthouse pair command is implemented in the Nushell CLI. Contributors may disagree because the repo already has patterns that could conflict with the issue wording.",
181 "options": [
182 {
183 "label": "Default timeout with a `--timeout` flag to override"
184 },
185 {
186 "label": "No timeout — wait indefinitely until pairing succeeds or user cancels (Ctrl+C)"
187 },
188 {
189 "label": "Progress indicator with a generous default timeout (e.g. 60s) and clear messaging"
190 }
191 ]
192 },
193 {
194 "id": "testing_strategy",
195 "prompt": "How should this feature be tested? (Hardware-dependent features are hard to unit test)",
196 "context": "Hardware pairing is hard to automate — we still need a team agreement on test scope.",
197 "explanation": "This decision affects how the lighthouse pair command is implemented in the Nushell CLI. Contributors may disagree because the repo already has patterns that could conflict with the issue wording.",
198 "options": [
199 {
200 "label": "Manual testing only — document test procedure in PR description"
201 },
202 {
203 "label": "Add basic tests for argument parsing and pre-flight checks (mock external commands)"
204 },
205 {
206 "label": "No tests needed — the project is marked as no longer maintained"
207 }
208 ]
209 },
210 {
211 "id": "documentation",
212 "prompt": "What documentation should accompany this feature?",
213 "context": "Final shared question: what docs ship with the command given the project deprecation notice.",
214 "explanation": "This decision affects how the lighthouse pair command is implemented in the Nushell CLI. Contributors may disagree because the repo already has patterns that could conflict with the issue wording.",
215 "options": [
216 {
217 "label": "Inline help text in the Nushell command (consistent with existing commands like `calibrate`)"
218 },
219 {
220 "label": "Inline help text plus a section in the README"
221 },
222 {
223 "label": "Inline help text only — README already says the project is no longer maintained"
224 }
225 ]
226 }
227 ]
228}