From 2f8cdefb40c2f399855556575a17329e4995099d Mon Sep 17 00:00:00 2001 From: kranthi Date: Fri, 14 Aug 2026 18:38:12 +0100 Subject: [PATCH 1/2] docs: add development guide and fix broken documentation links --- cli/README.md | 2 +- cli/src/__tests__/README.md | 2 +- docs/development.md | 114 ++++++++++++++++++++++++++++++++++++ 3 files changed, 116 insertions(+), 2 deletions(-) create mode 100644 docs/development.md diff --git a/cli/README.md b/cli/README.md index 45d8af675a..1d20d3e97c 100644 --- a/cli/README.md +++ b/cli/README.md @@ -53,7 +53,7 @@ bun run test:tmux-poc # โœ… Works: tmux send-keys -t session $'\e[200~hello\e[201~' ``` -See [tmux.knowledge.md](tmux.knowledge.md) for comprehensive tmux documentation and [src/__tests__/README.md](src/__tests__/README.md) for testing documentation. +See [scripts/tmux/README.md](../scripts/tmux/README.md) and [docs/testing.md](../docs/testing.md) for comprehensive tmux documentation and testing guides. ## Build diff --git a/cli/src/__tests__/README.md b/cli/src/__tests__/README.md index 19d124d74c..7f17881221 100644 --- a/cli/src/__tests__/README.md +++ b/cli/src/__tests__/README.md @@ -165,7 +165,7 @@ await sleep(1000) ## tmux Testing -**See [`../../tmux.knowledge.md`](../../tmux.knowledge.md) for comprehensive tmux documentation**, including: +**See [`../../../scripts/tmux/README.md`](../../../scripts/tmux/README.md) and [`../../../docs/testing.md`](../../../docs/testing.md) for comprehensive tmux documentation**, including: - Why standard `send-keys` doesn't work (must use bracketed paste mode) - Helper functions for Bash and TypeScript diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000000..8da5d13b73 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,114 @@ +# Development Guide + +This guide covers local environment setup, monorepo architecture, development workflows, and testing practices for contributing to Freebuff. + +--- + +## ๐Ÿ“ฆ Monorepo Architecture + +Freebuff is structured as a TypeScript monorepo using Bun workspaces: + +| Workspace | Path | Purpose | +|---|---|---| +| **CLI** | `cli/` | Terminal User Interface (TUI) built with React and OpenTUI | +| **SDK** | `sdk/` | `@codebuff/sdk` public package to orchestrate agents programmatically | +| **Common** | `common/` | Shared types, Zod schemas, utilities, and tool definitions | +| **Agents** | `agents/` | Agent definitions, prompts, and templates | +| **Agent Runtime** | `packages/agent-runtime/` | Multi-agent execution loop, step orchestration, and tool execution | +| **Code Map** | `packages/code-map/` | AST and Tree-sitter powered codebase indexing | +| **LLM Providers** | `packages/llm-providers/` | Model adapters (DeepSeek, OpenAI, Anthropic, Gemini, MiMo, MiniMax) | +| **Freebuff** | `freebuff/` | Freebuff distribution packaging and CLI build scripts | +| **Tmux Scripts** | `scripts/tmux/` | Terminal emulation helpers for interactive CLI testing | + +--- + +## ๐Ÿ› ๏ธ Prerequisites + +- **[Bun](https://bun.sh)**: `v1.3.14` or higher (primary package manager and runtime) +- **Node.js**: `v22+` (for compatibility with certain tooling) +- **Git**: For version control +- **tmux** *(optional)*: Required only for interactive CLI E2E testing (macOS: `brew install tmux`, Linux: `sudo apt-get install tmux`) + +--- + +## ๐Ÿš€ Getting Started + +### 1. Install Dependencies + +Install all workspace dependencies from the root: + +```bash +bun install +``` + +### 2. Build the SDK + +The CLI and other packages depend on the built SDK: + +```bash +bun run build:sdk +``` + +### 3. Run the CLI in Development Mode + +Start the terminal UI directly from source: + +```bash +# Standard CLI dev mode +bun start-cli + +# Or run Freebuff mode +bun run dev:freebuff +``` + +### 4. Build the Freebuff Binary + +Compile the standalone Freebuff distribution binary: + +```bash +bun run build:freebuff +``` + +--- + +## ๐Ÿงช Testing + +Freebuff uses `bun:test` for fast, isolated unit and integration testing. + +### Running Unit Tests + +Run all unit tests across the repository: + +```bash +bun test +``` + +Or run tests for a specific workspace: + +```bash +# Test common utilities +bun test common/src/ + +# Test SDK +bun test sdk/ + +# Test CLI +bun test cli/ +``` + +### Interactive CLI Testing (tmux) + +For testing terminal rendering, bracketed paste mode, and keyboard navigation, Freebuff uses tmux-based session testing. See [`docs/testing.md`](./testing.md) and [`scripts/tmux/README.md`](../scripts/tmux/README.md) for full details. + +--- + +## ๐Ÿ“‹ Code Conventions & Pre-PR Checklist + +Before opening a pull request, ensure the following checks pass: + +1. **Build the SDK**: `bun run build:sdk` +2. **Run Unit Tests**: `bun test` +3. **Validate Monorepo CI**: `bun run ci` +4. **Clean Code**: Follow TypeScript strict typing, avoid `any`, and preserve existing documentation. + +For pull request submission guidelines and scoping rules, see the [Contributing Guide](../CONTRIBUTING.md). From e145dc08dea137a76db18571f092d5f42214711f Mon Sep 17 00:00:00 2001 From: kranthi Date: Thu, 20 Aug 2026 13:03:26 +0100 Subject: [PATCH 2/2] docs: refine development guide with verified scripts, complete workspaces, and env notes --- docs/development.md | 58 +++++++++++++++++++++++++++++---------------- 1 file changed, 38 insertions(+), 20 deletions(-) diff --git a/docs/development.md b/docs/development.md index 8da5d13b73..917af20ce1 100644 --- a/docs/development.md +++ b/docs/development.md @@ -6,7 +6,7 @@ This guide covers local environment setup, monorepo architecture, development wo ## ๐Ÿ“ฆ Monorepo Architecture -Freebuff is structured as a TypeScript monorepo using Bun workspaces: +Freebuff is structured as a TypeScript monorepo using Bun workspaces (defined in [`package.json`](../package.json)): | Workspace | Path | Purpose | |---|---|---| @@ -17,6 +17,7 @@ Freebuff is structured as a TypeScript monorepo using Bun workspaces: | **Agent Runtime** | `packages/agent-runtime/` | Multi-agent execution loop, step orchestration, and tool execution | | **Code Map** | `packages/code-map/` | AST and Tree-sitter powered codebase indexing | | **LLM Providers** | `packages/llm-providers/` | Model adapters (DeepSeek, OpenAI, Anthropic, Gemini, MiMo, MiniMax) | +| **Evals** | `evals/` | Evaluation benchmarks (`buffbench`) for evaluating agent performance | | **Freebuff** | `freebuff/` | Freebuff distribution packaging and CLI build scripts | | **Tmux Scripts** | `scripts/tmux/` | Terminal emulation helpers for interactive CLI testing | @@ -25,9 +26,9 @@ Freebuff is structured as a TypeScript monorepo using Bun workspaces: ## ๐Ÿ› ๏ธ Prerequisites - **[Bun](https://bun.sh)**: `v1.3.14` or higher (primary package manager and runtime) -- **Node.js**: `v22+` (for compatibility with certain tooling) +- **Node.js**: `v22+` (for compatibility with ecosystem tooling) - **Git**: For version control -- **tmux** *(optional)*: Required only for interactive CLI E2E testing (macOS: `brew install tmux`, Linux: `sudo apt-get install tmux`) +- **tmux** *(optional)*: Required for interactive CLI E2E testing (macOS: `brew install tmux`, Linux: `sudo apt-get install tmux`) --- @@ -35,7 +36,7 @@ Freebuff is structured as a TypeScript monorepo using Bun workspaces: ### 1. Install Dependencies -Install all workspace dependencies from the root: +Install all workspace dependencies from the repository root: ```bash bun install @@ -43,13 +44,21 @@ bun install ### 2. Build the SDK -The CLI and other packages depend on the built SDK: +The CLI and other packages depend on the compiled SDK: ```bash bun run build:sdk ``` -### 3. Run the CLI in Development Mode +### 3. Build the Freebuff Binary + +Compile the standalone Freebuff distribution binary into `cli/bin/freebuff`: + +```bash +bun run build:freebuff +``` + +### 4. Run the CLI in Development Mode Start the terminal UI directly from source: @@ -57,17 +66,11 @@ Start the terminal UI directly from source: # Standard CLI dev mode bun start-cli -# Or run Freebuff mode +# Or run in Freebuff mode bun run dev:freebuff ``` -### 4. Build the Freebuff Binary - -Compile the standalone Freebuff distribution binary: - -```bash -bun run build:freebuff -``` +> **Note**: Running the interactive CLI directly from source validates client environment configuration (`.env.local` or environment variables) on startup. See the [Contributing Guide](../CONTRIBUTING.md) and root [`README.md`](../README.md) for details on backend services. --- @@ -83,7 +86,7 @@ Run all unit tests across the repository: bun test ``` -Or run tests for a specific workspace: +Or run tests for a specific workspace or file: ```bash # Test common utilities @@ -92,7 +95,7 @@ bun test common/src/ # Test SDK bun test sdk/ -# Test CLI +# Test CLI unit tests bun test cli/ ``` @@ -102,13 +105,28 @@ For testing terminal rendering, bracketed paste mode, and keyboard navigation, F --- -## ๐Ÿ“‹ Code Conventions & Pre-PR Checklist +## ๐Ÿ“‹ Available Root Scripts + +The following scripts are defined in root [`package.json`](../package.json): + +| Script | Command | Description | +|---|---|---| +| `bun run build:sdk` | `cd sdk && bun run build` | Builds `@codebuff/sdk` (ESM, CJS, types, WASM) | +| `bun run build:freebuff` | `bun freebuff/cli/build.ts 0.0.0-dev` | Compiles the standalone Freebuff binary | +| `bun run ci` | `bun run build:sdk && bun run build:freebuff` | Validates SDK and CLI builds for CI | +| `bun start-cli` / `bun dev` | `bun --cwd cli dev` | Launches CLI in development mode | +| `bun run dev:freebuff` | `FREEBUFF_MODE=true bun --cwd cli dev` | Launches CLI in Freebuff mode | +| `bun run buffbench` | `bun --cwd evals run-buffbench` | Runs evaluation benchmarks | +| `bun test` | `bun test` | Executes the test suite | + +--- + +## ๐Ÿ“‹ Pre-PR Checklist Before opening a pull request, ensure the following checks pass: -1. **Build the SDK**: `bun run build:sdk` +1. **Validate Monorepo CI**: `bun run ci` (runs `build:sdk` and `build:freebuff`) 2. **Run Unit Tests**: `bun test` -3. **Validate Monorepo CI**: `bun run ci` -4. **Clean Code**: Follow TypeScript strict typing, avoid `any`, and preserve existing documentation. +3. **Clean Code**: Follow TypeScript strict typing, avoid `any`, and preserve existing documentation. For pull request submission guidelines and scoping rules, see the [Contributing Guide](../CONTRIBUTING.md).