@lvce-editor/api 9.37.2 → 9.39.0

package/README.md

@@ -67,3 +67,34 @@ const registration = registerPortProvider({
 ```
 
 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.
+
+## Authentication providers
+
+Extensions can contribute a functional authentication provider with session callbacks. The provider's stable `id` and display `label` identify it; requested scopes are passed to the callbacks, and session results include an account, access token, and granted scopes.
+
+```ts
+import { activate, registerAuthenticationProvider } from '@lvce-editor/api'
+
+await activate()
+const registration = registerAuthenticationProvider({
+  id: 'example',
+  label: 'Example Account',
+  async getSessions(scopes) {
+    return []
+  },
+  async createSession(scopes) {
+    return {
+      id: 'account-session',
+      accessToken: 'token',
+      account: { id: 'account', label: 'Example Account' },
+      scopes,
+    }
+  },
+  async removeSession(sessionId) {},
+})
+
+// Dispose the contribution when the extension deactivates.
+registration.dispose()
+```
+
+The editor can call `executeAuthenticationProviderGetSessions`, `executeAuthenticationProviderCreateSession`, and `executeAuthenticationProviderRemoveSession` by provider id. Session callbacks are responsible for account selection, consent, token storage, and revocation.

package/dist/index.d.ts

@@ -2,6 +2,9 @@ export { activate } from './parts/Activation/Activation.ts';
 export { getColorThemeNames } from './parts/ColorTheme/ColorTheme.ts';
 export { markdownToVirtualDom } from './parts/Markdown/Markdown.ts';
 export { getAccessToken, type GetAccessTokenOptions } from './parts/Authentication/Authentication.ts';
+export { executeAuthenticationProviderCreateSession, executeAuthenticationProviderGetSessions, executeAuthenticationProviderRemoveSession, getAuthenticationProviderRegistrySnapshot, registerAuthenticationProvider, resetAuthenticationProviderRegistry, } from './parts/AuthenticationProviderRegistry/AuthenticationProviderRegistry.ts';
+export type { AuthenticationAccount, AuthenticationProvider, AuthenticationSession } from './parts/AuthenticationProvider/AuthenticationProvider.ts';
+export type { AuthenticationProviderRegistrySnapshot } from './parts/AuthenticationProviderRegistrySnapshot/AuthenticationProviderRegistrySnapshot.ts';
 export { createElectronWebContentsView } from './parts/ElectronWebContentsView/ElectronWebContentsView.ts';
 export { executeCommand } from './parts/ExecuteCommand/ExecuteCommand.ts';
 export { showFileQuickPick, showQuickInput, showQuickPick } from './parts/QuickPick/QuickPick.ts';
@@ -19,6 +22,7 @@ export { exists, getFileHash, getFileHashes, mkdir, readAsObjectUrl, readDirWith
 export { registerFileChangeHandler, type FileChangeHandler, type FileChanges } from './parts/FileChangeHandler/FileChangeHandler.ts';
 export { executeFileSystemProviderGetOpenExternalPath, executeFileSystemProviderIsReadonly, executeFileSystemProviderMkdir, executeFileSystemProviderReadDirWithFileTypes, executeFileSystemProviderReadFile, executeFileSystemProviderRemove, executeFileSystemProviderRename, executeFileSystemProviderWriteFile, getFileSystemProviderRegistrySnapshot, registerFileSystemProvider, resetFileSystemProviderRegistry, } from './parts/FileSystemProviderRegistry/FileSystemProviderRegistry.ts';
 export { closeUri, confirm, getRecentlyOpenedWorkspaceUris, getWorkspaceFolder, getWorkspaceUri, handleWorkspaceRefresh, openUri, setWorkspaceUri, showErrorMessage, showNotification, type ConfirmOptions, type NotificationType, type ShowErrorMessageOptions, } from './parts/Host/Host.ts';
+export { preparePrettyError } from './parts/PrettyError/PrettyError.ts';
 export { executeHoverProvider, getHoverProviderRegistrySnapshot, registerHoverProvider, resetHoverProviderRegistry } from './parts/Hover/Hover.ts';
 export { executeSignatureHelpProvider, getSignatureHelpProviderRegistrySnapshot, registerSignatureHelpProvider, resetSignatureHelpProviderRegistry, } from './parts/SignatureHelp/SignatureHelp.ts';
 export { getPlatform, getUserDataDir, type Platform } from './parts/Platform/Platform.ts';

package/dist/index.js

@@ -2,6 +2,7 @@ export { activate } from "./parts/Activation/Activation.js";
 export { getColorThemeNames } from "./parts/ColorTheme/ColorTheme.js";
 export { markdownToVirtualDom } from "./parts/Markdown/Markdown.js";
 export { getAccessToken } from "./parts/Authentication/Authentication.js";
+export { executeAuthenticationProviderCreateSession, executeAuthenticationProviderGetSessions, executeAuthenticationProviderRemoveSession, getAuthenticationProviderRegistrySnapshot, registerAuthenticationProvider, resetAuthenticationProviderRegistry, } from "./parts/AuthenticationProviderRegistry/AuthenticationProviderRegistry.js";
 export { createElectronWebContentsView } from "./parts/ElectronWebContentsView/ElectronWebContentsView.js";
 export { executeCommand } from "./parts/ExecuteCommand/ExecuteCommand.js";
 export { showFileQuickPick, showQuickInput, showQuickPick } from "./parts/QuickPick/QuickPick.js";
@@ -19,6 +20,7 @@ export { exists, getFileHash, getFileHashes, mkdir, readAsObjectUrl, readDirWith
 export { registerFileChangeHandler } from "./parts/FileChangeHandler/FileChangeHandler.js";
 export { executeFileSystemProviderGetOpenExternalPath, executeFileSystemProviderIsReadonly, executeFileSystemProviderMkdir, executeFileSystemProviderReadDirWithFileTypes, executeFileSystemProviderReadFile, executeFileSystemProviderRemove, executeFileSystemProviderRename, executeFileSystemProviderWriteFile, getFileSystemProviderRegistrySnapshot, registerFileSystemProvider, resetFileSystemProviderRegistry, } from "./parts/FileSystemProviderRegistry/FileSystemProviderRegistry.js";
 export { closeUri, confirm, getRecentlyOpenedWorkspaceUris, getWorkspaceFolder, getWorkspaceUri, handleWorkspaceRefresh, openUri, setWorkspaceUri, showErrorMessage, showNotification, } from "./parts/Host/Host.js";
+export { preparePrettyError } from "./parts/PrettyError/PrettyError.js";
 export { executeHoverProvider, getHoverProviderRegistrySnapshot, registerHoverProvider, resetHoverProviderRegistry } from "./parts/Hover/Hover.js";
 export { executeSignatureHelpProvider, getSignatureHelpProviderRegistrySnapshot, registerSignatureHelpProvider, resetSignatureHelpProviderRegistry, } from "./parts/SignatureHelp/SignatureHelp.js";
 export { getPlatform, getUserDataDir } from "./parts/Platform/Platform.js";

package/dist/parts/AuthenticationProvider/AuthenticationProvider.d.ts

@@ -0,0 +1,17 @@
+export interface AuthenticationAccount {
+    readonly id: string;
+    readonly label: string;
+}
+export interface AuthenticationSession {
+    readonly accessToken: string;
+    readonly account: AuthenticationAccount;
+    readonly id: string;
+    readonly scopes: readonly string[];
+}
+export interface AuthenticationProvider {
+    readonly createSession: (scopes: readonly string[]) => Promise<AuthenticationSession> | AuthenticationSession;
+    readonly getSessions: (scopes: readonly string[]) => Promise<readonly AuthenticationSession[]> | readonly AuthenticationSession[];
+    readonly id: string;
+    readonly label: string;
+    readonly removeSession: (sessionId: string) => Promise<void> | void;
+}

package/dist/parts/AuthenticationProvider/AuthenticationProvider.js

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

package/dist/parts/AuthenticationProviderRegistry/AuthenticationProviderRegistry.d.ts

@@ -0,0 +1,9 @@
+import type { AuthenticationProvider, AuthenticationSession } from '../AuthenticationProvider/AuthenticationProvider.ts';
+import type { AuthenticationProviderRegistrySnapshot } from '../AuthenticationProviderRegistrySnapshot/AuthenticationProviderRegistrySnapshot.ts';
+import type { Disposable } from '../Disposable/Disposable.ts';
+export declare const registerAuthenticationProvider: (provider: AuthenticationProvider) => Disposable;
+export declare const executeAuthenticationProviderGetSessions: (providerId: string, scopes: readonly string[]) => Promise<readonly AuthenticationSession[]>;
+export declare const executeAuthenticationProviderCreateSession: (providerId: string, scopes: readonly string[]) => Promise<AuthenticationSession>;
+export declare const executeAuthenticationProviderRemoveSession: (providerId: string, sessionId: string) => Promise<void>;
+export declare const getAuthenticationProviderRegistrySnapshot: () => AuthenticationProviderRegistrySnapshot;
+export declare const resetAuthenticationProviderRegistry: () => void;

package/dist/parts/AuthenticationProviderRegistry/AuthenticationProviderRegistry.js

@@ -0,0 +1,98 @@
+import * as ExtensionApiCommandRegistry from "../ExtensionApiCommandRegistry/ExtensionApiCommandRegistry.js";
+import { ExtensionApiError } from "../ExtensionApiError/ExtensionApiError.js";
+const providers = Object.create(null);
+const assertSession = (session, providerId) => {
+    if (!session || typeof session !== 'object') {
+        throw new ExtensionApiError(`authentication provider ${providerId} returned an invalid session`);
+    }
+    const value = session;
+    if (typeof value.id !== 'string' || value.id.length === 0) {
+        throw new ExtensionApiError(`authentication provider ${providerId} returned a session without an id`);
+    }
+    if (typeof value.accessToken !== 'string' || value.accessToken.length === 0) {
+        throw new ExtensionApiError(`authentication provider ${providerId} returned a session without an access token`);
+    }
+    if (!Array.isArray(value.scopes) || value.scopes.some((scope) => typeof scope !== 'string' || scope.length === 0)) {
+        throw new ExtensionApiError(`authentication provider ${providerId} returned a session with invalid scopes`);
+    }
+    if (!value.account || typeof value.account !== 'object') {
+        throw new ExtensionApiError(`authentication provider ${providerId} returned a session without an account`);
+    }
+    const account = value.account;
+    if (typeof account.id !== 'string' || account.id.length === 0 || typeof account.label !== 'string' || account.label.length === 0) {
+        throw new ExtensionApiError(`authentication provider ${providerId} returned a session with an invalid account`);
+    }
+    return session;
+};
+const assertScopes = (scopes) => {
+    if (!Array.isArray(scopes) || scopes.some((scope) => !(typeof scope === 'string' && scope.length > 0))) {
+        throw new ExtensionApiError('authentication scopes must be an array of non-empty strings');
+    }
+};
+const getProvider = (providerId) => {
+    const provider = providers[providerId];
+    if (!provider) {
+        throw new ExtensionApiError(`authentication provider ${providerId} not found`);
+    }
+    return provider;
+};
+export const registerAuthenticationProvider = (provider) => {
+    if (!provider) {
+        throw new ExtensionApiError('authentication provider is not defined');
+    }
+    const providerRecord = provider;
+    if (typeof providerRecord.id !== 'string' || providerRecord.id.length === 0) {
+        throw new ExtensionApiError('authentication provider is missing id');
+    }
+    const { id } = provider;
+    if (typeof providerRecord.label !== 'string' || providerRecord.label.length === 0) {
+        throw new ExtensionApiError(`authentication provider ${id} is missing label`);
+    }
+    for (const methodName of ['getSessions', 'createSession', 'removeSession']) {
+        if (typeof providerRecord[methodName] !== 'function') {
+            throw new ExtensionApiError(`authentication provider ${id} is missing ${methodName} function`);
+        }
+    }
+    if (id in providers) {
+        throw new ExtensionApiError(`authentication provider ${id} is already registered`);
+    }
+    providers[id] = provider;
+    ExtensionApiCommandRegistry.registerCommandMap(commandMap);
+    return {
+        dispose() {
+            delete providers[id];
+        },
+    };
+};
+export const executeAuthenticationProviderGetSessions = async (providerId, scopes) => {
+    assertScopes(scopes);
+    const sessions = await getProvider(providerId).getSessions(scopes);
+    if (!Array.isArray(sessions)) {
+        throw new ExtensionApiError(`authentication provider ${providerId} returned invalid sessions`);
+    }
+    return sessions.map((session) => assertSession(session, providerId));
+};
+export const executeAuthenticationProviderCreateSession = async (providerId, scopes) => {
+    assertScopes(scopes);
+    return assertSession(await getProvider(providerId).createSession(scopes), providerId);
+};
+export const executeAuthenticationProviderRemoveSession = async (providerId, sessionId) => {
+    if (typeof sessionId !== 'string' || sessionId.length === 0) {
+        throw new ExtensionApiError('authentication session id is missing');
+    }
+    await getProvider(providerId).removeSession(sessionId);
+};
+export const getAuthenticationProviderRegistrySnapshot = () => ({
+    providers: Object.values(providers).map(({ id, label }) => ({ id, label })),
+});
+export const resetAuthenticationProviderRegistry = () => {
+    for (const id of Object.keys(providers)) {
+        delete providers[id];
+    }
+};
+const commandMap = {
+    'ExtensionApi.executeAuthenticationProviderCreateSession': executeAuthenticationProviderCreateSession,
+    'ExtensionApi.executeAuthenticationProviderGetSessions': executeAuthenticationProviderGetSessions,
+    'ExtensionApi.executeAuthenticationProviderRemoveSession': executeAuthenticationProviderRemoveSession,
+    'ExtensionApi.getAuthenticationProviderRegistrySnapshot': getAuthenticationProviderRegistrySnapshot,
+};

package/dist/parts/AuthenticationProviderRegistrySnapshot/AuthenticationProviderRegistrySnapshot.d.ts

@@ -0,0 +1,6 @@
+export interface AuthenticationProviderRegistrySnapshot {
+    readonly providers: readonly {
+        readonly id: string;
+        readonly label: string;
+    }[];
+}

package/dist/parts/AuthenticationProviderRegistrySnapshot/AuthenticationProviderRegistrySnapshot.js

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

package/dist/parts/PrettyError/PrettyError.d.ts

@@ -0,0 +1,7 @@
+export interface PrettyError {
+    readonly codeFrame?: string;
+    readonly message?: string;
+    readonly name?: string;
+    readonly stack?: string;
+}
+export declare const preparePrettyError: (error: unknown) => Promise<PrettyError>;

package/dist/parts/PrettyError/PrettyError.js

@@ -0,0 +1,35 @@
+import { executeCommand } from "../ExecuteCommand/ExecuteCommand.js";
+const serializeError = (error) => {
+    if (error instanceof Error) {
+        return {
+            code: error.code,
+            codeFrame: error.codeFrame,
+            constructor: { name: error.constructor.name },
+            message: error.message,
+            name: error.name,
+            stack: error.stack,
+        };
+    }
+    if (error && typeof error === 'object') {
+        const value = error;
+        const constructorName = Object.hasOwn(value, 'constructor') ? value.constructor?.name : undefined;
+        return {
+            code: value.code,
+            codeFrame: value.codeFrame,
+            constructor: constructorName ? { name: constructorName } : undefined,
+            message: value.message || value.errorMessage,
+            name: value.name || constructorName,
+            stack: value.stack || value.errorStack,
+        };
+    }
+    return { message: String(error) };
+};
+export const preparePrettyError = async (error) => {
+    const serialized = serializeError(error);
+    try {
+        return (await executeCommand('ErrorHandling.preparePrettyError', serialized));
+    }
+    catch {
+        return serialized;
+    }
+};

package/dist/parts/View/View.d.ts

@@ -51,6 +51,8 @@ export interface VirtualDomViewInstance {
     readonly getCss?: () => string | Promise<string>;
     readonly getMenuEntries?: (menuId: string) => readonly MenuEntry[] | Promise<readonly MenuEntry[]>;
     readonly handleEvent?: (event: ViewEvent) => unknown;
+    /** Whether this document has edits that have not been saved. */
+    readonly isDirty?: () => boolean;
     readonly render: () => readonly VirtualDomNode[] | Promise<readonly VirtualDomNode[]>;
     readonly renderActions?: () => readonly ViewAction[] | Promise<readonly ViewAction[]>;
     readonly renderActionsDom?: () => readonly VirtualDomNode[];
@@ -59,6 +61,8 @@ export interface VirtualDomViewInstance {
     readonly renderSelections?: () => readonly ViewSelection[] | Promise<readonly ViewSelection[]>;
     readonly renderStatusBarItems?: () => readonly StatusBarItem[] | Promise<readonly StatusBarItem[]>;
     readonly renderTitle?: () => string | Promise<string>;
+    /** Persist committed edits. Reject on failure and retain dirty state until persistence succeeds. */
+    readonly save?: () => void | Promise<void>;
     readonly saveState?: () => unknown;
 }
 export type ViewCommand<State = VirtualDomViewInstance, Args extends readonly any[] = readonly any[]> = (state: State, ...args: Args) => State | Promise<State>;
@@ -87,6 +91,7 @@ export interface StatefulView<State = unknown> extends ViewBase<State> {
     readonly getCss?: (state: State) => string | Promise<string>;
     readonly getMenuEntries?: (state: State, menuId: string) => readonly MenuEntry[] | Promise<readonly MenuEntry[]>;
     readonly handleEvent?: (state: State, event: ViewEvent) => State | Promise<State>;
+    readonly isDirty?: (state: State) => boolean;
     readonly render: (state: State) => readonly VirtualDomNode[] | Promise<readonly VirtualDomNode[]>;
     readonly renderActions?: (state: State) => readonly ViewAction[] | Promise<readonly ViewAction[]>;
     readonly renderActionsDom?: (state: State) => readonly VirtualDomNode[];
@@ -95,6 +100,7 @@ export interface StatefulView<State = unknown> extends ViewBase<State> {
     readonly renderSelections?: (state: State) => readonly ViewSelection[] | Promise<readonly ViewSelection[]>;
     readonly renderStatusBarItems?: (state: State) => readonly StatusBarItem[] | Promise<readonly StatusBarItem[]>;
     readonly renderTitle?: (state: State) => string | Promise<string>;
+    readonly save?: (state: State) => State | Promise<State>;
     readonly saveState?: (state: State) => unknown;
 }
 export type View<State = unknown, ComponentState = unknown> = InstanceView<State, ComponentState> | StatefulView<State>;
@@ -116,6 +122,7 @@ export interface ViewRenderResultDom {
     readonly css?: string;
     readonly dom: readonly VirtualDomNode[];
     readonly focusSelector?: string;
+    readonly modified?: boolean;
     readonly scrollPosition?: ViewScrollPosition;
     readonly selections?: readonly ViewSelection[];
     readonly title?: string;
@@ -124,6 +131,7 @@ export interface ViewRenderResultDom {
 export interface ViewRenderResultPatches {
     readonly css?: string;
     readonly focusSelector?: string;
+    readonly modified?: boolean;
     readonly patches: readonly unknown[];
     readonly scrollPosition?: ViewScrollPosition;
     readonly selections?: readonly ViewSelection[];

package/dist/parts/ViewRegistry/ViewRegistry.js

@@ -236,6 +236,16 @@ const createStatefulViewInstance = (view, uid) => {
             ViewletStates.replace(uid, newState);
         };
     }
+    if (view.isDirty) {
+        instance.isDirty = () => view.isDirty(ViewletStates.get(uid));
+    }
+    if (view.save) {
+        instance.save = async () => {
+            const newState = await view.save(ViewletStates.get(uid));
+            assertViewState(view.id, newState);
+            ViewletStates.replace(uid, newState);
+        };
+    }
     if (view.renderActions) {
         instance.renderActions = () => view.renderActions(ViewletStates.get(uid));
     }
@@ -506,7 +516,14 @@ const withRenderMetadata = async (uid, viewId, result, instance, contextChange)
     const resultWithScrollPosition = await withScrollPosition(resultWithSelections, instance);
     const resultWithTitle = await withTitle(resultWithScrollPosition, instance);
     await ViewStatusBarItems.renderViewStatusBarItems(uid, viewId, instance);
-    return resultWithTitle;
+    if (typeof instance.isDirty !== 'function') {
+        return resultWithTitle;
+    }
+    const modified = instance.isDirty();
+    if (typeof modified !== 'boolean') {
+        throw new ExtensionApiError('view isDirty result must be a boolean');
+    }
+    return { ...resultWithTitle, modified };
 };
 const maybeClearContext = async (uid, viewId) => {
     if (!contexts[uid]) {

package/package.json

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