Phobos Extension for Visual Studio Code

The Phobos Extension for Visual Studio Code adds language support for Phobos HCL pipeline templates, powered by the Phobos Language Server.

Features

Editing

• Syntax highlighting for pipeline.hcl, release_lifecycle.hcl, *.pbvars (Phobos variables files — the analog of Terraform's .tfvars), and any .hcl file you've explicitly opted into via phobos.editor.associateAllHclFiles. Generic .hcl files are not claimed by default to avoid clashing with Terraform / Nomad / Packer in mixed-tool workspaces.
• Diagnostics — real-time error highlighting covering parse errors, missing required attributes, disallowed enum values, name-format violations, block-count limits, duplicate names, cross-field rules, stage_order correctness, return-type validation of HCL built-ins, dependency-name validation, dead action references, unused declarations, and plugin-alias resolution (unresolved plugin = <type>.<alias> refs, plus the ambiguity case where an action must pick one of several aliased instances). Both push and pull diagnostics supported; the client picks pull automatically when available.
• Completion — block types, attribute names, enumerated values, HCL built-ins, named-value namespaces (var., jwt., vcs_token., system., pipeline., this.), cross-task output references (all four shapes), alias-aware this.alias.* resolution, dependency-name completion inside dependencies = [...], and plugin-instance completion inside action { plugin = <cursor> } that offers every declared <type>.<alias> qualified name. vcs_token.<name>.value is offered as a completion when the cursor sits past the token name. Legacy phobos.* / action_outputs.* completion items render with strikethrough.
• Hover documentation — Markdown for blocks, attributes (with type info / allowed values / limits), action labels (description + inputs + outputs), per-output-reference hovers, and task-output hovers that resolve pipeline.stage.<s>[.pre|.post].task.<t>.outputs.<o> to the declared output "<o>" block.
• Go-to-definition and find-all-references across var., jwt., vcs_token., volume., pipeline.stage.*, this.action.*, this.alias.*, and plugin-alias references (cursor on an action's plugin = <type>.<alias> traversal jumps to the matching plugin block's alias).
• Rename with cross-file propagation for workspace-level declarations (variable, jwt, vcs_token). Plugin aliases rename in place: edits touch the alias half of each action { plugin = <type>.<alias> } usage; the type prefix stays anchored to the action-label.
• Call hierarchy — right-click a task / deployment / nested pipeline to see which siblings depend on it (incoming) and which it depends on (outgoing).
• Document highlight — cursor-on-declaration flashes every reference in the file.
• Formatting — Format Document (Shift+Alt+F) runs hclwrite.Format; on-type formatting re-formats the closing block when you type }.
• Semantic tokens layered on top of the TextMate grammar.
• Inlay hints for variable types, variable defaults, per-task action + output counts (: 2 actions, 1 output), per-stage children counts (: 3 tasks, : 2 tasks, 1 pipeline), deployment environments, and per-action plugin-instance badges. Action-plugin badges render the resolved instance: : docker.builder when the action sets plugin = docker.builder, falling back to the bare plugin type (: docker) otherwise. Each category is independently toggleable.
• Document links on plugin sources inside plugin_requirements, pointing at the plugin registry.
• Deprecation markers — legacy phobos.* / action_outputs.* references render with strikethrough. Hover explains the replacement; the Phobos: Migrate Deprecations in Current File command applies every preferred fix as a single undoable edit.
• Folding, document symbol, selection range, signature help — standard editor niceties.
• 19 built-in snippets for full templates (pipeline, multipipe), blocks (stage, stagephases, task, taskdeps, taskretry, pre, post, action, action-plugin for actions targeting an aliased plugin instance, output, var, plugins, plugin-alias for aliased plugin blocks, jwt, vcs, nested), and gates (approval — when = "manual" + approval_rules).

Variables files (*.pbvars)

The extension claims *.pbvars as Phobos documents — the analog of Terraform's .tfvars, used to supply concrete inputs to a sibling pipeline.hcl or release_lifecycle.hcl. Vars-file features are fully cross-file aware:

