From 9bbcff995d7c342c40a242fd6f7dda43246b5f6c Mon Sep 17 00:00:00 2001 From: Nexus Dev Date: Fri, 3 Apr 2026 23:00:16 +0000 Subject: [PATCH] docs(35-01): complete buildthis CLI package plan --- .planning/REQUIREMENTS.md | 8 +- .planning/ROADMAP.md | 6 +- .planning/STATE.md | 22 ++-- .../35-npx-buildthis-cli/35-01-SUMMARY.md | 100 ++++++++++++++++++ 4 files changed, 119 insertions(+), 17 deletions(-) create mode 100644 .planning/phases/35-npx-buildthis-cli/35-01-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 4a8099ba..4c71671f 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -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 diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 364202eb..c46b3b4b 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -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 | diff --git a/.planning/STATE.md b/.planning/STATE.md index 4ab2f9b5..2d9675b5 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -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 diff --git a/.planning/phases/35-npx-buildthis-cli/35-01-SUMMARY.md b/.planning/phases/35-npx-buildthis-cli/35-01-SUMMARY.md new file mode 100644 index 00000000..2de72e6f --- /dev/null +++ b/.planning/phases/35-npx-buildthis-cli/35-01-SUMMARY.md @@ -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