iLSP/EDITOR_SETUP.md

# iLSP — Editor Setup Guide

iLSP is a self-hosted LSP proxy at `ilsp.i80.dk` that provides smart autocomplete for:

- **Bicep** — internal module registry, parameter names, allowed values, version tags
- **Python** — Jedi-powered completions and diagnostics
- **YAML pipelines** — Azure DevOps template references and GitHub Actions reusable workflows

No extra editor plugins are needed beyond the standard language-server clients you
already have. iLSP speaks standard LSP over WebSocket and works with any editor that
supports LSP WebSocket transport.

---

## Neovim setup

```lua
-- In your LSP config (e.g. ~/.config/nvim/lua/lsp.lua)

-- Bicep
vim.lsp.start({
  name = "ilsp-bicep",
  cmd = vim.lsp.rpc.connect("wss://ilsp.i80.dk/bicep"),
  root_dir = vim.fs.dirname(vim.fs.find({ "bicepconfig.json", ".git" }, { upward = true })[1]),
  filetypes = { "bicep" },
})

-- YAML (pipeline files)
vim.lsp.start({
  name = "ilsp-yaml",
  cmd = vim.lsp.rpc.connect("wss://ilsp.i80.dk/yaml"),
  root_dir = vim.fs.dirname(vim.fs.find({ ".git" }, { upward = true })[1]),
  filetypes = { "yaml" },
})

-- Python
vim.lsp.start({
  name = "ilsp-python",
  cmd = vim.lsp.rpc.connect("wss://ilsp.i80.dk/python"),
  root_dir = vim.fs.dirname(vim.fs.find({ "pyproject.toml", ".git" }, { upward = true })[1]),
  filetypes = { "python" },
})
```

## VS Code setup

Install the [LSP WebSocket](https://marketplace.visualstudio.com/items?itemName=example.lsp-ws) extension (or equivalent), then add to `settings.json`:

```json
{
  "lspWebSocket.servers": [
    { "languageId": "bicep", "url": "wss://ilsp.i80.dk/bicep" },
    { "languageId": "yaml",  "url": "wss://ilsp.i80.dk/yaml" },
    { "languageId": "python","url": "wss://ilsp.i80.dk/python" }
  ]
}
```

---

## What iLSP adds on top of the standard schema

### Bicep — internal module registry

The standard Bicep LSP knows nothing about your internal ACR registry.
iLSP intercepts completion requests and injects:

| Context | What you get |
|---------|-------------|
| `'br/modules:<cursor>'` | All 27 internal modules (`appservice`, `roleassignments`, …) |
| `'br/modules:roleassignments:<cursor>'` | Available versions (`1.1.x`, `2.0.x`, `latest`, …) |
| `params {` inside a module block | Parameter names with types, required/optional, defaults |
| parameter value positions | Allowed values for enum-type params |

Items from the internal catalog always sort to the **top** of the completion list.

### YAML pipelines — AzDO template completions

When you type `- template:` in an `azure-pipelines.yml`, iLSP recognises the AzDO
pipeline format and injects completions from the `pipeline-templates` Bitbucket repo:

```yaml
steps:
  - template: tasks/k8s/deploy.yaml@pipeline-templates
    #                   ↑ cursor here → get all task templates with @pipeline-templates label
    parameters:
      environment: |  # ← cursor here → get param names for deploy.yaml
      targetNamespace:  # ← cursor here → get allowed values if defined
```

**Format detection** — iLSP auto-detects AzDO vs GHA:
- `- template:` or `stages:` / `trigger:` → AzDO mode
- `on:` / `workflow_call` / `runs-on:` → GHA mode

No extra configuration needed in your editor.

### YAML pipelines — GitHub Actions reusable workflows

In `.github/workflows/*.yml` files that call LRU-Digital reusable workflows:

```yaml
jobs:
  deploy:
    uses: LRU-Digital/infra/.github/workflows/deploy-k8s.yml@main
    #                          ↑ cursor here → get all reusable workflows
    with:
      environment: |  # ← cursor here → get input names for deploy-k8s.yml
```

---

## Updating the catalogs

Catalogs are baked into the Docker image at build time. To update them:

```bash
cd ~/Projects/iLSP

# 1. Regenerate catalogs from local repos
python3 scripts/sync_pipeline_templates.py   # → pipeline_templates_catalog.json
python3 scripts/sync_iac_module_sources.py   # → iac_source_catalog.json (from DevOpsMCP)
python3 scripts/sync_bicep_modules.py        # → bicep_modules_catalog.json

# 2. Push and deploy
bash scripts/push_catalogs.sh
```

The `/reload` endpoint on the running service reloads catalogs from volume-mounted
files if present, so you can update without a full redeploy for pipeline templates.

---

## Health check

```bash
curl https://ilsp.i80.dk/health
# → {"status":"ok","bicep_modules":27,"iac_source_modules":26,"pipeline_templates":48,"yaml_lsp":true,...}
```

| Field | What it means |
|-------|--------------|
| `bicep_modules` | Modules in the ACR registry catalog |
| `iac_source_modules` | Modules with source-level param docs |
| `pipeline_templates` | AzDO + GHA templates available for YAML completion |
| `yaml_lsp` | yaml-language-server detected and working |

---

## Smoke tests

```bash
# Against production
python3 scripts/smoke_test_completions.py

# Against local dev container
python3 scripts/smoke_test_completions.py http://localhost:2089
```

Tests 1–5 cover Bicep, tests 6–7 cover YAML pipeline templates.