KUJO THE COURSESTAGE 3 / Projects and tooling · LESSON 21
Mental model
The editor is a client of language tooling. It should help you navigate and diagnose Kujo without becoming a second implementation of the language. An adapter that guesses different semantics creates confusing disagreements with the CLI.
Stable tool contract
kujo lsp starts the language server. Its protocol contracts document initialization, document synchronization, diagnostics, completion, hover, navigation, references, rename, formatting, and related supported surfaces. Check the current capability response instead of assuming all optional LSP features exist.
The CLI also provides machine-readable helper commands such as lsp-diagnostics. Parser diagnostics do not execute the program. A clean editor view is therefore not proof that an effect will be permitted, a network response valid, or an assertion true.
A reproducible editor workflow
Point the adapter at the same pinned binary used by your terminal. Open the course repository as the project root. Introduce a syntax error, inspect its location, repair it, and run the normal VM command. Then navigate to an exported function and compare what the editor shows with its source documentation.
The success example intentionally uses an ordinary function: editor integration should improve routine work, not require a special syntax dialect. The breaking file supplies a genuine parser diagnostic for the helper and CLI drill.
Professional pattern
Keep stdout clean for protocol traffic when launching a language server over standard input/output. Debug logging belongs on the documented separate channel. Capture a minimal source fixture and the server version when reporting an editor discrepancy.
Common mistakes
An extension shipping its own outdated binary may disagree with your shell. Completion suggestions are not validation. Review rename edits before applying them, particularly across modules. Check and test the resulting source change.
Working example
func title(name) { return "Report: " + name }
assert_equal(title("jobs"), "Report: jobs")
print(title("jobs"))
Run it
From the course repository root, use the pinned Kujo 1.3.1 runtime.
kujo check examples/21.kujo
kujo run --untrusted examples/21.kujo
Captured output
Report: jobs
Break it and diagnose it
The malformed parameter list is diagnosed without executing a program. Compare CLI checking with LSP diagnostics on this same source.
func title(name { return name }
kujo run --untrusted examples/21-break.kujo
Exit status: 3. Captured diagnostic:
[KUJOPARSE001] [parser] error: Expected ')' to close function parameter list but found Punctuation('{')
--> examples/21-break.kujo:1:17
= help: Fix the parse error and rerun Kujo.
[KUJOPARSE001] [parser] error: Expected expression
--> examples/21-break.kujo:1:26
= help: Fix the parse error and rerun Kujo.
[KUJOPARSE001] [parser] error: Expected expression
--> examples/21-break.kujo:2:1
= help: Fix the parse error and rerun Kujo.
Exercise
Configure an editor to launch kujo lsp, inspect a syntax error, navigate to a function, and review a rename. Run check and the VM example afterward. Record the server version when comparing results.
Checkpoint
- I use a shared CLI/LSP version.
- I distinguish editor feedback from execution evidence.
- I review generated edits before accepting them.
Verified 2026-09-06 · Official Kujo 1.3.1 release · Source contract · Download example