diff --git a/README.md b/README.md index d5f1520..7cbe849 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ We always recommend using the latest version of these commands bundled with the - 🔄 **Dev Server Management** - Spawns and monitors dev servers (Vite, CRA, Next.js) - 🎨 **Beautiful Error Handling** - HTML error pages with auto-refresh and diagnostics - 💚 **Health Monitoring** - Periodic health checks with status updates -- 🔧 **Hot Config Reload** - Detects `webapp.json` changes automatically +- 🔧 **Hot Config Reload** - Detects `webapplication.json` changes automatically ## Quick Start @@ -71,7 +71,7 @@ We always recommend using the latest version of these commands bundled with the sf org login web --alias myorg ``` -3. **Create webapp.json:** +3. **Create webapplication.json:** ```json { @@ -94,6 +94,7 @@ We always recommend using the latest version of these commands bundled with the ## Documentation 📚 **[Complete Guide](SF_WEBAPP_DEV_GUIDE.md)** - Comprehensive documentation covering: + - Overview and architecture - Getting started (5-minute quick start) - Building the plugin @@ -171,11 +172,11 @@ USAGE $ sf webapp dev --name --target-org [options] REQUIRED FLAGS - -n, --name= Name of the webapp (must match webapp.json) + -n, --name= Name of the webapp (must match webapplication.json) -o, --target-org= Salesforce org to authenticate against OPTIONAL FLAGS - -u, --url= Dev server URL (overrides webapp.json) + -u, --url= Dev server URL (overrides webapplication.json) -p, --port= Proxy server port (default: 4545) --open Open browser automatically @@ -216,7 +217,7 @@ FEATURES - WebSocket support for Hot Module Replacement (HMR) - Beautiful HTML error pages with auto-refresh - Periodic health monitoring (every 5s) - - Configuration file watching (webapp.json) + - Configuration file watching (webapplication.json) - Graceful shutdown on Ctrl+C SEE ALSO diff --git a/SF_WEBAPP_DEV_GUIDE.md b/SF_WEBAPP_DEV_GUIDE.md index c394a83..65f5c85 100644 --- a/SF_WEBAPP_DEV_GUIDE.md +++ b/SF_WEBAPP_DEV_GUIDE.md @@ -10,7 +10,7 @@ The `sf webapp dev` command enables local development of modern web applications ### Key Features -- **Auto-Discovery**: Automatically finds `webapp.json` files in your project +- **Auto-Discovery**: Automatically finds `webapplication.json` files in your project - **Interactive Selection**: Prompts with arrow-key navigation when multiple webapps exist - **Authentication Injection**: Automatically adds Salesforce auth headers to API calls - **Intelligent Routing**: Routes requests to dev server or Salesforce based on URL patterns @@ -22,7 +22,7 @@ The `sf webapp dev` command enables local development of modern web applications ## Quick Start -### 1. Create `webapp.json` in your project +### 1. Create `webapplication.json` in your project ```json { @@ -56,18 +56,18 @@ sf webapp dev [OPTIONS] ### Options -| Option | Short | Description | Default | -| -------------- | ----- | --------------------------------------- | ------------- | -| `--target-org` | `-o` | Salesforce org alias or username | Required | -| `--name` | `-n` | Web application name (from webapp.json) | Auto-discover | -| `--url` | `-u` | Explicit dev server URL | Auto-detect | -| `--port` | `-p` | Proxy server port | 4545 | -| `--open` | `-b` | Open browser automatically | false | +| Option | Short | Description | Default | +| -------------- | ----- | ----------------------------------------------- | ------------- | +| `--target-org` | `-o` | Salesforce org alias or username | Required | +| `--name` | `-n` | Web application name (from webapplication.json) | Auto-discover | +| `--url` | `-u` | Explicit dev server URL | Auto-detect | +| `--port` | `-p` | Proxy server port | 4545 | +| `--open` | `-b` | Open browser automatically | false | ### Examples ```bash -# Simplest - auto-discovers webapp.json +# Simplest - auto-discovers webapplication.json sf webapp dev --target-org myOrg # With browser auto-open @@ -90,22 +90,22 @@ SF_LOG_LEVEL=debug sf webapp dev --target-org myOrg ## Webapp Discovery -The command automatically discovers `webapp.json` files in your project, making the `--name` flag optional in most cases. +The command automatically discovers `webapplication.json` files in your project, making the `--name` flag optional in most cases. ### How Discovery Works ```mermaid flowchart TD Start["sf webapp dev"] --> HasName{"--name provided?"} - HasName -->|Yes| SearchByName["Search for webapp.json with matching name field"] - HasName -->|No| SearchAll["Search all webapp.json files in project"] + HasName -->|Yes| SearchByName["Search for webapplication.json with matching name field"] + HasName -->|No| SearchAll["Search all webapplication.json files in project"] SearchByName --> FoundMatch{"Found?"} - FoundMatch -->|Yes| UseManifest["Use matched webapp.json"] + FoundMatch -->|Yes| UseManifest["Use matched webapplication.json"] FoundMatch -->|No| ErrorNotFound["Error: No webapp found with name X"] SearchAll --> Count{"How many found?"} - Count -->|0| ErrorNone["Error: No webapp.json found"] + Count -->|0| ErrorNone["Error: No webapplication.json found"] Count -->|1| UseManifest Count -->|Multiple| Prompt["Interactive selection prompt"] Prompt --> UseManifest @@ -115,12 +115,12 @@ flowchart TD ### Discovery Behavior -| Scenario | Behavior | -| -------------------------------- | --------------------------------------------------- | -| `--name myApp` provided | Finds webapp.json where `name` field equals "myApp" | -| No `--name`, single webapp found | Auto-selects the webapp | -| No `--name`, multiple found | Shows interactive selection with arrow keys | -| No `--name`, none found | Shows error with helpful message | +| Scenario | Behavior | +| -------------------------------- | ----------------------------------------------------------- | +| `--name myApp` provided | Finds webapplication.json where `name` field equals "myApp" | +| No `--name`, single webapp found | Auto-selects the webapp | +| No `--name`, multiple found | Shows interactive selection with arrow keys | +| No `--name`, none found | Shows error with helpful message | ### Search Scope @@ -135,14 +135,14 @@ The command searches the current directory and all subdirectories, excluding: ### Interactive Selection -When multiple `webapp.json` files are found, you'll see an interactive prompt: +When multiple `webapplication.json` files are found, you'll see an interactive prompt: ``` -Found 3 webapp.json files in project +Found 3 webapplication.json files in project ? Select the webapp to run: (Use arrow keys) -❯ myApp - My Application (webapp.json) - adminPortal - Admin Portal (apps/admin/webapp.json) - dashboard - Dashboard App (packages/dashboard/webapp.json) +❯ myApp - My Application (webapplication.json) + adminPortal - Admin Portal (apps/admin/webapplication.json) + dashboard - Dashboard App (packages/dashboard/webapplication.json) ``` Use arrow keys to navigate and Enter to select. @@ -194,7 +194,7 @@ Browser → Proxy → [Auth Headers Injected] → Salesforce → Response ## Configuration -### webapp.json Schema +### webapplication.json Schema #### Required Fields @@ -278,10 +278,10 @@ Use this when you want to start the dev server yourself. ### Manifest Hot Reload -Edit `webapp.json` while running - changes apply automatically: +Edit `webapplication.json` while running - changes apply automatically: ```bash -# Console output when you change webapp.json: +# Console output when you change webapplication.json: Manifest changed detected ✓ Manifest reloaded successfully Dev server URL updated to: http://localhost:5174 @@ -311,9 +311,9 @@ Automatically detects Salesforce Code Builder environment and binds to `0.0.0.0` ## Troubleshooting -### "No webapp.json found" +### "No webapplication.json found" -Ensure you have a `webapp.json` file with required fields: +Ensure you have a `webapplication.json` file with required fields: ```json { @@ -326,19 +326,19 @@ Ensure you have a `webapp.json` file with required fields: ### "No webapp found with name X" -The `--name` flag matches the `name` field inside `webapp.json`, not the file path: +The `--name` flag matches the `name` field inside `webapplication.json`, not the file path: ```bash -# This looks for webapp.json where name="myApp" +# This looks for webapplication.json where name="myApp" sf webapp dev --name myApp --target-org myOrg ``` -Check your `webapp.json` content to verify the name. +Check your `webapplication.json` content to verify the name. ### "No Dev Server Detected" 1. Ensure dev server is running: `npm run dev` -2. Verify URL in `webapp.json` is correct +2. Verify URL in `webapplication.json` is correct 3. Try explicit URL: `sf webapp dev --url http://localhost:5173 --target-org myOrg` ### "Port 4545 already in use" @@ -374,7 +374,7 @@ SF_LOG_LEVEL=debug sf webapp dev --target-org myOrg The command integrates with the Salesforce VSCode UI Preview extension (`salesforcedx-vscode-ui-preview`): -1. Extension detects `webapp.json` in workspace +1. Extension detects `webapplication.json` in workspace 2. User clicks "Preview" button on the file 3. Extension executes: `sf webapp dev --target-org --open` 4. If multiple webapps exist, uses `--name` to specify which one @@ -464,16 +464,16 @@ plugin-webapp/ ### Key Components -| Component | Purpose | -| ---------------------- | ------------------------------------------- | -| `dev.ts` | Command orchestration and lifecycle | -| `webappDiscovery.ts` | Recursive webapp.json discovery | -| `org.ts` | Salesforce authentication token management | -| `ProxyServer.ts` | HTTP proxy with WebSocket support | -| `handler.ts` | Request routing to dev server or Salesforce | -| `DevServerManager.ts` | Dev server process spawning and monitoring | -| `ManifestWatcher.ts` | webapp.json file watching for hot reload | -| `ErrorPageRenderer.ts` | Browser error page generation | +| Component | Purpose | +| ---------------------- | ------------------------------------------------ | +| `dev.ts` | Command orchestration and lifecycle | +| `webappDiscovery.ts` | Recursive webapplication.json discovery | +| `org.ts` | Salesforce authentication token management | +| `ProxyServer.ts` | HTTP proxy with WebSocket support | +| `handler.ts` | Request routing to dev server or Salesforce | +| `DevServerManager.ts` | Dev server process spawning and monitoring | +| `ManifestWatcher.ts` | webapplication.json file watching for hot reload | +| `ErrorPageRenderer.ts` | Browser error page generation | --- diff --git a/messages/webapp.dev.md b/messages/webapp.dev.md index 09d9ec9..95a3d15 100644 --- a/messages/webapp.dev.md +++ b/messages/webapp.dev.md @@ -1,86 +1,94 @@ # summary -Preview a web app locally without needing to deploy +Preview a web application locally and in real-time, without deploying it to your org. # description -Starts a local development server for a Web Application, using the local project files. This enables rapid development with hot reloading and immediate feedback. +This command starts a local development server so you can preview a web application using the local metadata files in your DX project. Using a local preview helps you quickly develop web applications, because you don't have to continually deploy metadata to your org. It also provides hot reloading; because you don't have to manually refresh, you get immediate feedback about your code changes. -The command launches a local proxy server that sits between your web application and Salesforce, automatically injecting authentication headers from the CLI's stored tokens. This allows your web app to make authenticated API calls to Salesforce without exposing credentials. +The command also launches a local proxy server that sits between your web application and Salesforce, automatically injecting authentication headers from Salesforce CLI's stored tokens. The proxy server allows your web app to make authenticated API calls to Salesforce without exposing credentials. When opening a browser to view the web application, you connect to the proxy server and not the development server. + +Even though you're previewing the web application locally and not deploying anything to an org, you're still required to authorize and specify an org to use this command. + +Salesforce web applications are represented by the WebApplication metadata type. # flags.name.summary -Identifies the Web Application (optional) +Name of the web application to preview. # flags.name.description -The unique name of the web application as defined in webapp.json. If not provided, the command will automatically discover webapp.json files in the current directory and subdirectories. If only one webapp.json is found, it will be used automatically. If multiple are found, you will be prompted to select one. +The unique name of the web application, as defined by the "name" property in the webapplication.json runtime configuration file. The webapplication.json file is located in the /webApplications/ directory of your DX project, such as force-app/main/default/webApplicatons/MyApp/webapplication.json. + +If you don't specify this flag, the command automatically discovers the webapplication.json files in the current directory and subdirectories. If the command finds only one webapplication.json, it automatically uses it. If it finds multiple files, the command prompts you to select one. # flags.url.summary -Dev server origin to forward UI/HMR/static requests +URL where your developer server runs, such as https://localhost:5173. All UI, static, and hot deployment requests are forwarded to this URL. # flags.url.description -The URL where your dev server is running (e.g., http://localhost:5173). Required if webapp.json does not contain a dev.command or dev.url configuration. All non-Salesforce API requests will be forwarded to this URL. +You must specify this flag if the web application's webapplication.json file doesn't contain a value for either the "dev.command" or "dev.url" configuration properties. All non-Salesforce API requests are forwarded to this URL. + +If you specify this flag, it overrides the value in the webapplication.json file. # flags.port.summary -Local proxy port +Local port where the proxy server listens. # flags.port.description -The port on which the proxy server will listen. Your browser should connect to this port, not directly to the dev server. The proxy will forward authenticated requests to Salesforce and other requests to your dev server. +Be sure your browser connects to this port, and not directly to the development server. The proxy then forwards authenticated requests to Salesforce and other requests to your local development server. # flags.open.summary -Auto-open proxy URL in default browser +Automatically open the proxy server URL in your default browser when the development server is ready. # flags.open.description -Automatically opens the proxy server URL in your default web browser when the server is ready. This saves you from manually copying and pasting the URL. The browser will open to the proxy URL (not the dev server URL directly), ensuring all requests are properly authenticated. +This flag saves you from manually copying and pasting the URL. The browser opens to the proxy URL, and not the development server URL directly, which ensures that all requests are property authenticated. # examples -- Start the development server (auto-discovers webapp.json): +- Start the local development server by automatically discovering the web application's webapplication.json file; use the org with alias "myorg": <%= config.bin %> <%= command.id %> --target-org myorg -- Start the development server with explicit webapp name: +- Start the development server by explicitly specifying the web application's name: <%= config.bin %> <%= command.id %> --name myWebApp --target-org myorg -- Start the development server with explicit dev server URL: +- Start at the specified development server URL: <%= config.bin %> <%= command.id %> --name myWebApp --url http://localhost:5173 --target-org myorg -- Start with custom port and auto-open browser: +- Start with a custom proxy port and automatically open the proxy server URL in your browser: <%= config.bin %> <%= command.id %> --target-org myorg --port 4546 --open -- Start with debug logging (using SF_LOG_LEVEL environment variable): +- Start with debug logging enabled by specifing the SF_LOG_LEVEL environment variable before running the command: SF_LOG_LEVEL=debug <%= config.bin %> <%= command.id %> --target-org myorg # info.manifest-changed -Manifest %s detected +Manifest %s detected. # info.manifest-reloaded -✓ Manifest reloaded successfully +✓ Manifest reloaded successfully. # info.dev-url-changed -Dev server URL updated to: %s +Development server URL updated to: %s. # info.dev-server-url -Dev server URL: %s +Development server URL: %s. # info.proxy-url -Proxy URL: %s (open this in your browser) +Proxy URL: %s (open this in your browser). # info.ready-for-development @@ -88,36 +96,36 @@ Proxy URL: %s (open this in your browser) # info.press-ctrl-c -Press Ctrl+C to stop the server +Press Ctrl+C to stop the server. # info.dev-server-healthy -✓ Dev server is responding at: %s +✓ Development server is responding at: %s. # info.dev-server-detected -✅ Dev server detected at %s +✅ Development server detected at %s. # info.start-dev-server-hint -Start your dev server to continue development +Start your development server to continue development. # warning.dev-server-not-responding -⚠ Dev server returned status %s from: %s +⚠ Development server returned status %s from: %s. # warning.dev-server-unreachable -⚠ Dev server is not responding at: %s +⚠ Development server is not responding at: %s. # warning.dev-server-unreachable-status -⚠️ Dev server unreachable at %s +⚠️ Development server unreachable at %s. # warning.dev-server-start-hint -The proxy server is running, but the dev server may not be started yet. -Make sure to start your dev server (e.g., 'npm run dev') before opening the browser. +The proxy server is running, but the development server may not have started yet. +Make sure to start your development server (such as 'npm run dev') before opening the browser. # warning.dev-command-changed @@ -125,20 +133,20 @@ dev.command changed to "%s" - restart the command to apply this change. # error.manifest-watch-failed -Failed to watch manifest: %s +Failed to watch manifest: %s. # error.dev-server-failed -Dev server failed to start: %s +Development server failed to start: %s. # info.multiple-webapps-found -Found %s webapp.json files in project +Found %s webapplication.json files in this DX project. # info.using-webapp -Using webapp: %s (%s) +Using web application: %s (%s). # prompt.select-webapp -Select the webapp to run: +Select the web application to run: diff --git a/src/commands/webapp/dev.ts b/src/commands/webapp/dev.ts index 33b43b8..d5e84a1 100644 --- a/src/commands/webapp/dev.ts +++ b/src/commands/webapp/dev.ts @@ -106,7 +106,7 @@ export default class WebappDev extends SfCommand { try { // Step 1: Discover and select webapp - this.logger.debug('Discovering webapp.json manifest(s)...'); + this.logger.debug('Discovering webapplication.json manifest(s)...'); const { webapp: discoveredWebapp, allWebapps } = await discoverWebapp(flags.name); @@ -180,7 +180,7 @@ export default class WebappDev extends SfCommand { devServerUrl = manifest.dev.url; this.logger.debug(`Using dev server URL from manifest: ${devServerUrl}`); } else if (manifest.dev?.command) { - // Start dev server from the directory containing webapp.json + // Start dev server from the directory containing webapplication.json this.logger.debug(`Starting dev server with command: ${manifest.dev.command}`); this.devServerManager = new DevServerManager({ command: manifest.dev.command, diff --git a/src/config/ManifestWatcher.ts b/src/config/ManifestWatcher.ts index beb3d15..8e385a9 100644 --- a/src/config/ManifestWatcher.ts +++ b/src/config/ManifestWatcher.ts @@ -38,8 +38,8 @@ export type ManifestChangeEvent = { */ export type ManifestWatcherOptions = { /** - * Path to the webapp.json manifest file - * Defaults to webapp.json in the current working directory + * Path to the webapplication.json manifest file + * Defaults to webapplication.json in the current working directory */ manifestPath?: string; @@ -66,10 +66,10 @@ export type ManifestWatcherEvents = { }; /** - * ManifestWatcher loads and monitors the webapp.json manifest file + * ManifestWatcher loads and monitors the webapplication.json manifest file * * Features: - * - Loads webapp.json from project root + * - Loads webapplication.json from project root * - Basic validation of required fields * - Watches for file changes and emits events * - Provides helpful error messages @@ -87,7 +87,7 @@ export class ManifestWatcher extends EventEmitter { super(); this.options = { - manifestPath: options.manifestPath ?? join(process.cwd(), 'webapp.json'), + manifestPath: options.manifestPath ?? join(process.cwd(), 'webapplication.json'), watch: options.watch ?? true, debounceMs: options.debounceMs ?? 300, }; @@ -122,10 +122,10 @@ export class ManifestWatcher extends EventEmitter { if (errors.length > 0) { throw new SfError( - `webapp.json missing required field${errors.length > 1 ? 's' : ''}: ${errors.join(', ')}`, + `webapplication.json missing required field${errors.length > 1 ? 's' : ''}: ${errors.join(', ')}`, 'ManifestValidationError', [ - 'Ensure all required fields are present in webapp.json:', + 'Ensure all required fields are present in webapplication.json:', ' - name: Unique identifier (e.g., "customerPortal")', ' - label: Display name (e.g., "Customer Portal")', ' - version: Semantic version (e.g., "1.0.0")', @@ -217,7 +217,9 @@ export class ManifestWatcher extends EventEmitter { }); this.emit( 'error', - new SfError('webapp.json was deleted', 'ManifestRemovedError', ['Recreate the webapp.json file to continue']) + new SfError('webapplication.json was deleted', 'ManifestRemovedError', [ + 'Recreate the webapplication.json file to continue', + ]) ); } else { try { @@ -248,10 +250,10 @@ export class ManifestWatcher extends EventEmitter { private loadManifest(): void { // Check if file exists if (!existsSync(this.options.manifestPath)) { - throw new SfError(`webapp.json not found at ${this.options.manifestPath}`, 'ManifestNotFoundError', [ + throw new SfError(`webapplication.json not found at ${this.options.manifestPath}`, 'ManifestNotFoundError', [ 'Make sure you are in the correct directory', - 'Create a webapp.json file in your project root', - 'Check that the file is named exactly "webapp.json"', + 'Create a webapplication.json file in your project root', + 'Check that the file is named exactly "webapplication.json"', ]); } @@ -261,7 +263,7 @@ export class ManifestWatcher extends EventEmitter { rawContent = readFileSync(this.options.manifestPath, 'utf-8'); } catch (error) { throw new SfError( - `Failed to read webapp.json: ${error instanceof Error ? error.message : String(error)}`, + `Failed to read webapplication.json: ${error instanceof Error ? error.message : String(error)}`, 'ManifestReadError', ['Check file permissions', 'Ensure the file is not locked by another process'] ); @@ -272,7 +274,7 @@ export class ManifestWatcher extends EventEmitter { try { parsed = JSON.parse(rawContent) as WebAppManifest; } catch (error) { - throw new SfError(`Invalid JSON in webapp.json: ${(error as Error).message}`, 'ManifestParseError', [ + throw new SfError(`Invalid JSON in webapplication.json: ${(error as Error).message}`, 'ManifestParseError', [ 'Check for missing commas or brackets', 'Validate JSON syntax using a JSON validator', 'Common issues: trailing commas, unquoted keys, single quotes instead of double quotes', @@ -315,7 +317,7 @@ export class ManifestWatcher extends EventEmitter { this.emit( 'error', new SfError(`File watcher error: ${error.message}`, 'ManifestWatcherError', [ - 'The webapp.json file watcher encountered an error', + 'The webapplication.json file watcher encountered an error', 'You may need to restart the command', ]) ); diff --git a/src/config/manifest.ts b/src/config/manifest.ts index 090f424..c3de9f7 100644 --- a/src/config/manifest.ts +++ b/src/config/manifest.ts @@ -40,7 +40,7 @@ export type DevConfig = { }; /** - * WebApp manifest configuration - defines the structure of webapp.json file + * WebApp manifest configuration - defines the structure of webapplication.json file * Extended from @salesforce/webapp-experimental with plugin-specific fields */ export type WebAppManifest = BaseWebAppManifest & { @@ -76,16 +76,16 @@ function validateManifest(manifest: WebAppManifest): void { if (errors.length > 0) { throw new SfError( - `webapp.json missing required field${errors.length > 1 ? 's' : ''}: ${errors.join(', ')}`, + `webapplication.json missing required field${errors.length > 1 ? 's' : ''}: ${errors.join(', ')}`, 'ManifestValidationError' ); } } /** - * Load and parse webapp.json manifest + * Load and parse webapplication.json manifest * - * @param manifestPath - Path to the webapp.json file + * @param manifestPath - Path to the webapplication.json file * @returns Promise resolving to the parsed manifest * @throws SfError if manifest file not found or validation fails */ @@ -103,15 +103,15 @@ export async function loadManifest(manifestPath: string): Promise { try { @@ -81,7 +81,7 @@ async function tryParseWebappManifest(filePath: string): Promise e.isFile() && e.name === 'webapp.json'); + const webappJsonFiles = entries.filter((e) => e.isFile() && e.name === 'webapplication.json'); const subdirectories = entries.filter((e) => e.isDirectory() && !shouldExcludeDirectory(e.name)); - // Process webapp.json files in parallel + // Process webapplication.json files in parallel const manifestPromises = webappJsonFiles.map(async (entry) => { const fullPath = join(dir, entry.name); const manifest = await tryParseWebappManifest(fullPath); if (manifest) { return { path: fullPath, - relativePath: relative(cwd, fullPath) || 'webapp.json', + relativePath: relative(cwd, fullPath) || 'webapplication.json', manifest, }; } @@ -137,7 +137,7 @@ async function searchDirectory(dir: string, cwd: string, depth: number = 0): Pro } /** - * Find all webapp.json files in a directory and its subdirectories + * Find all webapplication.json files in a directory and its subdirectories * * @param cwd - Directory to search from (defaults to process.cwd()) * @returns Array of discovered webapps sorted by path @@ -178,8 +178,8 @@ export async function discoverWebapp( // No webapps found if (allWebapps.length === 0) { throw new SfError( - 'No webapp.json found in the current directory or subdirectories.\n' + - 'Create a webapp.json file in your project root to get started.', + 'No webapplication.json found in the current directory or subdirectories.\n' + + 'Create a webapplication.json file in your project root to get started.', 'WebappNotFoundError' ); } diff --git a/src/error/ErrorHandler.ts b/src/error/ErrorHandler.ts index 6d63b6f..3da078d 100644 --- a/src/error/ErrorHandler.ts +++ b/src/error/ErrorHandler.ts @@ -121,20 +121,20 @@ export class ErrorHandler { } /** - * Create an error for missing webapp.json manifest + * Create an error for missing webapplication.json manifest * * @returns SfError with user-friendly message and suggestions */ public static createManifestNotFoundError(): SfError { - return new SfError('webapp.json not found in the current directory.', WebAppErrorCode.MANIFEST_NOT_FOUND, [ - 'Create a webapp.json file in your project root', + return new SfError('webapplication.json not found in the current directory.', WebAppErrorCode.MANIFEST_NOT_FOUND, [ + 'Create a webapplication.json file in your project root', 'Make sure you are in the correct project directory', - 'The webapp.json file should be in the project root', + 'The webapplication.json file should be in the project root', ]); } /** - * Create an error for invalid webapp.json manifest + * Create an error for invalid webapplication.json manifest * * @param validationErrors - Array of validation error messages * @returns SfError with user-friendly message and suggestions @@ -143,20 +143,20 @@ export class ErrorHandler { const errorList = validationErrors.map((err) => ` • ${err}`).join('\n'); return new SfError(`Web application manifest validation failed:\n${errorList}`, WebAppErrorCode.MANIFEST_INVALID, [ - 'Check the webapp.json file for syntax errors', + 'Check the webapplication.json file for syntax errors', 'Ensure all required fields are present: name, label, version, outputDir', 'Refer to the schema documentation for valid field formats', ]); } /** - * Create an error for JSON parse errors in webapp.json + * Create an error for JSON parse errors in webapplication.json * * @param parseError - The original parse error message * @returns SfError with user-friendly message and suggestions */ public static createManifestParseError(parseError: string): SfError { - return new SfError(`Failed to parse webapp.json: ${parseError}`, WebAppErrorCode.MANIFEST_PARSE_ERROR, [ + return new SfError(`Failed to parse webapplication.json: ${parseError}`, WebAppErrorCode.MANIFEST_PARSE_ERROR, [ 'Check for JSON syntax errors (missing commas, brackets, quotes)', 'Validate your JSON with a JSON validator tool', 'Make sure the file is saved with UTF-8 encoding', @@ -176,7 +176,7 @@ export class ErrorHandler { : `Dev server failed to start with command: ${command}`; return new SfError(message, WebAppErrorCode.DEV_SERVER_START_FAILED, [ - 'Check the dev.command in your webapp.json is correct', + 'Check the dev.command in your webapplication.json is correct', 'Make sure all dependencies are installed (run: npm install or yarn install)', 'Verify the command works when run manually in the terminal', 'Check the dev server logs for more details', @@ -195,7 +195,7 @@ export class ErrorHandler { WebAppErrorCode.DEV_SERVER_TIMEOUT, [ 'The dev server may be taking longer than expected to start', - 'Check if the dev server command is correct in webapp.json', + 'Check if the dev server command is correct in webapplication.json', 'Try running the dev server command manually to see if it starts', 'Increase the startup timeout if your dev server is slow to start', ] @@ -226,7 +226,7 @@ export class ErrorHandler { */ public static createDevServerCommandRequiredError(): SfError { return new SfError('Dev server command or URL is required.', WebAppErrorCode.DEV_SERVER_COMMAND_REQUIRED, [ - 'Add a "dev.command" field to your webapp.json (e.g., "npm run dev")', + 'Add a "dev.command" field to your webapplication.json (e.g., "npm run dev")', 'Or provide a --url flag to specify the dev server URL', 'Example: sf webapp dev --url http://localhost:5173', ]); diff --git a/src/server/DevServerManager.ts b/src/server/DevServerManager.ts index 506debd..d62c1dc 100644 --- a/src/server/DevServerManager.ts +++ b/src/server/DevServerManager.ts @@ -474,7 +474,7 @@ export class DevServerManager extends EventEmitter { this.logger.error(`Dev server process error: ${error.message}`); const sfError = new SfError(`Dev server process error: ${error.message}`, 'DevServerProcessError', [ - 'Check that the command is correct in webapp.json', + 'Check that the command is correct in webapplication.json', 'Verify all dependencies are installed', 'Try running the command manually to see the error', ]); diff --git a/src/templates/error-page.html b/src/templates/error-page.html index f358003..17d0699 100644 --- a/src/templates/error-page.html +++ b/src/templates/error-page.html @@ -1,755 +1,749 @@ + + + + {{PAGE_TITLE}} - Salesforce Local Dev Proxy + {{META_REFRESH}} + - - - -
- -
-
-

