@theia/plugin-ext 1.75.0-next.21 → 1.75.0-next.25

package/src/hosted/node/scanners/scanner-theia.ts

@@ -64,7 +64,11 @@ import {
     TerminalProfile,
     PluginIconContribution,
     PluginEntryPoint,
-    PluginPackageContribution
+    PluginPackageContribution,
+    WalkthroughContribution,
+    WalkthroughStepContribution,
+    PluginPackageWalkthroughStepMedia,
+    WalkthroughStepMedia
 } from '../../../common/plugin-protocol';
 import { promises as fs, readdirSync } from 'fs';
 import * as path from 'path';
@@ -557,6 +561,12 @@ export class TheiaPluginScanner extends AbstractPluginScanner {
             }
         }
 
+        try {
+            contributions.walkthroughs = this.readWalkthroughs(rawPlugin);
+        } catch (err) {
+            this.logger.error(`Could not read '${rawPlugin.name}' contribution 'walkthroughs'.`, rawPlugin.contributes.walkthroughs, err);
+        }
+
         return contributions;
     }
 
@@ -593,6 +603,91 @@ export class TheiaPluginScanner extends AbstractPluginScanner {
         return translation;
     }
 
+    protected readWalkthroughs(pck: PluginPackage): WalkthroughContribution[] | undefined {
+        if (!pck.contributes || !pck.contributes.walkthroughs) {
+            return undefined;
+        }
+        const pluginId = PluginIdentifiers.componentsToUnversionedId({ publisher: pck.publisher, name: pck.name, version: pck.version });
+        // `PluginModel` does not carry the extension icon, so it travels with the walkthroughs that show it.
+        const pluginIcon = pck.icon ? this.toPluginUrl(pck, pck.icon) : undefined;
+        const result: WalkthroughContribution[] = [];
+        for (const walkthrough of pck.contributes.walkthroughs) {
+            if (typeof walkthrough.id !== 'string' || !walkthrough.id) {
+                this.logger.error(`'contributes.walkthroughs.id' of '${pluginId}' must be defined and non-empty`);
+                continue;
+            }
+            if (typeof walkthrough.title !== 'string' || !walkthrough.title) {
+                this.logger.error(`'contributes.walkthroughs.title' of '${pluginId}.${walkthrough.id}' must be defined and non-empty`);
+                continue;
+            }
+            if (!Array.isArray(walkthrough.steps)) {
+                this.logger.error(`'contributes.walkthroughs.steps' of '${pluginId}.${walkthrough.id}' must be an array`);
+                continue;
+            }
+            const steps: WalkthroughStepContribution[] = [];
+            for (const step of walkthrough.steps) {
+                if (typeof step.id !== 'string' || !step.id) {
+                    this.logger.error(`'contributes.walkthroughs.steps.id' of '${pluginId}.${walkthrough.id}' must be defined and non-empty`);
+                    continue;
+                }
+                if (typeof step.title !== 'string' || !step.title) {
+                    this.logger.error(`'contributes.walkthroughs.steps.title' of '${pluginId}.${walkthrough.id}.${step.id}' must be defined and non-empty`);
+                    continue;
+                }
+                steps.push({
+                    id: step.id,
+                    title: step.title,
+                    description: step.description || '',
+                    media: this.resolveWalkthroughMedia(pck, step.media),
+                    completionEvents: step.completionEvents,
+                    when: step.when
+                });
+            }
+            result.push({
+                id: walkthrough.id,
+                title: walkthrough.title,
+                description: walkthrough.description || '',
+                steps,
+                when: walkthrough.when,
+                icon: walkthrough.icon,
+                pluginId,
+                pluginIcon
+            });
+        }
+        return result.length > 0 ? result : undefined;
+    }
+
+    protected resolveWalkthroughMedia(pck: PluginPackage, media?: PluginPackageWalkthroughStepMedia): WalkthroughStepMedia | undefined {
+        if (!media) {
+            return undefined;
+        }
+        if ('markdown' in media) {
+            return { markdown: this.toPluginUrl(pck, media.markdown) };
+        }
+        const altText = 'altText' in media ? media.altText as string : undefined;
+        if ('svg' in media) {
+            return { svg: this.toPluginUrl(pck, media.svg), ...(altText !== undefined && { altText }) };
+        }
+        if ('image' in media) {
+            if (typeof media.image === 'string') {
+                return { image: this.toPluginUrl(pck, media.image), ...(altText !== undefined && { altText }) };
+            }
+            // Only `dark` and `light` are mandatory; the high contrast variants fall back to them.
+            const dark = this.toPluginUrl(pck, media.image.dark);
+            const light = this.toPluginUrl(pck, media.image.light);
+            return {
+                image: {
+                    dark,
+                    light,
+                    hc: media.image.hc ? this.toPluginUrl(pck, media.image.hc) : dark,
+                    hcLight: media.image.hcLight ? this.toPluginUrl(pck, media.image.hcLight) : light
+                },
+                ...(altText !== undefined && { altText })
+            };
+        }
+        return undefined;
+    }
+
     protected readCommand({ command, title, shortTitle, original, category, icon, enablement }: PluginPackageCommand, pck: PluginPackage): PluginCommand {
         const { themeIcon, iconUrl } = this.transformIconUrl(pck, icon) ?? {};
         return { command, title, shortTitle, originalTitle: original, category, iconUrl, themeIcon, enablement };