• Diagnostics against the sibling template's variable declarations: unknown name, type mismatch (with friendly messages like variable "replicas" has type number but was assigned a value of type string), no-blocks rule, and HCL-native errors for unresolved references inside values.
• Snippet completion for declared variable names, shaped to the variable's declared cty.Type. String values insert quotes-with-cursor-between, numbers insert a 0 placeholder selected for one-keystroke overwrite, bools insert a true/false choice dropdown, lists wrap brackets, and object({...}) types pre-populate every declared field with its own tab stop, sorted alphabetically with = aligned. Already-assigned variables are filtered out of the suggestion list.
• Hover surfaces the sibling variable's description, declared type, and default-state.
• Live cross-file — unsaved edits to the sibling template propagate to the open .pbvars immediately; the LSP reads the in-editor buffer rather than disk.

UI

• Phobos activity-bar view container with two tree views:

  • Templates — every pipeline.hcl / release_lifecycle.hcl in the workspace, expanded to its outline. Click a symbol to jump.
  • Installed Plugins — the LSP's plugin inventory. Right-click Browse Online to open the plugin's registry page.

• Pipeline Graph webview — Phobos: Show Pipeline Graph renders stages, tasks, deployments, and nested pipelines as a layered DAG with dependencies = [...] edges. Click a node to jump to its declaration.

• Evaluated Context panel — Phobos: Show Evaluated Context opens a webview listing every namespace in the evaluator and its value at the cursor; updates as the cursor moves.

• Unified Phobos status-bar chip — one glanceable token combining language-server state, CLI version, plugin subprocess health, diagnostic counts across open templates, active-file deprecation count, and document kind (pipeline vs lifecycle).

  • $(check) Phobos 0.4.2 — everything healthy.
  • $(error) Phobos 0.4.2 · 3 / $(warning) Phobos 0.4.2 · 3 — actionable diagnostics (errors + warnings; infos / hints shift the icon but not the count).
  • $(alert) Phobos CLI missing, $(alert) Phobos stopped, $(alert) Phobos · 2 plugins failing — degraded subsystems.

  Hover shows the full breakdown. Click opens a QuickPick of actions (restart LS, install CLI, open Problems, migrate deprecations, show pipeline graph, show eval context, open project file, refresh plugins, show plugin output, view documentation).

• Phobos LS language-status item — Starting / Running / Stopped state in the VS Code language-status area ({} icon).

Plugin-aware features

When the template uses action "<plugin>_<action>" blocks and the corresponding plugin is installed via phobos plugin install, the language server introspects the plugin's schema and extends:

• Action-body diagnostics, completion, and hover.
• Hover on action labels — description, required inputs, declared outputs.
• Output-reference completion and hover for the plugin's typed outputs.
• "Plugin not installed" info-level diagnostic pointing at phobos sso login + phobos plugin install <org>/<name>.
• Install-plugin quick-fix. Accepting it runs the correct phobos plugin install command (with --version when the template pins one) in the Phobos Output channel, then reloads the server's inventory so the diagnostic clears without a restart.

Schemas are cached on disk next to the plugin binary, and the server watches ~/.phobos.d/plugins for changes so newly installed plugins light up without any explicit refresh.

Requirements

The extension delegates all language intelligence to the Phobos Language Server. Most users should install a platform-specific .vsix that bundles a matching language-server binary — in that case no separate install is necessary. Platform-neutral builds ship without the binary; in that case install phobos-language-server yourself:

go install gitlab.com/infor-cloud/martian-cloud/phobos/phobos-language-server/cmd@latest

Or download a pre-built binary from the releases page and place it on your PATH.

For action-body features you'll also need the relevant plugins installed locally:

phobos sso login              # if not already authenticated
phobos plugin install <org>/<plugin>

Getting Started

