fix(webapp): refactor dev server URL detection @W-21331028@

.github/workflows/validate-pr.yml

@@ -2,8 +2,7 @@ name: pr-validation
 
 on:
   pull_request:
-    types: [opened, reopened, edited]
-    # only applies to PRs that want to merge to main
+    types: [opened, reopened, edited, synchronize]
     branches: [main]
 
 jobs:

README.md

@@ -129,6 +129,11 @@ sf plugins
 
 Start a local development proxy server for webapp development with Salesforce authentication.
 
+**Two operating modes:**
+
+- **Command mode** (default): When `dev.command` is set in `webapplication.json` (or default `npm run dev`), the CLI starts the dev server. URL defaults to `http://localhost:5173`; override with `dev.url` or `--url` if needed.
+- **URL-only mode**: When only `dev.url` or `--url` is provided (no command), the CLI assumes the dev server is already running and does not start it. Proxy only.
+
 ```bash
 USAGE
   $ sf webapp dev --name <webapp-name> --target-org <org-alias> [options]
@@ -138,50 +143,29 @@ REQUIRED FLAGS
   -o, --target-org=<value>   Salesforce org to authenticate against
 
 OPTIONAL FLAGS
-  -u, --url=<value>          Dev server URL (overrides webapplication.json)
+  -u, --url=<value>          Dev server URL. Command mode: override default 5173. URL-only: required (server must be running)
   -p, --port=<value>         Proxy server port (default: 4545)
   --open                     Open browser automatically
 
-GLOBAL FLAGS
-  --flags-dir=<value>        Import flag values from a directory
-  --json                     Format output as json
-
 DESCRIPTION
-  Start a local development proxy server for webapp development.
-
-  This command starts a local HTTP proxy server that handles Salesforce
-  authentication and routes requests between your local dev server and
-  Salesforce APIs. It automatically spawns and monitors your dev server,
-  detects the URL, and provides health monitoring.
+  Starts a local HTTP proxy that injects Salesforce authentication and routes
+  requests between your dev server and Salesforce APIs. In command mode,
+  spawns and monitors the dev server (default URL: localhost:5173). In
+  URL-only mode, connects to an already-running dev server.
 
 EXAMPLES
-  Start proxy with automatic dev server management:
+  Command mode (CLI starts dev server, default port 5173):
 
     $ sf webapp dev --name myapp --target-org myorg --open
 
-  Use existing dev server:
+  URL-only mode (dev server already running):
 
     $ sf webapp dev --name myapp --target-org myorg --url http://localhost:5173 --open
 
-  Use custom proxy port:
+  Custom proxy port:
 
     $ sf webapp dev --name myapp --target-org myorg --port 8080 --open
 
-SUPPORTED DEV SERVERS
-  - Vite
-  - Create React App (Webpack)
-  - Next.js
-  - Any server that outputs http://localhost:PORT
-
-FEATURES
-  - Automatic Salesforce authentication injection
-  - Intelligent request routing (Salesforce vs dev server)
-  - WebSocket support for Hot Module Replacement (HMR)
-  - Beautiful HTML error pages with auto-refresh
-  - Periodic health monitoring (every 5s)
-  - Configuration file watching (webapplication.json)
-  - Graceful shutdown on Ctrl+C
-
 SEE ALSO
   - Complete Guide: SF_WEBAPP_DEV_GUIDE.md
 ```

SF_WEBAPP_DEV_GUIDE.md

@@ -234,38 +234,43 @@ Browser → Proxy → [Auth Headers Injected] → Salesforce → Response
 
 ## Configuration
 
-### webapplication.json Schema
+### Dev Server URL Resolution
 
-The `webapplication.json` file is **optional**. All fields are also optional - missing fields use defaults.
+The command operates in two distinct modes based on configuration:
 
-#### Dev Configuration
+| Mode | Configuration | Behavior |
+|------|---------------|----------|
+| **Command mode** | `dev.command` is set (or default `npm run dev`) | CLI starts the dev server. URL defaults to `http://localhost:5173`. Override with `dev.url` or `--url` if your dev server uses a different port. |
+| **URL-only mode** | `dev.url` or `--url` only (no `dev.command`) | CLI assumes the dev server is already running. Does **not** start the dev server. Starts proxy only and forwards to the given URL. |
 
