Forst — VS Code extension

Provides .ft language registration and connects to the Forst compiler’s HTTP LSP (forst lsp) for diagnostics on open, edit, and close.

Language features include Providers (use / with): syntax highlighting and snippets for wiring blocks, function hover showing required contracts, and related diagnostic links on unsatisfied Provider obligations (click through the obligation chain in the Problems panel).

LSP over HTTP

The server listens on POST / with Content-Type: application/json. Each request body is a single JSON-RPC 2.0 object (jsonrpc, id, method, params). The response is one JSON-RPC result or error object. This is not stdio LSP; editors need a small HTTP bridge (this extension implements one).

• GET / returns a short JSON description of the endpoint (for probes or manual checks).
• GET /health returns a health JSON payload.

Unsupported methods return JSON-RPC error -32601 Method not found (except initialized and $/cancelRequest, which are acknowledged with a null result when posted with an id).

Requirements

• forst on PATH, a workspace bin/forst from a clone, or leave forst.compiler.path empty so the extension uses @forst/cli (see Compiler download below).
• Default LSP URL: http://127.0.0.1:8081 (configurable via forst.lsp.port).

Develop (F5)

Use VS Code (or a fork that supports the Extension Development Host). Install dependencies at the repo root once (bun install). The preLaunch task runs from the monorepo root: bun run --filter forst compile (same effect as bun run compile inside packages/vscode-forst, or bun run vscode-forst:compile from the root package.json), which runs tsc -p ./ and emits out/extension.js. Tasks also prepend common PATH entries (~/.bun/bin, Homebrew, /usr/local/bin) so Cursor / VS Code can find bun when GUI apps get a minimal environment. That runs on F5 (see below) or via task build:vscode. @forst/cli stays external at runtime (shipped under node_modules in the VSIX) so the CLI can read its own package.json for the compiler version.

Important: --extensionDevelopmentPath must point at packages/vscode-forst, not the monorepo root. Otherwise the extension never loads (no Forst output channel, no Problems).

1. Build the compiler so forst is on PATH, or set forst.compiler.path later.
2. If you opened the whole Forst repo as the workspace (recommended): use the root .vscode/launch.json configuration “Run Extension (vscode-forst)” and press F5. That sets extensionDevelopmentPath to packages/vscode-forst and runs the compile: vscode-forst preLaunch task from the repo root (bun run --filter forst compile) so out/ is up to date.
3. If you opened only packages/vscode-forst as the workspace: use .vscode/launch.json “Run Extension (this folder = vscode-forst)” and F5; the preLaunch task uses the parent monorepo (cwd = two levels up) and runs the same bun run --filter forst compile from that root—keep this folder inside the full clone so ../.. is the repo with package.json / bun.lock.

In the Extension Development Host window, File → Open Folder and choose a tree that contains .ft files (e.g. examples/in). Open an .ft file; the status bar language mode should be Forst. Check View → Output and pick Forst — you should see “Forst extension activated.” and LSP logs after that.

Troubleshooting

• bun not found when the preLaunch task runs: the task prepends ~/.bun/bin, Homebrew, and /usr/local/bin to PATH. If it still fails, add Bun to ~/.zprofile (login PATH) or VS Code → Settings → terminal.integrated.env.osx so GUI-spawned tasks see bun. Install from bun.sh. The compile runs from the monorepo root via bun run --filter forst compile.
• No Forst channel: the dev host did not load this extension; fix extensionDevelopmentPath as above.
• Language mode Plain Text on .ft: extension not loaded, or another extension stole the association; confirm the dev host and try Change Language Mode → Forst.
• Cursor: extension debugging may differ; try VS Code if F5 does nothing.
• Parse errors on type Logger = { info(msg String) }: Providers contract shapes need a recent compiler (method signatures in typedef shapes). Run task build at the repo root so bin/forst is current, set forst.compiler.path to that binary if needed, then Forst: Restart language server. With forst.compiler.download enabled, the extension may use an older cached release until you point it at a local build.

Settings

Settings use two prefixes: forst.compiler.* (executable resolution and downloads) and forst.lsp.* (HTTP language server).

Compiler download

With forst.compiler.download enabled (default), the extension calls resolveForstBinary from the bundled @forst/cli. With forst.compiler.preferLatestRelease enabled (default), it passes preferLatestRelease: true, so the effective compiler version is the maximum of the bundled package semver and GitHub’s latest tag—see packages/cli README. Cached binaries live under the usual FORST_CACHE_DIR / ~/.cache/forst-cli/<version>/ layout.

Status bar

When the extension activates, the status bar shows the configured LSP port (right side, e.g. Forst :8081). The icon reflects LSP state: outline (idle/starting), checkmark (initialized), or error icon if the last operation failed. Click the item to open the Forst output channel (same as command Forst: Focus output).

Command palette

• Forst: Focus output — opens the Forst log channel (HTTP LSP client, spawn, health).
• Forst: Restart language server — stops the spawned process (if any), clears diagnostics, and re-syncs open .ft files.

CI

From the repo root: task build:vscode compiles this package. The same compile runs at the start of task ci:test (see Taskfile.yml). GitHub Actions uses package.json packageManager with setup-bun to pin the Bun version.

Releases (VS Code Marketplace and Open VSX)

The extension is versioned separately from the compiler: Release Please uses packages/vscode-forst and tags like vscode-forst-v0.0.19. When that GitHub Release is published, .github/workflows/publish-vscode-extension.yml builds dist/forst-vscode-<version>.vsix, uploads it to the release, and publishes the same VSIX to:

• VS Code Marketplace when VSCE_PAT is set — Azure DevOps PAT with Marketplace → Manage for publisher forst (create a PAT)
• Open VSX when OVSX_PAT is set — publisher forst (Open VSX token; see Auto publishing extensions)

If a secret is missing, that publish step is skipped and the workflow still succeeds.

@forst/cli dependency: In git, package.json uses workspace:* so local development and task build:vscode / task ci:test resolve the CLI from the monorepo (with task build:cli producing dist/ for types). task build:vsix (and the release workflow) rewrites that dependency to ^<cli semver> from packages/cli/package.json, runs bun install so the CLI is installed from npm, packages the VSIX, then restores package.json and bun.lockb. The published VSIX therefore bundles the registry package, matching end-user installs. Building a production VSIX requires @forst/cli to already exist on npm at a version compatible with the ^ range (typically publish the CLI before or with the same release train).