feat: implement dynamic list for available commands and themes on configuration change

Author: dermatz

src/commandsProvider.ts

@@ -1,4 +1,5 @@
 import * as vscode from 'vscode';
+import { execMageforge, getMagentoRoot } from './magento';
 
 export interface MageforgeCommand {
     id: string;
@@ -95,28 +96,142 @@ export const MAGEFORGE_COMMANDS: MageforgeCommand[] = [
     },
 ];
 
+/**
+ * Query the installed MageForge CLI for the commands it actually exposes.
+ * Returns the raw command names (e.g. `mageforge:theme:build`).
+ */
+export async function getAvailableMageforgeCommands(magentoRoot: string): Promise<string[]> {
+    const output = await execMageforge(magentoRoot, 'list', ['--raw', 'mageforge']);
+    return output
+        .split('\n')
+        .map((line) => stripAnsi(line).trim())
+        .filter((line) => line.length > 0)
+        .map((line) => line.split(/\s+/)[0]);
+}
+
 export class CommandsProvider implements vscode.TreeDataProvider<CommandTreeItem> {
+    private readonly _onDidChangeTreeData = new vscode.EventEmitter<CommandTreeItem | undefined>();
+    readonly onDidChangeTreeData = this._onDidChangeTreeData.event;
+
+    private availableCommands: Set<string> | undefined;
+    private loadError: string | undefined;
+    private loadingPromise: Promise<void> | undefined;
+
+    refresh(): void {
+        this.availableCommands = undefined;
+        this.loadError = undefined;
+        this.loadingPromise = undefined;
+        this._onDidChangeTreeData.fire(undefined);
+    }
+
     getTreeItem(element: CommandTreeItem): vscode.TreeItem {
         return element;
     }
 
-    getChildren(): CommandTreeItem[] {
-        return MAGEFORGE_COMMANDS.map((cmd) => new CommandTreeItem(cmd));
+    async getChildren(element?: CommandTreeItem): Promise<CommandTreeItem[]> {
+        if (element) {
+            return [];
+        }
+
+        await this.ensureCommandsLoaded();
+
+        if (this.loadError) {
+            return [new CommandTreeItem(undefined, this.loadError)];
+        }
+
+        const commands = this.availableCommands
+            ? MAGEFORGE_COMMANDS.filter((cmd) => this.availableCommands!.has(cmd.cliCommand))
+            : MAGEFORGE_COMMANDS;
+
+        return commands.map((cmd) => new CommandTreeItem(cmd));
+    }
+
+    private async ensureCommandsLoaded(): Promise<void> {
+        if (this.availableCommands !== undefined || this.loadError !== undefined) {
+            return;
+        }
+
+        if (this.loadingPromise) {
+            await this.loadingPromise;
+            return;
+        }
+
+        this.loadingPromise = this.loadCommands().finally(() => {
+            this.loadingPromise = undefined;
+        });
+        await this.loadingPromise;
+    }
+
+    private async loadCommands(): Promise<void> {
+        const root = getMagentoRoot();
+        if (!root) {
+            this.loadError = 'Open a Magento workspace to see available commands.';
+            return;
+        }
+
+        try {
+            const available = await getAvailableMageforgeCommands(root);
+            this.availableCommands = new Set(available);
+            this.loadError = undefined;
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.availableCommands = undefined;
+            this.loadError = formatLoadError(stripAnsi(message));
+        }
     }
 }
 
 export class CommandTreeItem extends vscode.TreeItem {
-    constructor(public readonly mageforgeCommand: MageforgeCommand) {
-        super(mageforgeCommand.label, vscode.TreeItemCollapsibleState.None);
-        this.description = mageforgeCommand.description;
-        this.tooltip = new vscode.MarkdownString(
-            `**${mageforgeCommand.label}**\n\n\`${mageforgeCommand.description}\``,
-        );
-        this.iconPath = new vscode.ThemeIcon(mageforgeCommand.icon);
-        this.command = {
-            command: mageforgeCommand.id,
-            title: mageforgeCommand.label,
-        };
-        this.contextValue = 'mageforgeCommand';
+    constructor(
+        public readonly mageforgeCommand: MageforgeCommand | undefined,
+        label?: string,
+    ) {
+        super(label ?? mageforgeCommand!.label, vscode.TreeItemCollapsibleState.None);
+
+        if (mageforgeCommand) {
+            this.description = mageforgeCommand.description;
+            this.tooltip = new vscode.MarkdownString(
+                `**${mageforgeCommand.label}**\n\n\`${mageforgeCommand.description}\``,
+            );
+            this.iconPath = new vscode.ThemeIcon(mageforgeCommand.icon);
+            this.command = {
+                command: mageforgeCommand.id,
+                title: mageforgeCommand.label,
+            };
+            this.contextValue = 'mageforgeCommand';
+        } else {
+            this.iconPath = new vscode.ThemeIcon('info');
+        }
+    }
+}
+
+/** Strip ANSI escape sequences (colors, cursor movement) from console output. */
+function stripAnsi(text: string): string {
+    return text.replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, '');
+}
+
+/**
+ * Convert a raw command failure into a user-friendly error message.
+ * Long messages are truncated so they do not break the tree view layout.
+ */
+function formatLoadError(message: string): string {
+    const normalized = message.toLowerCase();
+
+    if (
+        normalized.includes('ddev') &&
+        /not (running|started)|could not|failed|unable/i.test(message)
+    ) {
+        return 'DDEV is not running. Start the project with `ddev start` and try again.';
+    }
+    if (normalized.includes('docker-compose') || normalized.includes('docker compose')) {
+        return 'Docker Compose service unavailable. Check that containers are running.';
     }
+    if (normalized.includes('lando')) {
+        return 'Lando environment unavailable. Start the project with `lando start`.';
+    }
+    if (normalized.includes('command not found') || normalized.includes('no such file')) {
+        return 'MageForge CLI not found. Run `composer require openforgeproject/mageforge`.';
+    }
+
+    return message.length > 120 ? `${message.slice(0, 120)}…` : message;
 }

src/extension.ts

@@ -28,6 +28,16 @@ export function activate(context: vscode.ExtensionContext) {
         vscode.window.createTreeView('mageforge.themes', { treeDataProvider: themesProvider }),
     );
 
+    // Refresh dynamic views when MageForge settings change.
+    context.subscriptions.push(
+        vscode.workspace.onDidChangeConfiguration((event) => {
+            if (event.affectsConfiguration('mageforge')) {
+                commandsProvider.refresh();
+                themesProvider.refresh();
+            }
+        }),
+    );
+
     // Notify the user and open the changelog after the extension was updated.
     void showUpdateNotificationIfNeeded(context, changelogProvider);
 
@@ -53,6 +63,9 @@ export function activate(context: vscode.ExtensionContext) {
     );
 
     context.subscriptions.push(
+        vscode.commands.registerCommand('mageforge.refreshCommands', () =>
+            commandsProvider.refresh(),
+        ),
         vscode.commands.registerCommand('mageforge.refreshThemes', () => themesProvider.refresh()),
         vscode.commands.registerCommand(
             'mageforge.template.overrideFile',

src/test/extension.test.ts

@@ -20,6 +20,7 @@ suite('Extension Integration Test Suite', () => {
 
         assert.ok(mageforgeCommands.includes('mageforge.theme.build'));
         assert.ok(mageforgeCommands.includes('mageforge.theme.watch'));
+        assert.ok(mageforgeCommands.includes('mageforge.refreshCommands'));
         assert.ok(mageforgeCommands.includes('mageforge.refreshThemes'));
         assert.ok(mageforgeCommands.includes('mageforge.showChangelog'));
         assert.ok(mageforgeCommands.includes('mageforge.updateMageforge'));

src/test/unit/commandsProvider.test.ts

@@ -1,9 +1,31 @@
 import * as assert from 'assert';
-import { CommandTreeItem, CommandsProvider, MAGEFORGE_COMMANDS } from '../../commandsProvider';
+import mockRequire = require('mock-require');
+import type { MageforgeCommand } from '../../commandsProvider';
+
+type MockMagento = {
+    getMagentoRoot: () => string | undefined;
+    execMageforge: (root: string, command: string, args?: string[]) => Promise<string>;
+};
+
+function loadCommandsProvider(magentoMock: MockMagento) {
+    mockRequire('../../magento', magentoMock);
+    return mockRequire.reRequire(
+        '../../commandsProvider',
+    ) as typeof import('../../commandsProvider');
+}
 
 suite('commandsProvider.ts unit tests', () => {
+    teardown(() => {
+        mockRequire.stop('../../magento');
+    });
+
     suite('MAGEFORGE_COMMANDS', () => {
         test('contains expected commands', () => {
+            const { MAGEFORGE_COMMANDS } = loadCommandsProvider({
+                getMagentoRoot: () => undefined,
+                execMageforge: async () => '',
+            });
+
             const ids = MAGEFORGE_COMMANDS.map((cmd) => cmd.id);
             assert.ok(ids.includes('mageforge.theme.build'));
             assert.ok(ids.includes('mageforge.theme.watch'));
@@ -12,28 +34,142 @@ suite('commandsProvider.ts unit tests', () => {
         });
 
         test('theme commands accept themes', () => {
+            const { MAGEFORGE_COMMANDS } = loadCommandsProvider({
+                getMagentoRoot: () => undefined,
+                execMageforge: async () => '',
+            });
+
             const themeCommands = MAGEFORGE_COMMANDS.filter((cmd) => cmd.acceptsThemes);
             const ids = themeCommands.map((cmd) => cmd.id);
             assert.deepStrictEqual(ids.sort(), ['mageforge.theme.build', 'mageforge.theme.watch']);
         });
 
         test('watch command is marked as watch', () => {
+            const { MAGEFORGE_COMMANDS } = loadCommandsProvider({
+                getMagentoRoot: () => undefined,
+                execMageforge: async () => '',
+            });
+
             const watch = MAGEFORGE_COMMANDS.find((cmd) => cmd.id === 'mageforge.theme.watch');
             assert.strictEqual(watch?.isWatch, true);
         });
     });
 
+    suite('getAvailableMageforgeCommands', () => {
+        test('parses raw command list output', async () => {
+            const { getAvailableMageforgeCommands } = loadCommandsProvider({
+                getMagentoRoot: () => '/magento',
+                execMageforge: async () =>
+                    'mageforge:theme:build   Builds a theme\nmageforge:theme:list\nmageforge:system:version',
+            });
+
+            const available = await getAvailableMageforgeCommands('/magento');
+
+            assert.deepStrictEqual(available.sort(), [
+                'mageforge:system:version',
+                'mageforge:theme:build',
+                'mageforge:theme:list',
+            ]);
+        });
+    });
+
     suite('CommandsProvider', () => {
-        test('returns all commands as tree items', () => {
+        test('shows only commands reported by the CLI', async () => {
+            const { CommandsProvider, MAGEFORGE_COMMANDS } = loadCommandsProvider({
+                getMagentoRoot: () => '/magento',
+                execMageforge: async () =>
+                    'mageforge:theme:build\nmageforge:theme:watch\nmageforge:system:version',
+            });
+
+            const provider = new CommandsProvider();
+            const children = await provider.getChildren();
+
+            assert.strictEqual(children.length, 3);
+            const ids = children.map((child) => child.mageforgeCommand?.id);
+            assert.deepStrictEqual(ids.sort(), [
+                'mageforge.system.version',
+                'mageforge.theme.build',
+                'mageforge.theme.watch',
+            ]);
+        });
+
+        test('shows info message when no Magento root is found', async () => {
+            const { CommandsProvider } = loadCommandsProvider({
+                getMagentoRoot: () => undefined,
+                execMageforge: async () => '',
+            });
+
+            const provider = new CommandsProvider();
+            const children = await provider.getChildren();
+
+            assert.strictEqual(children.length, 1);
+            assert.strictEqual(children[0].mageforgeCommand, undefined);
+            assert.ok(children[0].label?.toString().includes('Magento workspace'));
+        });
+
+        test('shows user-friendly error when CLI call fails', async () => {
+            const { CommandsProvider } = loadCommandsProvider({
+                getMagentoRoot: () => '/magento',
+                execMageforge: async () => {
+                    throw new Error('ddev is not running');
+                },
+            });
+
+            const provider = new CommandsProvider();
+            const children = await provider.getChildren();
+
+            assert.strictEqual(children.length, 1);
+            assert.strictEqual(children[0].mageforgeCommand, undefined);
+            assert.ok(children[0].label?.toString().includes('DDEV'));
+        });
+
+        test('caches available commands across multiple getChildren calls', async () => {
+            let calls = 0;
+            const { CommandsProvider } = loadCommandsProvider({
+                getMagentoRoot: () => '/magento',
+                execMageforge: async () => {
+                    calls++;
+                    return 'mageforge:theme:build';
+                },
+            });
+
             const provider = new CommandsProvider();
-            const children = provider.getChildren();
+            await provider.getChildren();
+            await provider.getChildren();
 
-            assert.strictEqual(children.length, MAGEFORGE_COMMANDS.length);
+            assert.strictEqual(calls, 1);
+        });
+
+        test('refresh clears cache and reloads commands', async () => {
+            let calls = 0;
+            const { CommandsProvider } = loadCommandsProvider({
+                getMagentoRoot: () => '/magento',
+                execMageforge: async () => {
+                    calls++;
+                    return calls === 1
+                        ? 'mageforge:theme:build'
+                        : 'mageforge:theme:build\nmageforge:theme:watch';
+                },
+            });
+
+            const provider = new CommandsProvider();
+            const first = await provider.getChildren();
+            assert.strictEqual(first.length, 1);
+
+            provider.refresh();
+            const second = await provider.getChildren();
+            assert.strictEqual(second.length, 2);
+            assert.strictEqual(calls, 2);
         });
     });
 
     suite('CommandTreeItem', () => {
         test('sets label, description and command', () => {
+            const { CommandTreeItem, MAGEFORGE_COMMANDS } = loadCommandsProvider({
+                getMagentoRoot: () => undefined,
+                execMageforge: async () => '',
+            });
+
             const cmd = MAGEFORGE_COMMANDS[0];
             const item = new CommandTreeItem(cmd);
 
@@ -43,5 +179,18 @@ suite('commandsProvider.ts unit tests', () => {
             assert.strictEqual(item.command?.title, cmd.label);
             assert.strictEqual(item.contextValue, 'mageforgeCommand');
         });
+
+        test('renders info item without command', () => {
+            const { CommandTreeItem } = loadCommandsProvider({
+                getMagentoRoot: () => undefined,
+                execMageforge: async () => '',
+            });
+
+            const item = new CommandTreeItem(undefined, 'Info message');
+
+            assert.strictEqual(item.label, 'Info message');
+            assert.strictEqual(item.command, undefined);
+            assert.strictEqual(item.contextValue, undefined);
+        });
     });
 });