# Contributing to repolore

## Dev environment

Monorepo managed with pnpm workspaces. Node >= 20 required.

```sh
pnpm install
pnpm build   # builds all packages: core, cli, server, web (and gui, the optional add-on)
pnpm test    # runs the full test suite across all packages
pnpm lint    # ESLint (root-level; web uses its own oxlint via `pnpm --filter @repolore/web lint`)
pnpm format  # Prettier, writes in place
```

Run a package directly during development, no build step needed:

```sh
pnpm --filter @repolore/cli dev -- <args>   # e.g. `pnpm --filter @repolore/cli dev -- list`
pnpm dev:server                              # http://localhost:3000
pnpm dev:web                                  # http://localhost:5173
```

One gotcha: `pnpm --filter <pkg> dev -- <args>` runs with its **cwd set to that package's directory**, not wherever you ran `pnpm` from — pass absolute paths, or use `pnpm --filter @repolore/cli exec tsx src/index.ts <args>` if a relative path needs to resolve against your actual working directory.

## Project structure

- `packages/core` — all real logic: ingestion, chunking, embedding, vector store, chat/retrieval, doc-gen. `cli` and `server` both depend on it directly.
- `packages/cli` — the `repolore` command, published unscoped for `npx`/`npm install -g` ergonomics.
- `packages/server` — HTTP/SSE API, powers `repolore serve` and remote/self-hosted use.
- `packages/web` — the React web GUI, built static assets served by `server`.
- `packages/gui` — thin optional add-on (`repolore-gui`) bundling `server` + `web` so `repolore serve` is a single install.

`web` only ever talks to `server` over HTTP/SSE — it never imports `core` directly. `cli` and `server` never import from each other; anything that needs to work identically in local and remote mode goes through the `RagStore` interface (`LocalRagStore` vs. `RemoteRagStore`), not a branch scattered through command handlers.

## Making a change

- TypeScript everywhere, strict mode on.
- Add tests for new behavior — this project treats test coverage as part of the change, not an afterthought.
- Run `pnpm build && pnpm test && pnpm lint` before opening a PR.
- If your change touches anything under `packages/**`, add a changeset:

  ```sh
  pnpm changeset
  ```

  This prompts for which packages changed and a short summary, and writes a file under `.changeset/`. CI fails a PR that touches `packages/**` with no changeset present. All 5 published packages (`core`, `cli`, `server`, `gui`, `web`) are version-linked — they always bump together, so you don't need to figure out which specific packages to list beyond what actually changed.

- Keep PRs focused — one logical change per PR rather than bundling unrelated fixes.

## Releasing (maintainers)

Merging a changeset-bearing PR to `main` triggers a "Version Packages" PR with the version bumps and changelog entries computed from the pending changesets. Merging *that* PR publishes the new versions to npm automatically via CI (Trusted Publishing — no long-lived token involved).

## Questions / bugs

Open an issue. For anything involving a security vulnerability, see [`SECURITY.md`](./SECURITY.md) instead of a public issue.