W-20274055 sf-webapp-dev-command Foundation, messages & type definitions

This commit establishes the foundational files for the sf webapp dev command:

- Created TypeScript type definitions (src/config/types.ts) defining 10 interfaces
  for webapp.json manifest, proxy configuration, authentication, routing, and
  status tracking. All interfaces include comprehensive JSDoc documentation.

- Created JSON Schema (schemas/webapp-config.json) for webapp.json validation
  with regex patterns for name, version, and apiVersion fields, plus URL
  validation for dev server configuration.

- Created messages file (messages/webapp.dev.md) with 50+ user-facing messages
  including command descriptions, flag documentation, info messages, error
  messages with actionable suggestions, warnings, and debug messages.

- Updated package.json to add required dependencies:
  * chokidar (^3.6.0) for file watching
  * http-proxy (^1.18.1) for proxy server functionality
  * @types/http-proxy (^1.17.14) for TypeScript type definitions
  * Added webapp topic to oclif configuration

- Created unit tests (test/config/types.test.ts) for TypeScript types

- Created sample webapp.json fixture (test/fixtures/sample-webapp.json) for testing

These foundational files establish the contracts and interfaces that all
subsequent components (AuthManager, RequestRouter, ProxyServer, etc.) will
use, enabling parallel development of remaining tasks.

Author: deepu-mungamuri94

messages/webapp.dev.md

@@ -0,0 +1,233 @@
+# summary
+
+Preview a web app locally without needing to deploy
+
+# 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.
+
+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.
+
+# flags.name.summary
+
+Identifies the Web Application
+
+# flags.name.description
+
+The unique name of the web application as defined in webapp.json. This is used to load the appropriate configuration and settings.
+
+# flags.url.summary
+
+Dev server origin to forward UI/HMR/static requests
+
+# 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.
+
+# flags.port.summary
+
+Local proxy port
+
+# 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.
+
+# flags.target-org.summary
+
+Org to use for auth
+
+# flags.target-org.description
+
+The Salesforce org alias or username to use for authentication. The proxy will use this org's credentials to authenticate API requests to Salesforce.
+
+# flags.debug.summary
+
+Enable verbose proxy logging
+
+# flags.debug.description
+
+When enabled, the proxy will log detailed information about each request including headers, routing decisions, and response status. Useful for debugging authentication or routing issues. Note: Access tokens are never logged even in debug mode.
+
+# flags.open.summary
+
+Auto-open proxy URL in default browser
+
+# flags.open.description
+
+When enabled, automatically opens the proxy URL in your default browser after the proxy server starts.
+
+# examples
+
+- Start the development server with explicit dev server URL:
+
+  <%= config.bin %> <%= command.id %> --name myWebApp --url http://localhost:5173 --target-org myorg
+
+- Start the development server using webapp.json configuration:
+
+  <%= config.bin %> <%= command.id %> --name myWebApp --target-org myorg
+
+- Start with custom port and auto-open browser:
+
+  <%= config.bin %> <%= command.id %> --name myWebApp --target-org myorg --port 4546 --open
+
+- Start with debug logging:
+
+  <%= config.bin %> <%= command.id %> --name myWebApp --target-org myorg --debug
+
+# info.starting
+
+Starting development server for web app: %s
+
+# info.using-target-org
+
+Using target org: %s
+
+# info.proxy-running
+
+Proxy server running on %s
+
+# info.dev-server-url
+
+Dev server URL: %s
+
+# info.opening-browser
+
+Opening browser...
+
+# info.ready
+
+Web app development server is ready!
+
+# info.press-ctrl-c
+
+Press Ctrl+C to stop the server
+
+# info.starting-dev-server
+
+Starting dev server with command: %s
+
+# info.dev-server-started
+
+Dev server started at: %s
+
+# info.watching-manifest
+
+Watching webapp.json for changes...
+
+# info.manifest-reloaded
+
+Manifest reloaded successfully
+
+# error.manifest-not-found
+
+webapp.json not found in the current directory. Run 'sf webapp generate' to create a new web app.
+
+# error.manifest-invalid
+
+Invalid webapp.json: %s
+
+# error.manifest-validation-failed
+
+Manifest validation failed:
+%s
+
+# error.org-not-found
+
+Org '%s' not found. Check available orgs with 'sf org list'.
+
+# error.org-auth-failed
+
+Failed to authenticate with org '%s'. Run 'sf org login web --alias %s' to re-authenticate.
+
+# error.token-expired
+
+Your org authentication has expired. Run 'sf org login web --alias %s' to re-authenticate.
+
+# error.token-refresh-failed
+
+Failed to refresh access token. Run 'sf org login web --alias %s' to re-authenticate.
+
+# error.dev-server-failed
+
+Dev server failed to start: %s
+
+# error.dev-server-command-required
+
+No dev server URL provided and webapp.json does not contain dev.command or dev.url. Please provide --url flag or configure dev settings in webapp.json.
+
+# error.dev-server-timeout
+
+Dev server did not start within 30 seconds. Check the command in webapp.json and ensure your dev server outputs its URL to stdout.
+
+# error.port-in-use
+
+Port %s is already in use. Try a different port with --port flag.
+
+# error.proxy-start-failed
+
+Failed to start proxy server: %s
+
+# error.network-error
+
+Network error: %s. Check your internet connection.
+
+# error.request-failed
+
+Request to %s failed: %s
+
+# error.invalid-url
+
+Invalid URL: %s
+
+# error.connection-refused
+
+Connection refused to %s. Ensure the dev server is running.
+
+# warning.no-manifest-dev-config
+
+webapp.json does not contain dev configuration. Using provided --url flag.
+
+# warning.manifest-dev-command-override
+
+webapp.json contains dev.command but --url flag provided. Using --url flag.
+
+# warning.dev-server-stderr
+
+Dev server error: %s
+
+# debug.request-received
+
+[REQUEST] %s %s
+
+# debug.routing-decision
+
+[ROUTING] %s -> %s (auth: %s)
+
+# debug.auth-headers-injected
+
+[AUTH] Authorization headers injected
+
+# debug.proxying-request
+
+[PROXY] Forwarding to %s
+
+# debug.response-received
+
+[RESPONSE] %s %s
+
+# debug.websocket-upgrade
+
+[WEBSOCKET] Upgrading connection for %s
+
+# debug.manifest-change-detected
+
+[MANIFEST] Change detected, reloading...
+
+# debug.token-refresh-attempt
+
+[AUTH] Token expired, attempting refresh...
+
+# debug.token-refresh-success
+
+[AUTH] Token refresh successful
+

