Provide typing for global accessor of the Positron API for multi-IDE extensions

[jmcphers]

Extensions that are built exclusively for Positron can do this to bring in the Positron API:

import * as positron from 'positron'

This works in Positron, but will fail at runtime in VS Code since the thing that makes it work is the require interceptor (https://github.com/rstudio/positron/blob/main/src/vs/workbench/api/common/extHostRequireInterceptor.ts).

We need a way to load the Positron API safely for extensions that could run in either Positron or VS Code. Proposal:

• Define the Positron API surface as an interface
• Have the Positron API module implement the interface
• Create a global method (in the nodejs global namespace equivalent of window.) that returns this interface in Positron

In this way, Positron-specific extensions can keep using import * as positron, and multi-IDE extensions can call something safer like try { api = getPositronApi() } ... to access the API.

[jjallaire]

Example of how this is done for the VSCode API exposed to web views: https://www.npmjs.com/package/@types/vscode-webview?activeTab=code

[jmcphers]

This is now Kind Of Implemented. You can call acquirePositronApi() to get an instance of the API:

> var api = acquirePositronApi()
<undefined>
> api
[object Object]
> Object.keys(api)
version,runtime,window,RuntimeClientType,RuntimeClientState,LanguageRuntimeMessageType,LanguageRuntimeStreamName,RuntimeCodeExecutionMode,RuntimeErrorBehavior,LanguageRuntimeStartupBehavior,RuntimeOnlineState,RuntimeState,RuntimeCodeFragmentStatus
> api.version
2023.06.0

The main problem left to be solved is how to get typings for the API to load correctly in extensions (i.e. we need to somehow tell Typescript that this function returns the positron module)

[jjallaire]

It is the case that I can't really use this yet then (at least w/ Typescript) b/c there isn't a ready way to "cast" an object to a module? I could also just get it working w/ as any for the time being?

[jmcphers]

Yeah, I was trying to figure out if there was a way to tell Typescript that the return value is a module but didn't figure it out (there may be a way that I missed). You certainly can use it with as any if you don't need typing.

[jjallaire]

I would certainly prefer typing! If you think you'll figure out a solution soon I'll wait for that.

In the case that we can't figure out a solution, we may need to do something more like VS Code where positron isn't a module but rather an interface

[jjallaire]

I guess for now I can just cast the return value to an interface that I hand create? (Which I'm doing anyway in this case)

[jmcphers]

Yeah, that'll work just fine for typing. It might be simpler to cast specific namespaces to interfaces instead of trying to cast the entire value (e.g. api.runtime => RuntimeHooks, api.window => WindowHooks).

[jjallaire]

Here's how I declared the types: https://github.com/quarto-dev/quarto/blob/main/apps/vscode/src/%40types/hooks.d.ts

Then also declared:

declare global {
	function acquirePositronApi() : positron.PositronApi;
}