285bf585be
6 phases, 13 plans, 21 requirements. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
100 lines
4.2 KiB
Markdown
100 lines
4.2 KiB
Markdown
---
|
|
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
|