buildwithnexus 0.8.11 → 0.10.3

package/README.md

@@ -3,124 +3,137 @@
 [![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)
 
-Interactive CLI for NEXUS — a 56-agent autonomous software engineering organization. Tell it what to build. It figures out the rest.
-
-## Quick Start
+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.
 
 ```bash
 npm install -g buildwithnexus
 buildwithnexus
 ```
 
-On first run you'll be prompted to set your Anthropic API key. Keys are stored in `~/.buildwithnexus/.env.keys`.
+The first launch walks you through choosing a model. Then describe a task.
 
-## What It Does
+## Why
 
-Launch an interactive shell with three execution modes:
+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.
 
-- **PLAN** — Break down your request into a reviewable step-by-step plan
-- **BUILD** — Execute directly with live agent streaming
-- **BRAINSTORM** — Free-form exploration with the NEXUS CPO streaming their reasoning
+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.
 
-```
-╔════════════════════════════════════════════════════════════╗
-║        Nexus - Autonomous Agent Orchestration              ║
-║        v0.8.10                                              ║
-╚════════════════════════════════════════════════════════════╝
+## Models
 
-📝 Task: Build a REST API for user authentication
+Two wire protocols cover everything. Pick a provider during setup (or `bwn init`):
 
-Press Enter to use PLAN or choose a mode:
-  [1] PLAN   design & break down steps
-  [2] BUILD  execute with live streaming
-  [3] BRAINSTORM  free-form explore & Q&A
-```
+| 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 | — |
 
-## Commands
-
-### Core (Python backend required)
-
-| Command | Description |
-|---------|-------------|
-| `buildwithnexus` | Launch interactive shell (PLAN/BUILD/BRAINSTORM) |
-| `buildwithnexus da-init` | Set up API keys in `~/.buildwithnexus/.env.keys` |
-| `buildwithnexus run <task>` | Run a task directly via the backend |
-| `buildwithnexus brainstorm [idea]` | Brainstorm an idea with the NEXUS CPO |
-| `buildwithnexus server` | Start the NEXUS Python backend server |
-| `buildwithnexus da-status` | Check backend connectivity |
-| `buildwithnexus doctor` | Run diagnostics (backend health + environment) |
-| `buildwithnexus logs [-f]` | View server logs (stream with `-f`) |
-| `buildwithnexus keys list` | List configured API keys |
-| `buildwithnexus keys set <KEY_NAME>` | Set an API key |
-
-### Docker infrastructure (requires Docker + full NEXUS setup)
-
-| Command | Description |
-|---------|-------------|
-| `buildwithnexus 99 [instruction]` | AI pair-programming via full NEXUS engine |
-| `buildwithnexus start` | Start full NEXUS Docker services |
-| `buildwithnexus stop` | Stop NEXUS Docker services |
-| `buildwithnexus status [--json]` | Show Docker container health |
-| `buildwithnexus dashboard` | Open the NEXUS dashboard at `localhost:4200/dashboard` |
-| `buildwithnexus update` | Update to the latest version |
-| `buildwithnexus destroy [--force]` | Remove NEXUS and all data |
-| `buildwithnexus ssh` | Open SSH session into the sandbox |
-
-## Architecture
+Env vars override the stored key, so CI and one-offs Just Work. Keys live in
+`~/.buildwithnexus/.env.keys` (0600).
 
-```
-buildwithnexus CLI (TypeScript/Node.js)
-         │
-         │ SSE streaming
-         ▼
-NEXUS Backend (Python FastAPI, port 4200)
-         │
-         ▼
-LangGraph Runtime → 56-agent organization
-  • CPO (Opus) — brainstorm + strategy
-  • VP Engineering → 19 eng agents
-  • Product Management → 2 agents
-  • QA Team → 7 agents
-  • Security Team → 3 agents
-  • ML & Data → 6 agents
-  • Salesforce → 10 agents
-  • Documentation → 2 agents
-  • Consultant → 1 agent
-```
-
-## Requirements
+## Modes
 
-- **Node.js** >= 18
-- **Anthropic API key** (`sk-ant-...`) from [console.anthropic.com](https://console.anthropic.com)
-- NEXUS backend running on `localhost:4200` (for PLAN/BUILD/BRAINSTORM modes)
+- **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.
 
-Optional:
-- OpenAI API key (o3 reasoning support)
-- Google API key (Gemini multimodal support)
+```bash
+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
+buildwithnexus doctor          # diagnose setup (keys, tools, connectivity)
+```
 
-## Environment Variables
+Inside the interactive session:
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `ANTHROPIC_API_KEY` | — | Overrides stored key |
-| `OPENAI_API_KEY` | — | Overrides stored key |
-| `GOOGLE_API_KEY` | — | Overrides stored key |
-| `BACKEND_URL` | `http://localhost:4200` | NEXUS backend address |
-| `NEXUS_BACKEND_DIR` | `~/Projects/nexus` | Path to NEXUS backend for auto-start |
+```
+/model [name]             hot-swap the AI model mid-session
+/compact                  compress context (free up token budget)
+/review                   AI code review of current git diff
+/commit                   AI-drafted conventional commit message
+/pr                       AI-drafted pull request title + description
+/schedule <delay> <task>  run a task once in the background (5s, 2m, 1h)
+/loop <interval> <task>   run a task repeatedly in the background
+/workflows                list and manage background workflows
+/btw <context>            inject context into the next agent turn
+/config                   configure hooks, memory, and commands via AI
+/memory                   view and edit session memory
+/skills                   list skills and custom commands
+```
 
-## Security
+## 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" }] }
+    ]
+  }
+}
+```
 
-- API keys stored in `~/.buildwithnexus/.env.keys` with `0600` permissions
-- HMAC-SHA256 tamper detection on `.env.keys`
-- Input sanitization and output redaction via DLP layer
-- Backend URL validation before transmitting API keys
-- Audit trail at `~/.buildwithnexus/audit.log`
+## Build from source
 
-## Links
+```bash
+cargo build --release --manifest-path harness/Cargo.toml   # → harness/target/release/buildwithnexus
+bash scripts/vendor.sh                                      # vendor deps for offline / reproducible builds
+```
 
-- **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);