16 KiB
16 KiB
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | must_haves | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 35-npx-buildthis-cli | 01 | execute | 1 |
|
true |
|
|
Purpose: Final phase of v1.5 — gives developers a single command to get started with Nexus.
Output: Working buildthis package with tests, buildable via esbuild.
<execution_context> @$HOME/.claude/get-shit-done/workflows/execute-plan.md @$HOME/.claude/get-shit-done/templates/summary.md </execution_context>
@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/35-npx-buildthis-cli/35-RESEARCH.md@cli/esbuild.config.mjs @cli/package.json @cli/tsconfig.json @cli/src/utils/banner.ts @server/src/services/hardware.ts @pnpm-workspace.yaml
Task 1: Scaffold buildthis package with hardware detection and tests 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/__tests__/hardware.test.ts @server/src/services/hardware.ts — copy-adapt the detection logic (Apple Silicon via os.cpus + platform, GPU via si.graphics with 3s timeout, cpu_only fallback) @cli/esbuild.config.mjs — mirror the esbuild pattern (banner shebang, node20 target, esm format, external native deps) @cli/package.json — reference dependency versions for consistency @cli/tsconfig.json — mirror the tsconfig extends pattern @packages/branding/vitest.config.ts — mirror vitest config pattern - detectHardware() returns { tier: "apple_silicon", totalGb } when process.platform === "darwin" AND os.cpus()[0].model starts with "Apple" - detectHardware() returns { tier: "gpu", totalGb, gpuName, gpuVramGb } when si.graphics() resolves with a controller having vram >= 4096 MB within 3 seconds - detectHardware() returns { tier: "cpu_only", totalGb } when si.graphics() throws or times out after 3 seconds - detectHardware() returns { tier: "cpu_only", totalGb } when GPU VRAM is below 4 GB 1. Create `packages/buildthis/package.json`: - name: "buildthis", version: "0.1.0", type: "module" - bin: { "buildthis": "./dist/index.js" } - files: ["dist"] - publishConfig: { access: "public" } - engines: { node: ">=20" } - scripts: dev ("tsx src/index.ts"), build (esbuild + chmod), clean, typecheck, test ("vitest run") - dependencies: @clack/prompts ^0.10.0, commander ^13.1.0, picocolors ^1.1.1, open ^11.0.0, systeminformation 5 - devDependencies: @types/node ^22.12.0, tsx ^4.19.2, typescript ^5.7.3, vitest ^2.0.0, esbuild (latest)2. Create `packages/buildthis/tsconfig.json` extending `../../tsconfig.base.json` with outDir "dist", rootDir "src", include ["src"].
3. Create `packages/buildthis/esbuild.config.mjs` — simple config:
- entryPoints: ["src/index.ts"], bundle: true, platform: "node", target: "node20", format: "esm"
- outfile: "dist/index.js"
- banner: { js: "#!/usr/bin/env node" }
- external: ["systeminformation", "open", "@clack/prompts", "commander", "picocolors"]
- treeShaking: true, sourcemap: true
4. Create `packages/buildthis/vitest.config.ts` matching the branding package pattern: defineConfig with test.include ["src/**/*.test.ts"].
5. Create `packages/buildthis/src/hardware.ts`:
- Export type HardwareTier = "gpu" | "apple_silicon" | "cpu_only"
- Export interface HardwareResult { tier: HardwareTier; totalGb: number; gpuName?: string; gpuVramGb?: number }
- Export async function detectHardware(): Promise<HardwareResult>
- Apple Silicon path: process.platform === "darwin" && os.cpus()[0]?.model?.startsWith("Apple") -> return apple_silicon
- GPU path: Promise.race([si.graphics(), 3s timeout]), check controllers[0].vram >= 4096 (MB), return gpu with gpuName + gpuVramGb
- Fallback: cpu_only
- Copy logic from server/src/services/hardware.ts but simplified (no cache, no freeGb/usableGb — not needed for CLI display)
6. Create `packages/buildthis/src/banner.ts`:
- Export function printBuildthisBanner(): void
- Print a compact "buildthis" ASCII art header using picocolors (simpler than the full Nexus banner — just the word "buildthis" stylized, or reuse NEXUS_ART from cli/src/utils/banner.ts with a different tagline like "Bootstrap your AI workspace")
7. Create `packages/buildthis/src/__tests__/hardware.test.ts`:
- Mock os.cpus, os.totalmem, process.platform, si.graphics
- Test apple_silicon detection (darwin + Apple M4)
- Test gpu detection (linux + NVIDIA with 8GB VRAM)
- Test cpu_only fallback (si.graphics timeout)
- Test cpu_only when VRAM < 4GB
8. Run `pnpm install` from repo root to link the new workspace package.
9. Run `npx vitest run packages/buildthis/src/__tests__/hardware.test.ts` — all tests pass.
2. Create `packages/buildthis/src/index.ts`:
- #!/usr/bin/env node (handled by esbuild banner, but add comment)
- Import { program } from "commander"
- Import { bootstrap } from "./bootstrap.js"
- program.name("buildthis").description("Bootstrap your AI workspace").version("0.1.0")
- program.action(async () => { await bootstrap(); })
- program.parse()
3. Create `packages/buildthis/src/__tests__/bootstrap.test.ts`:
- Mock global fetch for probeRunningInstance tests
- Test probeRunningInstance returns true on 200 response
- Test probeRunningInstance returns false on connection error
- Test probeRunningInstance returns false on timeout
- Test that provider options array includes "local" when tier is not cpu_only
- Test that provider options array excludes "local" when tier is cpu_only
- Export a helper function getProviderOptions(tier: HardwareTier) from bootstrap.ts to make this testable — extract the options-building logic into a pure function
4. Run the full test suite: `npx vitest run packages/buildthis/src/__tests__/`
5. Run `pnpm --filter buildthis build` to verify esbuild produces dist/index.js with shebang.
6. Verify the built file: head -1 packages/buildthis/dist/index.js should show "#!/usr/bin/env node".
<success_criteria>
packages/buildthis/is a complete npm package with bin entry, esbuild config, and vitest config- Hardware detection covers all three tiers (apple_silicon, gpu, cpu_only) with 3-second GPU timeout
- Bootstrap probes port 3100, opens browser if running, guides install if not
- Provider options exclude local AI for cpu_only tier
- Non-TTY guard prevents hanging in CI/piped environments
- All unit tests pass, build produces valid CLI binary with shebang </success_criteria>