@shuyhere/bb-agent 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BB-Agent Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,192 @@
+# BB-Agent
+
+A Rust-native AI coding agent for the terminal — featuring a fullscreen TUI, multi-provider support, tool use, session persistence, branching, extensions, and skills.
+
+## Install
+
+### From source (all platforms — macOS, Linux)
+
+Requires [Rust](https://rustup.rs). Install Rust first if you don't have it:
+
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+source ~/.cargo/env
+```
+
+Then build and install BB-Agent:
+
+```bash
+git clone https://github.com/shuyhere/bb-agent.git
+cd bb-agent
+cargo install --path crates/cli
+```
+
+This compiles the `bb` binary and installs it to `~/.cargo/bin/bb` (which Rust adds to your PATH).
+
+### npm (Linux x86_64 — prebuilt binary)
+
+```bash
+npm install -g @shuyhere/bb-agent
+```
+
+> **macOS / other platforms:** npm install will print instructions to build from source.
+> Prebuilt binaries for macOS coming soon. After install, run `bb` to start.
+
+## Getting Started
+
+### 1. Login to a provider
+
+```bash
+bb login              # Interactive provider selection
+bb login anthropic    # Login to Anthropic (OAuth)
+bb login openai-codex # Login to OpenAI (OAuth)
+bb login google       # Login to Google (API key)
+```
+
+Or set environment variables: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`, etc.
+
+### 2. Start the TUI
+
+```bash
+bb
+```
+
+That's it! Run `bb` to launch the fullscreen interactive terminal UI. Type your prompt and press Enter.
+
+### More ways to use `bb`
+
+```bash
+bb                                    # Launch the fullscreen TUI
+bb "Explain this codebase"            # TUI with an initial prompt
+bb -p "What is 2+2?"                  # Print mode (non-interactive, pipe-friendly)
+bb -c                                 # Continue your last session
+bb -r                                 # Resume: pick from previous sessions
+bb --model sonnet                     # Use a specific model
+bb --model sonnet:high                # Model with extended thinking
+bb --list-models                      # List all available models
+```
+
+## Features
+
+- **Fullscreen TUI** — rich terminal interface with streaming output, markdown rendering, syntax highlighting
+- **Multi-provider** — Anthropic (Claude), OpenAI, Google (Gemini), Groq, xAI, OpenRouter, and custom OpenAI-compatible endpoints
+- **Built-in tools** — `read`, `write`, `edit`, `bash`, `find`, `grep`, `ls`, `web_search`, `web_fetch`, `browser_fetch`
+- **Session persistence** — SQLite-backed sessions with branching, forking, and tree navigation
+- **Extensions** — JS/TS plugin system for custom tools, commands, and hooks
+- **Skills** — markdown-based instruction files that auto-load contextual knowledge
+- **System prompt templates** — save and switch between named prompt configurations
+- **OAuth login** — browser-based login for Anthropic and OpenAI
+
+## System Prompt Templates
+
+Save prompt templates in `~/.bb-agent/system-prompts/` and switch between them:
+
+```bash
+bb --list-templates                   # List available templates
+bb -t coding                          # Start with "coding" template
+bb -t research                        # Start with "research" template
+bb --system-prompt @path/to/file.md   # Load prompt from any file
+```
+
+## Extensions & Skills
+
+```bash
+bb install npm:some-skill             # Install a global package
+bb install --local ./my-skill         # Install project-local
+bb list                               # List installed packages
+bb update                             # Update packages
+```
+
+## Configuration
+
+BB-Agent uses layered configuration:
+
+| File | Scope |
+|------|-------|
+| `~/.bb-agent/settings.json` | Global settings |
+| `<project>/.bb-agent/settings.json` | Project settings (overrides global) |
+| `~/.bb-agent/AGENTS.md` or `AGENTS.md` | System prompt additions |
+| `~/.bb-agent/system-prompts/<name>.md` | Named prompt templates |
+| `~/.bb-agent/skills/` | Global skills |
+| `~/.bb-agent/extensions/` | Global extensions |
+
+### Example `settings.json`
+
+```json
+{
+  "default_model": "claude-sonnet-4-20250514",
+  "default_provider": "anthropic",
+  "default_thinking": "medium",
+  "models": [
+    {
+      "id": "my-local-model",
+      "provider": "ollama",
+      "api": "openai",
+      "base_url": "http://localhost:11434/v1",
+      "context_window": 32000,
+      "max_tokens": 4096
+    }
+  ]
+}
+```
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `Enter` | Submit prompt |
+| `Shift+Enter` | Insert newline |
+| `Esc` | Clear input / cancel / exit prompt |
+| `Ctrl+C` | Exit |
+| `Ctrl+P` | Cycle models |
+| `Ctrl+O` | Open settings menu |
+| `Ctrl+Shift+O` | Expand/collapse tool calls |
+| `/` | Slash commands menu |
+| `@` | File mention autocomplete |
+
+## Workspace Crates
+
+| Crate | Description |
+|-------|-------------|
+| `bb-core` | Core agent, session, config, and runtime types |
+| `bb-session` | SQLite-backed session storage, branching, context building |
+| `bb-tools` | Built-in tool implementations |
+| `bb-provider` | Model/provider integrations and streaming |
+| `bb-hooks` | Hook event types for extensions |
+| `bb-plugin-host` | Plugin discovery and host runtime |
+| `bb-tui` | Terminal UI components and fullscreen experience |
+| `bb-cli` | The `bb` command-line application |
+
+## Documentation
+
+- [Configuration Reference](docs/configuration.md) — settings.json, AGENTS.md, templates
+- [Built-in Tools](docs/tools.md) — all 10 tools with parameters
+- [Extensions & Skills](docs/extensions.md) — plugins, skills, prompts, packages
+- [Providers & Models](docs/providers.md) — authentication, model selection, custom providers
+- [Development Guide](docs/development.md) — build from source, dev workflow, project structure, debugging
+- [Contributing](CONTRIBUTING.md) — code style, PR process
+- [Changelog](CHANGELOG.md) — release history
+- [Security](SECURITY.md) — vulnerability reporting, security model
+
+## Development
+
+See the full [Development Guide](docs/development.md) for detailed instructions.
+
+```bash
+git clone https://github.com/shuyhere/bb-agent.git
+cd bb-agent
+cargo install --path crates/cli      # Build + install to ~/.cargo/bin/bb
+bb                                   # Run it
+```
+
+Dev cycle:
+```bash
+cargo run --bin bb                   # Run without installing
+cargo test --workspace --release     # Run all 435 tests
+cargo fmt --all                      # Format
+cargo clippy --workspace             # Lint
+```
+
+## License
+
+[MIT License](LICENSE)

package/bin/bb

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+function findBinary() {
+  // 1. Check native/ dir (downloaded by postinstall)
+  const nativeBin = path.join(__dirname, "..", "native", "bb");
+  if (fs.existsSync(nativeBin)) {
+    try { fs.accessSync(nativeBin, fs.constants.X_OK); return nativeBin; } catch {}
+  }
+
+  // 2. Check PATH (cargo install)
+  const dirs = (process.env.PATH || "").split(path.delimiter);
+  for (const dir of dirs) {
+    // Skip our own bin/ dir to avoid infinite recursion
+    if (path.resolve(dir) === path.resolve(__dirname)) continue;
+    const full = path.join(dir, "bb");
+    try { fs.accessSync(full, fs.constants.X_OK); return full; } catch {}
+  }
+
+  return null;
+}
+
+const binary = findBinary();
+
+if (!binary) {
+  console.error(`
+BB-Agent binary not found.
+
+Install Rust (if needed):
+  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+  source ~/.cargo/env
+
+Then build BB-Agent:
+  git clone https://github.com/shuyhere/bb-agent.git
+  cd bb-agent && cargo install --path crates/cli
+
+Then run:
+  bb
+`;
+  process.exit(1);
+}
+
+try {
+  execFileSync(binary, process.argv.slice(2), { stdio: "inherit" });
+} catch (err) {
+  process.exit(err.status || 1);
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@shuyhere/bb-agent",
+  "version": "0.0.1",
+  "description": "BB-Agent — a Rust-native AI coding agent for the terminal",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shuyhere/bb-agent.git"
+  },
+  "homepage": "https://github.com/shuyhere/bb-agent",
+  "author": "shuyhere",
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "cli",
+    "terminal",
+    "tui",
+    "llm",
+    "anthropic",
+    "claude",
+    "openai",
+    "rust"
+  ],
+  "bin": {
+    "bb": "bin/bb"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const https = require("https");
+
+const VERSION = "0.0.1";
+const REPO = "shuyhere/bb-agent";
+const NATIVE_DIR = path.join(__dirname, "..", "native");
+const DOWNLOAD_TIMEOUT_MS = 15_000;
+
+function getTarget() {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  const platformMap = { darwin: "apple-darwin", linux: "unknown-linux-gnu" };
+  const archMap = { x64: "x86_64", arm64: "aarch64" };
+
+  const p = platformMap[platform];
+  const a = archMap[arch];
+  if (!p || !a) return null;
+  return `${a}-${p}`;
+}
+
+function downloadBinary(url, dest, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error("Download timed out")), timeoutMs);
+
+    const follow = (url, redirects = 0) => {
+      if (redirects > 5) { clearTimeout(timer); return reject(new Error("Too many redirects")); }
+
+      const mod = url.startsWith("https") ? https : require("http");
+      const req = mod.get(url, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          return follow(res.headers.location, redirects + 1);
+        }
+        if (res.statusCode !== 200) {
+          clearTimeout(timer);
+          return reject(new Error(`HTTP ${res.statusCode}`));
+        }
+        const file = fs.createWriteStream(dest);
+        res.pipe(file);
+        file.on("finish", () => { clearTimeout(timer); file.close(); resolve(); });
+        file.on("error", (e) => { clearTimeout(timer); reject(e); });
+      });
+      req.on("error", (e) => { clearTimeout(timer); reject(e); });
+      req.on("timeout", () => { req.destroy(); clearTimeout(timer); reject(new Error("Request timed out")); });
+    };
+    follow(url);
+  });
+}
+
+async function tryDownloadPrebuilt(target) {
+  const assetName = `bb-${target}`;
+  const url = `https://github.com/${REPO}/releases/download/v${VERSION}/${assetName}`;
+
+  fs.mkdirSync(NATIVE_DIR, { recursive: true });
+  const dest = path.join(NATIVE_DIR, "bb");
+
+  try {
+    console.log(`Downloading BB-Agent v${VERSION} for ${target}...`);
+    await downloadBinary(url, dest, DOWNLOAD_TIMEOUT_MS);
+    fs.chmodSync(dest, 0o755);
+
+    // Verify the binary is executable
+    try {
+      execSync(`"${dest}" --version`, { stdio: "pipe", timeout: 5000 });
+    } catch {
+      // Binary may not run on this platform (e.g. wrong arch) — remove it
+      fs.unlinkSync(dest);
+      return false;
+    }
+
+    console.log("✓ BB-Agent binary installed successfully.");
+    return true;
+  } catch (err) {
+    // Clean up partial download
+    try { fs.unlinkSync(dest); } catch {}
+    return false;
+  }
+}
+
+function findInPath(name) {
+  const dirs = (process.env.PATH || "").split(path.delimiter);
+  for (const dir of dirs) {
+    const full = path.join(dir, name);
+    try {
+      fs.accessSync(full, fs.constants.X_OK);
+      return full;
+    } catch {}
+  }
+  return null;
+}
+
+function checkExistingInstall() {
+  const existing = findInPath("bb");
+  if (!existing) return false;
+
+  try {
+    const version = execSync(`"${existing}" --version`, { encoding: "utf8", timeout: 5000 }).trim();
+    console.log(`✓ BB-Agent already installed: ${version} (${existing})`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  if (process.env.BB_SKIP_POSTINSTALL) {
+    return;
+  }
+
+  // Already installed via cargo install?
+  if (checkExistingInstall()) return;
+
+  const target = getTarget();
+
+  // Try prebuilt binary
+  if (target) {
+    const ok = await tryDownloadPrebuilt(target);
+    if (ok) return;
+  }
+
+  // No prebuilt available — print instructions instead of trying cargo build
+  // (cargo build takes 5+ minutes and would appear to hang)
+  const platform = `${os.platform()}-${os.arch()}`;
+  console.log("");
+  console.log("╔══════════════════════════════════════════════════════════════╗");
+  console.log("║  BB-Agent: no prebuilt binary for " + platform.padEnd(19) + "       ║");
+  console.log("║                                                              ║");
+  console.log("║  Install Rust (if needed):                                   ║");
+  console.log("║    curl --proto '=https' --tlsv1.2 -sSf https://rustup.rs|sh ║");
+  console.log("║    source ~/.cargo/env                                       ║");
+  console.log("║                                                              ║");
+  console.log("║  Then build BB-Agent:                                        ║");
+  console.log("║    git clone https://github.com/shuyhere/bb-agent.git        ║");
+  console.log("║    cd bb-agent && cargo install --path crates/cli            ║");
+  console.log("║                                                              ║");
+  console.log("║  Then run:  bb                                               ║");
+  console.log("╚══════════════════════════════════════════════════════════════╝");
+  console.log("");
+}
+
+main().catch((err) => {
+  // Never fail npm install — just print instructions
+  console.error("BB-Agent postinstall notice:", err.message);
+  console.log("Install manually: git clone https://github.com/shuyhere/bb-agent.git && cd bb-agent && cargo install --path crates/cli");
+});