# AGENTS.md — lsp-typst

## Project Overview

`lsp-typst` is an Emacs Lisp package that provides **LSP support for Typst** (the typesetting language) via `lsp-mode`. It connects to the **tinymist** LSP server to provide completion, diagnostics, formatting, and other LSP features in buffers using `typst-ts-mode`.

- **Homepage:** https://labs.phundrak.com/phundrak/lsp-typst
- **License:** GPLv3+

## Quick Start

```sh
# Enter the reproducible dev shell (Nix)
nix develop

# Run tests (currently a placeholder — see Testing Status below)
eask test
```

No build step is required — the package is pure Elisp.

## Dependencies

| Dependency        | Min. Version | Purpose                              |
|-------------------|--------------|--------------------------------------|
| Emacs             | 30.1         | Runtime                              |
| `lsp-mode`        | 10           | LSP client infrastructure            |
| `f`               | 0.20         | File path manipulation               |
| `typst-ts-mode`   | 0.12         | Typst major mode (recommended)       |

The package can also **auto-download** the `tinymist` binary from GitHub releases.

## Project Structure

| Path                                | Purpose                              |
|-------------------------------------|--------------------------------------|
| `lsp-typst.el`                      | Single-file package (all source)     |
| `Eask`                              | Eask build/test configuration        |
| `flake.nix`                         | Nix flake for reproducible dev shell |
| `flake.lock`                        | Locked Nix inputs (auto-generated)   |

Everything lives in one Elisp file; keep it that way unless complexity warrants splitting.

## Key Conventions

- **Lexical binding** is enabled (`lexical-binding: t`).
- **Colon-double-space** is enforced (`colon-double-space: t`).
- **Naming:** All public symbols are prefixed `lsp-typst-*`.
- **Docstrings:** Present on all `defcustom` and `defgroup` forms. First line is a complete sentence.
- **Comment style:** Section headers use `;;;` with standard Emacs conventions (`;;; Code:`, `;;; Commentary:`, `;;; lsp-typst.el ends here`).
- **Single-file package:** Keep source in `lsp-typst.el` unless the package grows significantly.
- **Indentation:** Standard Emacs Lisp indentation.

## Public API (User-Facing Customization)

| Variable                          | Default                                  | Description                         |
|-----------------------------------|------------------------------------------|-------------------------------------|
| `lsp-typst-server-command`        | `"tinymist"`                             | LSP server binary path              |
| `lsp-typst-server-command-args`   | `'("lsp")`                               | CLI arguments for the server        |
| `lsp-typst-download-url`          | Auto-detected per platform               | URL to download tinymist            |
| `lsp-typst-store-path`            | Inside `lsp-server-install-dir`          | Where the downloaded binary is kept |

There are no interactive commands defined — all configuration is via `defcustom`.

## Architecture Notes

The LSP client is registered in three steps inside `lsp-typst.el`:

1. **Language-ID mapping** — `typst-ts-mode` is mapped to the language id `"typst"` via `lsp-language-id-configuration`.
2. **Dependency definition** — The `typst` dependency is defined, pointing to either a system binary or a downloadable `tinymist` binary.
3. **Client registration** — `lsp-register-client` creates the client with:
   - `:language-id` → `"typst"`
   - `:major-modes` → `(nix-ts-mode)` (see **Known Quirks** below)
   - `:activation-modes` → `lsp-activate-on "typst"`
   - `:server-id` → `'typst`
   - Connection via `lsp-stdio-connection` calling `lsp-typst-server-command` + args
   - Initialization sends configuration via `lsp--set-configuration`

## Known Quirks

- **Suspicious `:major-modes` value:** The client registration lists `(nix-ts-mode)` as the major mode, which looks like a copy-paste artifact. The actual activation gate is `lsp-activate-on "typst"`, but if you're cleaning this up, it should probably be `(typst-ts-mode)`.
- **Only tinymist is supported:** The package is written specifically for **tinymist** (the successor to `typst-lsp`). Do not add support for the older `typst-lsp` server without explicit discussion.

## What Not to Touch

- **`flake.lock`** — Auto-generated by Nix. Regenerate with `nix flake update`. Never edit manually.

## Testing Status

**No tests exist.** The `Eask` test script is a placeholder:

```shell
echo "Error: no test specified" && exit 1
```

Any testing setup would need to be created from scratch (likely a `test/` directory with ERT tests).

## Decision Records

- **tinymist** is the only supported LSP server. The package was written after `typst-lsp` was deprecated in favor of tinymist.
- **No CI is configured** (no `.github/`, no `.gitlab-ci.yml`).
- **No README** exists — this `AGENTS.md` and the package commentary in `lsp-typst.el` serve as documentation.
- **Self-hosted git:** The canonical repository is on a Gitea/Forgejo instance at `labs.phundrak.com`, not GitHub.