Local Dev Proxy

-

Salesforce preview → Proxy → Your dev server

-
-
{{ERROR_STATUS}}
-
+ .metadata-card { + background: #f9f9f9; + padding: 15px; + border-radius: 6px; + border-left: 3px solid #2196f3; + } - -
- -
- -
-
-

{{ERROR_TITLE}}

- {{MESSAGE_CONTENT}} -
+ .metadata-card .label { + font-weight: 600; + color: #1a1a1a; + font-size: 0.85em; + margin-bottom: 6px; + } -
- {{AUTO_REFRESH_TEXT}} -
+ .metadata-card .value { + color: #666; + font-family: monospace; + font-size: 0.9em; + } -
-

What to do next

-
    -
  • Start your dev server using: npm run dev or yarn dev
    • -
  • Verify your dev server is running on the correct port
    • -
  • Check webapp.json for the correct dev server URL
    • -
  • This page will auto-refresh when the server is detected
    • -
-
+ /* ============================================ + SCROLLBARS + ============================================ */ + .code-output::-webkit-scrollbar, + .stack-trace-container::-webkit-scrollbar, + .live-logs::-webkit-scrollbar { + width: 8px; + } + + .code-output::-webkit-scrollbar-track, + .stack-trace-container::-webkit-scrollbar-track, + .live-logs::-webkit-scrollbar-track { + background: #1a1f2e; + border-radius: 4px; + } + + .code-output::-webkit-scrollbar-thumb, + .stack-trace-container::-webkit-scrollbar-thumb, + .live-logs::-webkit-scrollbar-thumb { + background: #4a5568; + border-radius: 4px; + } + + /* ============================================ + RESPONSIVE DESIGN + ============================================ */ + @media (max-width: 900px) { + .content-wrapper { + grid-template-columns: 1fr; + } + + .main-content { + border-right: none; + border-bottom: 1px solid #ccc; + } + + .diagnostics-panel { + padding: 30px 20px; + } + + .metadata-grid { + grid-template-columns: 1fr; + } + } + + @media (max-width: 768px) { + .top-header { + flex-direction: column; + gap: 15px; + padding: 20px; + } + + .main-content { + padding: 25px; + } + } + + + + +
+ +
+
+

Local Dev Proxy

+

Salesforce preview → Proxy → Your dev server

+
{{ERROR_STATUS}}
+
- -
-
-

⚠️ Runtime Error: {{ERROR_TYPE}}

-
-

{{ERROR_MESSAGE_TEXT}}

+ +
+ +
+ +
+
+

{{ERROR_TITLE}}

+ {{MESSAGE_CONTENT}}
-
-
-

Stack Trace

-
- {{FORMATTED_STACK_HTML}} +
{{AUTO_REFRESH_TEXT}}
+ +
+

What to do next

+
    +
  • Start your dev server using: npm run dev or yarn dev
    • +
  • Verify your dev server is running on the correct port
    • +
  • Check webapplication.json for the correct dev server URL
    • +
  • This page will auto-refresh when the server is detected
    • +
-
-
-
Error Type
-
{{ERROR_TYPE}}{{ERROR_CODE_BADGE}}
+ +
+
+

⚠️ Runtime Error: {{ERROR_TYPE}}

+
+

{{ERROR_MESSAGE_TEXT}}

+
-
-
Severity
-
{{SEVERITY_LABEL}}
-
-
-
Timestamp
-
{{TIMESTAMP_FORMATTED}}
+ +
+

Stack Trace

+
{{FORMATTED_STACK_HTML}}
-
-
Process ID
-
{{PID}}
+ +
+
+
Error Type
+
{{ERROR_TYPE}}{{ERROR_CODE_BADGE}}
+
+
+
Severity
+
{{SEVERITY_LABEL}}
+
+
+
Timestamp
+
{{TIMESTAMP_FORMATTED}}
+
+
+
Process ID
+
{{PID}}
+
-
-
-

{{SUGGESTIONS_TITLE}}

-
    - {{SUGGESTIONS_LIST}} -
+
+

{{SUGGESTIONS_TITLE}}

+
    + {{SUGGESTIONS_LIST}} +
+
-
- -
-
-

⚠️ {{ERROR_TITLE}}

-
-

{{ERROR_MESSAGE_TEXT}}

+ +
+
+

⚠️ {{ERROR_TITLE}}

+
+

{{ERROR_MESSAGE_TEXT}}

+
-
-
-

Error Output

-
- 
{{STDERR_OUTPUT}}
+
+

Error Output

+
+ 
{{STDERR_OUTPUT}}
+
-
-
- {{AUTO_REFRESH_TEXT}} -
+
{{AUTO_REFRESH_TEXT}}
-
-

{{SUGGESTIONS_TITLE}}

-
    - {{SUGGESTIONS_LIST}} -
+
+

{{SUGGESTIONS_TITLE}}

+
    + {{SUGGESTIONS_LIST}} +
+
-
- -
-

Diagnostics

- -
    -
  • - Dev Server URL: - {{DEV_SERVER_URL}} -
    • -
  • - Proxy URL: - {{PROXY_URL}} -
    • -
  • - Workspace Script: - {{WORKSPACE_SCRIPT}} -
    • -
  • - Target Org: - {{ORG_TARGET}} -
    • -
  • - Last Check: - {{LAST_CHECK_TIME}} -
    • - -
  • - Node Version: - {{NODE_VERSION}} -
    • -
  • - Platform: - {{PLATFORM}} -
    • -
  • - Memory Usage: - {{HEAP_USED_MB}} MB / {{HEAP_TOTAL_MB}} MB heap -
    • -
  • - Process ID: - {{PID}} -
    • -
- -
-
- [{{LAST_CHECK_TIME}}] - proxy ▶ waiting for backend... -
-
- [{{LAST_CHECK_TIME}}] - check {{DEV_SERVER_URL}} ▶ unreachable -
-
- [{{LAST_CHECK_TIME}}] - hint ▶ try "{{WORKSPACE_SCRIPT}}" + +
+

Diagnostics

+ +
    +
  • + Dev Server URL: + {{DEV_SERVER_URL}} +
    • +
  • + Proxy URL: + {{PROXY_URL}} +
    • +
  • + Workspace Script: + {{WORKSPACE_SCRIPT}} +
    • +
  • + Target Org: + {{ORG_TARGET}} +
    • +
  • + Last Check: + {{LAST_CHECK_TIME}} +
    • + +
  • + Node Version: + {{NODE_VERSION}} +
    • +
  • + Platform: + {{PLATFORM}} +
    • +
  • + Memory Usage: + {{HEAP_USED_MB}} MB / {{HEAP_TOTAL_MB}} MB heap +
    • +
  • + Process ID: + {{PID}} +
    • +
+ +
+
+ [{{LAST_CHECK_TIME}}] + proxy ▶ waiting for backend... +
+
+ [{{LAST_CHECK_TIME}}] + check {{DEV_SERVER_URL}} ▶ unreachable +
+
+ [{{LAST_CHECK_TIME}}] + hint ▶ try "{{WORKSPACE_SCRIPT}}" +
-
-
-
- [{{TIMESTAMP_FORMATTED}}] - error ▶ {{ERROR_TYPE}} detected -
-
- severity ▶ {{SEVERITY_LABEL}} +
+
+ [{{TIMESTAMP_FORMATTED}}] + error ▶ {{ERROR_TYPE}} detected +
+
+ severity ▶ {{SEVERITY_LABEL}} +
-
- -
-

⚠️ If Ctrl+C doesn't work

-

Copy and run this command in a new terminal to force-stop the proxy:

- -
-
Kill all processes on port {{PROXY_PORT}}:
-
-
lsof -ti:{{PROXY_PORT}} | xargs kill -9
- + +
+

⚠️ If Ctrl+C doesn't work

+

Copy and run this command in a new terminal to force-stop the proxy:

+ +
+
Kill all processes on port {{PROXY_PORT}}:
+
+
lsof -ti:{{PROXY_PORT}} | xargs kill -9
+ +
-
- - - -
-

- Salesforce Web App Development Proxy  •  Press Ctrl+C in the terminal to stop the - proxy -

+ + + +
+

+ Salesforce Web App Development Proxy  •  Press Ctrl+C in the terminal to stop the + proxy +

+
-
- - - \ No newline at end of file + + diff --git a/test/commands/webapp/dev.nut.ts b/test/commands/webapp/dev.nut.ts index 52eaa55..9f8913f 100644 --- a/test/commands/webapp/dev.nut.ts +++ b/test/commands/webapp/dev.nut.ts @@ -37,16 +37,16 @@ describe('webapp dev NUTs', () => { after(async () => { await session?.clean(); - // Clean up any test webapp.json files - const webappJsonPath = join(session?.dir ?? process.cwd(), 'webapp.json'); + // Clean up any test webapplication.json files + const webappJsonPath = join(session?.dir ?? process.cwd(), 'webapplication.json'); if (existsSync(webappJsonPath)) { unlinkSync(webappJsonPath); } }); it('should fail without target-org flag', () => { - // Create webapp.json for this test - const webappJsonPath = join(session.dir, 'webapp.json'); + // Create webapplication.json for this test + const webappJsonPath = join(session.dir, 'webapplication.json'); writeFileSync(webappJsonPath, JSON.stringify(testWebappJson, null, 2)); const result = execCmd('webapp dev --name testWebApp --json', { @@ -66,8 +66,8 @@ describe('webapp dev NUTs', () => { // These scenarios are covered by unit tests instead. // // Scenarios covered in unit tests: - // - Missing webapp.json manifest (ManifestWatcher.test.ts) - // - Invalid webapp.json schema (ManifestWatcher.test.ts) + // - Missing webapplication.json manifest (ManifestWatcher.test.ts) + // - Invalid webapplication.json schema (ManifestWatcher.test.ts) // - Malformed JSON syntax (ManifestWatcher.test.ts) // - Missing dev server config (DevServerManager.test.ts) // diff --git a/test/commands/webapp/dev.test.ts b/test/commands/webapp/dev.test.ts index 32b47f2..f776e03 100644 --- a/test/commands/webapp/dev.test.ts +++ b/test/commands/webapp/dev.test.ts @@ -97,7 +97,7 @@ describe('webapp:dev command integration', () => { const error = ErrorHandler.createManifestNotFoundError(); expect(error).to.be.instanceOf(SfError); expect(error.name).to.equal('ManifestNotFoundError'); - expect(error.message).to.include('webapp.json not found'); + expect(error.message).to.include('webapplication.json not found'); }); it('should create proper dev server command required error', () => { diff --git a/test/config/ManifestWatcher.test.ts b/test/config/ManifestWatcher.test.ts index 8ac3604..ffb3615 100644 --- a/test/config/ManifestWatcher.test.ts +++ b/test/config/ManifestWatcher.test.ts @@ -25,7 +25,7 @@ import type { WebAppManifest, ManifestChangeEvent } from '../../src/config/types describe('ManifestWatcher', () => { const $$ = new TestContext(); const testDir = join(process.cwd(), '.test-manifests'); - const testManifestPath = join(testDir, 'webapp.json'); + const testManifestPath = join(testDir, 'webapplication.json'); const validManifest: WebAppManifest = { name: 'testApp', @@ -92,7 +92,7 @@ describe('ManifestWatcher', () => { } catch (error) { expect(error).to.be.instanceOf(SfError); expect((error as SfError).name).to.equal('ManifestNotFoundError'); - expect((error as SfError).message).to.include('webapp.json not found'); + expect((error as SfError).message).to.include('webapplication.json not found'); expect((error as SfError).actions).to.exist; } @@ -127,7 +127,7 @@ describe('ManifestWatcher', () => { it('should handle read permission errors', async () => { // Create a file path that doesn't exist to simulate read error - const invalidPath = join(testDir, 'nonexistent', 'webapp.json'); + const invalidPath = join(testDir, 'nonexistent', 'webapplication.json'); const watcher = new ManifestWatcher({ manifestPath: invalidPath, watch: false }); @@ -459,8 +459,8 @@ describe('ManifestWatcher', () => { }); describe('Default Options', () => { - it('should use webapp.json in current directory by default', async () => { - const defaultPath = join(process.cwd(), 'webapp.json'); + it('should use webapplication.json in current directory by default', async () => { + const defaultPath = join(process.cwd(), 'webapplication.json'); // Create manifest in current directory writeFileSync(defaultPath, JSON.stringify(validManifest, null, 2)); diff --git a/test/error/ErrorHandler.test.ts b/test/error/ErrorHandler.test.ts index 545c4d3..cfa4716 100644 --- a/test/error/ErrorHandler.test.ts +++ b/test/error/ErrorHandler.test.ts @@ -76,9 +76,9 @@ describe('ErrorHandler', () => { expect(error).to.be.instanceOf(SfError); expect(error.name).to.equal(WebAppErrorCode.MANIFEST_NOT_FOUND); - expect(error.message).to.include('webapp.json'); + expect(error.message).to.include('webapplication.json'); expect(error.message).to.include('not found'); - expect(error.actions?.[0]).to.include('Create a webapp.json'); + expect(error.actions?.[0]).to.include('Create a webapplication.json'); }); it('should create manifest validation error with multiple issues', () => { diff --git a/test/fixtures/sample-webapp.json b/test/fixtures/sample-webapplication.json similarity index 100% rename from test/fixtures/sample-webapp.json rename to test/fixtures/sample-webapplication.json