# Development

```sh
bun install
cp .dev.vars.example .dev.vars
bun run db:migrate
bun run dev
```

The dev server runs at `http://localhost:3000`. The first account to sign up locally becomes the admin.

## How local development differs from production

`bun run dev` and `bun run preview` apply the overrides in `vite.config.ts` on top of `wrangler.jsonc`:

- `PUBLIC_URL=http://localhost:3000` and `GITFOR_LOCAL=true`
- Every Artifacts namespace and trigger filter is renamed to `<namespace>-dev`

The Artifacts binding uses `remote: true`, so local development talks to the real Artifacts service, in the
`-dev` namespace. Workers AI and `send_email` are also `remote: true`: dev uses your account's AI quota and
sends real mail unless `EMAIL_DEV_SINK` is set.

## Resetting local state

Local data is disposable. Rows in the local D1 point at repositories in the `-dev` namespace, so after switching
namespaces, or whenever local state is broken, reset it:

```sh
rm -rf .wrangler/state/v3/d1 && bun run db:migrate
```

Repositories created by local development before the `-dev` split live in the deployed namespace, and the
orphan sweep reports them there. Review that report before ever enabling deletion (see
[self-hosting.md](self-hosting.md#orphan-sweep)).

## Scripts

| Command                             | Purpose                                          |
| ----------------------------------- | ------------------------------------------------ |
| `bun run dev`                       | Local dev server                                 |
| `bun run build`                     | Production build and type-check                  |
| `bun run test`                      | Unit tests                                       |
| `bun run deploy`                    | Check config, apply D1 migrations, deploy        |
| `bun run cf-typegen`                | Regenerate `worker-configuration.d.ts`           |
| `bun run lint` / `bun run format`   | oxlint / oxfmt                                   |
| `bun run video:prepare` / `:upload` | Encode and publish videos ([video.md](video.md)) |

## Architecture

| Concern                                        | Cloudflare primitive                           |
| ---------------------------------------------- | ---------------------------------------------- |
| Git objects and refs                           | Artifacts (Workers binding + smart HTTP)       |
| Users, repos, issues, PRs, CI state            | D1 (with FTS5 search)                          |
| Sessions, refs/object/diff caches, token cache | KV                                             |
| Logs, CI artifacts, release assets             | R2                                             |
| Webhook fan-out and delivery, notifications    | Queues (with retries and a DLQ)                |
| Post-push pipeline, CI run orchestration       | Workflows (`PushWorkflow`, `CiRunWorkflow`)    |
| Job execution, log streaming, merges           | Durable Object `Runner` with a Container       |
| Push events from Artifacts                     | `triggers.events` (`cf.artifacts.repo.pushed`) |

Key code paths:

- `src/server.ts`: Worker entry (git proxy, runner API, raw/archive/asset routes, queue and cron handlers)
- `src/server/git/`: pkt-line, refs, packfile writer, receive-pack client, tree diff, merge-base
- `src/server/ci/`: workflow schema, expressions, compiler, bash job script, runner DO, scheduler
- `src/fns/`: TanStack Start server functions used by the UI
- `migrations/`: D1 schema