eda: LSP serve mode for cmd/archie-playbooks #452

Closed
opened 2026-10-27 13:36:23 +00:00 by sam · 0 comments
Owner

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

  • Security: zero advisories on record (GitHub Advisory Database, queried directly). License: MIT (compatible).
  • Maintenance: genuinely active -- commits within the last month (Aug 2026), real CI hygiene work (not a dead repo with a stale README). Not archived (unlike sourcegraph/go-lsp, the other candidate, which IS archived and was ruled out).
  • Dependency footprint: measured directly (not assumed) -- importing only the jsonrpc2.Conn surface pulls in exactly ONE dependency, no gorilla/websocket at all (go.sum showed a single entry). websocket is a lazy/optional dependency of the library, only pulled in if its WS-transport-specific APIs are actually called -- a stdio-only LSP transport never touches it.
  • Binary size cost: measured directly, same baseline methodology as the CEL vetting -- a minimal Go binary baseline was 2,343,283 bytes; adding jsonrpc2 (importing Conn) measured 2,715,265 bytes. Cost: +371,982 bytes (~0.36MB). Far lighter than CEL's +13MB, as expected for a narrow JSON-RPC engine vs. a full expression-language runtime.

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

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): - Security: zero advisories on record (GitHub Advisory Database, queried directly). License: MIT (compatible). - Maintenance: genuinely active -- commits within the last month (Aug 2026), real CI hygiene work (not a dead repo with a stale README). Not archived (unlike sourcegraph/go-lsp, the other candidate, which IS archived and was ruled out). - Dependency footprint: measured directly (not assumed) -- importing only the jsonrpc2.Conn surface pulls in exactly ONE dependency, no gorilla/websocket at all (go.sum showed a single entry). websocket is a lazy/optional dependency of the library, only pulled in if its WS-transport-specific APIs are actually called -- a stdio-only LSP transport never touches it. - Binary size cost: measured directly, same baseline methodology as the CEL vetting -- a minimal Go binary baseline was 2,343,283 bytes; adding jsonrpc2 (importing Conn) measured 2,715,265 bytes. Cost: +371,982 bytes (~0.36MB). Far lighter than CEL's +13MB, as expected for a narrow JSON-RPC engine vs. a full expression-language runtime. 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_
sam added the mediumtask labels 2026-10-27 13:36:23 +00:00
sam self-assigned this 2026-10-27 13:36:23 +00:00
sam closed this issue 2026-10-27 13:36:23 +00:00
sam added a new dependency 2026-10-27 13:42:03 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#452