Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
209 lines (131 loc) · 5.6 KB

CONTRIBUTING.md

File metadata and controls

209 lines (131 loc) · 5.6 KB

Contributing to Thuki

Thank you for your interest in contributing! This guide will walk you through everything you need to get started.

Table of Contents

Prerequisites

You'll need the following tools installed before you can build Thuki:

Required

Bun: JavaScript runtime and package manager

curl -fsSL https://bun.sh/install | bash

Rust: required for the Tauri backend

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

After installation, restart your shell or run source ~/.cargo/env to make cargo available. Thuki builds against stable Rust.

Running the coverage suite (required before submitting a PR) also needs the nightly-2026-03-30 toolchain with llvm-tools:

rustup toolchain install nightly-2026-03-30 --component llvm-tools

macOS: Thuki is macOS-only. It uses NSPanel and Core Graphics APIs that are not available on other platforms.

Optional

Docker: only needed if you want to run the isolated Docker sandbox instead of a local Ollama install

Ollama: if you're not using the Docker sandbox, install Ollama directly

Development Setup

  1. Fork and clone the repository

    git clone https://github.com/quiet-node/thuki.git
cd thuki

  2. Install frontend dependencies

    bun install

  3. Set up your AI backend (choose one):

    Option A: Docker sandbox (recommended for isolation)

    bun run sandbox:start

    This pulls the default model (gemma4:e2b) and starts the hardened container. It may take a few minutes on first run.

    Option B: Local Ollama

    Make sure Ollama is running and you have a model pulled:

    ollama pull gemma4:e2b

    Thuki connects to http://127.0.0.1:11434 by default.

  4. Configure environment (optional)

    cp .env.example .env

    Edit .env to customize quote display behavior or the system prompt. See docs/configurations.md for all available options.

  5. Launch the app

    bun run dev

    On first run, macOS will prompt for Accessibility permission. This is required for the global keyboard shortcut. Grant it once; it persists across restarts.

Running Tests

100% code coverage is mandatory. All new or modified code must maintain 100% coverage across lines, functions, branches, and statements. PRs that drop below 100% will not be merged.

Frontend tests (Vitest + React Testing Library)

bun run test              # Run all frontend tests
bun run test:watch        # Watch mode
bun run test:coverage     # Run with coverage report

Coverage output is in coverage/. Open coverage/index.html in a browser for a visual breakdown.

Backend tests (Cargo)

bun run test:backend           # Run all Rust tests
bun run test:backend:coverage  # Run with 100% line coverage enforcement

Run everything

bun run test:all           # Both frontend and backend tests
bun run test:all:coverage  # Both with coverage enforcement

Full validation gate

Before submitting a PR, run the full validation suite:

bun run validate-build

This runs lint, format check, typecheck, and build in sequence. All must pass with zero warnings and zero errors.

Code Style

Formatting and linting are enforced by CI. To avoid failed PR checks, run these locally before pushing:

bun run format   # Auto-format TypeScript/CSS (Prettier) and Rust (cargo fmt)
bun run lint     # ESLint + cargo clippy

Key style rules:

  • TypeScript: enforced by ESLint with @eslint-react rules
  • Rust: enforced by cargo clippy -- -D warnings (warnings are errors)
  • No console.log or debug output in committed code

Submitting a Pull Request

  1. Create a branch from main

    git checkout -b feat/your-feature-name

  2. Make your changes following the code style guidelines above

  3. Write or update tests to maintain 100% coverage

  4. Run the validation suite

    bun run test:all:coverage
bun run validate-build

  5. Commit your changes using Conventional Commits format:

    <type>: <short description>

    Common types: feat (new feature), fix (bug fix), docs (documentation), refactor, test, chore. Keep the subject line under 72 characters.

  6. Open a PR against main and fill out the PR template fully

  7. Respond to review feedback: maintainers aim to review within a few days

PR Guidelines

  • Keep PRs focused on a single change. Large, multi-concern PRs are harder to review and slower to merge.
  • If you're fixing a bug, include a test that would have caught the bug.
  • If you're adding a feature, document it in docs/configurations.md if it's configurable.
  • Link any related issues in the PR description.

Good First Issues

New to the codebase? Look for issues tagged good first issue on GitHub. These are scoped to be approachable without deep knowledge of the full system.

If you have a question or want to discuss an approach before writing code, open an issue or start a discussion; we're happy to help.