nexus/.planning/milestones/v1.5-phases/35-npx-buildthis-cli/35-01-SUMMARY.md

---

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