OpenACP/docs/gitbook/getting-started/for-contributors.md
0xmrpeter 63bee61daa fix: update outdated docs + add system command tests
- Fix adapter-reference.md and building-adapters.md (AdapterFactory → plugin pattern)
- Fix contributing.md (src/adapters/ → src/plugins/)
- Fix for-contributors.md (plugin-manager → PluginRegistry)
- Update configuration.md for per-plugin settings
- Update environment-variables.md for plugin-level env vars
- Add system command handler tests

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-26 22:14:52 +07:00

113 lines
3.6 KiB
Markdown

# Quick Start for Contributors
Welcome, and thank you for wanting to contribute! This guide gets your local development environment running so you can explore the code, fix bugs, or build new features.
## Prerequisites
- **Node.js 20 or later** — check with `node --version`
- **pnpm** — OpenACP uses pnpm for package management. Install it with `npm install -g pnpm`
- **Git**
---
## Set up the repository
```bash
# Clone the repo
git clone https://github.com/openacp/OpenACP.git
cd OpenACP
# Install dependencies
pnpm install
# Build the project
pnpm build
# Run the tests — everything should pass
pnpm test
# Start watch mode (rebuilds on every file save)
pnpm dev
```
That's it. You now have a fully working local build.
To run your local build instead of the globally installed version:
```bash
node dist/cli.js --version
```
---
## Project structure
```
src/
cli.ts Entry point for the CLI (start, install, uninstall, plugins, --version, --help)
main.ts Server startup — registers adapters and starts listening
index.ts Public API exports (for use as a library)
core/ The heart of OpenACP
config.ts Zod-validated config loader (~/.openacp/config.json)
core.ts OpenACPCore — the main orchestrator
session.ts Session lifecycle, prompt queue, auto-naming
agent-instance.ts ACP subprocess client — spawns and talks to agents
channel.ts ChannelAdapter abstract base class
plugin/ Plugin system (PluginRegistry, LifecycleManager, PluginContext)
command-registry.ts Central command registry with namespace resolution
commands/ Built-in system command handlers
setup/ Interactive setup wizard and reconfigure flow
plugins/
telegram/ Telegram adapter plugin (grammY)
discord/ Discord adapter plugin
slack/ Slack adapter plugin
```
---
## Key concepts
Understanding these three abstractions covers most of the codebase:
**ChannelAdapter** (`src/core/channel.ts`)
The abstract base that every platform integration extends. Implementations provide `sendMessage`, `sendPermissionRequest`, `sendNotification`, `createSessionThread`, and `renameSessionThread`. If you're adding a new platform, you're writing a ChannelAdapter.
**Session** (`src/core/session.ts`)
Represents one conversation between a user and an agent. It owns a prompt queue (so messages are processed serially, never in parallel), handles auto-naming after the first prompt, and manages the lifecycle of the underlying agent instance.
**AgentInstance** (`src/core/agent-instance.ts`)
The bridge between OpenACP and an AI agent. It spawns the agent as a subprocess, communicates via the ACP protocol, and converts ACP events into the internal `AgentEvent` types that the rest of the system understands.
---
## Running a single test file
```bash
pnpm test src/core/__tests__/session-lifecycle.test.ts
```
Or run all tests in watch mode:
```bash
pnpm test --watch
```
---
## Before you open a PR
- Make sure `pnpm build` completes without errors.
- Make sure `pnpm test` passes.
- For new features, add tests in `src/core/__tests__/` or alongside the relevant module.
- Follow the ESM-only convention — all imports use `.js` extensions, even for TypeScript source files.
---
## Where to go next
- [Contributing](../extending/contributing.md) — PR process, code conventions, and testing guidelines
- [Building Adapters](../extending/building-adapters.md) — step-by-step guide to adding a new platform
- [Plugin System](../extending/plugin-system.md) — how the plugin system works