OCX for VS Code

VS Code support for OCX — the OCI-registry-backed binary package manager.

Open a folder that contains an ocx.toml and the extension composes the project's toolchain with the ocx CLI and injects it into the editor, so language servers, extensions, terminals, and tasks find the tools your project declares.

What it does

• Extensions & language servers — the composed PATH is injected into the extension host, so language servers and other extensions find OCX-managed tools (node, go-task, …). Because running extensions cache their environment, OCX prompts to Restart Extensions when it changes (ocx.restart.automatic to skip the prompt).
• Terminals & tasks (opt-in) — enable ocx.env.applyToTerminals and newly opened terminals and tasks get the OCX PATH.
• Run ocx from the palette — resolve the lockfile, pull, upgrade, and clean without leaving the editor (see Commands).
• Live reload — edits to ocx.toml/ocx.lock reload the environment (ocx.watchForChanges).
• Tool groups (opt-in) — set ocx.groups to compose specific groups from ocx.toml (default, a named [group.*], or all) instead of only the default group.
• Status bar — shows the loaded state; click to reload.

Environment injection mutates PATH, so it runs only in a trusted workspace.

Commands

Run from the Command Palette (or bind to a key — see Tasks & keybindings).

The four ocx lifecycle commands run against the workspace ocx.toml, stream output to the OCX channel, and (except clean) reload the environment afterward.

Using OCX with tasks

The commands above run from the Command Palette, not from tasks.json. There is no custom OCX task type — built-in shell/process tasks already work, so you run the OCX-managed tools (or ocx itself) directly.

Run a toolchain binary

Enable ocx.env.applyToTerminals so tasks inherit the OCX PATH, then add the task. The setting takes effect in newly created task/terminal processes (reopen terminals or reload the window).

.vscode/settings.json:

{ "ocx.env.applyToTerminals": true }

.vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "type": "process",     // direct exec — no shell quoting
      "command": "go-task",  // any tool from ocx.toml, resolved on the injected PATH
      "args": ["build"]
    }
  ]
}

Run ocx and chain tasks

ocx itself runs as an ordinary task. dependsOn lets you chain a lockfile resolve into a build — something the palette commands cannot do:

{
  "version": "2.0.0",
  "tasks": [
    { "label": "ocx: lock",    "type": "process", "command": "ocx", "args": ["lock"] },
    { "label": "ocx: pull ci", "type": "process", "command": "ocx", "args": ["pull", "--group", "ci"] },
    {
      "label": "lock + build",
      "dependsOrder": "sequence",
      "dependsOn": ["ocx: lock", "build"],
      "group": { "kind": "build", "isDefault": true }  // Ctrl+Shift+B
    }
  ]
}

Bind a command to a key

Palette commands can't go in tasks.json, but they are bindable — keybindings.json:

[
  { "key": "ctrl+alt+l", "command": "ocx.lock" },
  { "key": "ctrl+alt+u", "command": "ocx.pull" }
]

Note: toolchain binaries (cmake, node, go-task, …) need ocx.env.applyToTerminals. ocx itself only needs to be installed (or ocx.path.executable set). Use "type": "shell" instead of "process" when a task needs pipes or &&.

Settings

ocx.toml validation

This extension contributes a JSON Schema for ocx.toml via the contributes.tomlValidation point consumed by Even Better TOML (tamasfe.even-better-toml). Install it for completion, hover, and diagnostics on ocx.toml. It is listed in the workspace's recommended extensions.

The schema is vendored from the ocx CLI's own generated project schema, so it covers [tools], [env], [group.<name>.tools], [group.<name>.env], and [package."<id>"].

Environment variables

ocx.toml declares environment variables in [env] (and per group in [group.<name>.env]). A bare string is a constant; a table names its modifier:

[env]
CI = "1"                                              # constant
JAVA_OPTS = { type = "constant", value = "-Xmx2g" }   # same, explicit
PATH = { type = "path", value = "node_modules/.bin" }
GODEBUG = { type = "list", separator = ",", value = "gctrace=1" }
JDK_JAVA_OPTIONS = { type = "list", value = "-Xmx2g" }

A list separator is agreed per variable across the whole composition: the first contributor that declares one sets it, later contributors that omit it inherit it, and two conflicting explicit separators are an error in ocx. When nobody declares one, it is a single space.

Composed values reach the extension host, and — with ocx.env.applyToTerminals on — terminals and tasks. Terminal mutators use the editor's prepend/append primitives, which cannot express the de-duplication, so a value already present in your shell profile may appear twice there.

Requirements

The ocx CLI must be installed and resolvable. Set ocx.path.executable if it is not on PATH. The list modifier needs ocx 0.5.6 or newer.

Contributing

Bug reports, feature requests, and PRs welcome. See CONTRIBUTING.md for the development setup, build/test workflow, commit conventions, and the roadmap.

License

Apache-2.0