eda: LSP serve mode for cmd/archie-playbooks #452
Notifications
Due Date
No due date set.
Depends on
Reference: sam/archie#452
Reference in new issue
Block a user
Split out of archie-core-t2db.20 on 2026-09-21, which explicitly authorised
the implementer to decide whether its two-part scope was one ticket or two.
It is two: the yaml.Node decoding upgrade (.20) is pure, unblocked and
gateable on its own, while this half cannot start until a dependency decision
is made.
Second entrypoint of the gopls-shaped binary from t2db.12 (lint mode shipped).
Sam kept it in scope rather than deferring it, because it is the same schema
source as the linter with a different consumer -- the design doc's
shared-package, thin-consumer principle.
Scope: a minimal LSP surface, diagnostics first, over the same
compile/validate path the lint mode and the daemon already share. Add an entry
to cmd/archie-playbooks's existing commands map (verified present at
main.go); t2db.12 built that table to take this addition without
restructuring.
internal/domain/eda/expr's Compile and Eval return structured errors that
should map cleanly to LSP diagnostics. Confirm that rather than re-deriving
error shapes.
Design
DEPENDENCY DECISION: RESOLVED. sourcegraph/jsonrpc2 is approved (Sam,
2026-09-21). The vetting record in this bead's notes is the approval basis:
zero advisories, MIT, actively maintained, one transitive dependency, and a
measured +372KB. The websocket dependency is lazy and a stdio-only transport
never pulls it.
The decision rests on scope, not on the library: this LSP is the first step
toward a full language server, not a permanently diagnostics-only one. Once
the server initiates its own requests (workspace/configuration,
client/registerCapability), request/response ID correlation is a real
correctness surface, and hand-rolling it would be work thrown away. Taking the
library now avoids writing a transport that gets replaced.
Add the dependency as part of this bead. go.mod and go.sum move with it.
SCOPE: diagnostics first. Hover and completion are client-initiated and need
no correlation, so they can follow without a transport change. Do not build
server-initiated requests speculatively.
BLOCKED ON archie-core-t2db.20, which is a genuine prerequisite rather than a
decision: diagnostics need real line numbers, and the loaders currently decode
into a plain map that discards them. .20 lands the yaml.Node decoding that
supplies them.
Add a new entry to cmd/archie-playbooks's existing commands map (verified
present at main.go). t2db.12 built that table to take this addition without
restructuring; do not restructure it.
internal/domain/eda/expr's Compile and Eval return structured errors that
should map cleanly to LSP diagnostics. Confirm that rather than re-deriving
error shapes.
SCOPED GATE COMMAND
go test ./cmd/archie-playbooks/... ./internal/domain/eda/... -count=1
&& go vet ./cmd/archie-playbooks/... ./internal/domain/eda/...
Acceptance criteria
cmd/archie-playbooks gains a serve/lsp command that publishes textDocument/publishDiagnostics for a playbook directory over the same compile/validate path the lint mode uses, with file and line positions from the yaml.Node decoding .20 lands.
Notes
Full vetting record for sourcegraph/jsonrpc2, 2026-09-03 (same rigor as the approved cel.dev/cel-go decision):
Verdict: sourcegraph/jsonrpc2 clears vetting cleanly -- safe, cheap, active, correctness-sensitive-and-worth-depending-on (same reasoning as CEL: reimplementing JSON-RPC request/response ID correlation by hand is a real correctness surface, not free). This is a complete, ready-to-approve recommendation, not yet approved -- do not add the dependency or start implementation until Sam signs off, mirroring the CEL process exactly (full vetting record produced, then explicit approval, then implementation).
Refinement, 2026-09-03: reconsidering the jsonrpc2 recommendation above -- jsonrpc2's main value is correlating a REQUEST this process sends against the eventual RESPONSE (needed for bidirectional JSON-RPC). A minimal diagnostics-only language server (this ticket's stated 'at minimum' scope) never needs to initiate its own request awaiting a correlated response -- it only receives client requests/notifications and sends back responses/notifications synchronously in the same read-dispatch-write loop, plus unprompted notifications (textDocument/publishDiagnostics) that need no correlation either. Under that narrower scope, hand-rolling the Content-Length-framed transport (bufio.Reader + encoding/json, genuinely ~50-100 lines, no ID-correlation subtlety since nothing is being correlated) may be the more honestly 'thin' choice, with zero new dependency. jsonrpc2 becomes the right call specifically if the implementer adds server-initiated requests later (workspace/configuration, client/registerCapability, etc.) -- decide based on which scope is actually being built, not pre-emptively. Recording both paths rather than a single overconfident answer.
2026-09-23: transport and protocol moved to go.lsp.dev (protocol, jsonrpc2, uri; all v1.0.1, BSD-3-Clause) at Sam's direction, replacing sourcegraph/jsonrpc2 and hand-written LSP types (
63be83e0). Vetting: govulncheck clean; archie-playbooks binary 39.3MB -> 44.2MB (+4.8MB, generated full-protocol types); archied does not import it. Pulls github.com/go-json-experiment/json (pseudo-version) transitively.Close reason
Shipped. LSP serve mode exists: internal/app/archieplaybooks/serve.go runs a real language server (go.lsp.dev/protocol) publishing diagnostics on open/save by linting the file saved directory, exposed as cmd/archie-playbooks serve. Verified: go test ./cmd/archie-playbooks/... ./internal/app/archieplaybooks/... passes (serve_test.go).
Imported from beads
archie-core-t2db.28· GitHub #1126 · type task · priority P2 · created 2026-09-21 · closed 2026-09-29