# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

`opencode_bridge` is a JupyterLab extension that acts as a thin bridge between the JupyterLab UI and a locally-running **OpenCode Serve** process (an AI coding assistant). The architecture, UI flow, and reference TypeScript skeletons are documented in `design.md` — read it before changing the interaction model. The high-level shape is: floating toolbar injected into each `CodeCell` → context provider (cell source, error traceback, neighbours) → REST/SSE call to the Jupyter server extension → server extension forwards to OpenCode Serve over local socket/HTTP.

This is a dual-package extension (one Python package + one NPM package) scaffolded from the [JupyterLab extension-template](https://github.com/jupyterlab/extension-template) v4.6.2 via Copier (see `.copier-answers.yml`). Do not hand-edit files marked "NEVER EDIT MANUALLY" in that file.

## Repository layout

| Path | Purpose |
| --- | --- |
| `src/` | TypeScript frontend (JupyterLab plugin lives in `src/index.ts`, REST helper in `src/request.ts`) |
| `opencode_bridge/` | Python server extension package; routes registered in `opencode_bridge/routes.py` |
| `schema/plugin.json` | Frontend settings schema (currently empty `properties: {}`) |
| `style/` | CSS entry points; `base.css` is empty, only `index.css` imports it |
| `lib/` | Build output of `src/` (gitignored) |
| `opencode_bridge/labextension/` | Build output of the full labextension bundle (gitignored) |
| `ui-tests/` | Playwright + Galata integration tests (separate `package.json` with its own `jlpm install`) |
| `jupyter-config/server-config/opencode_bridge.json` | Auto-enables the server extension on install |
| `design.md` | Architecture, UI flow, and reference TS skeletons — source of truth for the design |
| `.github/workflows/build.yml` | CI: `uv build` with Tsinghua PyPI mirror, then Gitea release + Bark notify |

The Python and JS package share the name `opencode_bridge` but live in different namespaces: the server extension is mounted at the URL prefix `opencode-bridge/...` (note the hyphen), while the Python/JS module name uses the underscore. Frontend → backend calls must hit `<baseUrl>/opencode-bridge/<endpoint>`.

## Common commands

All JS commands go through `jlpm` (JupyterLab's pinned yarn). The yarn setup uses **pnpm as the node linker** (see `.yarnrc.yml`) and disables `enableScripts`; do not run plain `npm install` on the root.

### Install / dev setup

```bash
python -m venv .venv && source .venv/bin/activate
pip install --editable ".[dev,test]"
jupyter-builder develop . --overwrite          # link frontend
jupyter server extension enable opencode_bridge   # server ext must be enabled manually in dev
jlpm install
```

### Build

```bash
jlpm build           # tsc + jupyter-builder (dev), fast iteration
jlpm build:prod      # full clean prod build for distribution
jlpm watch           # tsc -w + jupyter-builder watch in parallel
```

### Tests

```bash
jlpm test            # jest unit tests (src/__tests__/*) with coverage
pytest               # python tests (opencode_bridge/tests/*) — uses pytest-jupyter
# Integration (Playwright + Galata):
(cd ui-tests && jlpm install && jlpm playwright install)   # once
jlpm build:prod                                                    # required before UI tests
(cd ui-tests && jlpm playwright test)                              # run
(cd ui-tests && jlpm playwright test -u)                           # update snapshots
```

Jest config (`jest.config.js`) extends `@jupyterlab/testutils/lib/jest-config`; tests match `src/.*/.*.spec.ts[x]?$`. ESLint ignores `**/*.js`, `**/*.d.ts`, `tests`, `__tests__`, and `ui-tests` — TS files outside `ui-tests` are the only ones linted.

### Lint / format

```bash
jlpm lint           # stylelint + prettier + eslint (--fix variants)
jlpm lint:check     # CI variant, no --fix
```

Prettier is configured for single quotes, no trailing commas, no arrow parens (see `package.json` overrides). Stylelint enforces kebab-case class selectors.

### Release

`RELEASE.md` documents the manual flow (`hatch version`, `jlpm clean:all`, `python -m build`). The CI workflow auto-builds and creates a Gitea release on `v*` tags, then pushes a Bark notification (`.github/scripts/bark-notify.sh`) — Bark failures are non-fatal by design.

## Conventions specific to this repo

- **Server extension is enabled in two places**: `jupyter-config/server-config/opencode_bridge.json` (auto, on pip install) and must be enabled manually in dev mode. The pytest config (`conftest.py`) re-enables it via the `jp_server_config` fixture.
- **URL prefix vs. package name**: REST endpoints are mounted under `opencode-bridge/` (hyphen), even though the Python and JS packages are named `opencode_bridge` (underscore). `src/request.ts` hardcodes the hyphenated prefix; keep them in sync if you add endpoints.
- **Endpoint handlers must decorate every verb method with `@tornado.web.authenticated`** (see `opencode_bridge/routes.py`); the existing `HelloRouteHandler` only implements `get` — if you add POST/PATCH/PUT/DELETE, decorate each one.
- **Settings**: `schema/plugin.json` currently has no properties; the frontend loads it via `ISettingRegistry` in `src/index.ts`. When you add a setting, update `schema/plugin.json`, the `settingRegistry.load(...)` consumer, and document defaults.
- **Dev install of UI tests is a separate subproject**: `ui-tests/package.json` is not part of the root workspace. Run `jlpm install` inside `ui-tests/` once; do not move those deps to the root.
- **Generated artefacts**: `opencode_bridge/_version.py` is generated by hatch (gitignored) and `opencode_bridge/labextension/` is generated by the labextension build (gitignored). If you see them missing locally, you haven't run `jlpm build` yet.
- **PyPI mirror**: `pyproject.toml` pins the Tsinghua mirror for `uv`/`pip`, and CI sets `UV_DEFAULT_INDEX` to the same. Other users on slow/non-China networks may need to override this.

## Where to start when changing…

- **Adding a new REST endpoint**: add the handler in `opencode_bridge/routes.py` (with `@tornado.web.authenticated` on every verb), register the route under `opencode-bridge/<name>` in `setup_route_handlers`, then call it from the frontend via the `requestAPI` helper in `src/request.ts`.
- **Changing the cell UI / toolbar / inline prompt box**: `design.md` has working reference skeletons for `src/context_provider.ts` and `src/components/cell_toolbar.ts` — implement them; do not invent a new interaction model without updating the design doc.
- **Adding a JupyterLab setting**: `schema/plugin.json` + consume via `ISettingRegistry` in `src/index.ts`.
- **Packaging / release**: `RELEASE.md` + `.github/workflows/build.yml`; remember CI uses Gitea, not GitHub Releases.