@equinor/fusion-framework-cli 15.2.11 → 15.3.0

package/docs/dev-server.md

@@ -12,7 +12,7 @@ The Fusion Framework dev-server is your complete local development solution for
 
 🛠️ **Flexible Configuration** - Easy setup for both applications and portals with environment-specific overrides
 
-📝 **Configurable Development** - Optional `dev-server.config.ts` file for API mocking, service discovery customization, and environment variable overrides
+📝 **Executable Service Mocks** - Reusable `mocks/<service>.mock.ts` modules for local development and browser tests
 
 ## Quick Start
 
@@ -30,11 +30,17 @@ The dev-server automatically detects your project type, loads configuration file
 
 For detailed information about configuring the dev-server, see [Dev Server Configuration](dev-server-config.md).
 
-The dev-server automatically loads configuration from a `dev-server.config.ts` file in your project root, allowing you to customize API mocking, service discovery, and development environment settings without modifying your application code.
+The dev server automatically discovers executable `mocks/<service>.mock.ts` modules. Define service
+behavior there with `defineService`, run `ffc mock-server` in a foreground terminal, and use
+`ffc app dev` for real discovery plus local overrides or `ffc app dev --mock` for an isolated mock
+environment. See [Develop with mock services](../../dev-server/docs/mocking.md).
+
+Use `dev-server.config.ts` for SPA environment values, logging, discovery endpoints, and shared
+mock-server defaults. It is not the recommended place to handwrite service routes.
 
 ## Key Features
 
-- **Service Discovery Integration** - Automatically connects to Fusion service discovery and enables local API mocking
+- **Service Discovery Integration** - Connects to real discovery and overlays visible executable mock modules by service key
 - **Template Generation** - Dynamic HTML template generation with environment variable injection
 - **API Proxying** - Seamless API integration with request/response transformation capabilities
 - **Portal Support** - Full portal development with manifest loading and configuration management
@@ -92,7 +98,7 @@ flowchart TD
 - **Role**: API service discovery and request handling
 - **Responsibilities**:
   - Proxies requests to Fusion service discovery endpoints
-  - Enables local API mocking and development overrides
+  - Proxies discovered services and advanced server-owned development routes
   - Manages dynamic route mapping for discovered services
   - Provides request/response transformation capabilities
 
@@ -156,7 +162,9 @@ This workflow ensures that developers have immediate access to a fully functiona
 
 ## Service Discovery
 
-The API plugin (`@equinor/fusion-framework-vite-plugin-api-service`) acts as an intelligent proxy that intercepts and enriches service discovery requests, enabling flexible service integration and local development capabilities. This plugin transforms the development server into a sophisticated service gateway that can dynamically modify service endpoints, inject mock services, and provide seamless integration between local development and production services.
+The API plugin (`@equinor/fusion-framework-vite-plugin-api-service`) proxies discovered services
+through the local origin. During normal app development, the CLI overlays discovery-visible
+`mocks/<service>.mock.ts` definitions by key before the API plugin creates those proxy routes.
 
 ### Service Discovery Sequence
 
@@ -180,59 +188,40 @@ sequenceDiagram
 2. **Plugin Interception**: The API plugin intercepts this request before it reaches the external service
 3. **Proxy to Fusion**: The plugin forwards the request to the actual Fusion service discovery endpoint
 4. **Response Interception**: When the response returns, the plugin intercepts it before sending it back to the user
-5. **Service Enrichment**: The plugin enriches the response by:
-   - Adding mock services for local development
-   - Altering service endpoints for testing
-   - Injecting additional metadata or configuration
-   - Modifying service capabilities or scopes
-6. **Enhanced Response**: The user receives an enriched list of services that may include both real and mock services
-
-## Mocking
+5. **Service Processing**: The plugin rewrites service URIs to local proxy routes.
+6. **Response**: The browser receives the processed service list and calls back through the dev server.
 
-The API plugin implements a **middleware pattern** that creates dynamic processing routes for mocking API responses during development. While these middleware routes can handle various request processing tasks, their primary purpose is to provide mock data when backend services aren't available or when you need to test specific scenarios without hitting real APIs.
+## Mocking services
 
