friendly error message when cli does not exist

Summary: Added validateCliPath function to validate CLI path.  This will provide the download link if CLI does not exist.

Reviewed By: zjm-meta

Differential Revision:
D88069849

Privacy Context Container: L1334777

fbshipit-source-id: f94328d1bb073aa6eb664019df1a2f4bea840374

Author: Peter Wang

packages/vite-plugin-metaspatial/src/generate-glxf/cli-path-resolver.ts

@@ -8,6 +8,16 @@
 import * as path from 'path';
 import fs from 'fs-extra';
 
+/**
+ * Download URLs for Meta Spatial Editor by platform
+ */
+const DOWNLOAD_URLS = {
+  darwin: 'https://developers.meta.com/horizon/downloads/package/meta-spatial-editor-for-mac',
+  win32: 'https://developers.meta.com/horizon/downloads/package/meta-spatial-editor-for-windows',
+  linux: 'https://developers.meta.com/horizon/downloads/package/meta-spatial-editor-for-linux',
+  default: 'https://developers.meta.com/horizon/downloads/spatial-sdk/',
+} as const;
+
 /**
  * Get the highest version directory from Meta Spatial Editor installation
  * @param directoryPath - Base directory path
@@ -71,3 +81,72 @@ export function resolveMetaSpatialCliPath(): string {
     return 'MetaSpatialEditorCLI';
   }
 }
+
+/**
+ * Validate that the Meta Spatial CLI exists and is accessible
+ * @param cliPath - Path to the CLI executable
+ * @throws Error with helpful message including download link if CLI not found
+ */
+export async function validateCliPath(cliPath: string): Promise<void> {
+  const platform = process.platform as keyof typeof DOWNLOAD_URLS;
+  const downloadUrl = DOWNLOAD_URLS[platform] || DOWNLOAD_URLS.default;
+
+  // For Linux, the CLI might be in PATH, so we skip file existence check
+  // The spawn process will handle the error if it's not found
+  if (platform === 'linux' && !path.isAbsolute(cliPath)) {
+    return;
+  }
+
+  try {
+    const exists = await fs.pathExists(cliPath);
+
+    if (!exists) {
+      const errorMessage = [
+        `❌ Meta Spatial Editor CLI not found at: ${cliPath}`,
+        '',
+        '📥 Please download and install Meta Spatial Editor:',
+        `   ${downloadUrl}`,
+        '',
+        '🔧 Alternative solutions:',
+        '   1. Set the META_SPATIAL_EDITOR_CLI_PATH environment variable to the correct path',
+        '   2. Specify metaSpatialCliPath in your vite.config.js generateGLXF options',
+        '',
+      ].join('\n');
+
+      throw new Error(errorMessage);
+    }
+
+    // Check if the file is executable (Unix-like systems)
+    if (platform !== 'win32') {
+      try {
+        await fs.access(cliPath, fs.constants.X_OK);
+      } catch (error) {
+        const errorMessage = [
+          `❌ Meta Spatial Editor CLI found but is not executable: ${cliPath}`,
+          '',
+          '🔧 Make the file executable by running:',
+          `   chmod +x "${cliPath}"`,
+          '',
+        ].join('\n');
+
+        throw new Error(errorMessage);
+      }
+    }
+  } catch (error) {
+    // Re-throw our custom errors, or wrap system errors
+    if (error instanceof Error && error.message.includes('Meta Spatial Editor')) {
+      throw error;
+    }
+
+    const errorMessage = [
+      `❌ Error checking Meta Spatial Editor CLI at: ${cliPath}`,
+      `   ${error instanceof Error ? error.message : String(error)}`,
+      '',
+      '📥 If you need to install Meta Spatial Editor, download it from:',
+      `   ${downloadUrl}`,
+      '',
+    ].join('\n');
+
+    throw new Error(errorMessage);
+  }
+}

packages/vite-plugin-metaspatial/src/generate-glxf/cli-wrapper.ts

@@ -10,6 +10,7 @@ import * as os from 'os';
 import * as path from 'path';
 import fs from 'fs-extra';
 import { processAssets } from './asset-processor.js';
