Kopytko BrightScript

BrightScript & Kopytko language support for Visual Studio Code — syntax highlighting, IntelliSense, diagnostics, formatting, linting, and a built-in Roku debugger.

Features

• Syntax highlighting — full TextMate grammar for .brs files including @import/@mock annotations, as <type>, and m variable scopes
• IntelliSense — completions for 62+ ro* components, 80 interfaces, ~700 methods, built-in functions, keywords, and user-defined functions
• CreateObject type inference — member completions appear automatically after typing . on a variable created via CreateObject
• m.top member completion — auto-completes fields from your XML interface, parent components, and the SceneGraph node catalog
• Kopytko module support — module export completions with auto-insert @import, @import/@mock path completions and snippets
• Hover documentation — docs for components, methods, built-in functions, user-defined functions, and Kopytko module exports
• Go-to-definition — jump to @import/@mock files and user-defined function sources
• Signature help — parameter hints as you type function calls
• Find All References — workspace-wide symbol references
• Rename symbol — safe rename across the workspace
• Outline & Workspace Symbols — navigate functions, subs, AA methods, and test cases via the Outline view or Ctrl+T
• 31 diagnostic rules — undefined functions/variables, wrong argument count, unused imports/parameters, CreateObject validation, @import resolution, test framework checks, and more
• Inline suppression — ' kopytko-disable-next-line <rule> and ' kopytko-disable-line <rule> comments to suppress individual diagnostics per-line (glob patterns and rem style supported; use disable-next-line on the preceding line for @import/@mock annotations)
• Code actions — quick fixes for import diagnostics and unused parameters
• Document formatting — multi-pass engine with 60+ configurable rules (indentation, spacing, casing, blank lines, keyword style, and more)
• Configurable identifier casing — 10 casing dimensions (builtins, keywords, types, methods, user functions) with per-identifier overrides
• Kopytko Unit Testing Framework — test file detection, @mock support, expect() matcher completions, test case symbols in Outline
• Roku device discovery — SSDP-based network scanning with auto-rescan, manual entry, password management, and per-device environment selection
• BrightScript debugger — deploy, set breakpoints (conditional, hit-count, exception), inspect variables, step through code, REPL, multi-thread support

See docs/features.md for the full feature list with status and links to detailed documentation.

Standalone Tools

The formatting engine and linter are also available as standalone npm packages for use in CI pipelines and build tools:

Extension Settings

All settings use the kopytko. prefix in .vscode/settings.json or VS Code's user settings.

For formatting settings (kopytko.format.*) see the kopytko-formatter README. For linting settings (kopytko.lint.*) see the kopytko-linter README.

Language Server

Import Resolution

Read-only Paths

Casing

Casing settings control identifier casing in completions and formatting. Values: preserve, upper-case, lower-case, capitalize, pascal-case, camel-case.

Device Discovery

Device Manager

See docs/device-manager.md for the full Device Manager feature set.

Diagnostics (Runtime Telemetry)

See docs/diagnostics.md for the full settings reference and architecture.

Perfetto (App Tracing)

Roku Device Discovery

The Roku Devices panel in the Kopytko sidebar automatically discovers Roku devices on your local network using SSDP. Devices are listed with their model, serial number, and firmware version.

• Auto-scan — rescans on network changes and wake from sleep
• Manual entry — add a device by IP if not discovered automatically
• Secure passwords — stored in your OS keychain via VS Code's SecretStorage
• Active device — right-click → Set as Active Device to set the default deploy target
• Environment selection — choose a .kopytkorc environment per device
• Context menu — copy IP, open web portal, set password, view registry, upload package

Debugging on a Roku Device

Prerequisites

Enable developer mode on the Roku: on the remote press Home × 3, Up, Right, Left, Right, Left, Right. Note the device IP and set a developer password.

launch.json Configuration

Create .vscode/launch.json (or use Run → Add Configuration):

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "kopytko",
      "request": "launch",
      "name": "Run on Roku",
      "rootDir": "${workspaceFolder}"
    }
  ]
}

Tip: If you have an active device selected in the Roku Devices panel with a stored password and environment, host, password, and env are all filled in automatically. A minimal config only needs type, request, name, and rootDir.

What Happens When You Press F5

1. Injects remotedebug=1 into the manifest (enables socket-based debug protocol)
2. Runs kopytko start to build and deploy the app to the Roku
3. Restores the original manifest
4. Connects to the debug protocol on TCP port 8081

Debugging Capabilities

See docs/roku-debug.md for full architecture and troubleshooting.

Further Reading

• Feature overview
• Roku device management and debugging
• BrightScript component catalog
• Kopytko @import annotations
• Language server architecture
• Document formatting rules

Contributing

See CONTRIBUTING.md for development setup, building, testing, and project layout.

Releasing

Both packages are released via GitHub Actions workflows (Actions tab → Run workflow → pick patch/minor/major).

Release kopytko-formatter (npm)

1. Go to Actions → Release kopytko-formatter → Run workflow
2. Select patch, minor, or major
3. The workflow runs tests, bumps the version, updates the changelog, tags kopytko-formatter-v{x.y.z}, publishes to npm (OIDC provenance), and creates a GitHub Release

Release kopytko-linter (npm)

1. Go to Actions → Release kopytko-linter → Run workflow
2. Select patch, minor, or major
3. The workflow runs tests, bumps the version, updates the changelog, tags kopytko-linter-v{x.y.z}, publishes to npm (OIDC provenance), and creates a GitHub Release

Release vscode-kopytko (VS Code Marketplace)

1. Go to Actions → Release vscode-kopytko → Run workflow
2. Select patch, minor, or major
3. The workflow compiles, tests, bumps the version, updates the changelog, tags v{x.y.z}, publishes to the Marketplace, and creates a GitHub Release with the .vsix attached

Release order

When the formatter changes affect the extension:

1. Release kopytko-formatter first
2. Update the extension's kopytko-formatter dependency version
3. Release vscode-kopytko

Required secrets

npm uses OIDC provenance — no token needed. See docs/publishing.md for full setup.