docs(35-01): complete buildthis CLI package plan
This commit is contained in:
Nexus Dev
parent
c65fa168e6
commit
9bbcff995d
4 changed files with 119 additions and 17 deletions
|
|
@ -38,8 +38,8 @@
|
|||
|
||||
### CLI
|
||||
|
||||
- [ ] **CLI-01**: User can run `npx buildthis` to bootstrap Nexus from scratch
|
||||
- [ ] **CLI-02**: CLI bootstrapper detects hardware and walks through the same provider tiering as web onboarding
|
||||
- [x] **CLI-01**: User can run `npx buildthis` to bootstrap Nexus from scratch
|
||||
- [x] **CLI-02**: CLI bootstrapper detects hardware and walks through the same provider tiering as web onboarding
|
||||
|
||||
## Future Requirements
|
||||
|
||||
|
|
@ -88,8 +88,8 @@
|
|||
| VOICE-01 | Phase 34 | Complete |
|
||||
| VOICE-02 | Phase 34 | Complete |
|
||||
| VOICE-03 | Phase 34 | Complete |
|
||||
| CLI-01 | Phase 35 | Pending |
|
||||
| CLI-02 | Phase 35 | Pending |
|
||||
| CLI-01 | Phase 35 | Complete |
|
||||
| CLI-02 | Phase 35 | Complete |
|
||||
|
||||
**Coverage:**
|
||||
- v1.5 requirements: 21 total
|
||||
|
|
|
|||
|
|
@ -93,7 +93,7 @@ Plans:
|
|||
- [x] **Phase 32: Multi-Step Onboarding Wizard** — Assemble all provider tiers and hardware data into a skippable multi-step wizard; summary screen routes directly into chat (completed 2026-04-03)
|
||||
- [x] **Phase 33: Persistent Memory + Personal Assistant Mode** — File-backed memory with write-time sanitization, PersonalAssistantPage, conversation handoff to PM agent (completed 2026-04-03)
|
||||
- [x] **Phase 34: Voice** — Piper TTS with pre-warm progress, Whisper STT wired into voice service, onboarding voice step activated (completed 2026-04-03)
|
||||
- [ ] **Phase 35: npx buildthis CLI** — Standalone bootstrapper package with hardware detection and provider tiering parity with web onboarding
|
||||
- [x] **Phase 35: npx buildthis CLI** — Standalone bootstrapper package with hardware detection and provider tiering parity with web onboarding (completed 2026-04-03)
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -189,7 +189,7 @@ Plans:
|
|||
**Plans**: 1 plan
|
||||
|
||||
Plans:
|
||||
- [ ] 35-01-PLAN.md — Package scaffold, hardware detection, two-path bootstrap (probe running vs guide install), provider selection, tests
|
||||
- [x] 35-01-PLAN.md — Package scaffold, hardware detection, two-path bootstrap (probe running vs guide install), provider selection, tests
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -242,4 +242,4 @@ All 21 v1.5 requirements are mapped to exactly one phase. No orphans.
|
|||
| 32. Multi-Step Onboarding Wizard | v1.5 | 1/1 | Complete | 2026-04-03 |
|
||||
| 33. Persistent Memory + Personal Assistant Mode | v1.5 | 3/3 | Complete | 2026-04-03 |
|
||||
| 34. Voice | v1.5 | 2/2 | Complete | 2026-04-03 |
|
||||
| 35. npx buildthis CLI | v1.5 | 0/1 | Not started | - |
|
||||
| 35. npx buildthis CLI | v1.5 | 1/1 | Complete | 2026-04-03 |
|
||||
|
|
|
|||
|
|
@ -3,14 +3,14 @@ gsd_state_version: 1.0
|
|||
milestone: v1.5
|
||||
milestone_name: Smart Onboarding + Personal AI Assistant
|
||||
status: verifying
|
||||
stopped_at: Completed 34-voice/34-02
|
||||
last_updated: "2026-04-03T22:42:52.837Z"
|
||||
stopped_at: Completed 35-npx-buildthis-cli/35-01
|
||||
last_updated: "2026-04-03T23:00:01.400Z"
|
||||
last_activity: 2026-04-03
|
||||
progress:
|
||||
total_phases: 6
|
||||
completed_phases: 5
|
||||
total_plans: 12
|
||||
completed_plans: 12
|
||||
completed_phases: 6
|
||||
total_plans: 13
|
||||
completed_plans: 13
|
||||
percent: 0
|
||||
---
|
||||
|
||||
|
|
@ -21,12 +21,12 @@ progress:
|
|||
See: .planning/PROJECT.md (updated 2026-04-02)
|
||||
|
||||
**Core value:** A fresh onboard asks for ONE thing (root directory), auto-creates PM + Engineer agents, and drops you in the dashboard.
|
||||
**Current focus:** Phase 34 — voice
|
||||
**Current focus:** Phase 35 — npx-buildthis-cli
|
||||
|
||||
## Current Position
|
||||
|
||||
Phase: 35
|
||||
Plan: Not started
|
||||
Phase: 35 (npx-buildthis-cli) — EXECUTING
|
||||
Plan: 1 of 1
|
||||
Status: Phase complete — ready for verification
|
||||
Last activity: 2026-04-03
|
||||
|
||||
|
|
@ -64,6 +64,7 @@ Progress: [__________] 0%
|
|||
| Phase 33-persistent-memory P03 | 20 | 2 tasks | 6 files |
|
||||
| Phase 34-voice P01 | 3 | 2 tasks | 7 files |
|
||||
| Phase 34-voice P02 | 4 | 2 tasks | 3 files |
|
||||
| Phase 35-npx-buildthis-cli P01 | 263 | 2 tasks | 11 files |
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
|
|
@ -101,6 +102,7 @@ Key constraints for v1.5 (established at roadmap):
|
|||
- [Phase 34-voice]: voiceEnabled as Zod boolean with default(false) in nexus-settings — file-backed JSON, no DB migration
|
||||
- [Phase 34-voice]: VoiceStep inserted at step 4; rootDir shifts to step 5, summary to step 6 — clean sequential numbering
|
||||
- [Phase 34-voice]: TtsButton rendered inline in messages.map rather than inside MessageBubble — avoids prop drilling usePiperTts
|
||||
- [Phase 35-npx-buildthis-cli]: detectHardware() accepts optional platform param for testability; getProviderOptions() extracted as pure function; controller.vram uses nullish coalescing for TypeScript strict mode
|
||||
|
||||
### Pending Todos
|
||||
|
||||
|
|
@ -115,6 +117,6 @@ None yet.
|
|||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-04-03T22:42:08.346Z
|
||||
Stopped at: Completed 34-voice/34-02
|
||||
Last session: 2026-04-03T23:00:01.397Z
|
||||
Stopped at: Completed 35-npx-buildthis-cli/35-01
|
||||
Resume file: None
|
||||
|
|
|
|||
100
.planning/phases/35-npx-buildthis-cli/35-01-SUMMARY.md
Normal file
100
.planning/phases/35-npx-buildthis-cli/35-01-SUMMARY.md
Normal file
|
|
@ -0,0 +1,100 @@
|
|||
---
|
||||
phase: 35-npx-buildthis-cli
|
||||
plan: "01"
|
||||
subsystem: cli
|
||||
tags: [cli, npx, hardware-detection, bootstrap, commander, clack]
|
||||
dependency_graph:
|
||||
requires: []
|
||||
provides: [buildthis-package, hardware-detection-cli, bootstrap-logic]
|
||||
affects: [pnpm-workspace]
|
||||
tech_stack:
|
||||
added: [buildthis, commander, open, systeminformation, @clack/prompts, esbuild, vitest]
|
||||
patterns: [TDD, two-path-bootstrap, hardware-tier-detection, pure-function-extraction]
|
||||
key_files:
|
||||
created:
|
||||
- packages/buildthis/package.json
|
||||
- packages/buildthis/tsconfig.json
|
||||
- packages/buildthis/esbuild.config.mjs
|
||||
- packages/buildthis/vitest.config.ts
|
||||
- packages/buildthis/src/hardware.ts
|
||||
- packages/buildthis/src/banner.ts
|
||||
- packages/buildthis/src/bootstrap.ts
|
||||
- packages/buildthis/src/index.ts
|
||||
- packages/buildthis/src/__tests__/hardware.test.ts
|
||||
- packages/buildthis/src/__tests__/bootstrap.test.ts
|
||||
modified:
|
||||
- pnpm-lock.yaml
|
||||
decisions:
|
||||
- "detectHardware() accepts an optional platform parameter for testability rather than relying on process.platform directly"
|
||||
- "getProviderOptions() extracted as pure exported function to enable unit testing without invoking full bootstrap() flow"
|
||||
- "hardware.ts null-safety: controller.vram uses nullish coalescing (?? 0) to satisfy TypeScript strict mode"
|
||||
metrics:
|
||||
duration_seconds: 263
|
||||
completed_date: "2026-04-03"
|
||||
tasks_completed: 2
|
||||
files_created: 10
|
||||
files_modified: 1
|
||||
---
|
||||
|
||||
# Phase 35 Plan 01: buildthis Package — CLI Bootstrapper Summary
|
||||
|
||||
**One-liner:** `npx buildthis` bootstrapper package with hardware-aware provider selection (apple_silicon/gpu/cpu_only) and two-path boot logic (probe running instance or guide fresh install).
|
||||
|
||||
## Tasks Completed
|
||||
|
||||
| Task | Description | Commit | Status |
|
||||
|------|-------------|--------|--------|
|
||||
| 1 | Scaffold buildthis package with hardware detection and tests | 020fd36d | Done |
|
||||
| 2 | Implement bootstrap logic, CLI entry point, and integration tests | b516f13c | Done |
|
||||
|
||||
## What Was Built
|
||||
|
||||
### packages/buildthis
|
||||
|
||||
A standalone npm package (name: `buildthis`, published as `npx buildthis`) that acts as a zero-friction entry point for developers setting up Nexus.
|
||||
|
||||
**Hardware detection** (`src/hardware.ts`):
|
||||
- `detectHardware(platform?)` — returns `HardwareResult` with `tier: HardwareTier`
|
||||
- `apple_silicon`: darwin + CPU model starts with "Apple"
|
||||
- `gpu`: si.graphics() resolves with VRAM >= 4096 MB within 3 seconds
|
||||
- `cpu_only`: fallback when GPU query times out, errors, or returns insufficient VRAM
|
||||
|
||||
**Bootstrap logic** (`src/bootstrap.ts`):
|
||||
- `probeRunningInstance(port)` — fetches `http://127.0.0.1:{port}/api/health` with 2-second AbortSignal timeout
|
||||
- `getProviderOptions(tier)` — pure function returning provider options; excludes "local" for `cpu_only` tier
|
||||
- `bootstrap()` — prints banner, guards non-TTY, probes port 3100, then opens browser or guides install
|
||||
|
||||
**CLI entry point** (`src/index.ts`):
|
||||
- commander setup: `buildthis` command calls `bootstrap()`
|
||||
- esbuild produces `dist/index.js` with `#!/usr/bin/env node` shebang
|
||||
|
||||
### Test coverage
|
||||
|
||||
- 6 hardware detection tests: apple_silicon, gpu (NVIDIA 8GB), cpu_only (timeout), cpu_only (low VRAM), cpu_only (error), cpu_only (no controllers)
|
||||
- 8 bootstrap tests: probe returns true/false, provider options include/exclude local, all tiers have puter/google/apikey/skip
|
||||
|
||||
## Verification Results
|
||||
|
||||
```
|
||||
Tests: 14 passed (14)
|
||||
Build: pnpm --filter buildthis build — OK
|
||||
Shebang: head -1 packages/buildthis/dist/index.js => #!/usr/bin/env node
|
||||
Types: pnpm --filter buildthis typecheck — OK
|
||||
```
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 1 - Bug] Fixed TypeScript strict null error on controller.vram**
|
||||
- **Found during:** Task 2 typecheck verification
|
||||
- **Issue:** `controller.vram` typed as `number | null` in systeminformation types, causing TS18047
|
||||
- **Fix:** Added nullish coalescing `const vram = controller?.vram ?? 0` before comparison
|
||||
- **Files modified:** `packages/buildthis/src/hardware.ts`
|
||||
- **Commit:** b516f13c (included in Task 2 commit)
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None — all features are fully implemented. Provider selection prints real instructions; hardware detection uses real systeminformation library with proper mocking in tests only.
|
||||
|
||||
## Self-Check: PASSED
|
||||
Loading…
Add table
Reference in a new issue