How do you run this?

[praxder]

I apologize for the ignorant question. I don't know Node/Typescript, and so I was wondering how you're supposed to run this project? Might be helpful instructions to put in the README.

[TwitchBronBron]

No apologies necessary!

This project is currently mostly just a nodejs library that is leveraged by other projects. We use it heavily in the vscode-brightscript-language project to power the debugger experience for Roku projects.

This project IS designed to support being integrated into any IDE that supports the debug-adapter-protocol, but at this point I'm not aware of anyone trying to do that.

So if you're trying to use it standalone (like from a terminal), we don't currently have support for that. (I'm open to working with you to come up with designs/implementation for that).

If you're trying to contribute fixes, then you can start by following these instructions, and then pick "Extension + Debug Server" in vscode to launch a test vscode window. I've been meaning to create a better writeup on how to contribute, just haven't gotten around to it.

Hopefully this is helpful. Let me know what you're looking to do, and I can try and provide more specific information. :)

[praxder]

I use NeoVim as an IDE, and was trying to see if I could get roku-debug working with the DAP plugin. The docs for that plugin say that an adapter can be setup with one of the following:

- `executable`, to indicate that nvim-dap must launch the debug adapter. In
  this case nvim-dap will spawn the given process and communicate with it using
  stdio.

- `server`, to connect to a debug adapter via TCP.
  The adapter must be running, or started with a debug session via a
  `executable` configuration of the adapter. See the options further below.

- `pipe`, to connect to a debug adapter via a unix domain socket or named pipe.
  The adapter must be running, or started with a debug session via a
  `executable` configuration of the adapter. See the options further below.

But all three of these options require the debug server to be running. If I understand you correctly, the roku-debug Node project is directly included with the VSCode extension and not running independently, right?

[TwitchBronBron]

I think we can figure out a way to make this work for your project! We've done something similar in the brighterscript project with the LSP (see https://github.com/rokucommunity/brighterscript/pull/668).

So I'd envision it being used something like this:

npx roku-debug --dap

The --dap cli flag would instruct roku-debug to start up as a process/debug server, then neovim could connect to it with whatever DAP magic it wanted.

Now, how we implement the --dap concept is what we need to discuss a bit more, but here are some thoughts:

• we have a standalone nodejs script in vscode-brightscript-language here that shows how we spin up an instance of the debug server. So I'd imagine the roku-debug cli would implement similar logic
• If you can configure the neovim DAP plugin to use single-session mode, then we should be able to configure it to communicate over stdin/stdout. (see this section in the DAP docs).

Future concerns:

• how do we configure the neovim plugin to send the configuration options for roku-debug. We require things like rootDir, files, host, password, etc.
• Since this tool has only ever been implemented inside vscode, there might be some additional features we need to tweak to prevent crashes. I'm totally game for solving all of those, but just be aware there might be some growing pains as we work through them.

[TwitchBronBron]

I'm putting together a quick PR right now to implement the --dap cli flag. Stay tuned.

[TwitchBronBron]

Here's the PR. https://github.com/rokucommunity/roku-debug/pull/173

I'm working on writing a build script that will auto-generate a prerelease npm package so you can test it.

[TwitchBronBron]

Well, that took way longer than it should have, and I'm still not quite done. However, here's a link to an npm package for roku-debug that includes this cli flag.

https://github.com/rokucommunity/roku-debug/suites/18190359698/artifacts/1049879328

You can download that file, then run npm install path/to/file.tgz

Then run the process through neovim (somehow) by either using npx roku-debug --dap or node node_modules/roku-debug/dist/cli.js --dap depending on how you need to initialize it.

Give that a try, and I'll keep working on getting the build script working a little nicer. :D

Let me know if you have any questions!

[praxder]

Thanks for all the work on this! I really appreciate it. I'm probably missing something, but it appears as if that archive is a zip that only has four files in it:

CHANGELOG.md LICENSE package.json README.md

I also tried download the build artifact from the latest GH Actions run and see the same thing. Let me know if I'm missing something obvious.

---

In regards to some other comments:

If you can configure the neovim DAP plugin to use single-session mode, then we should be able to configure it to communicate over stdin/stdout. (see this section in the DAP docs).

I believe that should work just fine and be compatible, since those docs from Microsoft say:

single session mode: in this mode, the development tool starts a debug adapter as a standalone process and communicates with it through stdin and stdout.

And the executable DAP mode states:

to indicate that nvim-dap must launch the debug adapter. In this case nvim-dap will spawn the given process and communicate with it using stdio.

Which sounds like precisely what it's looking for. Obviously, this is all just from reading the docs though, and we'll fine out when the rubber meets the road of actually trying to run it. 😬🤞

---

Future concerns:

how do we configure the neovim plugin to send the configuration options for roku-debug. We require things like rootDir, files, host, password, etc.

I think that should be trivial. The plugins help page states each DAP entry supports the following options:

command: string         -- command to invoke
args:    string[]       -- arguments for the command
options?: {
  env?: {}              -- Set the environment variables for the command
  cwd?: string          -- Set the working directory for the command
  detached?: boolean    -- Spawn the debug adapter process in a detached state.
                           Defaults to true.
}
id?: string             -- Identifier of the adapter. This is used for the
                           `adapterId` property of the initialize request.
                           For most debug adapters setting this is not
                           necessary.

So we can set the rootDir, as well as passing whatever other data via direct command arguments or environment variables.

---

Once this issue is resolved (and the --dap flag is supported), we should try to get roku-debug added to the list of debug adapter implementations on Microsoft's website. Additionally, if I can get it working with the DAP plugin for NeoVim, I'll open a PR to get this added to the list there as well. :)

