Skip to content

Editor support (VS Code)

.strategy files get two editor superpowers from the repo's VS Code extension (editors/vscode-strategy):

  • Syntax highlighting: a TextMate grammar colors the script language: comments, keywords (strategy, when, stop, …), $ engine references ($platform.price.nan), step labels and triggers, types, booleans, numbers, and strings.
  • Live validation: a dependency-free client in the extension speaks Language Server Protocol over stdio to dio strategy lsp, a minimal LSP server built into the engine (src/engine/strategies/harness/strategy_lsp.ml). It runs the exact same parser and validator as dio strategy validate and surfaces the results as inline diagnostics as you type, before you ever restart the engine.

The extension has no runtime dependencies on npm, because the client uses only the built-in VS Code API. What it does need is the compiled dio binary.

1. Prerequisites

  1. A working build of dio (see Deploying for options). From the repo root:
dune build
# the binary lands at _build/default/bin/main.exe
  1. The binary must be reachable. Either put it on your PATH, or tell the extension where it is (see §3).

2. Install the extension

There are two equivalent ways. Both load the extension from the source folder, with no packaging registry involved.

Package the folder once, then install the .vsix:

cd editors/vscode-strategy
npx --yes @vscode/vsce package
code --install-extension dio-strategy-0.1.0.vsix --force

Re-run these two commands after you change anything under editors/vscode-strategy to update the installed copy.

Option B: run a development instance

Launch a dedicated VS Code window with the extension pre-loaded from the folder:

code --extensionDevelopmentPath=editors/vscode-strategy .

Use this when iterating on the extension itself; Ctrl+Shift+P → Developer: Reload Window picks up your JS changes without reinstalling.

Reload the window after installing

Newly installed or updated extensions only activate on a fresh window. Run Ctrl+Shift+P → Developer: Reload Window once after installing.

The extension activates on onLanguage:strategy. Because the manifest registers the .strategy file extension, highlighting is automatic and you do not need a files.associations entry. Verify a file got the grammar with Ctrl+Shift+P → Developer: Inspect Editor Tokens and Scopes: tile types should report the source.strategy scope.

3. Point the server at the binary

Highlighting needs nothing, but live validation spawns dio strategy lsp from the executable named in the dioStrategy.binary setting:

  • Default: dio (attempts to find dio on your PATH).
  • Workspace: the repo ships with .vscode/settings.json already set:
{
  "dioStrategy.binary": "./_build/default/bin/main.exe"
}

Relative paths resolve against the workspace folder, so a fresh dune build in this repo is all that's needed.

  • Any other machine or container: set it in your own user settings (Ctrl+, → search dioStrategy.binary) to the absolute path of the dio binary, or add dio to your PATH.

If the extension cannot start the server it shows a warning toast naming the binary it tried; highlighting still works, only validation is off.

4. Using it

Open a strategy file and it is colored immediately. As you type:

  • Undocumented or unknown actions/facts/parameters are flagged at the step where they appear (red = error, yellow = warning), with the message from the validator, e.g. step ev_cancelled: unknown action: apply_order_evet.
  • Parse errors (missing colon, unknown trigger, bad indentation) are reported at the exact line and column.
  • Fix one file as you write it; validate everything with dio strategy validate strategies/<name>.strategy before you restart the engine.

Duplicate labels, effectful actions missing a dedup_key, bad action argument names/types, and unknown $platform.* / $state.* references are all caught live, because this is the same Strategy_compile.validate the engine runs at startup.

Verifying the server by hand

You can talk to the LSP server directly to confirm it is working. It is a standard stdio JSON-RPC process:

printf 'Content-Length: 75\r\n\r\n{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' \
  | _build/default/bin/main.exe strategy lsp

A healthy server responds with an initialize result advertising textDocumentSync and serverInfo.dio-strategy, then exits quietly on EOF.

Only dio strategy lsp talks LSP; the other strategy commands stay CLI-only

command is
dio strategy lsp Language Server Protocol server over stdio (drives VS Code)
dio strategy validate <file> one-shot CLI validation (exit 0 = ok)
dio strategy compile <file> [-o out.json] lower script → JSON form

5. Other editors

dio strategy lsp is a plain LSP server and speaks the industry-standard protocol, so any LSP-capable editor (Neovim, Emacs, Zed, …) can attach to dio strategy lsp in stdio mode. The TextMate grammar lives at editors/vscode-strategy/syntaxes/strategy.tmLanguage.json and is also usable by any editor with TextMate grammar support.

See Strategy script language for the language itself, and Authoring a strategy for wiring a file into a running engine.