From 75065051b7ad83dd6d1b0a31e8eb89b6bf77de36 Mon Sep 17 00:00:00 2001 From: Thierno Bah <44367278+soulbah@users.noreply.github.com> Date: Thu, 8 Oct 2026 12:25:03 +0200 Subject: [PATCH] docs: simplify editor setup guides --- README.md | 62 ++++++++++++++---------------------- vscode/README.md | 81 +++++++++++++++--------------------------------- zed/README.md | 49 ++++++++++------------------- 3 files changed, 65 insertions(+), 127 deletions(-) diff --git a/README.md b/README.md index 2e57e2d..adfabc3 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,37 @@ # Rootform editors -VS Code and Zed extensions for Rootform `.rf.hcl` source, powered by -`rootform lsp` from a local Rootform CLI. The extensions do not include or -download Rootform; language semantics come from Rootform's compiler, and the -clients own syntax presentation, launch and lifecycle. +VS Code and Zed extensions for `.rf.hcl` source: diagnostics, completion, +hover, definitions and formatting through `rootform lsp`. -- [VS Code](vscode/README.md), for the Visual Studio Marketplace and Open VSX -- [Zed](zed/README.md), for the Zed extension registry +Install a local [Rootform CLI](https://docs.rootform.dev/installation/), then +choose your editor: -## Development +| Editor | Setup | +| --- | --- | +| VS Code (Visual Studio Marketplace, Open VSX) | [Extension guide](vscode/README.md) | +| Zed (extension registry) | [Extension guide](zed/README.md) | -```sh -bun install --frozen-lockfile -bun run verify -``` - -`verify` checks that both manifests share one version and description, checks -formatting, builds and unit-tests the VS Code client, tests the Zed queries -against the pinned HCL grammar and builds the Zed package for `wasm32-wasip2` -with Rust 1.90, the toolchain the Zed registry packages with. +Both clients launch an existing executable from settings or `PATH`. They ship +no compiler, download no Rootform binary and execute no providers. +See [editing Rootform source](https://docs.rootform.dev/language/editors/). -Real integration qualification uses an explicitly provided Rootform executable -and a local VS Code. Nothing is downloaded: +## Develop ```sh -VSCODE_EXECUTABLE_PATH="/Applications/Visual Studio Code.app/Contents/MacOS/Code" \ -ROOTFORM_BINARY="/absolute/path/to/rootform" \ -bun run --cwd vscode test:integration +bun install --frozen-lockfile +bun run verify ``` -The runner uses a temporary multi-root fixture workspace with unique VS Code -user-data and extension directories. The fixture source is synthetic. - -To try the Zed package, run `zed: install dev extension` in Zed and select the -`zed/` directory. Zed may need network access to prepare the pinned HCL -grammar and `wasi-sdk` while building it; the language server always comes -from the local Rootform executable. - -Native editor runtime qualification currently covers macOS arm64. The Zed -package also builds for `wasm32-wasip2`; Linux and Windows editor runtimes -have not yet been qualified. - -## Releasing +The gate validates manifests, formatting, VS Code build and tests, Zed grammar +queries and the `wasm32-wasip2` package with Rust 1.90. Real editor integration +requires an explicitly provided local Rootform executable; see the +[editor contract](docs/editor-contract.md). +Native editor qualification covers macOS arm64. Linux and Windows runtime +qualification remains separate from package checks. -[Releasing](docs/releasing.md) covers versioning, the release workflow and -publication to each store. +[Releasing](docs/releasing.md) covers versioning and store publication. ## License -Source is [Apache-2.0](LICENSE). Third-party dependencies retain their original -licenses. Rootform name and logo: trademark rights reserved, see -[TRADEMARKS.md](https://github.com/rootform-dev/rootform/blob/dev/TRADEMARKS.md). +[Apache-2.0](LICENSE). Third-party dependencies retain their licenses. +[Rootform trademark terms](https://github.com/rootform-dev/rootform/blob/dev/TRADEMARKS.md) apply. diff --git a/vscode/README.md b/vscode/README.md index af53a25..2a8bc91 100644 --- a/vscode/README.md +++ b/vscode/README.md @@ -1,31 +1,19 @@ # Rootform for VS Code -Write Rootform `.rf.hcl` source with diagnostics, completion, hover, go to -definition and formatting. The extension adds the Rootform language mode, with -syntax highlighting, comments, bracket matching, automatic closing, -indentation and folding, and connects VS Code to `rootform lsp` from your -local Rootform CLI. - -Rootform owns parsing, compilation and formatting. The extension contains no -compiler and does not include or download Rootform. Editing runs no Terraform, -OpenTofu, provider or cloud call. - -## Requirements - -- Rootform on your machine. Follow - [Install Rootform](https://docs.rootform.dev/installation/), then check that - `rootform version` works. -- VS Code 1.133 or later. +Write `.rf.hcl` with diagnostics, completion, hover, definitions and formatting. +The extension adds syntax highlighting and launches `rootform lsp` from your +local CLI. It ships no compiler and downloads no Rootform binary. Editing +executes no providers and makes no cloud calls. ## Get started -1. Install Rootform, then this extension. -2. Open a trusted workspace containing `.rf.hcl` files. -3. Edit a Dialect or Policy Pack. Diagnostics follow your unsaved changes. +1. [Install Rootform](https://docs.rootform.dev/installation/) and verify + `rootform version`. +2. Install the extension in VS Code 1.133 or later. +3. Open a trusted workspace containing `.rf.hcl` files. -The extension starts `rootform` from VS Code's `PATH`. If Rootform is -installed elsewhere, set **Rootform: Server Path** to the absolute path of the -executable: +The extension uses `rootform` from VS Code's `PATH`. For another location, set +**Rootform: Server Path**: ```json { @@ -33,45 +21,26 @@ executable: } ``` -`.rf.json` source files also reach the language server; VS Code keeps its JSON -presentation for them. - -## Settings and commands - -| Setting or command | Purpose | -| --- | --- | -| `rootform.server.path` | Absolute path, or command name resolved through `PATH`, of the local Rootform executable. Default: `rootform`. | -| **Rootform: Restart Language Server** | Restarts `rootform lsp`, for example after replacing the executable outside VS Code. | - -## Workspace trust - -The extension starts the configured executable only in a trusted workspace. -In Restricted Mode, syntax highlighting still works and no process starts. A -workspace cannot change `rootform.server.path` until you trust it. +The setting accepts an absolute path or a command name. Run **Rootform: Restart +Language Server** after changing the executable. `.rf.json` files also reach the +server, while VS Code keeps their JSON presentation. -## Troubleshooting +## Trust and troubleshooting -- **Rootform executable was not found**: install Rootform or set - `rootform.server.path` to an absolute path. A desktop application may not - see the `PATH` of your terminal. -- If the process does not complete LSP initialization within 10 seconds, the - extension stops it and points to the setting. A failed first start is not - retried: fix the setting, then run **Rootform: Restart Language Server**. -- A server that stops after a successful start is restarted by the language - client, within a bounded number of attempts. +In Restricted Mode, syntax highlighting works and no process starts. A workspace +cannot change the executable path until you trust it. -## Learn more +If Rootform is missing, set an absolute path; VS Code may have a different +`PATH` from your terminal. Initialization times out after 10 seconds. Fix the +setting, then restart the language server. After a successful start, unexpected +server exits have a bounded number of automatic retries. -- [Rootform in VS Code](https://docs.rootform.dev/integrations/vscode/) -- [Edit Rootform source](https://docs.rootform.dev/language/editors/) -- [`rootform lsp` reference](https://docs.rootform.dev/reference/cli/lsp/) -- [Report an issue](https://github.com/rootform-dev/editors/issues) +[VS Code guide](https://docs.rootform.dev/integrations/vscode/) | +[`rootform lsp`](https://docs.rootform.dev/reference/cli/lsp/) | +[Report an issue](https://github.com/rootform-dev/editors/issues) ## License -The extension source is licensed under [Apache-2.0](https://github.com/rootform-dev/editors/blob/dev/vscode/LICENSE). -Bundled runtime packages keep their own licenses, listed in -[THIRD_PARTY_NOTICES.md](https://github.com/rootform-dev/editors/blob/dev/vscode/THIRD_PARTY_NOTICES.md). -Rootform name and logo: trademark rights reserved, see -[TRADEMARKS.md](https://github.com/rootform-dev/rootform/blob/dev/TRADEMARKS.md). +[Third-party notices](https://github.com/rootform-dev/editors/blob/dev/vscode/THIRD_PARTY_NOTICES.md) +and [Rootform trademark terms](https://github.com/rootform-dev/rootform/blob/dev/TRADEMARKS.md) apply. diff --git a/zed/README.md b/zed/README.md index 2247a09..19c7623 100644 --- a/zed/README.md +++ b/zed/README.md @@ -1,23 +1,18 @@ # Rootform for Zed -Write Rootform `.rf.hcl` source with diagnostics, completion, hover, go to -definition and formatting. The extension adds Rootform syntax highlighting, -bracket matching, indentation and folding, and starts `rootform lsp` from your -local Rootform CLI. - -Rootform owns parsing, compilation and formatting. The extension does not -include or download Rootform. +Write `.rf.hcl` with diagnostics, completion, hover, definitions and formatting. +The extension adds syntax highlighting and launches `rootform lsp` from your +local CLI. It ships no compiler and downloads no Rootform binary. ## Get started -1. [Install Rootform](https://docs.rootform.dev/installation/) and check that - `rootform version` works. -2. In Zed, open **Extensions**, search for **Rootform** and install it. +1. [Install Rootform](https://docs.rootform.dev/installation/) and verify + `rootform version`. +2. In Zed's **Extensions**, install **Rootform**. 3. Open a `.rf.hcl` file. -The extension finds `rootform` on the worktree `PATH` and starts it with the -`lsp` argument. If Rootform is installed elsewhere, set both the path and the -arguments in Zed's settings: +The extension finds `rootform` on the worktree `PATH`. To choose another +executable, set both its path and arguments: ```json { @@ -32,26 +27,16 @@ arguments in Zed's settings: } ``` -With `binary.path` set, Zed launches that executable directly and passes -`binary.env` to it. Keep `arguments` set to `["lsp"]`: without it, Rootform -starts without a subcommand. - -## Troubleshooting - -A missing executable produces a message with the complete setting. After -fixing a launch error or replacing Rootform, run -`editor: restart language server`. - -## Learn more +Zed launches that executable directly and passes `binary.env` to it. +Keep `arguments` set to `["lsp"]`. After a launch error or executable replacement, +run `editor: restart language server`. -- [Rootform in Zed](https://docs.rootform.dev/integrations/zed/) -- [Edit Rootform source](https://docs.rootform.dev/language/editors/) -- [Report an issue](https://github.com/rootform-dev/editors/issues) +[Zed guide](https://docs.rootform.dev/integrations/zed/) | +[`rootform lsp`](https://docs.rootform.dev/reference/cli/lsp/) | +[Report an issue](https://github.com/rootform-dev/editors/issues) ## License -The extension source is licensed under [Apache-2.0](LICENSE). The pinned HCL -Tree-sitter grammar and the Rust crates compiled into the extension keep their -own licenses, listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). -Rootform name and logo: trademark rights reserved, see -[TRADEMARKS.md](https://github.com/rootform-dev/rootform/blob/dev/TRADEMARKS.md). +[Apache-2.0](LICENSE). [Third-party notices](THIRD_PARTY_NOTICES.md) cover the +pinned HCL grammar and Rust dependencies. +[Rootform trademark terms](https://github.com/rootform-dev/rootform/blob/dev/TRADEMARKS.md) apply.