[TwitchBronBron]

Oops! I had disabled the actual package building because I was testing the artifact URL comment so it was saving time. I re-enabled that, so the latest build artifacts should be valid now.

https://github.com/rokucommunity/roku-debug/actions/runs/6871028938

[TwitchBronBron]

Okay, I finally got the npm package auto-builder script working, so as we iterate on this feature, I can generate temporary packages for you to test. Here's the latest one which has a few package.json fixes in it to allow everything to run. Please give that a try and let me know how it goes!

https://github.com/rokucommunity/roku-debug/pull/173#issuecomment-1813207190

[praxder]

What info do I need to pass the roku-debug adapter to tell it how to attach to the existing (and running) Roku application?

Here is some config I'm using for the nvim-dap plugin:

local dap = require('dap')

dap.adapters.brightscript = {
   type = 'executable',
   command = '/usr/local/opt/node@18/bin/node',
   args = { '/Users/Smith/Developer/settop/roku/node_modules/roku-debug/dist/cli.js', '--dap' },
   options = {
      detached = false
   },
}

dap.configurations.brs = {
   {
      type = 'brightscript',
      request = 'launch',
      name = "Launch file",
      -- "skipFiles"= [
      --   "<node_internals>/**"
      -- ],
      program = "${workspaceFolder}/node_modules/roku-debug/dist/index.js",
      preLaunchTask = "tsc: build - tsconfig.json",
      internalConsoleOptions = "openOnSessionStart",
      outFiles = {
         "${workspaceFolder}/node_modules/roku-debug/dist/**/*.js"
      },
   },
}

This doesn't work. The dap.adapters.brightscript table (which simply spins up the debug adapter), seems to be working. The nvim plugin I'm using allows monitoring of the Requests and Events, and I see there's some traffic (initialized, then launched, then immediately terminated).

The second map (dap.configurations.brs) is meant to tell roku-debug how to connect to and run the actual debug session on the device. The docs for the plugin say that only the first three fields are required (type, request, and name) and the others are arbitrary and debug-adapter specific. I tried to copy some of the properties from the launch.json file from roku-debug project, but I'm apparently still missing something. Any ideas? I'm assuming I'll need to pass it the IP address and password of the device I'm using.

[TwitchBronBron]

What info do I need to pass the roku-debug adapter to tell it how to attach to the existing (and running) Roku application?

We don't currently support the "attach" method of debugging (and other than scraping telnet logs, Roku doesn't support this concept either). We need to control the entire sideload experience from start to finish.

The typical flow is:

• in your editor, click "start debugging"
• your editor initializes a new DAP connection and sends along your launch configuration values (rootDir, files array, host, password, etc...)
• roku-debug builds/zips your project, connects to telnet (or debug protocol), sideloads the device. Now you have a working debug session.

I'd be open to setting up a video call if you'd like to try to work through some of this stuff together?

[praxder]

That's helpful. I'll DM you through LinkedIn to set that up.

[TwitchBronBron]

You can also find me on the RokuCommunity slack at this link. But LinkedIn works too. :)

[praxder]

For anyone having this issue in the future: @TwitchBronBron was kind enough to hop on a call for multiple hours and help get this figured out. It's now working with NeoVim and the nvim-dap plugin. See here for specific instructions on how to configure.