- 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>
113 lines
3.6 KiB
Markdown
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
|