feat: initial commit

2026-07-09 17:23:56 +02:00
commit 0d9958caa6
7 changed files with 385 additions and 0 deletions
@@ -0,0 +1,103 @@
+# 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.