-| Field         | Type   | Description                           | Default                   |
-| ------------- | ------ | ------------------------------------- | ------------------------- |
-| `dev.command` | string | Command to start dev server           | `npm run dev`             |
-| `dev.url`     | string | Dev server URL (when already running)  | `http://localhost:5173`   |
+**URL precedence:** `--url` flag > `dev.url` in manifest > default `http://localhost:5173` (when command is used)
 
-All fields are optional. Only specify what you need to override.
+### webapplication.json Schema
 
-**Option A: No manifest (uses defaults)**
+The `webapplication.json` file is **optional**. All fields are also optional - missing fields use defaults.
 
-If no `webapplication.json` exists:
+#### Dev Configuration
 
-- Dev command: `npm run dev`
-- Name: folder name
-- Manifest watching: disabled
+| Field         | Type   | Description | Default |
+| ------------- | ------ | ----------- | ------- |
+| `dev.command` | string | Command to start the dev server (e.g., `npm run dev`). When set, the CLI starts the dev server and uses default URL `http://localhost:5173` unless overridden. | `npm run dev` |
+| `dev.url`     | string | Dev server URL. **Command mode**: Override the default 5173 port if needed. **URL-only mode**: Required—the CLI assumes the server is already running and does not start it. | `http://localhost:5173` |
 
-**Option B: Minimal manifest**
+**Command mode (CLI starts dev server):**
 
 ```json
 {
   "dev": {
-    "command": "npm start"
+    "command": "npm run dev"
   }
 }
 ```
 
-**Option C: Explicit URL (dev server already running)**
+- CLI runs `npm run dev` and waits for the server to be ready
+- Default URL: `http://localhost:5173`
+- Override port: add `"url": "http://localhost:3000"` if your dev server uses a different port
+
+**URL-only mode (proxy only, server already running):**
 
 ```json
 {
@@ -275,7 +280,15 @@ If no `webapplication.json` exists:
 }
 ```
 
-Use this when you want to start the dev server yourself.
+- No `dev.command` — CLI does **not** start the dev server
+- You must start the dev server yourself (e.g., `npm run dev` in another terminal)
+- CLI starts only the proxy and forwards to the given URL
+
+**No manifest (uses defaults):**
+
+- Dev command: `npm run dev`
+- Default URL: `http://localhost:5173`
+- Manifest watching: disabled
 
 #### Routing Configuration (Optional)
 
@@ -375,19 +388,19 @@ Automatically detects Salesforce Code Builder environment and binds to `0.0.0.0`
 
 ## The `--url` Flag
 
-The `--url` flag provides control over which dev server URL the proxy uses. It has smart behavior depending on whether the URL is already available.
+The `--url` flag overrides the dev server URL. Behavior depends on whether you have a command configured:
 
-### Behavior
+| Scenario | Command in manifest? | `--url` behavior |
+|----------|----------------------|------------------|
+| URL-only mode | No | Required. CLI assumes the server is already running and does not start it. Use when you run the dev server yourself. |
+| Command mode | Yes | Optional override. Default is `http://localhost:5173`. Use `--url` to point to a different port. |
+| URL reachable | Either | Proxy-only: skips starting dev server, starts proxy only |
+| URL not reachable | Yes (command) | Starts dev server and warns if actual URL differs from `--url` |
+| URL not reachable | No (URL-only) | Error: server must be running at the given URL |
 
-| Scenario                 | What Happens                                                      |
-| ------------------------ | ----------------------------------------------------------------- |
-| `--url` is reachable     | **Proxy-only mode**: Skips starting dev server, only starts proxy |
-| `--url` is NOT reachable | Starts dev server, warns if actual URL differs from `--url`       |
-| No `--url` provided      | Starts dev server automatically, detects URL                      |
+### Connect to Existing Dev Server (Proxy-Only Mode)
 
