@lvce-editor/api 9.30.0 → 9.31.0

package/README.md

@@ -50,3 +50,20 @@ await storeSecret('access-token', token)
 const savedToken = await getSecret('access-token')
 await deleteSecret('access-token')
 ```
+
+## Workspace ports
+
+Declare `"onPorts:codespaces"` in the extension's `activation` array and register a provider after activating the API:
+
+```ts
+import { registerPortProvider } from '@lvce-editor/api'
+
+const registration = registerPortProvider({
+  scheme: 'codespaces',
+  async providePorts(workspaceUri) {
+    return [{ port: 3000, forwardedAddress: 'https://my-codespace-3000.app.github.dev/', origin: 'devcontainer.json' }]
+  },
+})
+```
+
+Ports queries matching extensions with the current workspace URI. Each extension may register one provider per scheme. Return an empty array when no ports are available, and dispose the registration when deactivating. The provider supplies addresses; the API does not create tunnels or change their visibility. Results from disposed registrations are discarded.

package/dist/index.d.ts

@@ -62,3 +62,6 @@ export type { ShowQuickPickOptions } from './parts/ShowQuickPickOptions/ShowQuic
 export type { StatusBarItem, StatusBarItemProvider, StatusBarItemProviderHandle, StatusBarItemProviderRegistrySnapshot, } from './parts/StatusBar/StatusBar.ts';
 export { setRemoteDescription, startWebRtcAudioStream, stopWebRtcAudioStream, readMicLevels } from './parts/WebRtc/WebRtc.ts';
 export type { MicLevelsResult, ReadMicLevelOptions, SetRemoteDescriptionOptions, StartWebRpcAudioStreamOptions, WebRtcAudioConstraints, } from './parts/WebRtc/WebRtc.ts';
+export { registerPortProvider } from './parts/PortProviderRegistry/PortProviderRegistry.ts';
+export type { PortProvider } from './parts/PortProvider/PortProvider.ts';
+export type { ForwardedPort } from './parts/ForwardedPort/ForwardedPort.ts';

package/dist/index.js

@@ -33,3 +33,4 @@ export { getStatusBarItemProviderRegistrySnapshot, registerStatusBarItemProvider
 export { handleExtensionManagementMessagePort } from "./parts/HandleExtensionManagementMessagePort/HandleExtensionManagementMessagePort.js";
 export { createNodeRpc, createRpc } from "./parts/Rpc/Rpc.js";
 export { setRemoteDescription, startWebRtcAudioStream, stopWebRtcAudioStream, readMicLevels } from "./parts/WebRtc/WebRtc.js";
+export { registerPortProvider } from "./parts/PortProviderRegistry/PortProviderRegistry.js";

package/dist/parts/ForwardedPort/ForwardedPort.d.ts

@@ -0,0 +1,7 @@
+export interface ForwardedPort {
+    readonly active?: boolean;
+    readonly forwardedAddress: string;
+    readonly origin?: string;
+    readonly port: number;
+    readonly runningProcess?: string;
+}

package/dist/parts/ForwardedPort/ForwardedPort.js

@@ -0,0 +1 @@
+export {};

package/dist/parts/PortProvider/PortProvider.d.ts

@@ -0,0 +1,5 @@
+import type { ForwardedPort } from '../ForwardedPort/ForwardedPort.ts';
+export interface PortProvider {
+    readonly providePorts: (workspaceUri: string) => readonly ForwardedPort[] | Promise<readonly ForwardedPort[]>;
+    readonly scheme: string;
+}

package/dist/parts/PortProvider/PortProvider.js

@@ -0,0 +1 @@
+export {};

package/dist/parts/PortProviderRegistry/PortProviderRegistry.d.ts

@@ -0,0 +1,5 @@
+import type { Disposable } from '../Disposable/Disposable.ts';
+import type { ForwardedPort } from '../ForwardedPort/ForwardedPort.ts';
+import type { PortProvider } from '../PortProvider/PortProvider.ts';
+export declare const providePorts: (workspaceUri: string) => Promise<readonly ForwardedPort[]>;
+export declare const registerPortProvider: (provider: PortProvider) => Disposable;

package/dist/parts/PortProviderRegistry/PortProviderRegistry.js

@@ -0,0 +1,37 @@
+import * as ExtensionApiCommandRegistry from "../ExtensionApiCommandRegistry/ExtensionApiCommandRegistry.js";
+import { ExtensionApiError } from "../ExtensionApiError/ExtensionApiError.js";
+const providers = new Map();
+export const providePorts = async (workspaceUri) => {
+    const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(workspaceUri)?.[1].toLowerCase();
+    const provider = scheme ? providers.get(scheme) : undefined;
+    if (!provider) {
+        return [];
+    }
+    const ports = await provider.providePorts(workspaceUri);
+    if (!Array.isArray(ports) ||
+        ports.some((port) => !port || !Number.isSafeInteger(port.port) || port.port < 1 || port.port > 65_535 || typeof port.forwardedAddress !== 'string')) {
+        throw new ExtensionApiError('port provider returned invalid ports');
+    }
+    return providers.get(scheme) === provider ? ports : [];
+};
+export const registerPortProvider = (provider) => {
+    if (!provider ||
+        typeof provider.scheme !== 'string' ||
+        !/^[a-z][a-z0-9+.-]*$/.test(provider.scheme) ||
+        typeof provider.providePorts !== 'function') {
+        throw new ExtensionApiError('port provider requires a URI scheme and providePorts function');
+    }
+    const { scheme } = provider;
+    if (providers.has(scheme)) {
+        throw new ExtensionApiError(`port provider for ${scheme} is already registered`);
+    }
+    providers.set(scheme, provider);
+    ExtensionApiCommandRegistry.registerCommandMap({ 'ExtensionApi.providePorts': providePorts });
+    return {
+        dispose() {
+            if (providers.get(scheme) === provider) {
+                providers.delete(scheme);
+            }
+        },
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lvce-editor/api",
-  "version": "9.30.0",
+  "version": "9.31.0",
   "description": "Tree-shakeable extension API for Lvce Editor extensions.",
   "keywords": [
     "lvce-editor",