Skip to content

Commit e64da7d

Browse files
author
hack-cli-tests
committed
Merge branch 'symphony/HACK-465-improve-crash-capture-restart-guidance-and-proxy' into symphony/HACK-546-integration-hack-428-20-more
# Conflicts: # README.md
2 parents e7499a7 + 67004c4 commit e64da7d

8 files changed

Lines changed: 1574 additions & 2 deletions

‎docs/cli.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2346,6 +2346,14 @@ Options:
23462346

23472347
Usage: `hack doctor [options]`
23482348

2349+
Use this as the first recovery step when runtime or proxy behavior looks wrong. The command now groups failures into:
2350+
2351+
- temporary breakage you can usually recover with restart commands such as `hack global up`, `hack restart`, or daemon restart
2352+
- deeper configuration drift that should go through `hack doctor --fix`
2353+
- manual follow-up items that are intentionally not auto-classified
2354+
2355+
If the problem still reproduces after the suggested recovery flow, collect a bundle with `hack crash-capture`.
2356+
23492357
Options:
23502358

23512359
| Flag | Type | Default | Description |
@@ -2361,9 +2369,17 @@ Collects a post-failure bundle under `.tmp/crash-capture-<timestamp>/` including
23612369

23622370
- `metadata.json` with platform/project context
23632371
- `commands.json` with command outcomes
2372+
- `summary.json` with failed commands and recommended next steps
2373+
- `README.txt` with a short triage map for the bundle
23642374
- `docker` / `hack` snapshots
23652375
- macOS unified log slices (OrbStack + kernel container events) when available
23662376

2377+
Recommended usage:
2378+
2379+
1. Run `hack doctor` first to try restart or repair guidance.
2380+
2. If the issue persists, run `hack crash-capture --path <repo>`.
2381+
3. Read `summary.json`, then `commands.json`, then the referenced `*.log` files.
2382+
23672383
Options:
23682384

23692385
| Flag | Type | Default | Description |

‎docs/plans/2026-03-14-runtime-crash-recovery-design.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Runtime Crash Recovery Design
2+
3+
## Context
4+
5+
`hack doctor` already detects many runtime and proxy failure modes, and `hack crash-capture` already snapshots some local state. The gap is operator usability: warnings are isolated, restart versus repair paths are not grouped into a repeatable sequence, and crash bundles require too much manual interpretation.
6+
7+
This issue targets runtime and proxy breakage where users need to answer three questions quickly:
8+
9+
1. Is this likely temporary breakage that a restart can fix?
10+
2. Is this deeper configuration drift that needs repair?
11+
3. If it still fails, what artifact should be collected for diagnosis?
12+
13+
## Goals
14+
15+
- Make crash bundles immediately useful for diagnosis without requiring source familiarity.
16+
- Make restart and proxy recovery steps explicit in `hack doctor`.
17+
- Separate temporary runtime/proxy drift from deeper configuration problems.
18+
- Keep the recovery flow consistent across CLI output and written docs.
19+
20+
## Non-Goals
21+
22+
- Reworking core runtime startup behavior.
23+
- Adding background crash daemons or automatic upload/reporting.
24+
- Expanding `doctor --fix` beyond its current repair scope.
25+
26+
## Approaches Considered
27+
28+
### 1. Add structured recovery guidance plus richer crash bundle summaries (recommended)
29+
30+
Keep the existing commands, but add:
31+
- recovery classification in `hack doctor`
32+
- a readable recovery panel with ordered commands
33+
- structured crash-bundle summaries plus extra diagnostics
34+
35+
Pros:
36+
- Fits existing operator workflow.
37+
- Low risk to core runtime behavior.
38+
- Improves both human UX and diagnostic artifacts.
39+
40+
Cons:
41+
- Requires keeping diagnosis heuristics conservative.
42+
43+
### 2. Add more raw logs only
44+
45+
Pros:
46+
- Small code change.
47+
48+
Cons:
49+
- Does not solve the “what should I do next?” problem.
50+
- Keeps diagnosis dependent on tribal knowledge.
51+
52+
### 3. Auto-run repair actions from every relevant command
53+
54+
Pros:
55+
- Fewer manual steps in ideal cases.
56+
57+
Cons:
58+
- Higher blast radius.
59+
- Too aggressive for ambiguous failure states.
60+
61+
## Recommended Design
62+
63+
Adopt approach 1.
64+
65+
### Doctor Recovery Workflow
66+
67+
`hack doctor` should classify warnings/errors into operator-facing buckets:
68+
69+
- `temporary breakage`
70+
- global proxy/runtime not running
71+
- stale project host mapping
72+
- daemon not running or starting
73+
- `configuration repair`
74+
- CoreDNS forwarding failure
75+
- missing CA
76+
- ingress network/subnet drift
77+
- dnsmasq/resolver drift
78+
- `manual follow-up`
79+
- anything not safely auto-classified
80+
81+
After the checks complete, `hack doctor` should print one recovery panel that:
82+
83+
1. lists the immediate restart commands first
84+
2. lists repair commands second
85+
3. finishes with verification and crash-capture collection
86+
87+
That panel should make the intended sequence obvious:
88+
89+
1. `hack global up` for missing proxy/global runtime
90+
2. `hack restart` for stale project host mappings
91+
3. `hack daemon start` or `hack daemon clear && hack daemon start` for daemon drift
92+
4. `hack doctor --fix` for configuration repair
93+
5. `hack doctor` to verify
94+
6. `hack crash-capture --path <repo>` if still broken
95+
96+
### Crash Bundle Improvements
97+
98+
`hack crash-capture` should produce a bundle that is useful before opening individual log files.
99+
100+
New artifacts:
101+
- `summary.json` with captured command outcomes, detected symptoms, and recommended next steps
102+
- `README.txt` with a short human-readable bundle map and recovery sequence
103+
104+
Additional captured state:
105+
- `hack doctor --path <repo>`
106+
- `hack global status --json`
107+
- `hack daemon logs --no-follow`
108+
- global proxy logs where available
109+
- docker network inspection for ingress/logging networks
110+
111+
The bundle should also avoid avoidable capture failures. The current process snapshot uses `rg`; it should fall back to a more portable filter so process capture still works on machines without ripgrep.
112+
113+
### Diagnostics Heuristics
114+
115+
Both `hack doctor` and `hack crash-capture` should share the same conservative recovery diagnosis rules so the bundle summary and live CLI guidance do not drift.
116+
117+
Rules:
118+
- Only classify a step as restartable when the associated check directly implies that restart action.
119+
- Prefer `hack doctor --fix` for DNS/network/CA drift.
120+
- Preserve unknown issues as explicit follow-up items instead of over-claiming a fix path.
121+
122+
## Testing
123+
124+
- Add unit tests for doctor recovery classification and rendered action groups.
125+
- Add unit tests for crash bundle summary generation and human-readable README content.
126+
- Add command-level tests for crash-capture outputs that do not require live Docker access.
127+
128+
## Docs
129+
130+
- Update CLI docs for `hack doctor` and `hack crash-capture`.
131+
- Update README troubleshooting so it mirrors the exact same recovery sequence as the CLI.

