buildwithnexus 0.8.10 → 0.10.1

package/README.md

@@ -3,113 +3,119 @@
 [![npm version](https://img.shields.io/npm/v/buildwithnexus?style=flat-square&color=blue)](https://www.npmjs.com/package/buildwithnexus)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 
-Launch an autonomous AI runtime with triple-nested VM isolation in one command.
+A hilariously fast, **agentic AI CLI harness** — written in Rust. Remote models
+via API key, or local models on your machine. It plans, edits files, and runs
+commands, asking before each change. One static binary, four dependencies, no
+runtime to babysit.
 
-## What It Does
+```bash
+npm install -g buildwithnexus
+buildwithnexus
+```
 
-One command bootstraps a complete NEXUS instance:
+The first launch walks you through choosing a model. Then describe a task.
 
-- **QEMU VM** running Ubuntu 24.04 (auto-installed if missing)
-- **Docker** inside the VM for isolated CLI sessions
-- **KVM** inside the VM for inner virtual machines (triple nesting)
-- **NEXUS server** running on port 4200 with full agent orchestration
-- **Cloudflare tunnel** (optional) for remote access
+## Why
 
-All isolation is mandatory — NEXUS refuses to start unless it detects proper nesting (VM + Docker + KVM).
+The original `buildwithnexus` was a TypeScript CLI talking to a Python /
+LangGraph backend over HTTP. This is a ground-up rewrite that keeps the *benefits*
+of that engine — planning, a ReAct tool loop, approval gates, role-specialized
+agents — as plain Rust control flow, with **none** of the framework weight. No
+Python, no Docker, no tunnel. The orchestration that LangGraph did at runtime is
+just code here, which is where the speed comes from.
 
-## Quick Start
+Design bias, in order: **performance**, then **fewer lines**, then **fewer
+dependencies** — never at the cost of the UX. Enums and `match` over trait
+objects; flat data tables over registries; one pooled HTTP connection reused
+across every step of the agent loop.
 
-```bash
-npx buildwithnexus init
-```
+## Models
 
-This walks you through API key setup, VM resource allocation, and boots a fully provisioned NEXUS instance in ~10-25 minutes (first run). Subsequent starts take ~30 seconds.
+Two wire protocols cover everything. Pick a provider during setup (or `bwn init`):
 
-## Requirements
+| Provider | Kind | Key |
+|----------|------|-----|
+| Anthropic (Claude) | remote | `ANTHROPIC_API_KEY` |
+| OpenAI | remote | `OPENAI_API_KEY` |
+| OpenRouter | remote | `OPENROUTER_API_KEY` |
+| Groq | remote | `GROQ_API_KEY` |
+| Hugging Face | remote | `HF_TOKEN` |
+| Ollama | local | — |
+| llama.cpp server | local | — |
+| LM Studio | local | — |
 
-- **Node.js** >= 18
-- ~4GB RAM and ~20GB disk available for the VM
-- An Anthropic API key
+Env vars override the stored key, so CI and one-offs Just Work. Keys live in
+`~/.buildwithnexus/.env.keys` (0600).
 
-### macOS (ARM or Intel)
+## Modes
 
-QEMU is installed automatically via Homebrew. If Homebrew isn't installed, get it at [brew.sh](https://brew.sh).
+- **PLAN** — decompose the task into steps you approve or edit, then execute.
+- **BUILD** — the agentic ReAct loop: read/edit files, run commands, iterate.
+- **BRAINSTORM** — free-form chat, no tools.
 
 ```bash
-npx buildwithnexus init
+buildwithnexus                 # full-screen interactive session
+buildwithnexus run <task>      # execute a task (agentic, headless)
+buildwithnexus plan <task>     # decompose, approve, then execute
+buildwithnexus brainstorm <q>  # free-form chat
+buildwithnexus init            # (re)configure provider / model / key
+buildwithnexus providers       # list built-in providers
 ```
 
-### Linux (x64)
-
-QEMU is installed automatically via apt. Requires `sudo` access for package installation.
-
-```bash
-npx buildwithnexus init
+## Permissions
+
+Every mutating tool (`write_file`, `edit_file`, `run_command`) passes a gate:
+`ask` (default), `auto` (yolo), or `readonly`. Set it during setup.
+
+## Hooks
+
+Run your own commands at the same lifecycle points as Claude Code, configured in
+`~/.buildwithnexus/settings.json` (user) and/or `.buildwithnexus/settings.json`
+(project). User hooks are always active; **project hooks run only after you trust
+that folder** (you're prompted once, and a project hook may *deny* a tool but
+never *grant* one — so cloning a hostile repo can't run or unlock anything).
+Events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`,
+`SessionEnd`. Each hook command receives the event as JSON on stdin.
+
+`PreToolUse` can gate a tool: exit code **2** (or a JSON
+`permissionDecision: "deny"`) blocks it — even under `auto`. `"allow"` skips the
+prompt; otherwise the normal gate applies. Matchers are `*`, an exact tool name,
+or a `|`-separated list. See [`examples/settings.json`](./examples/settings.json).
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "run_command",
+        "hooks": [{ "type": "command", "command": "echo 'no shell on main' >&2; exit 2" }] }
+    ]
+  }
+}
 ```
 
-### Windows (via WSL2)
-
-buildwithnexus requires WSL2 with an Ubuntu distribution. Native Windows is not supported.
-
-1. Install WSL2: `wsl --install -d Ubuntu`
-2. Open Ubuntu terminal
-3. Install Node.js: `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`
-4. Run: `npx buildwithnexus init`
-
-KVM nested virtualization must be enabled in your BIOS/UEFI settings.
+## Build from source
 
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `buildwithnexus init` | Full scaffolding + VM boot (10 phases) |
-| `buildwithnexus start` | Start an existing VM + server |
-| `buildwithnexus stop` | Graceful shutdown |
-| `buildwithnexus status` | VM / Docker / server / tunnel health |
-| `buildwithnexus doctor` | Diagnose QEMU, ports, SSH, disk |
-| `buildwithnexus logs [-f]` | Stream server logs |
-| `buildwithnexus update` | Upload latest release, rebuild, restart |
-| `buildwithnexus destroy [--force]` | Remove VM + all data |
-| `buildwithnexus keys set\|list` | Manage API keys |
-| `buildwithnexus ssh` | Direct SSH into the VM |
-| `buildwithnexus brainstorm [idea]` | Brainstorm an idea with the Chief of Staff |
-
-## Architecture
-
-```
-Host (your machine)
-  └─ QEMU VM (Ubuntu 24.04)
-       ├─ Docker (nexus-cli-sandbox)
-       ├─ KVM / libvirt (inner VMs)
-       └─ NEXUS server (:4200)
+```bash
+cargo build --release --manifest-path harness/Cargo.toml   # → harness/target/release/buildwithnexus
+bash scripts/vendor.sh                                      # vendor deps for offline / reproducible builds
 ```
 
