@equinor/fusion-framework-dev-server 2.0.19 → 2.1.0

package/dist/types/process-services.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/types.d.ts

@@ -63,7 +63,7 @@ export { UserConfig as DevServerOverrides } from 'vite';
  * };
  * ```
  */
-export type DevServerOptions<TEnv extends Partial<FusionTemplateEnv> = Partial<FusionTemplateEnv>> = {
+export interface DevServerOptions<TEnv extends Partial<FusionTemplateEnv> = Partial<FusionTemplateEnv>> {
     /** SPA template settings. When provided, the dev server injects these values into the HTML template at serve time. */
     spa?: {
         /** Static environment object or factory function that produces it on each request. */
@@ -91,4 +91,4 @@ export type DevServerOptions<TEnv extends Partial<FusionTemplateEnv> = Partial<F
         /** Custom logger instance. When omitted a default {@link ConsoleLogger} is created. */
         logger?: ConsoleLogger;
     };
-};
+}

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "2.0.19";
+export declare const version = "2.1.0";

package/docs/advanced.md

@@ -0,0 +1,79 @@
+# Advanced usage
+
+Use these extension points after the default discovery proxy and SPA environment work. Most
+applications do not need custom service processing.
+
+> [!IMPORTANT]
+> These are not the primary service-mocking APIs. Define application mocks in
+> `mocks/<service>.mock.ts` with `defineService`; use `processServices` only when a host must
+> transform real discovery independently of mock behavior.
+
+## Transform discovered services
+
+Call `processServices(data, args)` first, then transform its result. This preserves standard local
+URI rewriting and proxy route generation.
+
+```typescript
+import { createDevServer, processServices } from '@equinor/fusion-framework-dev-server';
+
+const server = await createDevServer({
+  api: {
+    serviceDiscoveryUrl: 'https://service-discovery.example.com',
+    processServices: (data, args) => {
+      const processed = processServices(data, args);
+      return {
+        ...processed,
+        data: processed.data.filter((service) => service.key !== 'deprecated-service'),
+      };
+    },
+  },
+});
+```
+
+Throwing from a processor fails the discovery request. Validate upstream assumptions instead of
+silently returning a partial service list.
+
+> [!CAUTION]
+> A custom processor replaces the default processing entry point. Call `processServices` first
+> unless you intend to own all URI rewriting and proxy-route generation yourself.
+
+## Add Vite configuration
+
+The second argument is merged over generated Vite configuration:
+
+```typescript
+import { createDevServer } from '@equinor/fusion-framework-dev-server';
+import myPlugin from 'my-vite-plugin';
+
+const server = await createDevServer(
+  { api: { serviceDiscoveryUrl: 'https://service-discovery.example.com' } },
+  {
+    plugins: [myPlugin()],
+    server: { host: '0.0.0.0', port: 3001 },
+  },
+);
+```
+
+Prefer first-class `spa`, `api`, and `log` options when they cover the requirement. Use overrides
+for Vite-owned behavior and additional plugins.
+
+## Own the Vite lifecycle
+
+Use `createDevServerConfig` when a test harness or larger CLI creates Vite itself:
+
+```typescript
+import { createDevServerConfig } from '@equinor/fusion-framework-dev-server';
+import { createServer } from 'vite';
+
+const config = createDevServerConfig({
+  api: { serviceDiscoveryUrl: 'https://service-discovery.example.com' },
+});
+const server = await createServer(config);
+await server.listen();
+```
+
+## Extend `DevServerOptions`
+
+Optional tooling can use declaration merging because `DevServerOptions` is an interface. Keep the
+augmentation in the owning plugin and import that plugin's types where extended options are
+authored. The mock-server plugin's `mockServer` section is the reference implementation.

package/docs/configuration.md

@@ -0,0 +1,117 @@
+# Configure the dev server
+
+`DevServerOptions<TEnv>` has three base sections: `spa`, `api`, and `log`. Start with required
+`api.serviceDiscoveryUrl`, then add browser environment and logging when your host needs them.
+
+## Configure the browser environment
+
+`spa.templateEnv` can be a static object or a function. The SPA plugin serializes its value into
+the page for browser-side Fusion modules.
+
+```typescript
+const options = {
+  spa: {
+    templateEnv: {
+      portal: { id: 'my-portal' },
+      title: 'My application',
+      serviceDiscovery: {
+        url: 'https://service-discovery.example.com',
+        scopes: ['api://example.com/user_impersonation'],
+      },
+      msal: {
+        clientId: 'client-id',
+        tenantId: 'tenant-id',
+        redirectUri: '/authentication/login-callback',
+        requiresAuth: 'true',
+      },
+    },
+  },
+};
+```
+
+Use a factory when values come from a runtime source:
+
+```typescript
+const options = {
+  spa: {
+    templateEnv: () => ({
+      title: 'Local application',
+      telemetry: { consoleLevel: 0 },
+    }),
+  },
+};
+```
+
+Browser telemetry and server logging use different scales. `telemetry.consoleLevel` controls the
+browser console; `log.level` controls terminal output.
+
+## Configure service discovery and proxying
+
+`api.serviceDiscoveryUrl` is the upstream endpoint the Node server fetches. The default
+`processServices` rewrites each discovered URI to the local origin and creates a proxy route.
+
+> [!WARNING]
+> `spa.templateEnv.serviceDiscovery.url` configures the browser, while
+> `api.serviceDiscoveryUrl` configures the Node proxy. Setting only one can produce a page that
+> loads successfully but cannot resolve or proxy services.
+
+```typescript
+const options = {
+  api: { serviceDiscoveryUrl: 'https://service-discovery.example.com' },
+};
+```
+
+Add `api.routes` for a small server-owned endpoint:
+
+```typescript
+const options = {
+  api: {
+    serviceDiscoveryUrl: 'https://service-discovery.example.com',
+    routes: [
+      {
+        match: '/health',
+        middleware: (_request, response) => {
+          response.setHeader('content-type', 'application/json');
+          response.end(JSON.stringify({ status: 'ready' }));
+        },
+      },
+    ],
+  },
+};
+```
+
+Prefer executable `mocks/<service>.mock.ts` modules from the
+[mock-server guide](mocking.md) for local services. Reserve `api.routes` for server-owned behavior
+that is not a service mock; do not reproduce OpenAPI operations as handwritten dev-server
+middleware.
+
+## Configure terminal logging
+
+```typescript
+const options = {
+  api: { serviceDiscoveryUrl: 'https://service-discovery.example.com' },
+  log: { level: 4 },
+};
+```
+
+Server levels are `0` None, `1` Error, `2` Warning, `3` Info, and `4` Debug. Info is the default.
+Supply `log.logger` when a host already owns a configured `ConsoleLogger` hierarchy.
+
+## Extend configuration from optional plugins
+
+`DevServerOptions` is an interface so optional packages can contribute configuration without the
+base package depending on them. Importing the mock-server plugin types adds `mockServer`:
+
+```typescript
+import type {} from '@equinor/fusion-framework-cli-plugin-mock-server';
+import type { DevServerOptions } from '@equinor/fusion-framework-dev-server';
+
+const options: DevServerOptions = {
+  api: { serviceDiscoveryUrl: 'https://service-discovery.example.com' },
+  mockServer: { path: 'mocks', port: 4010, seed: 42 },
+};
+```
+
+> [!TIP]
+> This empty type import activates TypeScript declaration merging: it adds `mockServer` to
+> `DevServerOptions` for type checking without producing a runtime import.

package/docs/getting-started.md

@@ -0,0 +1,82 @@
+# Getting started
+
+Use `@equinor/fusion-framework-dev-server` to create a Fusion-aware Vite server programmatically.
+Application projects that only need to run locally should prefer `ffc app dev`, which builds on
+these lower-level primitives and supplies application conventions.
+
+## Install the package
+
+```sh
+pnpm add -D @equinor/fusion-framework-dev-server vite
+```
+
+The package supports Vite 7 and 8.
+
+## Understand the request flow
+
+```mermaid
+flowchart LR
+  Browser[Browser application] -->|reads template environment| SPA[SPA configuration]
+  Browser -->|calls local service URI| Proxy[Development server proxy]
+  Proxy -->|fetches service list| Discovery[Fusion service discovery]
+  Proxy -->|forwards API request| Backend[Backend service]
+```
+
+`spa.templateEnv.serviceDiscovery` tells browser-side Fusion modules where discovery is.
+`api.serviceDiscoveryUrl` tells the Node server where to fetch services before rewriting them
+through local proxy routes. Keeping the roles separate supports custom portals and proxy setups.
+
+## Create the server
+
+```typescript
+import { createDevServer } from '@equinor/fusion-framework-dev-server';
+
+const server = await createDevServer({
+  spa: {
+    templateEnv: {
+      portal: { id: 'my-portal' },
+      title: 'My application',
+      serviceDiscovery: { url: 'https://service-discovery.example.com', scopes: [] },
+      msal: {
+        clientId: 'client-id',
+        tenantId: 'tenant-id',
+        redirectUri: '/authentication/login-callback',
+        requiresAuth: 'true',
+      },
+    },
+  },
+  api: { serviceDiscoveryUrl: 'https://service-discovery.example.com' },
+});
+
+await server.listen();
+server.printUrls();
+```
+
+> [!NOTE]
+> `createDevServer` returns a Vite server but does not call `listen()`. Your command chooses when
+> startup happens and how startup failures are handled.
+
+## Generate configuration instead
+
+Use `createDevServerConfig` when another tool owns the Vite lifecycle:
+
+```typescript
+import { createDevServerConfig } from '@equinor/fusion-framework-dev-server';
+import { createServer } from 'vite';
+
+const config = createDevServerConfig({
+  api: { serviceDiscoveryUrl: 'https://service-discovery.example.com' },
+});
+
+const server = await createServer(config);
+await server.listen();
+```
+
+The generated configuration includes React Fast Refresh, SPA template injection, service
+discovery proxying, and the default logger.
+
+## Next steps
+
+- [Configure the dev server](configuration.md) for environment factories, API routes, and logs.
+- [Develop with mock services](mocking.md) for local or deterministic backends.
+- [Advanced usage](advanced.md) for discovery transforms and Vite plugins.

package/docs/mocking.md

@@ -0,0 +1,229 @@
+# Develop with mock services
+
+Use `@equinor/fusion-framework-cli-plugin-mock-server` when a Fusion application needs a local,
+deterministic, or not-yet-deployed backend. The plugin adds `ffc mock-server`; it does not change
+the base dev-server runtime or start a background process automatically.
+
+The recommended application workflow has three parts:
+
+1. Create `mocks/<service>.mock.ts` with `defineService`.
+2. Run `ffc mock-server` in a foreground terminal.
+3. Run `ffc app dev` for real discovery plus local overrides, or `ffc app dev --mock` for an
+  isolated mock environment.
+
+> [!IMPORTANT]
+> Keep service mock behavior in `<service>.mock.ts`, not `dev-server.config.ts`. The executable
+> module is reusable by local development, Playwright, and the programmatic mock server. Reserve
+> `api.routes` and `api.processServices` for advanced server infrastructure and discovery
+> transformations that are not service mocks.
+
+## Migrate existing dev-server configuration
+
+Migrate one service at a time. Move behavior owned by a backend service into
+`mocks/<service>.mock.ts`; keep host-level behavior in `dev-server.config.ts`.
+
+| Existing configuration | New location | Use when |
+| --- | --- | --- |
+| `api.processServices` adds or redirects one service | `serviceDiscovery` in `<service>.mock.ts` | The change exists only to make that service available locally. |
+| `api.routes` returns a mocked OpenAPI operation | `routes` in `<service>.mock.ts` | The path and method belong to the service's OpenAPI contract. |
+| `api.routes` implements request-aware service behavior | `middleware` in `<service>.mock.ts` | The behavior needs request headers, parameters, or a parsed body. |
+| Schema faker overrides | `components` in `<service>.mock.ts` | Generated OpenAPI responses need deterministic field values. |
+| Filtering or rewriting real discovery for the whole host | Keep `api.processServices` | The transformation is infrastructure behavior rather than a service mock. |
+| Dev-server health checks or other host-owned endpoints | Keep `api.routes` | The route belongs to the local host, not to one backend service. |
+
+For example, a legacy configuration might replace the generated proxy route for an existing
+`inventory` service with a local response:
+
+```typescript
+// dev-server.config.ts
+import { defineDevServerConfig, processServices } from '@equinor/fusion-framework-cli/dev-server';
+
+export default defineDevServerConfig(() => ({
+  api: {
+    processServices: (services, args) => {
+      const processed = processServices(services, args);
+      return {
+        ...processed,
+        routes: [
+          ...processed.routes.filter((route) => route.match !== '/inventory/api*sub'),
+          {
+            match: '/inventory/api*sub',
+            middleware: (_request, response) => {
+              response.setHeader('content-type', 'application/json');
+              response.end(JSON.stringify([{ id: 'local-item', name: 'Local item' }]));
+            },
+          },
+        ],
+      };
+    },
+  },
+}));
+```
+
+Move that service-owned response into an executable mock module. Paths in `routes` are relative to
+the service and must match an operation in its OpenAPI document:
+
+```typescript
+// mocks/inventory.mock.ts
+import schema from './inventory.openapi.json' with { type: 'json' };
+import { defineService } from '@equinor/fusion-openapi-mock-server/discovery';
+
+export default defineService({
+  key: 'inventory',
+  serviceDiscovery: 'replace',
+  schema,
+  routes: {
+    '/items': {
+      get: {
+        mock: [{ id: 'local-item', name: 'Local item' }],
+      },
+    },
+  },
+});
+```
+
+`'replace'` is appropriate because the module carries a complete schema and deliberately replaces
+the real discovery entry during normal development or a same-key preset in isolated mode. Use
+`'merge'` only when a selected preset or earlier local mock layer already supplies the service and
+schema; the standalone mock server never inherits schemas from remote discovery. Use `'new'` with
+a `schema` for a pre-production service, or `false` with a `schema` for a direct-only endpoint.
+
+Complete the migration:
+
+1. Install `@equinor/fusion-framework-cli-plugin-mock-server` and
+   `@equinor/fusion-openapi-mock-server` as development dependencies.
+2. Start `ffc mock-server` in a foreground terminal.
+3. Run `ffc app dev` to combine real discovery with local definitions, or use
+   `ffc app dev --mock http://localhost:4010` for an isolated environment.
+4. Verify the migrated service, then remove only its old `api.routes` and `api.processServices`
+   branches. Leave unrelated host-level configuration in place.
+
+During an incremental migration, migrated and legacy services can coexist. Do not define the same
+service behavior in both places; route precedence can hide which implementation handled a request.
+
+## Install and start the mock server
+
+```sh
+pnpm add -D @equinor/fusion-framework-cli-plugin-mock-server
+ffc mock-server
+```
+
+> [!IMPORTANT]
+> Keep this foreground process running in one terminal and start the application in another. The
+> plugin intentionally does not create an unowned background process.
+
+Check that startup completed before connecting the app:
+
+```sh
+curl http://localhost:4010/@fusion-mock/health
+```
+
+> [!TIP]
+> Use the health endpoint as the `url` readiness check in Playwright's `webServer` configuration.
+
+## Define one executable module per service
+
+```text
+mocks/
+  inventory.mock.ts
+  inventory.openapi.json
+```
+
+```typescript
+import schema from './inventory.openapi.json' with { type: 'json' };
+import { defineService } from '@equinor/fusion-openapi-mock-server/discovery';
+
+export default defineService({
+  key: 'inventory',
+  serviceDiscovery: 'new',
+  schema,
+  components: {
+    InventoryItem: { name: () => 'Local item' },
+  },
+});
+```
+
+The module keeps service ownership, schema, deterministic fields, routes, and middleware in one
+retrieval-friendly place.
+
+This example uses `'new'` because `inventory` is not registered yet; startup fails if the key later
+appears in real discovery. Use `'merge'` only when a selected preset or earlier local mock layer
+already provides the service schema and only selected local behavior should change.
+
+## Choose the development mode
+
+### Combine real discovery with selected local services
+
+```sh
+ffc mock-server
+ffc app dev
+```
+
+Normal development fetches real discovery and overlays discovery-visible local definitions by
+service key. Use this when most real backends remain useful.
+
+### Use only predefined and local mocks
+
+```sh
+ffc mock-server
+ffc app dev --mock http://localhost:4010
+```
+
+`--mock` points application discovery at the standalone server. The mock server never fetches real
+service discovery; it resolves only bundled presets and local modules. Use this for isolated
+development, CI, and browser tests.
+
+> [!WARNING]
+> `--mock` is intentionally isolated. A service missing from the bundled presets and local modules
+> will not fall back to remote service discovery.
+
+A preset is a built-in group of service definitions. The default `fusion` preset supplies common
+services that framework modules resolve during startup. Local modules are layered after presets,
+so app-specific behavior can override the baseline.
+
+## Choose a discovery mode
+
+| Mode | Developer scenario |
+| --- | --- |
+| `'merge'` | Override selected behavior of a service supplied by a selected preset or earlier local mock layer while inheriting its schema. Remote discovery alone is not a merge source. |
+| `'new'` | Add a pre-production service expected to enter real discovery before release. Definition resolution fails if the key already exists in discovery or an earlier mock layer. |
+| `'replace'` | Supply a complete local definition and deliberately replace an earlier same-key definition. |
+| `false` | Serve an app-owned endpoint without advertising it through discovery. Configure its `<key>.localhost` mock URL directly in environment-specific app config. |
+
+> [!CAUTION]
+> Use `'new'` only as a temporary pre-production contract. Once the real service key appears,
+> definition resolution fails on purpose; register the backend before release and remove or change
+> the local definition.
+
+For example, a service with key `my-api` and `serviceDiscovery: false` is still served at
+`http://my-api.localhost:4010`; it is simply absent from `/@fusion-mock/discovery`. This mirrors an
+application-owned API URL that production configuration supplies directly.
+
+Register that URL through the app's environment-specific `endpoints` configuration. The
+[HTTP-client guide](../../app/docs/http-clients.md#mock-an-application-config-endpoint-locally)
+contains the complete `app.config.local.ts` recipe and restart caveat.
+
+## Configure shared defaults
+
+```typescript
+import type {} from '@equinor/fusion-framework-cli-plugin-mock-server';
+import { defineDevServerConfig } from '@equinor/fusion-framework-cli';
+
+export default defineDevServerConfig(() => ({
+  mockServer: {
+    path: 'mocks',
+    host: 'localhost',
+    port: 4010,
+    seed: 42,
+  },
+}));
+```
+
+Command-line flags override these defaults. `path` is relative to the project root.
+
+## Test in a real browser
+
+Use Playwright's `webServer` array to own both foreground processes and stop them after the suite.
+The mock server exposes HTTP endpoints for per-test operation overrides and reset.
+
+See the [plugin reference](../../cli-plugins/mock-server/README.md), [OpenAPI mock-server guide](../../utils/openapi-mock-server/docs/getting-started.md), and [Playwright cookbook](../../../cookbooks/app-react-mock-playwright/README.md).

package/docs/troubleshooting.md

@@ -0,0 +1,68 @@
+# Troubleshooting
+
+Start with the visible symptom, then check the responsible layer. Browser environment, server
+discovery, and backend proxying are separate steps.
+
+## The package cannot be resolved
+
+```sh
+pnpm add -D @equinor/fusion-framework-dev-server
+```
+
+Vite must also satisfy the Vite 7 or 8 peer dependency.
+
+## Service discovery fails
+
+Check `api.serviceDiscoveryUrl` first. The Node process must reach this URL. Authentication, VPN,
+DNS, and environment availability can differ from browser access.
+
+If the browser receives the wrong URL, inspect `spa.templateEnv.serviceDiscovery` instead. It
+controls browser configuration and does not replace the API option.
+
+## A discovered API request fails
+
+1. Confirm the service key exists in discovery.
+2. Enable server debug logging with `log.level: 4`.
+3. Inspect the rewritten local service URI returned to the browser.
+4. Check that the upstream URI is absolute and reachable from Node.
+5. Review custom `api.processServices` logic and route precedence.
+
+## A mock service is missing
+
+The mock server is separate. Confirm `ffc mock-server` is running and
+`/@fusion-mock/health` responds.
+
+Confirm the source file matches `mocks/<service>.mock.ts` and default-exports a `defineService(...)`
+result. The service key in that module must match the key requested by the application.
+
+Normal `ffc app dev` overlays only discovery-visible definitions. Definitions using
+`serviceDiscovery: false` must be configured directly in app config, for example with a
+`http://<key>.localhost:4010` URL. In `--mock` mode, confirm the application uses the same origin
+and port as the manually started server.
+
+If a definition using `serviceDiscovery: 'new'` reports a collision, real discovery or an earlier
+mock layer already owns that key. Do not change it to `'replace'` just to hide the error: remove the
+temporary pre-production mock after registration, or use `'merge'` when the intent is to override
+selected behavior of the existing service.
+
+## Authentication fails
+
+Check `clientId`, `tenantId`, and `redirectUri` in `spa.templateEnv.msal`. The redirect URI must
+match the identity provider registration and local URL.
+
+## Turn on diagnostics
+
+```typescript
+const options = {
+  api: { serviceDiscoveryUrl: 'https://service-discovery.example.com' },
+  log: { level: 4 },
+  spa: { templateEnv: { telemetry: { consoleLevel: 0 } } },
+};
+```
+
+The scales differ: `log.level` uses `0` None through `4` Debug, while browser
+`telemetry.consoleLevel` uses `0` Debug through `4` Critical.
+
+> [!TIP]
+> Start with `log.level: 4` for discovery and proxy failures. Add browser telemetry only when the
+> failure occurs after the page has loaded.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-dev-server",
-  "version": "2.0.19",
+  "version": "2.1.0",
   "description": "Package for running a development server for fusion-framework",
   "type": "module",
   "exports": {
@@ -30,14 +30,14 @@
   },
   "dependencies": {
     "@vitejs/plugin-react": "^6.0.1",
-    "@equinor/fusion-framework-vite-plugin-api-service": "2.0.5",
-    "@equinor/fusion-framework-vite-plugin-spa": "4.0.17",
-    "@equinor/fusion-log": "2.0.2"
+    "@equinor/fusion-framework-vite-plugin-api-service": "2.0.6",
+    "@equinor/fusion-log": "2.0.3",
+    "@equinor/fusion-framework-vite-plugin-spa": "4.1.0"
   },
   "devDependencies": {
     "typescript": "^7.0.2",
     "vite": "^8.0.0",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
     "vite": "^7.0.0 || ^8.0.0"

package/src/process-services.test.ts

@@ -0,0 +1,36 @@
+import { IncomingMessage } from 'node:http';
+import { Socket } from 'node:net';
+
+import { describe, expect, it } from 'vitest';
+
+import { processServices } from './process-services.js';
+
+const request = new IncomingMessage(new Socket());
+request.headers.referer = 'http://localhost:3000';
+
+describe('processServices', () => {
+  it('proxies localhost subdomains through the portable shared-host route', () => {
+    const result = processServices(
+      [{ key: 'people', name: 'People', uri: 'http://people.localhost:4010' }],
+      { route: '/@fusion-api', request },
+    );
+
+    expect(result.routes).toEqual([
+      {
+        match: '/people/*sub',
+        proxy: { target: 'http://localhost:4010' },
+      },
+    ]);
+  });
+
+  it('preserves normal upstream proxy targets and path rewriting', () => {
+    const result = processServices(
+      [{ key: 'people', name: 'People', uri: 'https://people.example/api' }],
+      { route: '/@fusion-api', request },
+    );
+    const [route] = result.routes ?? [];
+
+    expect(route?.proxy?.target).toBe('https://people.example');
+    expect(route?.proxy?.rewrite?.('/people/api/persons')).toBe('/api/persons');
+  });
+});