mirror of
https://github.com/ksyasuda/SubMiner.git
synced 2026-03-20 12:11:28 -07:00
sudacode
ee95e86ad5
- Stats dashboard redesign design and implementation plans - Episode detail and Anki card link design - Internal knowledge base restructure - Backlog tasks for testing, verification, and occurrence tracking
174 lines
5.7 KiB
Markdown
174 lines
5.7 KiB
Markdown
# Stats Subcommand Implementation Plan
|
|
|
|
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
|
|
|
**Goal:** Add `subminer stats` plus app-side `--stats` support so SubMiner can launch only the stats dashboard stack, reuse an existing app instance, and fail when immersion tracking is disabled.
|
|
|
|
**Architecture:** The launcher gets a new `stats` subcommand that forwards into a dedicated Electron CLI flag. The app handles that flag through a focused stats command service that validates immersion tracking, ensures tracker/server startup, opens the browser, and optionally reports success/failure through a response file so second-instance reuse preserves shell exit status.
|
|
|
|
**Tech Stack:** TypeScript, Bun test runner, Electron single-instance lifecycle, Commander-based launcher CLI.
|
|
|
|
---
|
|
|
|
### Task 1: Record launcher command coverage
|
|
|
|
**Files:**
|
|
- Modify: `launcher/main.test.ts`
|
|
- Modify: `launcher/commands/command-modules.test.ts`
|
|
|
|
**Step 1: Write the failing test**
|
|
|
|
Add coverage that `subminer stats` routes through a dedicated launcher command and forwards `--stats` into the app process.
|
|
|
|
**Step 2: Run test to verify it fails**
|
|
|
|
Run: `bun test launcher/main.test.ts launcher/commands/command-modules.test.ts`
|
|
Expected: FAIL because the `stats` command does not exist yet.
|
|
|
|
**Step 3: Write minimal implementation**
|
|
|
|
Add the launcher parser, command module, and dispatch wiring needed for the tests to pass.
|
|
|
|
**Step 4: Run test to verify it passes**
|
|
|
|
Run: `bun test launcher/main.test.ts launcher/commands/command-modules.test.ts`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add launcher/main.test.ts launcher/commands/command-modules.test.ts launcher/config/cli-parser-builder.ts launcher/main.ts launcher/commands/stats-command.ts
|
|
git commit -m "feat: add launcher stats command"
|
|
```
|
|
|
|
### Task 2: Add failing app CLI parsing/runtime tests
|
|
|
|
**Files:**
|
|
- Modify: `src/cli/args.test.ts`
|
|
- Modify: `src/main/runtime/cli-command-runtime-handler.test.ts`
|
|
- Modify: `src/main/runtime/cli-command-context.test.ts`
|
|
|
|
**Step 1: Write the failing test**
|
|
|
|
Add tests for:
|
|
- parsing `--stats`
|
|
- starting the app for `--stats`
|
|
- stats command behavior when immersion tracking is disabled
|
|
- stats command behavior when startup succeeds
|
|
|
|
**Step 2: Run test to verify it fails**
|
|
|
|
Run: `bun test src/cli/args.test.ts src/main/runtime/cli-command-runtime-handler.test.ts src/main/runtime/cli-command-context.test.ts`
|
|
Expected: FAIL because the new flag/service is not implemented.
|
|
|
|
**Step 3: Write minimal implementation**
|
|
|
|
Extend CLI args and add the smallest stats command runtime surface required by the tests.
|
|
|
|
**Step 4: Run test to verify it passes**
|
|
|
|
Run: `bun test src/cli/args.test.ts src/main/runtime/cli-command-runtime-handler.test.ts src/main/runtime/cli-command-context.test.ts`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add src/cli/args.test.ts src/main/runtime/cli-command-runtime-handler.test.ts src/main/runtime/cli-command-context.test.ts src/cli/args.ts src/main/cli-runtime.ts src/main/runtime/cli-command-context.ts src/main/runtime/cli-command-context-deps.ts
|
|
git commit -m "feat: add app stats cli command"
|
|
```
|
|
|
|
### Task 3: Add stats-only startup plumbing
|
|
|
|
**Files:**
|
|
- Modify: `src/main.ts`
|
|
- Modify: `src/core/services/startup.ts`
|
|
- Modify: `src/core/services/cli-command.ts`
|
|
- Modify: `src/main/runtime/immersion-startup.ts`
|
|
- Test: existing runtime tests above plus any new focused stats tests
|
|
|
|
**Step 1: Write the failing test**
|
|
|
|
Add focused tests around the stats startup service and response-path reporting before touching production logic.
|
|
|
|
**Step 2: Run test to verify it fails**
|
|
|
|
Run: `bun test src/core/services/cli-command.test.ts`
|
|
Expected: FAIL because stats startup/reporting is missing.
|
|
|
|
**Step 3: Write minimal implementation**
|
|
|
|
Implement:
|
|
- stats-only startup gating
|
|
- tracker/server/browser startup orchestration
|
|
- response-file success/failure reporting for reused primary-instance handling
|
|
|
|
**Step 4: Run test to verify it passes**
|
|
|
|
Run: `bun test src/core/services/cli-command.test.ts`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add src/main.ts src/core/services/startup.ts src/core/services/cli-command.ts src/main/runtime/immersion-startup.ts src/core/services/cli-command.test.ts
|
|
git commit -m "feat: add stats-only startup flow"
|
|
```
|
|
|
|
### Task 4: Update docs/help
|
|
|
|
**Files:**
|
|
- Modify: `src/cli/help.ts`
|
|
- Modify: `docs-site/immersion-tracking.md`
|
|
- Modify: `docs-site/mining-workflow.md`
|
|
|
|
**Step 1: Write the failing test**
|
|
|
|
Add/update any help-text assertions first.
|
|
|
|
**Step 2: Run test to verify it fails**
|
|
|
|
Run: `bun test src/cli/help.test.ts`
|
|
Expected: FAIL until help text includes stats usage.
|
|
|
|
**Step 3: Write minimal implementation**
|
|
|
|
Document `subminer stats` and clarify that explicit invocation forces the local dashboard server to start.
|
|
|
|
**Step 4: Run test to verify it passes**
|
|
|
|
Run: `bun test src/cli/help.test.ts`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add src/cli/help.ts src/cli/help.test.ts docs-site/immersion-tracking.md docs-site/mining-workflow.md
|
|
git commit -m "docs: document stats subcommand"
|
|
```
|
|
|
|
### Task 5: Verify integrated behavior
|
|
|
|
**Files:**
|
|
- No new files required
|
|
|
|
**Step 1: Run targeted unit/integration lanes**
|
|
|
|
Run:
|
|
- `bun run typecheck`
|
|
- `bun run test:launcher`
|
|
- `bun test src/cli/args.test.ts src/core/services/cli-command.test.ts src/main/runtime/cli-command-runtime-handler.test.ts src/main/runtime/cli-command-context.test.ts src/cli/help.test.ts`
|
|
|
|
Expected: PASS
|
|
|
|
**Step 2: Run broader maintained lane if the targeted slice is clean**
|
|
|
|
Run: `bun run test:fast`
|
|
Expected: PASS or surface unrelated pre-existing failures.
|
|
|
|
**Step 3: Commit verification fixes if needed**
|
|
|
|
```bash
|
|
git add -A
|
|
git commit -m "test: stabilize stats command coverage"
|
|
```
|