@equinor/fusion-framework-cli 12.1.2 → 12.2.0

package/dist/esm/version.js

@@ -1,3 +1,3 @@
 // Generated by genversion.
-export const version = '12.1.2';
+export const version = '12.2.0';
 //# sourceMappingURL=version.js.map

package/dist/types/bin/app-check.d.ts

@@ -27,5 +27,5 @@ type AppCheckOptions = {
  * @returns A promise that resolves when the check is complete.
  * @public
  */
-export declare const checkApp: (options: AppCheckOptions) => Promise<void>;
+export declare const checkApp: (options: AppCheckOptions) => Promise<boolean>;
 export default checkApp;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "12.1.2";
+export declare const version = "12.2.0";

package/docs/dev-server-config.md

@@ -0,0 +1,382 @@
+The dev-server supports optional configuration through a `dev-server.config.ts` file in your project root. This allows you to customize how your application interacts with the Fusion Framework during development.
+
+> [!NOTE]
+> Basic server options like `port`, `host`, and `open` are configured via CLI flags or Vite configuration, not through `dev-server.config.ts`.
+
+## Why Configure the Dev Server?
+
+The default dev-server configuration works for most applications, but you may want to customize it when:
+
+- **Testing API integrations**: Mock services or override API responses during development
+- **Debugging service discovery**: Filter or modify discovered services for testing
+- **Customizing the development environment**: Adjust template variables, CLI logging, or browser console logging
+- **Isolating development scenarios**: Configure different behaviors for different development stages
+
+## Getting Started
+
+Create a `dev-server.config.ts` file in your project root. Start simple with object configuration:
+
+```typescript
+// Simple object configuration
+export default {
+  api: {
+    routes: [{
+      match: '/my-api/test',
+      middleware: (req, res) => res.end('OK')
+    }]
+  }
+};
+```
+
+For conditional configuration based on environment or other runtime logic, use function configuration:
+
+```typescript
+import { defineDevServerConfig } from '@equinor/fusion-framework-cli';
+
+export default defineDevServerConfig(({ base }) => {
+  // Access to base config and environment for advanced logic
+  const isLocalDev = process.env.USER === 'your-username'; // Example condition
+
+  return {
+    api: {
+      routes: [
+        // Different routes based on conditions
+        isLocalDev && { match: '/api/local-dev', middleware: localHandler }
+      ].filter(Boolean) // Remove falsy values
+    }
+  };
+});
+```
+
+> [!TIP]
+> Start with object config. Use function config only when you need conditional logic or access to the base configuration.
+
+## TypeScript Integration
+
+For full TypeScript support and intellisense, import the configuration types:
+
+```typescript
+import { defineDevServerConfig, type DevServerConfig } from '@equinor/fusion-framework-cli';
+
+// Fully typed configuration
+export default defineDevServerConfig(({ base }): DevServerConfig => ({
+  ...base,
+  api: {
+    ...base.api,
+    routes: [
+      {
+        match: '/api/users',
+        middleware: (req, res) => {
+          // req and res are properly typed
+          res.setHeader('Content-Type', 'application/json');
+          res.end(JSON.stringify([]));
+        }
+      }
+    ]
+  }
+}));
+```
+
+The configuration object supports full TypeScript intellisense, including:
+- Auto-completion for all configuration options
+- Type checking for middleware functions
+- Proper typing for service discovery responses
+
+## Configuration Overview
+
+The dev-server configuration supports these main areas:
+
+| Area | Purpose | Common Use Cases |
+|------|---------|------------------|
+| `api.routes` | Mock API endpoints | Testing UI without backend, error scenarios |
+| `api.processServices` | Modify service discovery | Add mock services, override endpoints |
+| `api.serviceDiscoveryUrl` | Change discovery endpoint | Custom/dev environments |
+| `spa.templateEnv` | Override Fusion config | Portal settings, MSAL config, telemetry |
+| `log` | Control CLI logging verbosity | Debug dev-server issues, reduce terminal noise |
+
+## How Configuration Works
+
+The `dev-server.config.ts` file is designed for **overriding** the default dev-server behavior. You only specify what you want to change - the system automatically merges your overrides with the defaults.
+
+### Object Configuration (Recommended)
+Just export the properties you want to override:
+
+```typescript
+export default {
+  // Only override what you need to change
+  api: {
+    routes: [{
+      match: '/api/users',
+      middleware: (req, res) => res.end(JSON.stringify([]))
+    }]
+  },
+  spa: {
+    templateEnv: {
+      telemetry: { consoleLevel: 0 } // Only override telemetry
+    }
+  }
+};
+```
+
+The dev-server automatically merges this with its default configuration.
+
+### Function Configuration (Advanced)
+Use functions when you need conditional logic or access to runtime values:
+
+```typescript
+export default defineDevServerConfig(({ base }) => {
+  // You have access to base config and runtime environment
+  return {
+    api: {
+      routes: [
+        // Your routes automatically merge with any existing ones
+        { match: '/api/test', middleware: testHandler }
+      ]
+    }
+  };
+});
+```
+
+**Key Point**: You don't need to manually spread/merge anything. Just provide the overrides you want - the merging happens automatically.
+
+## Array Merging Behavior
+
+The dev-server uses intelligent array merging:
+
+- **Routes**: Merged by `match` path - routes with identical paths are replaced (yours wins)
+- **Other arrays**: Deduplicated using `Set` - removes exact duplicates
+- **Services**: In service discovery, arrays are typically replaced rather than merged
+
+Example route merging:
+```typescript
+// Base config has:
+routes: [{ match: '/api/users', middleware: baseHandler }]
+
+// Your config has:
+routes: [{ match: '/api/users', middleware: yourHandler }]
+
+// Result: yourHandler replaces baseHandler for /api/users
+```
+
+## Quick Start Examples
+
+### I Need To...
+| I want to... | Configuration | Example |
+|--------------|---------------|---------|
+| Mock an API endpoint | `api.routes` | `routes: [{ match: '/api/users', middleware: (req, res) => res.end('[]') }]` |
+| Add a mock service | `api.processServices` | Add services to the service discovery response |
+| Override MSAL config | `spa.templateEnv.msal` | `msal: { clientId: 'dev-client-id' }` |
+| Change telemetry logging | `spa.templateEnv.telemetry` | `telemetry: { consoleLevel: 0 }` |
+| Reduce CLI noise | `log.level` | `log: { level: 2 }` |
+
+## Essential Configurations
+
+### API Mocking
+
+**When you need it**: Your application depends on backend services that aren't available during development, or you want to test specific API responses without hitting real services.
+
+**How it works**: Add custom routes that intercept API calls and return mock data.
+
+```typescript
+export default defineDevServerConfig(() => ({
+  api: {
+    routes: [
+      {
+        match: '/api/users',
+        middleware: (req, res) => {
+          res.setHeader('Content-Type', 'application/json');
+          res.end(JSON.stringify([
+            { id: 1, name: 'John Doe', role: 'developer' },
+            { id: 2, name: 'Jane Smith', role: 'designer' }
+          ]));
+        }
+      },
+      // Mock error responses
+      {
+        match: '/api/users/404',
+        middleware: (req, res) => {
+          res.statusCode = 404;
+          res.end(JSON.stringify({ error: 'User not found' }));
+        }
+      }
+    ]
+  }
+}));
+```
+
+**Benefits**: Develop UI components and user flows without backend dependencies. Test error handling scenarios easily.
+
+### Service Discovery Customization
+
+**When you need it**: You're developing against a service that doesn't exist yet in the remote service discovery, or you want to override service endpoints for local development.
+
+**How it works**: Add mock services to the service discovery response that your application can use during development.
+
+```typescript
+export default defineDevServerConfig(() => ({
+  api: {
+    processServices: (dataResponse) => {
+      const { data, routes } = dataResponse;
+
+      // Add mock services for development
+      const mockServices = [
+        {
+          key: 'my-new-service',
+          name: 'My New Service (Mock)',
+          uri: '/api/mock-service' // This will be proxied by the dev server
+        },
+        {
+          key: 'beta-feature-api',
+          name: 'Beta Feature API (Mock)',
+          uri: 'https://beta-api.example.com'
+        }
+      ];
+
+      return {
+        data: [...data, ...mockServices],
+        routes
+      };
+    }
+  }
+}));
+```
+
+**Benefits**: Develop against planned services before they're deployed. Test integration scenarios with mock endpoints.
+
+### Template Environment Variables
+
+**When you need it**: You need to override default Fusion Framework template configuration for development.
+
+**How it works**: Modify the template environment variables that control the SPA bootstrap process.
+
+```typescript
+export default defineDevServerConfig(() => ({
+  spa: {
+    templateEnv: {
+      // Override document title
+      title: 'My Custom App Title',
+
+      // Override portal configuration
+      portal: {
+        id: 'my-custom-portal',
+        tag: 'development'
+      },
+
+      // Modify service discovery
+      serviceDiscovery: {
+        url: 'https://custom-service-discovery.example.com',
+        scopes: ['api://custom-scope/.default']
+      },
+
+      // Override MSAL configuration
+      msal: {
+        tenantId: 'custom-tenant-id',
+        clientId: 'custom-client-id',
+        redirectUri: 'https://localhost:3000/auth-callback',
+        requiresAuth: 'true'
+      },
+
+      // Configure telemetry logging level
+      telemetry: {
+        consoleLevel: 0 // Debug level (most verbose)
+      }
+    }
+  }
+}));
+```
+
+**Benefits**: Customize the Fusion Framework bootstrap behavior and control browser console logging verbosity for your specific development needs.
+
+**Available telemetry levels:**
+- `0`: Debug (shows all telemetry including debug messages)
+- `1`: Information (shows info, warnings, errors, critical)
+- `2`: Warning (shows warnings, errors, critical - default)
+- `3`: Error (shows only errors and critical messages)
+- `4`: Critical (shows only critical messages - least verbose)
+
+### CLI Logging
+
+**When you need it**: You want to control the verbosity of dev-server output in your terminal/console.
+
+**How it works**: Configure the logger level or provide a custom logger instance for CLI output.
+
+```typescript
+export default defineDevServerConfig(() => ({
+  log: {
+    // Info level (default) - shows info, warnings, and errors
+    level: 3, 
+  }
+}));
+```
+
+**Available levels:**
+- `0`: Silent (no logging)
+- `1`: Error (errors only)
+- `2`: Warning (warnings and errors)
+- `3`: Info (info, warnings, and errors - **default**)
+- `4`: Debug (debug, info, warnings, and errors - most verbose)
+
+**Quick reference:**
+```typescript
+// Quiet development (reduce noise)
+log: { level: 2 }
+
+// Default logging (recommended)
+log: { level: 3 }
+
+// Debug dev-server issues
+log: { level: 4 }
+```
+
+## Common Patterns
+
+### Override MSAL for Local Development
+
+```typescript
+export default {
+  spa: {
+    templateEnv: {
+      msal: {
+        clientId: 'dev-client-id',
+        redirectUri: 'http://localhost:3000/auth-callback'
+      }
+    }
+  }
+};
+```
+
+
+
+
+## Troubleshooting
+
+### Configuration Not Loading
+- Verify file name: `dev-server.config.ts` in project root
+- Ensure default export: `export default { ... }`
+- Check for TypeScript errors in config file
+
+### Services Not Appearing
+- Ensure `processServices` returns `{ data: Service[], routes: Route[] }`
+- Verify you're not accidentally filtering out needed services
+
+### Template Variables Not Available
+- Variables are injected as `import.meta.env.FUSION_SPA_*`
+- Access them as `import.meta.env.FUSION_SPA_MY_VAR`
+
+## Advanced Usage
+
+### Custom Service Discovery Endpoint
+
+For custom environments with different service discovery URLs:
+
+```typescript
+export default {
+  api: {
+    serviceDiscoveryUrl: 'https://custom-discovery.example.com/api/service-discovery'
+  }
+};
+```
+
+> [!WARNING]
+> Only use when working with non-standard environments. The default Fusion service discovery endpoint is usually correct.
+

package/docs/dev-server.md

@@ -24,6 +24,10 @@ ffc portal dev
 
 The dev-server automatically detects your project type, loads configuration files, and starts a development server with all Fusion Framework features ready to use. No complex setup required - just run the command and start building.
 
+## Configuration
+
+For detailed information about configuring the dev-server, see [Dev Server Configuration](dev-server-config.md).
+
 ## Key Features
 
 - **Service Discovery Integration** - Automatically connects to Fusion service discovery and enables local API mocking

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-cli",
-  "version": "12.1.2",
+  "version": "12.2.0",
   "keywords": [
     "Fusion",
     "Fusion Framework",
@@ -103,13 +103,13 @@
     "ora": "^9.0.0",
     "read-package-up": "^11.0.0",
     "simple-git": "^3.28.0",
-    "vite": "^7.1.5",
+    "vite": "^7.1.9",
     "vite-tsconfig-paths": "^5.1.4",
     "zod": "^4.1.8",
-    "@equinor/fusion-framework-dev-portal": "1.1.3",
-    "@equinor/fusion-framework-dev-server": "1.1.3",
+    "@equinor/fusion-framework-dev-server": "1.1.4",
     "@equinor/fusion-framework-module-msal-node": "1.0.7",
-    "@equinor/fusion-imports": "1.1.4"
+    "@equinor/fusion-imports": "1.1.4",
+    "@equinor/fusion-framework-dev-portal": "1.2.0"
   },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^28.0.3",
@@ -132,10 +132,10 @@
     "type-fest": "^5.0.0",
     "typescript": "^5.8.2",
     "vitest": "^3.2.4",
-    "@equinor/fusion-framework-module": "5.0.2",
-    "@equinor/fusion-framework-module-http": "7.0.1",
-    "@equinor/fusion-framework-module-app": "7.0.1",
-    "@equinor/fusion-framework-module-service-discovery": "9.0.1"
+    "@equinor/fusion-framework-module": "5.0.3",
+    "@equinor/fusion-framework-module-app": "7.0.2",
+    "@equinor/fusion-framework-module-http": "7.0.2",
+    "@equinor/fusion-framework-module-service-discovery": "9.0.2"
   },
   "peerDependenciesMeta": {
     "typescript": {