# Contributing to OpenChamber ## Getting Started ```bash git clone https://github.com/openchamber/openchamber.git cd openchamber bun install ``` ## Dev Scripts Run commands from the project root unless a section says otherwise. ### Web | Script | Description | Ports | |--------|-------------|-------| | `bun run dev` | Default web HMR dev flow. | auto-selected dev ports | | `bun run dev:web:full` | Build watcher + Express server. No HMR — manual refresh after changes. | `3001` (server + static) | | `bun run dev:web:hmr` | Vite dev server + Express API. **Open the Vite URL for HMR**, not the backend. | `5180` (Vite HMR), `3902` (API) | | `bun run start:web` | Start the packaged web server. | `3000` by default | Both are configurable via env vars: `OPENCHAMBER_PORT`, `OPENCHAMBER_HMR_UI_PORT`, `OPENCHAMBER_HMR_API_PORT`. ### Desktop (Electron) ```bash bun run electron:dev # HMR web UI + Electron shell bun run electron:dev:bundled # Electron shell using built web assets bun run electron:build # Package desktop app for the current platform ``` Desktop supports macOS, Windows, and Linux. The build output is written to `packages/electron/dist`. macOS builds create `dmg` and `zip` files. You need Xcode/build tools for notarized packaging and icon asset work. Windows builds create an NSIS installer. If signing env vars are not set, the build script makes an unsigned installer. Linux builds produce an AppImage for the native x64 or arm64 host. For desktop-specific details, see [`packages/electron/README.md`](./packages/electron/README.md). ### VS Code Extension ```bash bun run vscode:dev # Watch mode + Extension Development Host bun run vscode:build # Build extension + webview bun run vscode:package # Create a local .vsix package ``` `bun run vscode:dev` opens an Extension Development Host automatically. You can override the editor or workspace with `OPENCHAMBER_VSCODE_BIN` and `OPENCHAMBER_VSCODE_DEV_WORKSPACE`. Example: `OPENCHAMBER_VSCODE_BIN=cursor bun run vscode:dev`. ### Shared UI (`packages/ui`) No standalone app server. This is a source-level library used by Web, Desktop, and VS Code. Useful package commands: ```bash bun run build:ui bun run type-check:ui bun run lint:ui ``` ## Build And Package Commands | Command | What it does | |---------|--------------| | `bun run build` | Build all workspaces | | `bun run build:web` | Build only `packages/web` | | `bun run build:ui` | Build only `packages/ui` | | `bun run build:electron` | Run Electron package build script without full packaging | | `bun run electron:build` | Build packaged desktop app for the current OS | | `bun run vscode:build` | Build the VS Code extension | | `bun run vscode:package` | Package the VS Code extension as `.vsix` | | `bun run pack:web` | Create a package archive for `@openchamber/web` | ## Platform Build Notes You usually build desktop installers on the target platform. macOS: ```bash bun run electron:build bun run release:test:intel bun run release:test:arm ``` Windows: ```bash bun run electron:build ``` Linux x64 and arm64 AppImages are packaged natively on the matching host architecture. Use Bun for dependency installation and packaging orchestration: ```bash OPENCHAMBER_TARGET_ARCH=x64 bun run electron:build # On an arm64 host: OPENCHAMBER_TARGET_ARCH=arm64 bun run electron:build bun run --cwd packages/electron verify:linux-appimage ``` The final AppImage verifier checks desktop identity and the architecture of Electron, the bundled OpenCode CLI, and packaged native modules. ## Before Submitting ```bash bun run type-check # Must pass bun run lint # Must pass bun run build # Must succeed ``` For docs-only changes, validation may be enough: ```bash bun run docs:validate ``` ## Code Style - Functional React components only - TypeScript strict mode — no `any` without justification - Use existing theme colors/typography from `packages/ui/src/lib/theme/` — don't add new ones - Components must support light and dark themes - Prefer early returns and `if/else`/`switch` over nested ternaries - Tailwind v4 for styling; typography via `packages/ui/src/lib/typography.ts` ## Pull Requests Pull requests are review handoffs, not just diffs. A reviewer must be able to understand the intended behavior, assess the risk, and verify the result without reconstructing the contributor's work. Before opening a pull request: 1. Read [`AGENTS.md`](./AGENTS.md), every project skill matching the character of the change, and the nearest package README and module `DOCUMENTATION.md`. 2. Keep the change focused. Separate unrelated cleanup or refactors. 3. Run the validation required by the applicable project guidance, not only the broad commands above. 4. Complete the pull request template with concrete, current evidence. ### Pull Request Contract Every pull request must explain: - **Intent:** the user or maintainer problem being solved and the resulting behavior. - **Non-goals:** nearby behavior intentionally left unchanged when the scope could otherwise be ambiguous. - **Affected surfaces:** packages, runtimes, persisted/external contracts, and user-visible states affected by the change. - **Repository guidance:** the skills and owning documentation that were applicable, why they applied, and how the implementation satisfies their important constraints. - **Validation:** exact automated and manual checks performed, their result, and anything that was not verified. A command name without a result is not evidence. - **Risk and failure behavior:** meaningful failure, rollback, cleanup, compatibility, security, performance, or cross-runtime considerations. Do not claim a runtime, platform, relay path, performance characteristic, or interaction is correct based only on type-checking or linting. If required validation could not be performed, state that explicitly and explain why. ### Visual Evidence User-visible changes require evidence that lets a reviewer compare the behavior before and after the change. Attach screenshots for static states and a short recording for motion, gestures, drag-and-drop, focus, or multi-step interactions. Claims about performance, memory, CPU, rendering, startup, or similar empirical behavior require relevant before and after measurements. Choose evidence based on the affected behavior: - Include before and after states. If a meaningful before state cannot be captured, explain why. - Include narrow/mobile and desktop states when shared or responsive UI is affected. - Include light and dark states when colors, styling, surfaces, or visual states change. - Include relevant loading, empty, error, disabled, long-content, or high-contrast states when the change affects them. - For Settings changes, show the relevant narrow and wide settings pane states. Evidence must represent the current pull request HEAD. After implementation changes that can affect the demonstrated behavior, refresh the evidence or state why it remains valid. If there is genuinely no user-visible change, say so and provide a concrete reason; deleting the evidence section is not an exemption. ### Review Enforcement The automated reviewer performs one unified review of correctness, repository guidance compliance, pull request quality, and evidence. It independently determines which project skills apply from the character of the current diff, reads those skills and their required references, and checks the implementation against them. The reviewer records the exact HEAD it inspected and returns one verdict: - `PASS`: no blocking correctness, compliance, or evidence issue was found. - `NEEDS_EVIDENCE`: no correctness, repository-guidance, or contribution-contract blocker was found, but a required screenshot, interaction recording, or empirical measurement is missing, stale, contradictory, or inadequate. - `BLOCKED`: a concrete correctness, security, repository-rule, or contribution contract violation must be fixed. - `HUMAN_REVIEW_REQUIRED`: the change affects review policy or another boundary that automation must not approve on its own. The workflow exposes the current state as exactly one readiness label: `review:pending`, `review:ready`, `review:needs-evidence`, `review:blocked`, `review:human-required`, or `review:automation-failed`. A new review removes the previous readiness label before it starts, and only `review:ready` means the pull request is ready to enter the maintainer review queue. Draft pull requests have no readiness label. AI review verdicts are advisory and never fail the pull request check. Readiness is communicated only through the `review:*` label and immutable review comment. The `automation` job fails only when the workflow itself cannot complete or verify a trustworthy result, in which case it applies `review:automation-failed`. Each completed review creates a new comment tied to its reviewed HEAD so the conversation remains chronological. Previous review comments are not rewritten. ## Project Structure ``` packages/ ui/ Shared React components, hooks, stores, and theme system web/ Web server (Express) + frontend (Vite) + CLI electron/ Electron desktop shell vscode/ VS Code extension (extension host + webview) ``` See [AGENTS.md](./AGENTS.md) for detailed architecture reference. ## Not a developer? You can still help: - Report bugs or UX issues — even "this felt confusing" is valuable feedback - Test on different devices, browsers, or OS versions - Suggest features or improvements via issues - Help others in Discord ## Questions? Open an [issue](https://github.com/openchamber/openchamber/issues) or ask in [Discord](https://discord.gg/ZYRSdnwwKA).