+import { validateCliPath } from './cli-path-resolver.js';
 
 /**
  * Execute Meta Spatial CLI and process the generated assets
@@ -21,6 +22,9 @@ export async function executeMetaSpatialExport(
   finalGltfDir: string,
   verbose: boolean = false,
 ): Promise<void> {
+  // Validate CLI path before attempting execution
+  await validateCliPath(cliPath);
+
   // Create temporary directory
   const tempDir = await fs.mkdtemp(
     path.join(os.tmpdir(), 'metaspatial-export-'),
@@ -31,6 +35,7 @@ export async function executeMetaSpatialExport(
 
     if (verbose) {
       console.log(`🚀 Executing Meta Spatial CLI export:`);
+      console.log(`   CLI: ${cliPath}`);
       console.log(`   Project: ${absoluteProjectPath}`);
       console.log(`   Temp output: ${tempDir}`);
     }

packages/vite-plugin-metaspatial/tests/cli-path-resolver.test.ts

@@ -6,7 +6,7 @@
  */
 
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { getHighestVersion, resolveMetaSpatialCliPath } from '../src/generate-glxf/cli-path-resolver.js';
+import { getHighestVersion, resolveMetaSpatialCliPath, validateCliPath } from '../src/generate-glxf/cli-path-resolver.js';
 import fs from 'fs-extra';
 import * as path from 'path';
 
@@ -200,4 +200,87 @@ describe('CLI Path Resolver', () => {
       expect(result).not.toBe('/Applications/Meta Spatial Editor.app/Contents/MacOS/CLI');
     });
   });
+
+  describe('validateCliPath', () => {
+    beforeEach(() => {
+      // Reset to darwin for most tests
+      Object.defineProperty(process, 'platform', {
+        value: 'darwin',
+      });
+    });
+
+    it('should pass validation when CLI exists and is executable on macOS', async () => {
+      const cliPath = '/Applications/Meta Spatial Editor.app/Contents/MacOS/CLI';
+
+      vi.mocked(fs.pathExists).mockResolvedValue(true);
+      vi.mocked(fs.access).mockResolvedValue(undefined);
+
+      await expect(validateCliPath(cliPath)).resolves.toBeUndefined();
+    });
+
+    it('should pass validation when CLI exists on Windows', async () => {
+      Object.defineProperty(process, 'platform', {
+        value: 'win32',
+      });
+
+      const cliPath = 'C:\\Program Files\\Meta Spatial Editor\\v20\\Resources\\CLI.exe';
+
+      vi.mocked(fs.pathExists).mockResolvedValue(true);
+
+      await expect(validateCliPath(cliPath)).resolves.toBeUndefined();
+    });
+
+    it('should skip validation for Linux with non-absolute path', async () => {
+      Object.defineProperty(process, 'platform', {
+        value: 'linux',
+      });
+
+      const cliPath = 'MetaSpatialEditorCLI';
+
+      await expect(validateCliPath(cliPath)).resolves.toBeUndefined();
+      expect(fs.pathExists).not.toHaveBeenCalled();
+    });
+
+    it('should throw helpful error when CLI does not exist on macOS', async () => {
+      const cliPath = '/Applications/Meta Spatial Editor.app/Contents/MacOS/CLI';
+
+      vi.mocked(fs.pathExists).mockResolvedValue(false);
+
+      await expect(validateCliPath(cliPath)).rejects.toThrow('Meta Spatial Editor CLI not found');
+      await expect(validateCliPath(cliPath)).rejects.toThrow('meta-spatial-editor-for-mac');
+      await expect(validateCliPath(cliPath)).rejects.toThrow('META_SPATIAL_EDITOR_CLI_PATH');
+    });
+
+    it('should throw helpful error when CLI does not exist on Windows', async () => {
+      Object.defineProperty(process, 'platform', {
+        value: 'win32',
+      });
+
+      const cliPath = 'C:\\Program Files\\Meta Spatial Editor\\v20\\Resources\\CLI.exe';
+
+      vi.mocked(fs.pathExists).mockResolvedValue(false);
+
+      await expect(validateCliPath(cliPath)).rejects.toThrow('Meta Spatial Editor CLI not found');
+      await expect(validateCliPath(cliPath)).rejects.toThrow('meta-spatial-editor-for-windows');
+    });
+
+    it('should throw helpful error when CLI exists but is not executable on macOS', async () => {
+      const cliPath = '/Applications/Meta Spatial Editor.app/Contents/MacOS/CLI';
+
+      vi.mocked(fs.pathExists).mockResolvedValue(true);
+      vi.mocked(fs.access).mockRejectedValue(new Error('Permission denied'));
+
+      await expect(validateCliPath(cliPath)).rejects.toThrow('not executable');
+      await expect(validateCliPath(cliPath)).rejects.toThrow('chmod +x');
+    });
+
+    it('should include download link in error message for unknown errors', async () => {
+      const cliPath = '/Applications/Meta Spatial Editor.app/Contents/MacOS/CLI';
+
+      vi.mocked(fs.pathExists).mockRejectedValue(new Error('Unknown error'));
+
+      await expect(validateCliPath(cliPath)).rejects.toThrow('Error checking Meta Spatial Editor CLI');
+      await expect(validateCliPath(cliPath)).rejects.toThrow('download');
+    });
+  });
 });