‎docs/plans/2026-03-14-runtime-crash-recovery-plan.md‎

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
# Runtime Crash Recovery Implementation Plan
2+
3+
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
4+
5+
**Goal:** Improve runtime/proxy recovery by adding explicit operator guidance in `hack doctor` and richer, self-explanatory artifacts in `hack crash-capture`.
6+
7+
**Architecture:** Keep the existing diagnostics commands, but add shared recovery diagnosis helpers that classify failures into restart, repair, and follow-up buckets. Use those helpers to render a recovery panel in `hack doctor` and to write `summary.json` and `README.txt` inside crash bundles.
8+
9+
**Tech Stack:** Bun, TypeScript, Bun test, existing CLI display helpers
10+
11+
---
12+
13+
### Task 1: Add failing tests for doctor recovery guidance
14+
15+
**Files:**
16+
- Create: `tests/doctor-command.test.ts`
17+
- Modify: `src/commands/doctor.ts`
18+
19+
**Step 1: Write the failing test**
20+
21+
Add focused tests for recovery diagnosis such as:
22+
- proxy/global runtime down suggests `hack global up`
23+
- stale host mapping suggests `hack restart`
24+
- DNS/network drift suggests `hack doctor --fix`
25+
- stale daemon state suggests the daemon restart path
26+
27+
**Step 2: Run test to verify it fails**
28+
29+
Run:
30+
```bash
31+
bun test tests/doctor-command.test.ts
32+
```
33+
34+
Expected: FAIL because the exported diagnosis helpers do not exist yet.
35+
36+
**Step 3: Write minimal implementation**
37+
38+
Export the smallest helper surface needed to classify check results and render ordered recovery actions.
39+
40+
**Step 4: Run test to verify it passes**
41+
42+
Run:
43+
```bash
44+
bun test tests/doctor-command.test.ts
45+
```
46+
47+
Expected: PASS
48+
49+
**Step 5: Commit**
50+
51+
```bash
52+
git add src/commands/doctor.ts tests/doctor-command.test.ts
53+
git commit -m "test: cover doctor recovery guidance"
54+
```
55+
56+
### Task 2: Add failing tests for crash bundle summaries
57+
58+
**Files:**
59+
- Create: `tests/crash-capture.test.ts`
60+
- Modify: `src/commands/crash-capture.ts`
61+
62+
**Step 1: Write the failing test**
63+
64+
Add tests for:
65+
- summary generation from command results
66+
- readable README content
67+
- recovery recommendations matching doctor heuristics
68+
- process snapshot command not depending on `rg`
69+
70+
**Step 2: Run test to verify it fails**
71+
72+
Run:
73+
```bash
74+
bun test tests/crash-capture.test.ts
75+
```
76+
77+
Expected: FAIL because the new helpers and artifacts do not exist yet.
78+
79+
**Step 3: Write minimal implementation**
80+
81+
Export bundle-summary helpers and update the capture command list/artifact writers.
82+
83+
**Step 4: Run test to verify it passes**
84+
85+
Run:
86+
```bash
87+
bun test tests/crash-capture.test.ts
88+
```
89+
90+
Expected: PASS
91+
92+
**Step 5: Commit**
93+
94+
```bash
95+
git add src/commands/crash-capture.ts tests/crash-capture.test.ts
96+
git commit -m "test: cover crash bundle summaries"
97+
```
98+
99+
### Task 3: Implement the doctor recovery panel
100+
101+
**Files:**
102+
- Modify: `src/commands/doctor.ts`
103+
- Test: `tests/doctor-command.test.ts`
104+
105+
**Step 1: Write the failing test**
106+
107+
Extend the tests to assert grouped recovery actions and the temporary-vs-configuration distinction.
108+
109+
**Step 2: Run test to verify it fails**
110+
111+
Run:
112+
```bash
113+
bun test tests/doctor-command.test.ts
114+
```
115+
116+
Expected: FAIL
117+
118+
**Step 3: Write minimal implementation**
119+
120+
- classify checks into recovery buckets
121+
- render a single panel with ordered commands
122+
- keep unknown issues explicit rather than guessing
123+
124+
**Step 4: Run test to verify it passes**
125+
126+
Run:
127+
```bash
128+
bun test tests/doctor-command.test.ts
129+
```
130+
131+
Expected: PASS
132+
133+
**Step 5: Commit**
134+
135+
```bash
136+
git add src/commands/doctor.ts tests/doctor-command.test.ts
137+
git commit -m "feat: add explicit doctor recovery guidance"
138+
```
139+
140+
### Task 4: Implement richer crash bundle artifacts
141+
142+
**Files:**
143+
- Modify: `src/commands/crash-capture.ts`
144+
- Test: `tests/crash-capture.test.ts`
145+
146+
**Step 1: Write the failing test**
147+
148+
Extend the tests to assert:
149+
- `summary.json` structure
150+
- `README.txt` guidance text
151+
- additional capture commands included
152+
153+
**Step 2: Run test to verify it fails**
154+
155+
Run:
156+
```bash
157+
bun test tests/crash-capture.test.ts
158+
```
159+
160+
Expected: FAIL
161+
162+
**Step 3: Write minimal implementation**
163+
164+
- capture additional doctor/global/runtime diagnostics
165+
- write bundle summary/readme artifacts
166+
- switch the process snapshot command to a portable filter
167+
168+
**Step 4: Run test to verify it passes**
169+
170+
Run:
171+
```bash
172+
bun test tests/crash-capture.test.ts
173+
```
174+
175+
Expected: PASS
176+
177+
**Step 5: Commit**
178+
179+
```bash
180+
git add src/commands/crash-capture.ts tests/crash-capture.test.ts
181+
git commit -m "feat: improve crash capture triage artifacts"
182+
```
183+
184+
### Task 5: Update docs and verify quality gates
185+
186+
**Files:**
187+
- Modify: `README.md`
188+
- Modify: `docs/cli.md`
189+
190+
**Step 1: Write the failing test**
191+
192+
No automated test. Use doc consistency review against the implementation.
193+
194+
**Step 2: Run verification**
195+
196+
Run:
197+
```bash
198+
bun test tests/doctor-command.test.ts tests/crash-capture.test.ts
199+
bun test
200+
bun x ultracite fix
201+
bun x ultracite check
202+
```
203+
204+
Expected: targeted tests pass; full suite and checks pass or expose any unrelated failures that must be reported.
205+
206+
**Step 3: Write minimal implementation**
207+
208+
Update docs to mirror the same recovery sequence shown by `hack doctor`.
209+
210+
**Step 4: Commit**
211+
212+
```bash
213+
git add README.md docs/cli.md
214+
git commit -m "docs: document runtime and proxy recovery workflow"
215+
```

0 commit comments

Comments
 (0)