Skip to content

development.md

Latest commit

 

History

History
119 lines (81 loc) · 4.76 KB

development.md

File metadata and controls

119 lines (81 loc) · 4.76 KB
Raw

Development

See AGENTS.md for build requirements, release protocol, and the completeness rule.

Prerequisites

  • Node.js 22 LTS (CI runs on Node 22)
  • npm (comes with Node)

Setup

git clone https://github.com/aebrer/dreb
cd dreb
npm install
npm run build

Run from source:

node /path/to/dreb/packages/coding-agent/dist/cli.js

The script can be run from any directory. dreb keeps the caller's current working directory.

Monorepo structure

packages/
  ai/              # Model registry, provider APIs, types (@dreb/ai)
  agent/           # Core agent loop, event system, types (@dreb/agent-core)
  tui/             # Terminal UI components (@dreb/tui)
  coding-agent/    # CLI, tools, interactive mode, TUI app (@dreb/coding-agent)
  semantic-search/ # Semantic code search library + MCP server (@dreb/semantic-search)
  telegram/        # Telegram bot frontend over RPC (@dreb/telegram)
  dashboard/       # Web dashboard server/client over RPC (@dreb/dashboard)

Dependencies flow one way through the workspace: coding-agent depends on agent, ai, and tui; frontend packages such as telegram, dashboard, and semantic-search build on the published workspace APIs instead of creating reverse dependencies. Changes to a dependency require rebuilding downstream packages — npm run build handles this automatically in the correct order.

Code style

The project uses Biome for linting and formatting:

npx biome check --write <files>    # Lint + format
npx biome check --write .          # Whole repo

A pre-commit hook runs biome checks, tests, and tsgo --noEmit (matching CI) automatically.

Testing

npm test                                           # All workspace tests
npx vitest --run packages/coding-agent/test/some.test.ts  # Single file
bash test.sh                                       # Full suite, offline (no live provider calls)
bash test.sh --live-api                            # Also run live provider tests (spends real quota)

Live provider tests are opt-in. They make real, billed requests with API keys and subscription OAuth logins from ~/.dreb/agent/auth.json, so npm test, bash test.sh, the pre-commit hook, and CI all skip them by default, even when credentials are present. Credentials are not read or refreshed unless you opt in.

  • DREB_LIVE_API=1 (or bash test.sh --live-api) enables live provider tests for every provider you have credentials for.
  • DREB_LIVE_API_EXPENSIVE=1 additionally enables the context-overflow tests, which send prompts larger than a model's full context window (hundreds of thousands of tokens per request). It has no effect without DREB_LIVE_API=1.

Target a single file or provider when running live tests, for example DREB_LIVE_API=1 npx vitest --run packages/ai/test/stream.test.ts -t "OpenAI Codex". New live tests must gate on isLiveApiEnabled() (or isExpensiveLiveApiEnabled()) from the package's test/live-api.ts; packages/ai/test/live-api-gating.test.ts fails if a credential-gated skipIf/runIf bypasses it. test.sh also disables local LLM tests.

When updating live model fixtures, check protocol behavior as well as catalog membership. Adaptive Claude tests that assert visible thinking must request thinkingDisplay: "summarized". A conservative registry window is not necessarily the endpoint's hard limit: overflow tests may need to check full input usage (input + cacheRead + cacheWrite) when the server accepts a request beyond the configured window.

Type checking

npx tsgo --noEmit

CI runs this across the full repo including examples/. Run it locally before committing — tests alone won't catch type errors in non-test files.

The pre-commit hook runs in order: biome check → tsgo --noEmit → test.sh.

Contributing

  1. Open an issue describing the change
  2. Create a feature branch from master
  3. Make changes, ensure tests pass and tsgo --noEmit is clean
  4. Open a PR against master — CI must be green before merge

Forking / Rebranding

Configure via package.json:

{
  "drebConfig": {
    "name": "dreb",
    "configDir": ".dreb"
  }
}

Change name, configDir, and bin field for your fork. Affects CLI banner, config paths, and environment variable names.

Path Resolution

dreb runs in three execution modes (npm install, standalone binary, tsx from source), all of which need to find package assets correctly.

Always use src/config.ts for package assets:

import { getPackageDir, getThemeDir } from "./config.js";

Never use __dirname directly for package assets.

Debug Command

/debug (hidden) writes to ~/.dreb/agent/dreb-debug.log:

  • Rendered TUI lines with ANSI codes
  • Last messages sent to the LLM