Contributing

Contributing to CortexPrism

Contributions are welcome! CortexPrism is open source and accepts bug reports, feature ideas, documentation improvements, and code contributions.

Getting Started

Prerequisites: Deno 2.x. Docker is optional.

git clone https://github.com/CortexPrism/cortex.git
cd cortex
deno run --allow-all src/db/migrate.ts

# Verify everything passes
deno task check   # Type-check
deno task lint    # Lint
deno task fmt     # Format
deno task test    # Run tests

Development Workflow

1. Create a feature branch from main
2. Make changes following conventions
3. Verify: deno task check && deno task lint && deno task fmt && deno task test
4. Commit using conventional commit format
5. Open a PR against main

Code Conventions

TypeScript

• Strict mode — no implicit any, no ! assertions without comment
• Async-first — prefer async/await over raw Promise chains
• Fire-and-forget — background tasks use .catch(() => {}), never block
• Error handling — catch at boundaries, surface actionable messages
• No hardcoded secrets — use vault + env vars
• No hardcoded paths — use PATHS from src/config/paths.ts

Subprocess Spawning

Use Deno.Command — never Deno.run (deprecated).

Adding a New Tool

1. Create src/tools/builtin/your_tool.ts implementing Tool from src/tools/types.ts
2. Register in src/tools/registry.ts
3. Wire into src/server/ws.ts if needed for Web UI
4. Add policy rule if it executes shell commands or makes network requests
5. Add tests in tests/your_tool_test.ts

Adding a New CLI Command

1. Create src/cli/your-cmd.ts exporting a Command from @cliffy/command
2. Register in src/main.ts
3. Document in README and CHANGELOG

Adding a Database Migration

1. Create src/db/migrations/NNN_description.sql (next sequential number)
2. Add entry to targets array in src/db/migrate.ts
3. Never edit applied migrations — create new ones instead

Adding a New LLM Provider

1. Create src/llm/your-provider.ts implementing LLMProvider from src/llm/types.ts
2. Register in src/llm/factory.ts
3. Add provider config schema
4. Add to setup wizard in src/cli/setup.ts
5. Document in README, CHANGELOG, and LLM Providers wiki page

Writing Tests

Tests live in tests/ and use Deno's built-in test runner:

deno task test                          # All tests
deno test --allow-all tests/memory_test.ts  # Single file

• Follow pattern: tests/<module>_test.ts
• Prefer unit tests without live LLM API calls
• Use mocks/stubs for integration tests

Commit Style

Use Conventional Commits:

feat: add discord channel adapter
fix: handle empty response from Ollama
docs: update CLI reference
chore: bump deno.json dependencies
refactor: extract policy evaluation into pure function
test: add workspace path traversal cases

Opening a Pull Request

• One logical change per PR
• Fill in the PR template
• Link related issues with Closes #123
• CI must pass (lint, format, type-check, tests)
• Rebase on main before requesting review

Issue Reporting

• Bugs — use the Bug Report template, include OS, Deno version, full error
• Features — use the Feature Request template
• Security — do NOT open public issues; follow Security Policy

License

By contributing you agree that your contributions will be licensed under MIT.