VSCode TRU Extension

This extension adds TRU language highlighting and a theme that matches the TRU Admin editor colors.

What it includes

• TRU language definition (.tru files)
• Syntax highlighting for TRU v0.3 (keywords, explicit return types, templated containers like array<T> / map<T> / json<T>, null-safe ?, strings, numbers, comments, functions, builtins)
• Bundled Rust LSP (tru_server --lsp) for diagnostics, completion, hover, go-to-definition, references, symbols, formatting, code actions, rename, and optional semantic tokens
• Bundled tru_server binary support (extension runs standalone without requiring an external language server)
• Theme: TRU Admin Light
• Automatic TRU file icon for .tru files via language icon contribution
• Automatic Material Icon Theme integration for .tru via material-icon-theme.files.associations when that icon theme is active
• Optional TRU-specific token colors (disabled by default so .tru files use your active theme's standard colors)
• Semantic token highlighting is disabled by default so .tru files keep normal VS Code/theme text colors unless you explicitly enable it
• Automatic workspace-wide diagnostics are disabled by default so unopened .tru files do not get warning-colored Explorer or tab labels
• TRU diagnostics default to errors instead of all, so warning-only file labels stay on normal VS Code colors unless you opt in
• JSON schema validation for tru.json (requires mode: "debug"|"release")
• JSON schema validation for *.tru.backup archives
• Command: TRU: Run TRU Function (tru.runFunction)
• Command: TRU: Run Upgrade Check (tru.upgradeCheck)
• Command: TRU: Refresh Language Analysis (tru.refreshLanguageAnalysis)
• Command: TRU: Apply Token Colors (tru.applyTokenColors)
• Command: TRU: Reset Token Colors (tru.resetTokenColors)
• Diagnostics from upgrade checks are shown in Problems panel
• Diagnostics from server language analysis are shown in Problems panel
• Quick-fix actions in Problems/quick fix menu can copy the TRU issue code for any diagnostic with a code
• Output channel: TRU (request/response logs)

Legacy surface types are intentionally not documented in the extension anymore:

• object was removed from TRU 0.3 surface syntax
• unknown was removed from TRU 0.3 surface syntax
• use json, map<T>, array<T>, or a concrete class name instead

Use

1. Open vscode-tru/ in VS Code.
2. Run npm install -g vsce if you want to package.
3. Press F5 to launch an Extension Development Host.
4. Select the theme: Preferences -> Color Theme -> TRU Admin Light.
5. If you use Material icons, set Preferences -> File Icon Theme -> Material Icon Theme.
6. By default, the extension auto-starts its bundled tru_server in stdio LSP mode for editor language features. TRU run/upgrade commands can also use the bundled HTTP mode when needed.
7. Open command palette and run:
   • TRU: Run TRU Function
   • TRU: Run Upgrade Check
   • TRU: Refresh Language Analysis
8. The extension auto-reconciles Material .tru icon association on startup and when extensions/settings change. If custom SVG wiring is unavailable in the current host, it falls back to a managed built-in Material icon mapping for .tru.

Debug setup

The repo now includes launch/tasks configs in both places:

• Root workspace: .vscode/launch.json and .vscode/tasks.json
• Extension folder: vscode-tru/.vscode/launch.json and vscode-tru/.vscode/tasks.json

Available debug launch configs:

• TRU Extension: Run
• TRU Extension: Run + Open Sample (root workspace)
• TRU Extension: Run + Open Parent Workspace (extension-only workspace)

Run one of these from VS Code Run and Debug and an Extension Development Host will start with this extension loaded from source.

Quick verification

After the server is running, use:

cd vscode-tru
npm run verify:tru-diagnostics

Optional arguments:

npm run verify:tru-diagnostics -- --base-url http://127.0.0.1:3000 --admin-key "<admin key>"

Use strict mode to fail the command if any returned diagnostic is missing a canonical code:

npm run verify:tru-diagnostics -- --strict

The script prints sample diagnostics from:

• GET /admin/diagnostics
• GET /admin/upgrade/check

and verifies that canonical code fields are present.

Publishing (automation)

Use the Bash automation script from vscode-tru/:

cd vscode-tru
./publish.sh --skip-publish --skip-npm-install

Examples:

• Build only (dry-run publish target):

./publish.sh --skip-publish --what-if

• Build and publish (with automatic PAT from /home/dxfoso/tru/.env):

./publish.sh --bump patch

Or via npm scripts:

npm run publish:build     # build only, no publish
npm run publish:patch     # bump patch and publish
npm run publish:minor     # bump minor and publish
npm run publish:sh       # interactive publish flow (no bump)

PAT support order:

• --pat argument
• VSCE_PAT environment variable
• /home/dxfoso/tru/.env values: VSCE_PAT, VSCODE_PAT, VSCODE_MARKETPLACE_PAT, MARKETPLACE_PAT, GITHUB_PAT, GH_PAT, GH_TOKEN, GITHUB_TOKEN
• interactive prompt fallback

Publish options:

• --skip-npm-install
• --skip-publish
• --what-if
• --bump <major|minor|patch|premajor|preminor|prepatch|prerelease>

Extension settings

• tru.serverBaseUrl (default http://127.0.0.1:3000)
• tru.useBundledServer (default true)
• tru.bundledServerHost (default 127.0.0.1)
• tru.bundledServerPort (default 0, auto-select)
• tru.adminKey (optional x-tru-admin header for admin endpoints)
• tru.runDefaultFunction (prefill function name for run command)
• tru.autoApplyTokenColors (default false)
• tru.autoApplySemanticTokenColors (default false)
• tru.integrateMaterialIconAssociation (default true)
• tru.enableServerLanguageFeatures (default true)

TRU icon options

Current icon in use:

• vscode-tru/icons/tru.svg for:
  • extension icon (package.json > icon)
  • activity bar icon (package.json > viewsContainers.activitybar.icon)
  • file explorer .tru association (extension.js > DEFAULT_TRU_FILE_ICON_PATH)

Files

• package.json
• language-configuration.json
• syntaxes/tru.tmLanguage.json
• schemas/tru.schema.json
• schemas/tru-backup.schema.json
• themes/tru-admin-light-color-theme.json
• extension.js
• bin/tru_server (generated during build/package)