-### Use Case 1: Connect to Existing Dev Server (Proxy-Only Mode)
-
-If you prefer to manage your dev server separately:
+When you run the dev server yourself:
 
 ```bash
 # Terminal 1: Start your dev server manually
@@ -404,36 +417,18 @@ sf webapp dev --url http://localhost:5173 --target-org myOrg
 ```
 ✅ URL http://localhost:5173 is already available, skipping dev server startup (proxy-only mode)
 ✅ Ready for development!
-   → Proxy: http://localhost:4545
-   → Dev server: http://localhost:5173
+   → http://localhost:4545 (open this URL in your browser)
 ```
 
-### Use Case 2: URL Mismatch Warning
+### Override Default Port (Command Mode)
 
-If you specify a `--url` that doesn't match where the dev server actually starts:
+When using `dev.command`, the default URL is `http://localhost:5173`. Override with `--url` if your dev server uses a different port:
 
 ```bash
-# No dev server running, specify wrong port
-sf webapp dev --url http://localhost:9999 --target-org myOrg
+sf webapp dev --url http://localhost:3000 --target-org myOrg
 ```
 
-**Output:**
-
-```
-Warning: ⚠️ The --url flag (http://localhost:9999) does not match the actual dev server URL (http://localhost:5173/).
-The proxy will use the actual dev server URL.
-```
-
-The command continues working with the actual dev server URL.
-
-### Important Notes
-
-- The `--url` flag checks **only** the URL you specify, not other ports
-- If you have a dev server on port 5173 but specify `--url http://localhost:9999`:
-  - Command checks 9999 → not available
-  - Starts a NEW dev server → may get port 5174 (if 5173 is taken)
-  - Warns about mismatch (9999 ≠ 5174)
-- To use an existing dev server, specify its **exact** URL with `--url`
+If the URL is not reachable, the CLI starts the dev server and uses the actual URL (with a warning if it differs).
 
 ---
 

messages/webapp.dev.md

@@ -96,12 +96,44 @@ Proxy URL: %s (open this URL in your browser)
 
 # info.press-ctrl-c
 
-Press Ctrl+C to stop the proxy server
+Press Ctrl+C to stop.
+
+# info.press-ctrl-c-target
+
+Press Ctrl+C to stop the %s.
+
+# info.stopped-target
+
+✅ Stopped %s.
+
+# info.stop-target-dev
+
+dev server
+
+# info.stop-target-proxy
+
+proxy server
+
+# info.stop-target-both
+
+dev and proxy servers
 
 # info.server-running
 
 Dev server is running. Stop it by running "SFDX: Close Live Preview" from the VS Code command palette.
 
+# info.server-running-target-dev
+
+Dev server is running. Stop it by running "SFDX: Close Live Preview" from the VS Code command palette.
+
+# info.server-running-target-proxy
+
+Proxy server is running. Stop it by running "SFDX: Close Live Preview" from the VS Code command palette.
+
+# info.server-running-target-both
+
+Dev and proxy servers are running. Stop them by running "SFDX: Close Live Preview" from the VS Code command palette.
+
 # info.dev-server-healthy
 
 ✓ Dev server is responding at: %s
@@ -139,6 +171,15 @@ dev.command changed to "%s" - restart the command to apply this change.
 
 Failed to watch manifest: %s
 
+# error.dev-url-unreachable
+
+Dev server unreachable at %s.
+Start your dev server manually at that URL, or add dev.command to webapplication.json to start it automatically.
+
+# error.port-in-use
+
+Port %s is already in use. Try specifying a different port with the --port flag or stopping the service that's using the port.
+
 # error.dev-server-failed
 
 %s
@@ -192,14 +233,3 @@ The proxy will use the actual dev server URL.
 
 Vite WebApp proxy detected at %s - using Vite's built-in proxy (standalone proxy skipped)
 
-# info.stopped-proxy-only
-
-✅ Stopped proxy server.
-
-# info.stopped-dev-only
-
-✅ Stopped dev server.
-
-# info.stopped-dev-and-proxy
-
-✅ Stopped dev & proxy servers.