Touba Language Toolkit for VS Code

Touba Language Toolkit is the official VS Code extension for .tb files. It connects daily authoring to the compiler, CLI and Touba artifacts.

Availability

The update described here is being qualified on all four platforms. The installation instructions below apply once it is published. To explore a project today, use touba explore with the Touba CLI.

Explore the project

Touba: Explore Project opens an interactive graph with Architecture, Flow and Governance views. Search and filter resources, read signatures and responsibilities, and open their source. Touba: View in Graph selects the declaration at the cursor. Saved sources refresh the graph; exploration requires a trusted workspace.

Use touba explore for the same views in your browser. Explorer guide · Guided tutorial.

Install the extension

In VS Code 1.143.1 or later, search for Touba Language Toolkit by Touba in Extensions, then select Install. Use @id:touba.touba-tools to find the extension directly. This method does not require a terminal command.

If the code command is available, you can also use the terminal:

Terminal

code --install-extension touba.touba-tools

VS Code selects the matching package: macOS Apple Silicon, macOS Intel, Linux x64 or Windows x64. For offline installation, download the matching VSIX from the Hub, then choose Extensions → … → Install from VSIX….

The extension bundles the compiler and runtime for editing and self-contained files. Install the Touba CLI for terminal commands and project workflows.

macOS: code command not found

If the terminal displays zsh: command not found: code, the VS Code command is missing from PATH. code belongs to VS Code; touba is the language CLI. Configure VS Code as follows:

1. Open Visual Studio Code from Applications.
2. Open the Command Palette with ⌘⇧P (Cmd+Shift+P).
3. Search for shell command, then choose Shell Command: Install 'code' command in PATH.
4. Open a new terminal, then verify the command and install the extension:

Terminal

code --version
code --install-extension touba.touba-tools

For a one-time installation without changing PATH, if VS Code is installed in /Applications, use its full path:

Terminal

"/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code" --install-extension touba.touba-tools

You can also use the Extensions view described above. See the official VS Code instructions for macOS.

Editor features

The extension provides:

• .tb syntax highlighting and file association;
• compiler-backed diagnostics;
• symbols, completion, hover and go-to-definition;
• explicit execution of the current file;
• inspection of AIR, manifest and report artifacts;
• graphical exploration of resources, flow and declared governance;
• text rendering for traces and architecture views;
• navigation from a trace event to source.

Capability diagnostics include descriptions required for catalogs presented to the decision provider.

Commands

Command	Function
Touba: Explore Project	open the project graph explorer
Touba: View in Graph	locate the element at the cursor in the graph
Touba: Run Current File	compile and run the active .tb file
Touba: Check CLI	verify the resolved Touba command
Touba: Open Terminal	open a terminal for the project
Touba: Inspect Artifact	inspect an AIR, manifest, trace or report
Touba: Inspect Artifacts	inspect an explicit artifact set
Touba: Render Architecture	render a readable AIR projection
Touba: Render Trace	display a trace timeline
Touba: Open Trace Event Source	open an event source location
Touba: Validate Memory Action Plan	validate a memory action plan

Recognize packages

Touba-managed packages/ directories display a P badge, a dedicated color and the Touba packages tooltip, including inside nested projects. For a package-box icon as well, choose Preferences: File Icon Theme → Touba File Icons in the Command Palette. This theme is optional; your current theme is left unchanged. Its box icons follow the folder name, while the P badge checks the parent Touba manifest.

If the badge is hidden, enable explorer.decorations.badges and explorer.decorations.colors. A Git decoration can take precedence.

CLI resolution

For Check CLI and terminal commands, the extension resolves the CLI in this order:

1. TOUBA_CLI_PATH when defined;
2. touba in the VS Code process PATH;
3. $HOME/.touba/bin/touba.

Run Touba: Check CLI to display the selected command and verify protocol versions. Editing features can use the embedded runtime; terminal commands use the installed CLI.

Run a file

Touba: Run Current File compiles the active document to temporary AIR and runs it with the bundled runtime, unless TOUBA_CLI_PATH selects another installation. ask interactions open a VS Code input control and resume the run with explicit host input.

The SQLite journal remains in .touba/traces.sqlite after execution. Output shows its path and the reference to open with Touba: Render Trace. Each page replaces the previous view, keeping long traces readable. An interaction following a dispatch is not replayed automatically.

A program that depends on external tools, secrets or a manifest uses the normal project path. The extension does not discover a .env, handler or secret by convention.

Read artifacts

Rendering commands open text views derived from artifacts selected by the user. A trace provides the event sequence; an architecture projection provides declarations, imports, budgets and relations. This view remains aligned with AIR and does not create parallel status.

For a complete path, see the VS Code and JavaScript Project.

Read a stored trace

Keep the trace in a journal and save its reference:

Terminal

touba run program.air.json --trace-store .touba/traces.sqlite --output json-reference > run.json

1. Open run.json and run Touba: Render Trace.
2. Select the matching traces.sqlite journal.
3. The Touba Trace output shows one page. Next page replaces it with the next one.

Each page contains up to 100 events and 1 MiB of event content. Reading uses the bundled Core in a trusted workspace and leaves the journal unchanged. A reference identifies one execution segment; a resumed run has its own segment.

Touba: Open Trace Event Source also accepts run.json or a standalone reference. Select the executed AIR, event ID and journal. The extension verifies the segment, reads the requested event and opens its source. Full JSON trace documents remain readable up to 16 MiB.

First run

Save this program as a .tb file, then select Touba: Run Current File.

source.tb

module examples.test

strategy RunTest
    do
        show
            with message as "test"

Identify an installation and troubleshoot

Touba: Check CLI displays the loaded build, platform and selected CLI. After updating a VSIX, save your files and use Developer: Reload Window. Check the CLI separately with touba version.

To select a CLI, set TOUBA_CLI_PATH in the environment that launches VS Code, then restart the application. The terminal.integrated.env.* settings apply to the terminal, not the extension host.

CompilerUnavailable indicates that the selected compiler cannot start or returns an unusable response. Check its selection and TOUBA_COMPILE_BIN, then reopen the file. Syntax and type diagnostics update as you edit.

Trace navigation resolves relative source paths from the open folder. Without a workspace folder, select the source root when prompted. Keep the source layout alongside the matching artifacts.