Qoc

Developer setup

Clone the Qoc repository, build from source, run the test suite, and contribute a change.

The full Qoc source is available on GitHub at github.com/qoc-app/qoc — this guide walks you through building, testing, and contributing to the project.

Prerequisites

Building from source requires Node.js 20+, npm 10+, and Git. Docker is optional but useful for running the integration test suite in an isolated environment. The build process has been tested on macOS 14+, Ubuntu 22.04+, and Windows 11 with WSL 2.

Clone and build

  1. 1

    Clone the repository

    Clone from GitHub and change into the repository root. The repo contains the CLI source (packages/cli), the MCP server (packages/mcp), the web dashboard (packages/dashboard), and shared types (packages/types).

  2. 2

    Install dependencies

    Run npm install from the repository root. The workspace is managed with npm workspaces; all package dependencies are installed in one step.

  3. 3

    Build all packages

    Run npm run build to compile TypeScript across all packages. Compiled output lands in each package's dist/ directory. The root package.json also exposes build:cli, build:mcp, and build:dashboard scripts if you want to build a single package.

  4. 4

    Link the local CLI binary

    Run npm run link (or npm link inside packages/cli) to place the locally built qoc binary on your PATH. Confirm with qoc --version; it should show a +dev suffix.

Clone and build commands

bash
git clone https://github.com/qoc-app/qoc.git
cd qoc
npm install
npm run build
npm run link

# Verify the development binary
qoc --version
# qoc v0.73.0-dev

Running the test suite

The test suite is split into unit tests (fast, no external dependencies) and integration tests (require Docker for a sandboxed environment). Run npm test for unit tests only, or npm run test:integration to run the full suite including connector stubs and a paper venue simulation.

Test files live alongside the source they test, named *.test.ts. The test runner is Vitest. Coverage reports are written to coverage/ after npm run test:coverage.

Test commands

bash
# Unit tests only (no Docker required)
npm test

# Full integration suite (requires Docker)
npm run test:integration

# Coverage report
npm run test:coverage
open coverage/index.html

Watch mode during development

Run npm run dev to start a watch build that recompiles changed packages automatically. In a second terminal, run qoc up --dev to have the service reload from the local dist/ on each recompile — no restart needed.

Contributing a change

Fork the repository on GitHub, create a feature branch from main, and open a pull request. The CI pipeline runs the full test suite, a TypeScript strict-mode check, and a lint pass against the project's ESLint config. All three must pass before a PR can be merged.

Significant new features should start as a GitHub issue with a brief proposal so the design can be discussed before implementation. Bug fixes and documentation improvements can go straight to a PR.

Contribution checklist

  1. 01Fork and clone your fork
  2. 02Create a branch: git checkout -b feat/your-feature
  3. 03Make your changes and add or update tests
  4. 04Run npm test and npm run build locally — both must pass
  5. 05Push your branch and open a pull request against main
  6. 06Respond to review feedback; the team aims to review within two business days

Code style

The project uses TypeScript strict mode throughout. No any types without an explicit suppression comment explaining why. Prefer explicit return types on exported functions. Run npm run lint to check style before pushing.

PreviousQuick startNext The Unified Trading Account