- contributing.md: full step-by-step guide for publishing to registry - getting-started-plugin.md: brief mention with link after npm publish step Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
7.6 KiB
Contributing
Contributions are welcome. This page covers how to set up a development environment, project conventions, testing expectations, and the PR process.
Dev Setup
Requirements: Node.js >= 20, pnpm >= 10.
# 1. Fork https://github.com/Open-ACP/OpenACP and clone your fork
git clone https://github.com/<your-username>/OpenACP.git
cd OpenACP
# 2. Install dependencies
pnpm install
# 3. Compile TypeScript
pnpm build
# 4. Run the CLI locally
pnpm start
# 5. Watch mode (recompiles on save)
pnpm dev
# 6. Run the test suite
pnpm test
The compiled output lands in dist/. The entry point is dist/cli.js.
For publishing-related work, pnpm build:publish bundles via tsup into dist-publish/ — this is what gets shipped to npm as @openacp/cli.
Project Conventions
ESM-only
The package uses "type": "module". All import statements must use .js extensions, even when importing .ts source files:
// Correct
import { ChannelAdapter } from './channel.js'
// Wrong — will fail at runtime
import { ChannelAdapter } from './channel'
TypeScript
strict: trueis enforced.- Target: ES2022.
- Module resolution: NodeNext.
- All new files must be
.ts. No plain.jsinsrc/.
File and Module Layout
- Source lives in
src/. Tests live insrc/**/__tests__/or next to the file they test. - Core abstractions belong in
src/core/. Plugin implementations (including adapters) belong insrc/plugins/<name>/. - Public API exports flow through
src/index.ts→src/core/index.ts.
Testing Guidelines
The test framework is Vitest. Run with pnpm test (single run) or pnpm test:watch (interactive watch mode).
Test Flows, Not Internals
Tests should validate behavior against specifications, not implementation details. Focus on observable outcomes: what events are emitted, what methods are called, what state changes result.
// Good — tests the outcome of a complete flow
it('sends a message to the adapter after the agent responds', async () => {
const adapter = mockAdapter()
await core.handleIncomingMessage({ ... })
await vi.waitFor(() => expect(adapter.sendMessage).toHaveBeenCalledWith(...))
})
// Avoid — tests a private implementation detail
it('calls _processQueue internally', () => { ... })
Mock at Boundaries
Mock AgentInstance, ChannelAdapter, and SessionStore — not internal classes. Use vi.fn() for mocks. For event-driven mocks, use TypedEmitter from openacp:
import { TypedEmitter } from 'openacp'
import type { AgentEvent } from 'openacp'
function mockAgentInstance() {
const emitter = new TypedEmitter<{ agent_event: (event: AgentEvent) => void }>()
return Object.assign(emitter, {
sessionId: 'agent-sess-1',
prompt: vi.fn().mockResolvedValue(undefined),
cancel: vi.fn().mockResolvedValue(undefined),
destroy: vi.fn().mockResolvedValue(undefined),
onPermissionRequest: vi.fn(),
}) as any
}
Async Assertions
For fire-and-forget operations, use vi.waitFor() rather than arbitrary sleeps:
await vi.waitFor(() => {
expect(adapter.sendMessage).toHaveBeenCalledTimes(3)
})
Use await Promise.resolve() for microtask timing when you just need to flush the microtask queue.
Timer-Based Tests
Use vi.useFakeTimers() for anything involving timeouts (e.g. permission gate expiry, session TTL):
beforeEach(() => vi.useFakeTimers())
afterEach(() => vi.useRealTimers())
it('times out the permission request after 60 seconds', async () => {
// ...setup...
await vi.advanceTimersByTimeAsync(60_000)
expect(result).toBe('timed_out')
})
What to Cover
Good contributions include tests for:
- All state machine transitions — both valid paths and invalid ones. Verify events emitted on each.
- Error recovery — after an error, the system must remain usable.
- Concurrency — serial processing guarantees, queue ordering, race conditions.
- Boundary values — at exactly the limit (e.g.
maxConcurrentSessions). - Cleanup — timers, listeners, and files are removed in
afterEach. - Idempotency — double
connect(), doubleresolve(), doublestop()must be safe.
Cleanup
Always clean up in afterEach:
afterEach(async () => {
await core.stop()
vi.clearAllMocks()
})
PR Process
-
Branch from
develop, notmain:git checkout develop git pull upstream develop git checkout -b feat/my-feature -
Write tests before or alongside your implementation. PRs without tests for new behavior will be asked to add them.
-
Build and test before pushing:
pnpm build && pnpm test -
Open a PR against
develop. In your PR description:- Explain what the change does and why.
- List any breaking changes.
- Note any backward compatibility considerations (see the
CLAUDE.mdbackward-compat section for the full policy).
-
Backward compatibility: if you change config fields, storage formats, CLI commands, or plugin APIs, you must handle old data gracefully. New config fields need
.default()or.optional()in the Zod schema. See the projectCLAUDE.mdfor the full policy.
Publishing a Plugin to the Registry
Built a plugin? Share it with the community by adding it to the OpenACP Plugin Registry.
Step 1: Publish to npm
cd my-plugin
npm run build
npm publish --access=public
Step 2: Create a registry entry
Fork Open-ACP/plugin-registry and create a JSON file in plugins/:
Filename: your npm package name with @ removed and / replaced by --.
@yourname/openacp-translator→yourname--openacp-translator.jsonopenacp-plugin-tts→openacp-plugin-tts.json
Content:
{
"name": "my-plugin",
"displayName": "My Awesome Plugin",
"description": "What your plugin does in one line",
"npm": "@yourname/openacp-my-plugin",
"repository": "https://github.com/yourname/openacp-my-plugin",
"author": {
"name": "yourname",
"github": "yourname"
},
"version": "1.0.0",
"minCliVersion": "2026.0326.0",
"category": "utility",
"tags": ["keyword1", "keyword2"],
"icon": "🔧",
"license": "MIT",
"verified": false,
"featured": false,
"createdAt": "2026-03-27T00:00:00Z"
}
Categories: adapter, utility, integration, ai, security, media
Step 3: Submit a Pull Request
Submit your PR to the registry repo. CI will automatically:
- Validate your JSON format
- Verify your npm package exists
- Auto-merge if everything passes
After submission
- Your plugin appears in
openacp plugin searchwithin minutes - A daily CI job keeps the version synced with npm — no need to update manually
- Maintainers may review your plugin and mark it as verified (✓)
Requirements
- Plugin must be published on npm before submitting
- Plugin must export a valid
OpenACPPlugininterface - Plugin must have a README with installation instructions
- Plugin must specify a license
Code Style
- Follow the patterns of the file you are editing — consistency within a file takes priority.
- Prefer explicit types over
any. Useunknownwhen the type is genuinely unknown. - Use
createChildLogger({ module: 'my-module' })for structured logging instead ofconsole.log. - Keep files focused. If a file grows beyond ~300 lines, consider splitting it.
- No default exports from core modules — use named exports so tree-shaking and refactoring tools work reliably.