nanocl for vscode

YAML validation, hover documentation and completion for nanocl Statefiles, using the OpenAPI specification matching each document's ApiVersion.

Install locally

Install the supplied VSIX with Extensions → … → Install from VSIX…, or:

code --install-extension /absolute/path/to/nanocl-vscode-0.1.6.vsix

The package includes Red Hat's YAML language engine. No separate YAML extension, nanocl daemon or CLI is needed. If YAML by Red Hat is already enabled, nanocl integrates with it to avoid duplicate editor providers. The extension ID is next-hat.nanocl-vscode.

Open a Statefile and hover over a field for documentation, or press Ctrl+Space for completion. Invalid fields and values appear in the Problems panel and as editor underlines. Try the included examples/Statefile.yml and examples/Statefile.invalid.yml.

Versions, downloads and updates

ApiVersion: v0.18

This downloads https://docs.next-hat.com/specs/nanocld/0.18.yaml at runtime. v0.17 selects 0.17.yaml, and other versions follow the same pattern. There is no fixed list of supported versions: the endpoint must provide a compatible OpenAPI 3.1 specification containing Statefile. Versions with a patch component, such as v0.18.1, use the major/minor spec 0.18.yaml. Quoted strings without the v prefix also work. Each YAML document in a multi-document file selects its own version; unsaved ApiVersion edits update the selection.

When ApiVersion is missing, 0.18 supplies completion and the missing-field validation. Invalid version values receive a format diagnostic and do not choose a remote URL. An unavailable version never falls back to another version's spec.

• Specs download on demand when the YAML engine requests validation, hover or completion. No spec or generated schema is shipped in the VSIX.
• Each version is cached separately in VS Code's extension global storage. The extension checks for an update on first use in each editor session, then at most once per hour while that version is used. Checks use ETag and Last-Modified when the server provides them. There is no background polling while the editor is idle.
• A changed spec is converted and cached only after successful parsing and conversion. Later editor requests use the new schema without reinstalling the extension.
• Offline operation uses the last valid cached spec. First use of a version requires network access. Failed or malformed downloads preserve good cached data; a cold failure can be retried on an editor request after one minute.
• Downloads have a 10-second timeout and a 5 MiB size limit. A failed check can delay the first validation by up to that timeout. Problems are reported in the nanocl output channel with one warning per version/session. Without a cached spec, version-specific validation, hover and completion are unavailable; YAML syntax checking still works.

Recognized files and syntax header

Any basename containing statefile or Statefile and ending in .yml or .yaml is recognized, including my-statefile.yml, my-Statefile-prod.yaml, and prefixstatefilesuffix.yml. Extensionless Statefile and statefile also work. A parent directory named statefile does not activate unrelated YAML files.

For another YAML filename, add this header among the leading comments:

# syntax=nanocl/Statefile
ApiVersion: v0.17

Adding or removing the header updates validation without saving. VS Code must identify the document as YAML. The header is an editor hint and is not executed by nanocl. An explicit standard # yaml-language-server: $schema=... modeline takes precedence over automatic matching; it must point to a JSON Schema, not the raw OpenAPI document.

Validation by Kind

The extension links Resource/Secret Data to the following components, when present in the downloaded version:

Envelope fields such as Name, Kind and required Data still receive validation for unknown kinds. The mapping follows the official resource reference and secret reference. Env payloads are validated when the selected spec includes SecretEnv; versions without that component leave them unchecked. The extension adds no substitute constraints. Known payloads provide nested validation, completion and source descriptions. Changing Kind takes effect without saving.

Validation preserves the source spec's constraints. It cannot enforce rules missing from the spec, check referenced Secrets, evaluate template expressions, fetch SubStates, or validate certificate contents. Templates in numeric or boolean fields may produce diagnostics until rendered. The extension does not execute Statefiles or modify editor settings.

Troubleshooting

Ensure the language shown in the status bar is YAML, and nanocl is enabled in the current VS Code environment (local, SSH, container or WSL). Check yaml.validate, yaml.hover, yaml.completion, and editor.renderValidationDecorations. Remove conflicting modelines or schema associations. For download problems, open Output → nanocl and check that the extension host can reach docs.next-hat.com.

Development

Use Node.js 22 or newer:

npm ci
npm run check
npm run package

The VSIX is written to the project directory as nanocl-vscode-0.1.6.vsix. Builds and automated tests do not require spec downloads. Test-only snapshots live under test/fixtures/ and are excluded from the package. src/schema.cjs extracts the Statefile schema and transitively referenced components, preserving descriptions and constraints. It rewrites references into a self-contained schema and applies the kind mapping. The runtime cache records source hashes and HTTP cache validators.

The package uses publisher ID next-hat; building it does not publish it to a store. The bundled Red Hat YAML engine provides editor diagnostics, hover documentation and completion. See VALIDATION.md in the source tree for checks and the editor test procedure.