gasm-sdk/docs/ZED.md

Using gasm-devkit with Zed

This document is deliberately blunt, because the situation is a genuine conflict between two of the project's own commitments, and papering over it would be dishonest.

The conflict

gasm-devkit is pure Go, no C, no cgo, no JavaScript runtimes, no native binaries, no vendor lock-in, no platform-specific IDE internals.

Zed's extension model, as verified against Zed's own documentation, is:

• Extensions are written in Rust and compiled to WebAssembly (wasm32-wasip2).
• Syntax highlighting is provided by Tree-sitter grammars, which are C compiled to WebAssembly with the wasi-sdk, from a grammar written in a JavaScript DSL.
• A new language cannot be registered through configuration alone. Defining a language requires an extension, and every language extension must name a Tree-sitter grammar. (Zed's lsp settings section configures already-registered servers; it does not register an arbitrary external binary for a brand-new language.)

There is therefore no pure-Go path into Zed's extension host. This is a property of Zed, not of gasm-devkit: no language tooling author can feed Zed a pure-Go highlighting grammar, because Zed's highlighting engine is Tree-sitter and its plugin runtime is Rust/WASM.

What gasm-devkit gives Zed regardless

The toolkit's integration surface is the Language Server Protocol, an open standard. Through gasm lsp it provides, with zero editor-specific code:

• autocomplete (instructions, registers, pseudo-registers, labels),
• hover documentation,
• diagnostics (the linter, pushed as you type),
• document outline (functions and labels),
• syntax highlighting, delivered as LSP semantic tokens.

That last point matters: Zed can render highlighting entirely from LSP semantic tokens ("semantic_tokens": "full" replaces Tree-sitter highlighting for a language). So the highlighting capability exists in pure Go; what Zed needs is merely to be told that .s files are a language served by gasm lsp.

The honest options

1. Use an editor that registers an external LSP by configuration. Neovim, Helix, VS Code and Sublime all let you associate .s with the gasm lsp binary and use its semantic tokens — no Rust, no C, no lock-in. This is the option that satisfies every stated constraint with no exception.

2. Treat a Zed adapter as one quarantined exception. A minimal Zed extension — a few lines of Rust that register the language and launch gasm lsp — plus either a Tree-sitter grammar or "full" semantic tokens for highlighting. Crucially, this adapter is the editor's plugin format; it is sandboxed inside Zed and never linked into, compiled into, or shipped with the Go toolkit. gasm-devkit itself stays pure Go. But producing it uses the Rust/wasi-sdk/Tree-sitter toolchain, which the project constraints forbid — so it must be a conscious, explicit decision, not a silent one.

The author's philosophy — digital sovereignty, no dependency on toolchains he does not control — is the tie-breaker, and it is a value judgement rather than a technical one. gasm-devkit is built so that either choice keeps the toolkit itself clean: the pure-Go core and the LSP are the product; a Zed adapter, if ever wanted, is a thin, separable leaf.

Wiring the LSP (editor-agnostic)

Run the server and point an LSP client at it:

go run ./cmd/gasm lsp        # or: go install ./cmd/gasm && gasm lsp

Associate the command with *.s (and *_amd64.s / *_arm64.s) in whichever editor you use. The server infers the target architecture from the file-name suffix and selects the amd64 or arm64 instruction tables accordingly.