package.json

@@ -8,13 +8,16 @@
     "@oclif/core": "^4",
     "@salesforce/core": "^8.23.4",
     "@salesforce/kit": "^3.2.4",
-    "@salesforce/sf-plugins-core": "^12"
+    "@salesforce/sf-plugins-core": "^12",
+    "chokidar": "^3.6.0",
+    "http-proxy": "^1.18.1"
   },
   "devDependencies": {
     "@oclif/plugin-command-snapshot": "^5.3.8",
     "@salesforce/cli-plugins-testkit": "^5.3.41",
     "@salesforce/dev-scripts": "^11.0.4",
     "@salesforce/plugin-command-reference": "^3.1.77",
+    "@types/http-proxy": "^1.17.14",
     "eslint-plugin-sf-plugin": "^1.20.33",
     "oclif": "^4.22.40",
     "ts-node": "^10.9.2",
@@ -54,6 +57,9 @@
     "topics": {
       "hello": {
         "description": "Commands to say hello."
+      },
+      "webapp": {
+        "description": "Commands for web application development."
       }
     },
     "flexibleTaxonomy": true

schemas/webapp-config.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.salesforce.com/webapp-config.json",
+  "title": "Salesforce Web Application Configuration",
+  "description": "Configuration schema for Salesforce web applications",
+  "type": "object",
+  "required": ["name", "label", "version", "apiVersion", "outputDir"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Unique name identifier for the web app",
+      "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$",
+      "examples": ["customerPortal", "myApp", "sales_dashboard"]
+    },
+    "label": {
+      "type": "string",
+      "description": "Human-readable label for the web app",
+      "minLength": 1,
+      "examples": ["Customer Portal", "My Application"]
+    },
+    "description": {
+      "type": "string",
+      "description": "Description of the web app"
+    },
+    "version": {
+      "type": "string",
+      "description": "Version of the web app in semantic versioning format",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "examples": ["1.0.0", "2.1.3"]
+    },
+    "apiVersion": {
+      "type": "string",
+      "description": "Salesforce API version",
+      "pattern": "^[0-9]+\\.[0-9]+$",
+      "examples": ["60.0", "61.0"]
+    },
+    "outputDir": {
+      "type": "string",
+      "description": "Output directory for built assets",
+      "examples": ["dist", "build", "out"]
+    },
+    "dev": {
+      "type": "object",
+      "description": "Development configuration",
+      "properties": {
+        "command": {
+          "type": "string",
+          "description": "Command to run the dev server (e.g., 'npm run dev')",
+          "examples": ["npm run dev", "yarn dev", "pnpm dev"]
+        },
+        "url": {
+          "type": "string",
+          "description": "Explicit URL for the dev server",
+          "pattern": "^https?://[^\\s]+$",
+          "examples": ["http://localhost:3000", "http://localhost:5173"]
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": true
+}
+