lsp-typst/AGENTS.md

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

# 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:

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.