1. Install the extension from the VS Code Marketplace (VS Code, Cursor, Kiro) or the Open VSX Registry (VSCodium, Code OSS, Gitpod, Theia).
2. Install phobos-language-server (see above) — or skip this step if you installed a platform-specific .vsix that ships the binary.
3. Open a Phobos template. The language server starts automatically and the Phobos status chip appears in the status bar.
4. If the phobos CLI is missing, click the chip → Install or update CLI, or run Phobos: Install or Update CLI from the palette.

Commands

Configuration

Core

Inlay hints

Document links, semantic tokens, diagnostics

Workspace Trust

Phobos templates can reference plugins installed at ~/.phobos.d/plugins/, and the language server normally spawns those plugin binaries to fetch schemas used for completion, hover, and validation inside action bodies. In untrusted workspaces the extension launches the server with PHOBOS_LSP_DISABLE_PLUGINS=1, which disables the subprocess-spawn path entirely. Syntax highlighting and built-in diagnostics stay available; plugin-specific action-body features are suppressed until you grant trust. Trust transitions restart the language server automatically.

The following settings are declared as restrictedConfigurations — VS Code ignores workspace-scoped overrides for them until trust is granted, so a hostile workspace can't point the extension at an attacker-controlled binary, host, or profile:

• phobos.languageServer.path
• phobos.languageServer.tcp.port
• phobos.cliPath
• phobos.profile
• phobos.instance.host

Virtual workspaces (over SSH, Codespaces with a virtual file system, etc.) are unsupported — the language server requires a local filesystem and the extension declines to start in those contexts.

Development

Prerequisites

• Node.js >= 20
• npm >= 10

Build

npm install
npm run download:syntax   # fetch the hashicorp/syntax HCL grammar (pinned by SHA-256)
npm run compile           # dev bundle via esbuild

Watch mode

npm run watch

Type checking and linting

npm run check-types
npm run lint

Tests

npm test           # one-shot
npm run test:watch # iterate

Debug

Open the repository in VS Code and press F5. The .vscode/launch.json "Run Extension" configuration launches a second VS Code window with the extension loaded from the current working tree.

Package

npm run package

This produces a platform-neutral .vsix file that can be installed locally with code --install-extension phobos-*.vsix. To bundle a language-server binary alongside the extension (as the Marketplace builds do), set VSCODE_TARGET and run:

VSCODE_TARGET=linux-x64 npm run download:lsp && \
npm run compile:prod && \
npx vsce package --target linux-x64 --no-dependencies

Security

If you've discovered a security vulnerability in this extension, please let us know by creating a confidential issue in this project.

Defence-in-depth measures in place:

• Workspace-trust gating — plugin subprocesses and the settings that pick a binary / host / profile are disabled in untrusted workspaces.
• POSIX single-quoting — every argv element in extension-issued shell commands is wrapped in '…' (with '\'' escapes for embedded singles). A hostile plugin_requirements.version containing $(…), backticks, globs, redirects, or history expansions renders as a literal.
• Narrowed child-process environment — runInOutputChannel and the phobos --version probe pass an allowlist (PATH / HOME / proxy / locale / TLS-cert paths, plus AWS_* / PHOBOS_* / GO* / GIT_* / LC_* prefixes), not the full process.env.
• Bounded + cancellable commands — child_process.spawn({ shell: false }) with a 10-minute timeout and a user-facing Cancel notification (SIGTERM → 3 s grace → SIGKILL).
• Verified bundled binary — the bundled language-server binary is SHA-256-verified against the release manifest at package time. Release CI sets STRICT_VERIFY=1 so a missing manifest is a hard packaging failure.
• Pinned-download safety — build/download-lsp.mjs rejects non-https:// GITLAB_HOST values and only sends PRIVATE_TOKEN to hostnames explicitly listed in GITLAB_ALLOWED_HOSTS (default gitlab.com).

Statement of support

Please submit any bugs or feature requests as issues. MRs are welcome.

License

Phobos Extension for Visual Studio Code is distributed under Mozilla Public License v2.0.