Editor Integrations

chio-lsp flags a policy or manifest mistake while you type it, inside VS Code, Zed, or any editor that speaks the Language Server Protocol. Its diagnostics carry the same registry codes as chio doctor.

Both extensions are thin clients: they spawn chio-lsp and forward edits and requests. The server owns the document cache, validation, and the completion, hover, and definition catalogs, so every editor gets the same answers.

1. Check the language server

The installer puts chio-lsp on your PATH beside chio. The editor needs no running kernel, receipt store, or trust-control service.

chio-lsp --version

chio-lsp 0.2.0

You should see the same version as chio --version. If the shell cannot find it, rerun the installer, or pin the binary's absolute path in step 3.

2. Load the extension for your editor

For VS Code, install the Chio extension from the marketplace, or search for Chio in the Extensions view.

code --install-extension backbay.vscode-chio

Installing extensions...
Extension 'backbay.vscode-chio' v0.2.0 was successfully installed.

For Zed, run zed: extensions from the command palette, search for Chio, and install it.

You should see Chio language support activate when you open a matching file such as chio.yaml. If the editor treats the file as plain YAML, select the Chio language mode.

3. Point the editor at the binary

Both editors resolve chio-lsp on PATH and spawn it with no arguments. Pin an absolute path when the binary lives elsewhere.

{
  "chio.lsp.path": "/opt/chio/bin/chio-lsp",
  "chio.lsp.args": [],
  "chio.trace.server": "off"
}

{
  "lsp": {
    "chio-lsp": {
      "binary": {
        "path": "/opt/chio/bin/chio-lsp",
        "arguments": []
      }
    }
  }
}

The server speaks LSP over stdio and takes no command-line options, so leave the arguments empty. In Zed an empty or whitespace-only path falls back to the bare chio-lsp on PATH.

4. Open an incomplete chio.yaml and see a diagnostic

In a scratch directory, create a chio.yaml that omits the required policy key.

version: 1
capabilities: []

You should see an error from chio-lsp with the code urn:chio:error:cli:doctor-chio-yaml-invalid and the message that policy is missing. A missing key has no token to point at, so the caret sits at the start of the document. If nothing appears, check the filename, the language mode, and the binary path from step 3.

import json, os, subprocess, sys, time

def frame(msg):
    body = json.dumps(msg).encode()
    return b"Content-Length: %d\r\n\r\n%s" % (len(body), body)

def replies(messages):
    server = os.environ.get("CHIO_LSP", "chio-lsp")
    proc = subprocess.Popen([server], stdin=subprocess.PIPE, stdout=subprocess.PIPE)
    for msg in messages:
        proc.stdin.write(frame(msg))
        proc.stdin.flush()
        time.sleep(0.5)
    proc.stdin.close()
    raw, out = proc.stdout.read().decode(), []
    while "Content-Length: " in raw:
        head = raw.index("Content-Length: ")
        gap = raw.index("\r\n\r\n", head)
        size = int(raw[head + 16 : gap])
        out.append(json.loads(raw[gap + 4 : gap + 4 + size]))
        raw = raw[gap + 4 + size :]
    return out

OPEN = {"jsonrpc": "2.0", "id": 1, "method": "initialize",
        "params": {"processId": None, "rootUri": None, "capabilities": {}}}
READY = {"jsonrpc": "2.0", "method": "initialized", "params": {}}
BAD_CONFIG = {"jsonrpc": "2.0", "method": "textDocument/didOpen", "params": {"textDocument": {
    "uri": "file:///work/chio.yaml", "languageId": "chio-yaml", "version": 1,
    "text": "version: 1\ncapabilities: []\n"}}}

if sys.argv[1] == "handshake":
    for reply in replies([OPEN]):
        if "result" in reply:
            print(json.dumps(reply["result"], indent=2))
else:
    for reply in replies([OPEN, READY, BAD_CONFIG]):
        if reply.get("method") == "textDocument/publishDiagnostics":
            print(json.dumps(reply["params"]["diagnostics"], indent=2))

$ python3 lsp-probe.py handshake

{
  "capabilities": {
    "completionProvider": {
      "triggerCharacters": [
        ":",
        " ",
        "-"
      ]
    },
    "definitionProvider": true,
    "hoverProvider": true,
    "textDocumentSync": 1
  },
  "serverInfo": {
    "name": "chio-lsp",
    "version": "0.1.0"
  }
}

$ python3 lsp-probe.py diagnostic

[
  {
    "code": "urn:chio:error:cli:doctor-chio-yaml-invalid",
    "message": "chio.yaml is missing required key `policy`.",
    "range": {
      "end": {
        "character": 0,
        "line": 0
      },
      "start": {
        "character": 0,
        "line": 0
      }
    },
    "severity": 1,
    "source": "chio-lsp"
  }
]

5. Scaffold a manifest from a snippet

In a new app.chio-manifest.yaml, type manifest-skeleton and expand it.

version: 1
name: manifest_name
policy:
  default: deny
capabilities:
  - id: capability_id
    scope:
      - scope.action
guards:
  - ref: guard.identifier

You should see a complete starting manifest with policy, capabilities, and guard references filled in with default values. Snippets use LSP-standard ${1:label} placeholders, so both editors accept the same source. Three more prefixes are listed in the reference below.

6. Confirm chio doctor reports the same code

Run chio doctor in the directory holding the incomplete chio.yaml from step 4.

$ chio doctor --skip-network | grep -E 'chio_yaml|missing:'

  [error] chio_yaml (urn:chio:error:cli:doctor-chio-yaml-invalid): ~/chio/chio.yaml is missing required keys: policy
    missing: policy

You should see urn:chio:error:cli:doctor-chio-yaml-invalid and missing: policy, the code your editor showed. The editor and the CLI check the same required keys, version and policy, and draw their codes from one registry.