-Port forwarding: SSH `localhost:2222`, NEXUS `localhost:4200`, HTTPS `localhost:8443`.
-
-## Security
-
-Built-in DLP (Data Loss Prevention) layer protects every data path — zero dependencies, zero configuration:
-
-- **Input Sanitization** — YAML escaping and `shellCommand` tagged templates prevent injection
-- **Output Redaction** — API keys auto-redacted from logs, errors, and stdout
-- **Secret Validation** — format + injection character checks on all API keys at input
-- **File Integrity** — HMAC-SHA256 tamper detection on `.env.keys`
-- **Audit Trail** — every sensitive operation logged to `~/.buildwithnexus/audit.log`
-- **Environment Scrubbing** — child processes (QEMU, Docker, SSH) never inherit secrets
-- **SSH TOFU** — host key pinned on first connect, verified on every subsequent connection
-- SSH key-only auth (ed25519, no passwords)
-- UFW firewall (deny all, allow 22/80/443/4200)
-- auditd enabled (SOC 2 compliance)
-- Docker hardened (no-new-privileges, log rotation, cap-drop ALL)
-- API keys stored in `~/.buildwithnexus/.env.keys` with `0600` permissions
-- All directories created with `0700` permissions
-- Nesting enforcement guard prevents running outside VM isolation
-
-## Links
-
-- **npm:** [npmjs.com/package/buildwithnexus](https://www.npmjs.com/package/buildwithnexus)
-- **Docs:** [buildwithnexus.dev](https://buildwithnexus.dev)
-- **GitHub:** [github.com/Garretts-Apps/buildwithnexus](https://github.com/Garretts-Apps/buildwithnexus)
+The npm package is a thin wrapper: `postinstall` downloads the prebuilt binary
+for your platform from the GitHub Release and **verifies its SHA-256** before
+use, falling back to a `cargo` build (using vendored deps when present). Releases
+also carry build-provenance attestations (`gh attestation verify`).
+
+## Safety
+
+- Default permission is **ask** — every file write, edit, and command is
+  confirmed. `auto` ("yolo") and `readonly` are opt-in.
+- File tools are confined to the working directory; reads outside it, and of
+  sensitive paths (the key store, `~/.ssh`, `.env`, `*.pem`), require
+  confirmation even in `auto`. Catastrophic commands (`rm -rf /`, `mkfs`, …) too.
+- API keys are never sent to a non-HTTPS endpoint, and key-like tokens are
+  redacted from surfaced errors.
+- In non-interactive / `--json` runs, anything that would prompt is denied
+  rather than blocking.
 
 ## License
 

package/SECURITY.md

@@ -0,0 +1,85 @@
+# Security Policy
+
+## Supported Versions
+
+`buildwithnexus` is published to npm under semantic versioning. Only the latest
+released minor line receives security fixes.
+
+| Version    | Supported          |
+|------------|--------------------|
+| 0.8.x      | :white_check_mark: |
+| < 0.8      | :x:                |
+
+## Reporting a Vulnerability
+
+**Do not open a public GitHub issue for security problems.**
+
+Report vulnerabilities privately via GitHub's coordinated-disclosure flow:
+
+  https://github.com/Garretts-Apps/buildwithnexus/security/advisories/new
+
+Or by email to `security@buildwithnexus.dev`.
+
+We aim to acknowledge new reports within **3 business days** and to ship a fix
+or mitigation within **30 days** of acknowledgement, depending on severity. We
+will credit reporters in the advisory unless they ask to remain anonymous.
+
+## Scope
+
+In scope:
+
+- The `buildwithnexus` npm package (CLI, bundled NEXUS source tarball,
+  installer scripts).
+- The publish pipeline in `.github/workflows/publish.yml`.
+- The bundled NEXUS Python source (`dist/nexus-release.tar.gz`).
+- Any release artifacts attached to GitHub Releases (SBOM, checksums).
+
+Out of scope:
+
+- Vulnerabilities in upstream dependencies — please report those upstream first;
+  if exploitable through `buildwithnexus`, also notify us.
+- Self-XSS or social-engineering against your own developer machine.
+- Issues that require an attacker to already control your CI secrets, npm
+  account, or developer machine.
+
+## Verifying a Release
+
+Every release on npm from `v0.9.0` onward ships with **npm provenance** — a
+SLSA-Build-L3-style attestation cryptographically tying the tarball back to the
+specific GitHub Actions workflow run that built it.
+
+To verify:
+
+```sh
+npm view buildwithnexus@<version> --json | jq .dist.attestations
+```
+
+Or interactively in the terminal:
+
+```sh
+npx -y npm-audit-resolver buildwithnexus
+```
+
+The publish workflow also attaches a CycloneDX SBOM (`sbom.cdx.json`) and a
+`SHA256SUMS.txt` to each GitHub Release. You can reproduce the tarball locally
+by checking out the corresponding tag and running:
+
+```sh
+git clone --branch v<version> https://github.com/Garretts-Apps/buildwithnexus
+cd buildwithnexus
+NEXUS_SRC=/path/to/nexus npm run build && npm run bundle
+sha256sum dist/nexus-release.tar.gz
+```
+
+## Hardening Inside the Package
+
+- `prepublishOnly` refuses to publish unless `NEXUS_SRC` is explicitly set to a
+  valid nexus checkout. No silent fall-through to a stale `/tmp/` copy.
+- `postinstall` was removed. `npm install buildwithnexus` no longer executes
+  any project-defined lifecycle script on the user's machine.
+- All GitHub Actions in our workflows are pinned to specific minor versions
+  (Dependabot proposes SHA-pinned bumps weekly).
+- The publish workflow runs with the minimum permissions required, plus
+  `id-token: write` only for OIDC provenance signing.
+- `npm ci --ignore-scripts` is used in CI to neutralise transitive postinstall
+  scripts during builds and audits.

package/bin/buildwithnexus.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+'use strict';
+// Thin launcher: hand off to the native Rust binary with stdio inherited so the
+// alternate-screen TUI works exactly as if it were invoked directly.
+const { spawnSync } = require('child_process');
+const { existing } = require('../scripts/resolve-binary.js');
+
+const bin = existing();
+if (!bin) {
+  process.stderr.write(
+    'buildwithnexus: native binary not found.\n' +
+    '  Reinstall the package, or build it locally with Rust (https://rustup.rs):\n' +
+    '    npm explore buildwithnexus -- npm run build\n'
+  );
+  process.exit(1);
+}
+
+const result = spawnSync(bin, process.argv.slice(2), { stdio: 'inherit' });
+if (result.error) {
+  process.stderr.write(`buildwithnexus: ${result.error.message}\n`);
+  process.exit(1);
+}
+process.exit(result.status === null ? 1 : result.status);