---
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