@lvce-editor/api 9.30.0 → 9.32.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/dist/parts/QuickPick/QuickPick.d.ts

@@ -1,5 +1,6 @@
 import type { ShowQuickInputOptions } from '../ShowQuickInputOptions/ShowQuickInputOptions.ts';
 import type { ShowQuickPickOptions } from '../ShowQuickPickOptions/ShowQuickPickOptions.ts';
 export declare const showFileQuickPick: () => Promise<void>;
+/** Shows a freeform text field without a results list. Returns undefined on cancellation. */
 export declare const showQuickInput: (options?: ShowQuickInputOptions) => Promise<string | undefined>;
 export declare const showQuickPick: (options: ShowQuickPickOptions) => Promise<unknown>;

package/dist/parts/QuickPick/QuickPick.js

@@ -3,6 +3,7 @@ import { executeCommand } from "../ExecuteCommand/ExecuteCommand.js";
 export const showFileQuickPick = async () => {
     await executeCommand('QuickPick.showFile');
 };
+/** Shows a freeform text field without a results list. Returns undefined on cancellation. */
 export const showQuickInput = async (options = {}) => {
     return ExtensionManagementWorker.invoke('ExtensionHostQuickPick.showQuickInput', options);
 };

package/dist/parts/ShowQuickPickOptions/ShowQuickPickOptions.d.ts

@@ -3,4 +3,6 @@ export interface ShowQuickPickOptions {
     readonly acceptInput?: boolean;
     readonly items: readonly QuickPickItem[];
     readonly placeholder?: string;
+    /** Text accepts freeform input without a results list; select filters items (the default). */
+    readonly type?: 'text' | 'select';
 }

package/package.json

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