# Contributing

> Build GUIJam from source. Set up the pnpm and Rust workspace, run the example app against your checkout, and run the same checks as CI.

GUIJam is a pnpm workspace for the TypeScript packages and a Cargo workspace for the Rust daemon, in one repository: [github.com/francistinao/gui-jam](https://github.com/francistinao/gui-jam).

## Set up

You need Node 22.18 or later, pnpm 10, and Rust. The pinned toolchain in `rust-toolchain.toml` is installed by rustup.

```bash
git clone https://github.com/francistinao/gui-jam.git
cd gui-jam
pnpm install
pnpm exec playwright install chromium
cargo build -p gjd-daemon
pnpm build
```

## Try your checkout

Run the example app against your checkout:

```bash
GUIJAM_GJD_BIN=$PWD/target/debug/gjd pnpm --filter small-react-tailwind4 dev
```

Try GUIJam in one of your own Vite apps without changing its tracked files, then remove it again:

```bash
scripts/try-guijam.sh setup ../my-app
scripts/try-guijam.sh clean ../my-app
```

Create fresh apps for every supported framework with their official starters and a real `guijam init`, then test them all:

```bash
scripts/playground.sh
pnpm test:playground
```

Try the setup CLI on any app:

```bash
GUIJAM_GJD_BIN=$PWD/target/debug/gjd node packages/guijam/dist/cli.js init --skip-install --cwd ../my-app
```

## Run the checks

Run every check the CI runs, stopping at the first failure:

```bash
scripts/gate.sh
```

| Command                                                         | What it does                                                                                |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `pnpm build`                                                    | Builds every package; the fixtures use the built output                                     |
| `pnpm check`                                                    | Lints and formats with Biome                                                                |
| `pnpm typecheck`                                                | Type-checks the packages and the fixtures                                                   |
| `pnpm test`                                                     | Runs the unit tests (Vitest)                                                                |
| `pnpm test:e2e`                                                 | Builds, then runs the browser tests (Playwright) against the fixtures                       |
| `pnpm test:playground`                                          | Builds, then runs the browser tests against the apps `scripts/playground.sh` creates        |
| `pnpm contracts:gen`                                            | Regenerates the TypeScript and Rust types from `contracts/`                                 |
| `pnpm contracts:check`                                          | Fails if the generated contracts are out of date                                            |
| `cargo fmt --all --check`                                       | Checks Rust formatting                                                                      |
| `cargo clippy --workspace --all-targets -- -D warnings`         | Lints the Rust code                                                                         |
| `cargo test --workspace`                                        | Runs the Rust tests                                                                         |
| `scripts/smoke-package.sh`                                      | Packs `guijam`, installs it outside the workspace, and checks that it loads and type-checks |
| `cargo run -p gjd-daemon -- provider list`                      | Lists the AI CLIs as the daemon sees them                                                   |
| `cargo run -p gjd-daemon -- provider test claude-code --runs 5` | Runs a real CLI five times and reports timings (spends tokens)                              |

The browser tests use a stand-in for Claude Code, so they spend no tokens.

## Repository layout

| Path                    | What it is                                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------------------------- |
| `packages/guijam`       | The published package: `guijam/vite`, `guijam/nuxt`, `guijam/astro`, `guijam/next` and the `guijam` CLI |
| `packages/vite-plugin`  | Source locations, in-memory previews, hot-update tracking, and the Next.js loader and relay             |
| `packages/overlay`      | The browser widget (React in a shadow root)                                                             |
| `packages/contracts-ts` | TypeScript types generated from `contracts/`                                                            |
| `contracts/`            | JSON Schemas shared by every process                                                                    |
| `crates/gjd-core`       | Source inspection, the patch engine and the journal                                                     |
| `crates/gjd-providers`  | Provider CLI adapters                                                                                   |
| `crates/gjd-daemon`     | The `gjd` binary                                                                                        |
| `fixtures/`             | Apps the tests run against                                                                              |
| `tests/e2e/`            | Playwright suites                                                                                       |
| `tests/playground/`     | Playwright suite for the apps `scripts/playground.sh` creates                                           |
