ccs/CONTRIBUTING.md

Contributing to CCS

CCS is a Bun + TypeScript CLI with a React dashboard. This guide is the shortest path to making a clean change without reverse-engineering the repo first.

Before You Start

• An issue is helpful for medium or large changes, but small fixes and docs updates can go straight to a PR.
• Branch from dev.
• Open PRs against dev.
• Use conventional commits.
• If you change user-facing behavior, update the docs that describe it.
• Suspected security vulnerabilities do not go through public issues. Use SECURITY.md.

If you are new to the project, start with a docs fix, a focused bug fix, or an issue labeled good first issue.

Repo Map

Area	Main paths	Typical follow-up
CLI runtime	src/, lib/, config/, scripts/	Add or update tests in tests/
Dashboard UI	ui/src/	Run cd ui && bun run validate
Web server and config APIs	src/web-server/, src/api/, src/config/	Add unit or integration coverage
Documentation	https://docs.ccs.kaitran.ca, README.md, docs/, CONTRIBUTING.md	Keep user-facing docs in sync
Static assets	assets/	Verify screenshots and references still match

Useful directories:

• tests/unit/ for focused logic tests
• tests/integration/ for cross-module behavior
• tests/npm/ for packaging checks
• tests/native/ for shell and platform coverage
• docs/ for architecture, roadmap, and internal implementation notes

Environment Setup

Prerequisites

• Node.js >=18
• Bun >=1.0
• GitHub CLI (gh) if you want to open PRs from the terminal

Clone and install

git clone https://github.com/YOUR_USERNAME/ccs.git
cd ccs
git remote add upstream https://github.com/kaitranntt/ccs.git

git checkout dev
git pull upstream dev

bun install
cd ui && bun install && cd ..

Branching and PRs

Create all normal contribution branches from dev.

git checkout dev
git pull upstream dev
git checkout -b feat/short-description

Use these prefixes:

• feat/* for features
• fix/* for bug fixes
• docs/* for documentation-only changes

Rules:

• Never commit directly to main or dev.
• Open PRs to dev, not main.
• Treat hotfix/* as maintainer-only emergency flow from main.
• Delete your branch after merge.

AI Review Lane

CCS PR review no longer depends on anthropics/claude-code-action. The repository review lane is self-hosted PR-Agent:

• The retained .github/workflows/ai-review.yml runs PR-Agent in GitHub Actions.
• PR-Agent reviews run on the existing self-hosted cliproxy runner.
• Use /review on the PR when you need a fresh pass after follow-up commits.
• Only the trusted /review comment path is enabled on the privileged self-hosted runner.
• Keep repository-level reviewer instructions in the root .pr_agent.toml.
• Keep runtime wiring and defaults in ai-review.yml, which still maps the existing AI_REVIEW_BASE_URL, AI_REVIEW_MODEL, and AI_REVIEW_API_KEY integrations onto PR-Agent's OPENAI.* and config.* settings.
• If you change review defaults, update the workflow or .pr_agent.toml alongside the contributor or architecture docs in the same PR.

Example:

git push -u origin docs/contributing-refresh
gh pr create --base dev --title "docs(contributing): refresh contributor guide"

Local Development

Safe test environment

CCS reads and writes under ~/.ccs/. Do not test against your real setup when developing.

Unix:

export CCS_HOME="$(mktemp -d)"

PowerShell:

$env:CCS_HOME = Join-Path $env:TEMP ("ccs-" + [guid]::NewGuid())

If you touch code that reads CCS paths, route it through getCcsDir() in src/utils/config-manager.ts so tests stay isolated.

Common workflows

bun run build            # Compile CLI
bun run dev              # Build server and start local config dashboard
bun run dev:symlink      # Point global ccs to local build
bun run dev:unlink       # Restore original global ccs
cd ui && bun run dev     # Dashboard-only dev server

Use bun run dev from the repo root when working on the local dashboard experience behind ccs config.

Validation

If you can, run these before you open or update a PR:

bun run format
bun run lint:fix
bun run validate
bun run validate:ci-parity

If you changed the dashboard:

cd ui
bun run format
bun run validate

Helpful targeted commands:

bun run test:unit
bun run test:all
bun run test:native
bun run test:e2e

bun run validate is the main gate. It covers typechecking, linting, format checks, maintainability checks, and automated tests for the main project.

If you cannot run the full suite, that is still fine for early or docs-only PRs. Just say what you did run, or what blocked you, in the PR.

What To Update With Your Change

If you change CLI behavior

• Update the relevant --help output in src/commands/.
• Add or update automated coverage in tests/.
• Update README.md if the user workflow changed.

If you change dashboard behavior

• Keep CLI and dashboard parity where the feature supports both.
• Update ui/src/ and any affected tests.
• Run UI validation from ui/.

If you change config, providers, or architecture

• Update the relevant docs in docs/.
• Mention migration or compatibility notes in the PR.
• If the change affects automated PR review behavior, update the ai-review.yml or .pr_agent.toml guidance as well.

Commit Style

CCS uses conventional commits because the release and workflow tooling depend on them.

git commit -m "fix(doctor): handle missing config gracefully"
git commit -m "feat(cliproxy): add provider quota check"
git commit -m "docs(contributing): simplify contributor workflow"

Avoid:

git commit -m "fix stuff"
git commit -m "WIP"
git commit -m "update file"

Release Notes

Releases are automated with semantic-release.

• Merges to dev publish the @dev channel.
• Merges to main publish the @latest channel.
• Do not manually bump versions, create tags, or run manual npm publish.

Security Reporting

If you think you found a security vulnerability, do not open a public GitHub issue.

Use the private reporting path in SECURITY.md:

• https://github.com/kaitranntt/ccs/security/advisories/new

Public issues are fine for normal bugs, regressions, docs problems, and feature requests. They are not fine for exploit details, leaked credentials, or anything that could put users at risk before a fix ships.

Need Help?

• Bugs and features: https://github.com/kaitranntt/ccs/issues
• Questions: https://github.com/kaitranntt/ccs/issues/new/choose
• Security reports: https://github.com/kaitranntt/ccs/security/advisories/new
• Hosted docs: https://docs.ccs.kaitran.ca
• User-facing docs: README.md
• Internal architecture notes: docs/
• Community expectations: .github/CODE_OF_CONDUCT.md