-```mermaid
-sequenceDiagram
-    participant DevServer as Dev Server
-    participant Middleware as Middleware
-    participant MockData as Mock Data
-    participant Browser
+Application mocks are executable service modules, not dev-server middleware declarations:
 
-    DevServer->>Middleware: Initialize middleware stack
-    
-    Browser->>DevServer: Execute API request
-    DevServer->>Middleware: Route through middleware
-    Middleware->>Middleware: Process request
-    Middleware->>MockData: Fetch mock data
-    MockData->>Middleware: Return mock response
-    Middleware->>DevServer: Return processed response
-    DevServer->>Browser: Return mock data
+```text
+mocks/
+  inventory.mock.ts
+  inventory.openapi.json
 ```
 
-1. **Middleware Initialization**: The dev-server initializes the middleware stack with configured routes and processing rules
-2. **Request Interception**: API requests from the browser are routed through the middleware layer
-3. **Request Processing**: The middleware processes the request according to its configured rules and logic
-4. **Data Resolution**: The middleware fetches appropriate data (mock or real) based on the request and configuration
-5. **Response Processing**: The middleware processes and transforms the response before returning it
-6. **Response Delivery**: The processed response is returned to the browser through the dev-server
+`defineService` keeps the service key, discovery intent, OpenAPI schema, deterministic component
+values, operation routes, and request-aware middleware together. The same module works in local
+development and browser tests.
 
-#### Usage Example
+```mermaid
+flowchart LR
+    A["mocks/inventory.mock.ts"] --> B["ffc mock-server"]
+    B --> C["inventory.localhost:4010"]
+    B --> D["/@fusion-mock/discovery"]
+    E["ffc app dev"] --> F["real discovery + visible local modules"]
+    G["ffc app dev --mock"] --> H["preset + local modules only"]
+    F --> C
+    H --> C
+```
 
-```typescript
-import type { MiddlewareRoute } from '@equinor/fusion-framework-vite-plugin-api-service';
+The mock server is a standalone foreground process and never fetches remote discovery. Plain
+`ffc app dev` still uses real discovery and overlays visible local definitions. `ffc app dev
+--mock` points discovery at the standalone server and is intentionally isolated.
 
-const mockDataRoute: MiddlewareRoute = {
-  match: '/api/users',
-  middleware: (req, res, next) => {
-    // Return mock data for users endpoint
-    res.setHeader('Content-Type', 'application/json');
-    res.end(JSON.stringify([
-      { id: 1, name: 'John Doe' },
-      { id: 2, name: 'Jane Smith' }
-    ]));
-  }
-};
-```
+See [Develop with mock services](../../dev-server/docs/mocking.md) for a copyable module and
+discovery-mode guidance.
 
 ## Re-Routing requests
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-cli",
-  "version": "15.2.11",
+  "version": "15.3.0",
   "keywords": [
     "Fusion",
     "Fusion Framework",
@@ -111,11 +111,11 @@
     "vite": "^8.0.0",
     "vite-tsconfig-paths": "^6.0.4",
     "zod": "^4.4.3",
-    "@equinor/fusion-framework-dev-server": "2.0.19",
-    "@equinor/fusion-framework-module-azure-identity": "0.2.3",
-    "@equinor/fusion-framework-dev-portal": "11.0.3",
-    "@equinor/fusion-framework-vite-plugin-raw-imports": "2.0.1",
-    "@equinor/fusion-imports": "2.0.2"
+    "@equinor/fusion-framework-module-azure-identity": "0.3.0",
+    "@equinor/fusion-imports": "2.0.3",
+    "@equinor/fusion-framework-vite-plugin-raw-imports": "2.0.2",
+    "@equinor/fusion-framework-dev-portal": "11.0.4",
+    "@equinor/fusion-framework-dev-server": "2.1.0"
   },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^29.0.0",
@@ -126,7 +126,6 @@
     "@types/adm-zip": "^0.5.0",
     "@types/normalize-package-data": "^2.4.4",
     "@types/semver": "^7.7.1",
-    "@vitest/coverage-v8": "^4.0.18",
     "adm-zip": "^0.6.0",
     "ajv": "^8.17.1",
     "is-ci": "^4.1.0",
@@ -137,12 +136,13 @@
     "rxjs": "^7.8.1",
     "type-fest": "^5.0.0",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.0",
-    "@equinor/fusion-framework-module": "6.1.2",
-    "@equinor/fusion-framework-module-app": "8.0.5",
-    "@equinor/fusion-framework-module-http": "8.0.5",
-    "@equinor/fusion-framework-module-service-discovery": "10.0.2",
-    "@equinor/fusion-framework-react-router": "2.4.0"
+    "vitest": "^4.1.10",
+    "@equinor/fusion-framework-module": "6.1.3",
+    "@equinor/fusion-framework-cli-plugin-mock-server": "^0.1.0",
+    "@equinor/fusion-framework-module-app": "8.1.0",
+    "@equinor/fusion-framework-module-http": "8.1.0",
+    "@equinor/fusion-framework-react-router": "2.4.1",
+    "@equinor/fusion-framework-module-service-discovery": "10.1.0"
   },
   "peerDependenciesMeta": {
     "typescript": {
@@ -153,7 +153,6 @@
     "prebuild": "tsc -b",
     "build": "rollup -c rollup.config.js",
     "build:clean": "rm -rf dist && rm -rf bin/build && rm -f tsconfig.tsbuildinfo && pnpm build",
-    "test": "vitest",
-    "test:coverage": "vitest run --coverage"
+    "test": "vitest"
   }
 }