nika-lsp

Language Server Protocol (LSP) implementation for Nika YAML workflows.

Features

• Syntax Validation — Real-time YAML validation for .nika.yaml workflows
• Autocompletion — 5 semantic verbs (infer, exec, fetch, invoke, agent)
• MCP Tool Discovery — Completion for available MCP tools
• Task Dependency Validation — Validates with: references and DAG structure
• Template Variable Completion — {{with.*}} and {{inputs.*}} variables
• Go-to-Definition — Navigate to task definitions
• Hover Documentation — Inline docs for verbs and parameters
• Diagnostics — NIKA error codes with actionable suggestions

Installation

From crates.io (recommended)

cargo install nika-lsp

From Homebrew

brew install supernovae-st/tap/nika-lsp

From source

git clone https://github.com/supernovae-st/nika
cd nika/tools/nika-lsp
cargo install --path .

Verify installation

nika-lsp --version

Editor Setup

VS Code

1. Install the YAML extension
2. Add to your settings.json:

{
  "yaml.customTags": ["!include scalar"],
  "yaml.schemas": {
    "https://nika.sh/schema/workflow.json": "*.nika.yaml"
  },
  "yaml.languageserver.enabled": false,
  "[yaml]": {
    "editor.defaultFormatter": null
  }
}

3. Configure the LSP in VS Code:

   • Install LSP client extension or configure manually
   • Add nika-lsp as a custom language server

Neovim (nvim-lspconfig)

Add to your Neovim configuration:

local lspconfig = require('lspconfig')
local configs = require('lspconfig.configs')

-- Define nika-lsp if not already defined
if not configs.nika_lsp then
  configs.nika_lsp = {
    default_config = {
      cmd = { 'nika-lsp' },
      filetypes = { 'yaml' },
      root_dir = function(fname)
        return lspconfig.util.root_pattern('.nika', 'nika.yaml', '.git')(fname)
      end,
      settings = {},
    },
  }
end

-- Enable nika-lsp
lspconfig.nika_lsp.setup({
  on_attach = function(client, bufnr)
    -- Your on_attach function here
  end,
})

Helix

Add to ~/.config/helix/languages.toml:

[[language]]
name = "yaml"
language-servers = ["nika-lsp", "yaml-language-server"]

[language-server.nika-lsp]
command = "nika-lsp"

Zed

Add to your Zed settings:

{
  "lsp": {
    "nika-lsp": {
      "binary": {
        "path": "nika-lsp"
      }
    }
  },
  "languages": {
    "YAML": {
      "language_servers": ["nika-lsp", "yaml-language-server"]
    }
  }
}

Sublime Text (LSP package)

Add to LSP settings:

{
  "clients": {
    "nika-lsp": {
      "command": ["nika-lsp"],
      "selector": "source.yaml",
      "schemes": ["file"]
    }
  }
}

Emacs (lsp-mode)

Add to your Emacs configuration:

(with-eval-after-load 'lsp-mode
  (add-to-list 'lsp-language-id-configuration
    '(yaml-mode . "yaml"))
  (lsp-register-client
    (make-lsp-client
      :new-connection (lsp-stdio-connection '("nika-lsp"))
      :activation-fn (lsp-activate-on "yaml")
      :server-id 'nika-lsp)))

Usage

The LSP server starts automatically when your editor opens a .nika.yaml file. Features include:

Completions

Type a verb and get intelligent suggestions:

tasks:
  - id: my_task
    # Type 'inf' and get 'infer:' completion with documentation

Diagnostics

Get real-time error feedback:

tasks:
  - id: task1
    with:
      data: nonexistent_task  # Error: Unknown task 'nonexistent_task'
    infer: "Process {{with.data}}"

Hover Documentation

Hover over verbs for inline documentation:

tasks:
  - id: research
    agent:  # Hover for: "Multi-turn agentic loop with MCP tools"
      prompt: "Research AI papers"

Configuration

The LSP respects the following settings (when supported by your editor):

Supported Schema Versions

• nika/workflow@0.12 (current)
• nika/workflow@0.11
• nika/workflow@0.10
• nika/workflow@0.9
• nika/workflow@0.8
• nika/workflow@0.5
• nika/workflow@0.3

Development

# Build
cargo build

# Test
cargo test

# Run with logging
RUST_LOG=debug nika-lsp

Architecture

nika-lsp/
├── src/
│   ├── main.rs           # LSP server entry point
│   ├── backend.rs        # Language server implementation
│   ├── completion.rs     # Completion provider
│   ├── diagnostics.rs    # Validation diagnostics
│   ├── hover.rs          # Hover documentation
│   └── document.rs       # Document management
└── Cargo.toml

The LSP integrates with the main nika crate for:

• AST parsing — Uses nika::ast::parse_yaml() for accurate parsing
• Validation — Leverages nika::analyzer for semantic validation
• Error codes — Surfaces NIKA-xxx error codes with fix suggestions

Related

• nika — Main CLI and runtime
• nika.sh — Documentation
• JSON Schema — Workflow schema

License

MIT License — see LICENSE for details.