@equinor/fusion-framework-cli 13.3.19-next.0 → 14.0.0

package/CHANGELOG.md

@@ -1,17 +1,123 @@
 # Change Log
 
-## 13.3.19-next.0
+## 14.0.0
+
+### Major Changes
+
+- abffa53: Major version bump for Fusion Framework React 19 release.
+
+  All packages are bumped to the next major version as part of the React 19 upgrade. This release drops support for React versions below 18 and includes breaking changes across the framework.
+
+  **Breaking changes:**
+  - Peer dependencies now require React 18 or 19 (`^18.0.0 || ^19.0.0`)
+  - React Router upgraded from v6 to v7
+  - Navigation module refactored with new history API
+  - `renderComponent` and `renderApp` now use `createRoot` API
+
+  **Migration:**
+  - Update your React version to 18.0.0 or higher before upgrading
+  - Replace `NavigationProvider.createRouter()` with `@equinor/fusion-framework-react-router`
+  - See individual package changelogs for package-specific migration steps
+
+### Minor Changes
+
+- abffa53: Add automatic support for `?raw` imports in Vite builds.
+
+  The CLI now automatically includes the `rawImportsPlugin` in Vite configurations, enabling `?raw` imports for markdown files (and other configured extensions) without manual plugin configuration.
+
+  ```typescript
+  import readmeContent from "../../README.md?raw";
+  ```
+
+  This ensures consistent behavior across all Fusion Framework CLI builds.
+
+- abffa53: Add `app serve` command to serve built applications with the dev-portal.
+
+  The new `serve` command provides a production-like preview environment for testing built applications locally. It serves your built application through the dev-portal, similar to the `dev` command but using production-built files.
+
+  ```sh
+  pnpm fusion-framework-cli app serve
+  pnpm fusion-framework-cli app serve --port 5000
+  pnpm fusion-framework-cli app serve --dir ./dist --host 0.0.0.0
+  ```
+
+  The command automatically detects the build directory from your Vite configuration and provides options for custom port, host, directory, manifest, and config files. The application must be built first using `ffc app build` before serving.
+
+- abffa53: Add route schema support to app manifests for documentation and API schema generation.
+
+  **New Features:**
+  - **module-app**: Added `RouteSchemaEntry` type and `routes` field to `AppManifest` interface
+  - **cli**: Added `RouteSchemaEntry` type export for app manifest generation
+
+  Route schemas allow applications to document their routes in app manifests, enabling automatic API documentation and schema generation. The `RouteSchemaEntry` type represents a route with its path, description, and optional parameter/search schemas.
+
+  ```typescript
+  import type {
+    RouteSchemaEntry,
+    AppManifest,
+  } from "@equinor/fusion-framework-module-app";
+
+  const manifest: AppManifest = {
+    appKey: "my-app",
+    displayName: "My App",
+    description: "My app description",
+    type: "standalone",
+    routes: [
+      ["/", "Home page"],
+      ["/products", "Products listing page"],
+      ["/products/:id", "Product detail page", { id: "Product ID" }],
+    ],
+  };
+  ```
 
 ### Patch Changes
 
-- [#3820](https://github.com/equinor/fusion-framework/pull/3820) [`f647825`](https://github.com/equinor/fusion-framework/commit/f647825cb5712763b09dafda21fd996211c78b78) Thanks [@odinr](https://github.com/odinr)! - relase next
+- ae92f13: Require `simple-git` 3.32.3 or newer in published package manifests to align installs with the upstream fix for CVE-2026-28292.
+
+  This does not change the CLI API. It tightens the minimum allowed dependency version so fresh installs and manifest-based scanners resolve the first safe `simple-git` release.
+
+- c123c39: chore: bump simple-git from 3.32.3 to 3.33.0
+
+  Includes security improvements:
+  - Pathspec input sanitization for git.clone() and git.mirror()
+  - Enhanced git -c safety checks
+
+- 3de232c: fix(cli): break turbo workspace cycle for AI plugins
+
+  Upgrade turbo from 2.8.10 to 2.8.14. This version introduces stricter workspace cycle detection, requiring the AI plugin dependencies to be moved from the CLI package's devDependencies to the root package.json.
+
+  The CLI plugins are now configured at the repository root (fusion-cli.config.ts) instead of in the packages/cli package, ensuring a clean workspace dependency graph for turbo's build scheduler.
+
+  This change has no impact on the published CLI package's public API. Plugins continue to be wired identically; only the source of the wire definition has changed.
+
+  Additional improvements from turbo 2.8.14:
+  - Fix: Ensures turbo watch mode respects task dependencies on first run
+  - Perf: Skip irrelevant packages for faster monorepo builds
+  - Feature: AI agent telemetry support in turbo traces
+
+- 32bcf83: Bump `vite` from `7.3.1` to `8.0.0`.
+
+  Vite 8 replaces Rollup with Rolldown and esbuild with Oxc for faster builds.
+  No breaking API changes affect this codebase. The `dev-server` peerDependency
+  is widened to accept both Vite 7 and Vite 8.
 
-- Updated dependencies [[`f647825`](https://github.com/equinor/fusion-framework/commit/f647825cb5712763b09dafda21fd996211c78b78), [`fa89ed8`](https://github.com/equinor/fusion-framework/commit/fa89ed8aeed919950ef6a6775e60eb6904ec7946)]:
-  - @equinor/fusion-framework-vite-plugin-raw-imports@1.1.0-next.1
-  - @equinor/fusion-imports@1.1.12-next.0
-  - @equinor/fusion-framework-dev-portal@5.0.0-next.0
-  - @equinor/fusion-framework-dev-server@1.1.32-next.0
-  - @equinor/fusion-framework-module-msal-node@3.0.2-next.0
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+- Updated dependencies [aa35c46]
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+- Updated dependencies [32bcf83]
+- Updated dependencies [abffa53]
+  - @equinor/fusion-framework-dev-portal@5.0.0
+  - @equinor/fusion-framework-dev-server@2.0.0
+  - @equinor/fusion-framework-module-msal-node@4.0.0
+  - @equinor/fusion-framework-vite-plugin-raw-imports@2.0.0
+  - @equinor/fusion-imports@2.0.0
 
 ## 13.3.18
 

package/README.md

@@ -1,242 +1,199 @@
-[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](./LICENSE)
+# @equinor/fusion-framework-cli
 
-Fusion Framework CLI is a command-line tool for developing, building, and publishing applications and portal templates within the Fusion Framework ecosystem. It streamlines workflows, automates common tasks, and supports modern CI/CD pipelines.
+Command-line toolkit for developing, building, and publishing Fusion Framework applications and portal templates. Provides a unified developer experience from local development to production deployment.
 
-**What you can build:**
-- **Fusion Applications**: Interactive web apps that run within the Fusion Portal
-- **Portal Templates**: Customizable portal configurations for different business contexts
+## Features
 
-**Key capabilities:**
-- **Template-based app creation**: Generate new Fusion applications from predefined templates
-- Development server with hot reload and service discovery
-- Application manifest and configuration management
-- Automated building, bundling, and deployment
-- Environment-specific configuration handling
-- Integrated authentication and authorization
-- CI/CD pipeline support with automated publishing
-- **Plugin system**: Extensible architecture with optional plugins (e.g., AI/LLM commands)
+- **Application scaffolding** — generate new Fusion apps from predefined templates
+- **Development server** — hot-reload dev server with service discovery and authentication
+- **Build & bundle** — Vite-based production builds with manifest generation
+- **Publish & tag** — upload bundles and configs to the Fusion app/portal service
+- **Snapshot versions** — timestamped preview builds for PRs and CI (`--snapshot`)
+- **Portal templates** — build, bundle, and deploy portal configurations
+- **Service discovery** — resolve Fusion service endpoints from any environment
+- **Authentication** — Azure AD login, token management, CI/CD token support
+- **Plugin system** — extend the CLI with optional plugin packages
 
-## Prerequisites
-
-- **Node.js** (LTS version recommended)
-- **pnpm** (or npm/yarn) package manager
-- **Fusion Framework app or portal project** (or create a new one)
-- **Access to Fusion services** (for authentication and deployment)
-
-## Features & Benefits
-
-- **🚀 Unified developer experience**: Single tool for the entire development lifecycle - from local development to production deployment
-- **⚡ Rapid local development**: Built-in dev server with hot reload, service discovery, and real-time feedback
-- **🎯 Environment-specific configuration**: Seamlessly manage manifests and configs across dev, test, and production environments
-- **🔐 Integrated authentication**: Secure your apps locally and in CI/CD with Azure AD integration and token management
-- **🔍 Service discovery**: Built-in support for Fusion services with automatic endpoint resolution
-- **📦 Automated bundling & deployment**: One-command building, packaging, and publishing to Fusion registry
-- **🏗️ Extensible architecture**: Support for apps, portals, widgets, and future Fusion components
-- **📚 Comprehensive documentation**: Migration guides, detailed setup instructions, and troubleshooting resources
-
-## Getting Started
-
-**Install the CLI**
+## Installation
 
 ```sh
 pnpm add -D @equinor/fusion-framework-cli
 ```
 
-**Create a new Fusion application from template**
+The package exposes two binary aliases: `fusion-framework-cli` and `ffc`.
 
-Generate a new Fusion application using predefined templates:
+## Usage
+
+### Create a new application
 
 ```sh
-# Create a new app with interactive template selection
-pnpm fusion-framework-cli app create my-new-app
+# Interactive template selection
+pnpm fusion-framework-cli app create my-app
 
-# Create with a specific template
+# Use a specific template
 pnpm fusion-framework-cli app create my-app --template react-app
-
-# Create in a specific directory with debug logging
-pnpm fusion-framework-cli app create my-app --directory ./projects --debug
 ```
 
-**Initialize or update your app's manifest and config files**
-
-Create the required configuration files for your app:
-
-- `app.manifest.ts` - Defines your app's metadata and capabilities
-- `app.config.ts` - Contains runtime configuration and environment variables
-
-See [Developing Apps](docs/application.md) for detailed setup and configuration guidance.
-
-**Start the development server**
+### Local development
 
 ```sh
+# Start the dev server (app)
 pnpm fusion-framework-cli dev
-```
-
-**Log in to the Fusion Framework (if needed)**
 
-```sh
-pnpm fusion-framework-cli auth login
+# Start the dev server (portal)
+pnpm fusion-framework-cli portal dev
 ```
 
-**Build and publish your app**
+### Build and publish
 
 ```sh
-# Publish without config
-pnpm fusion-framework-cli publish --env <environment>
-
-# Publish and upload config in one command
-pnpm fusion-framework-cli publish --env <environment> --config
-```
-
-**Build or publish snapshot artifacts**
-
-> [!CAUTION]
-> Snapshot versions are designed for **preview and testing purposes only** (e.g., pull requests, CI/CD test deployments). The snapshot version **only affects the manifest build metadata** — your `package.json` and source files remain unchanged.
+# Build an application
+pnpm fusion-framework-cli app build
 
-- Use `--snapshot` to emit timestamped snapshot versions
-- Default: `--snapshot` → `{version}-snapshot.{unix_timestamp}`
-- Optional identifier: `--snapshot pr-123` → `{version}-pr-123.{unix_timestamp}`
-- Semver coercion strips any pre-release suffix first, e.g. `1.2.3-beta.1` → `1.2.3-snapshot.{unix_timestamp}`
+# Bundle into a zip archive
+pnpm fusion-framework-cli app pack
 
-**Common use cases:**
-- Pull request previews: `--snapshot pr-456`
-- Nightly builds: `--snapshot nightly`
-- Feature branch testing: `--snapshot feature-xyz`
+# Publish bundle + config to an environment
+pnpm fusion-framework-cli app publish --env ci --config
 
-```sh
-# Package an app with a snapshot version
-pnpm fusion-framework-cli app pack --snapshot
+# Snapshot build for a PR
 pnpm fusion-framework-cli app pack --snapshot pr-123
-
-# Publish with a snapshot version
-pnpm fusion-framework-cli app publish --snapshot
-pnpm fusion-framework-cli app publish --snapshot nightly
 ```
 
-**Upload configuration**
+### Authentication
 
 ```sh
-# Upload config with publish command
-pnpm fusion-framework-cli publish --config --env <environment>
-
-# Or upload config separately
-pnpm fusion-framework-cli app config --publish --env <environment>
-```
+# Interactive login
+pnpm fusion-framework-cli auth login
 
-> **Tip:** For CI/CD and automation, set the `FUSION_TOKEN` environment variable. See [Authentication](docs/auth.md) for details.
+# Retrieve a token
+pnpm fusion-framework-cli auth token
 
-## Common Commands
+# CI/CD: set FUSION_TOKEN environment variable instead
+```
 
-| Command                                | Description                          |
-| -------------------------------------- | ------------------------------------ |
-| `pnpm fusion-framework-cli app create` | Create new Fusion applications from templates |
-| `pnpm fusion-framework-cli auth ...` | Authenticate with Fusion             |
-| `pnpm fusion-framework-cli app ...`    | Working with Fusion applications     |
-| `pnpm fusion-framework-cli portal ...` | Working with Fusion portal templates |
-| `pnpm fusion-framework-cli disco ...` | Service discovery and resolution     |
+### Command overview
 
-**Optional Plugins:**
 | Command | Description |
-|---------|-------------|
-| `pnpm fusion-framework-cli ai ...` | AI/LLM commands (requires `@equinor/fusion-framework-cli-plugin-ai`) |
-
-**Plugin System:**
-
-The CLI supports optional plugins that extend functionality. To use plugins:
-
-1. Install the plugin package: `pnpm add -D @equinor/fusion-framework-cli-plugin-ai`
-2. Create a `fusion-cli.config.ts` file in your project root:
-   ```typescript
-   import { defineFusionCli } from '@equinor/fusion-framework-cli';
-   
-   export default defineFusionCli(() => ({
-     plugins: [
-       '@equinor/fusion-framework-cli-plugin-ai',
-     ],
-   }));
-   ```
-
-Plugins are automatically discovered and loaded when the CLI starts. The config file can be `.ts`, `.js`, or `.json`. If no config file exists, the CLI works normally without plugins.
-
-## Example: package.json
-
-A minimal example for a Fusion Framework app:
-
-```json
-{
-  "name": "@equinor/fusion-framework-app",
-  "version": "1.0.0",
-  "description": "My Fusion Framework Application",
-  "main": "dist/bundle.js",
-  "files": [
-    "dist/",
-    "assets/",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "fusion-framework-cli app build",
-    "dev": "fusion-framework-cli dev",
-    "publish": "fusion-framework-cli app publish"
-  },
-  "devDependencies": {
-    "@equinor/fusion-framework-cli": "^11.0.0"
-  }
-}
+|---|---|
+| `app create` | Scaffold a new Fusion application from a template |
+| `app build` | Build the application with Vite |
+| `app pack` | Bundle the build into a zip archive |
+| `app publish` | Build, pack, and upload in one step |
+| `app upload` | Upload a pre-built bundle |
+| `app config` | Generate or publish app configuration |
+| `app tag` | Tag a published version (e.g. `latest`) |
+| `app check` | Verify app registration in the app store |
+| `app dev` | Start the application dev server |
+| `app serve` | Preview a production build locally |
+| `portal build` | Build a portal template |
+| `portal pack` | Bundle the portal into a zip archive |
+| `portal publish` | Build, pack, and upload a portal |
+| `portal upload` | Upload a pre-built portal bundle |
+| `portal config` | Generate or publish portal configuration |
+| `portal tag` | Tag a published portal version |
+| `portal dev` | Start the portal dev server |
+| `auth login` | Authenticate with Azure AD |
+| `auth logout` | Clear stored credentials |
+| `auth token` | Print or acquire an access token |
+| `disco resolve` | Resolve a Fusion service endpoint |
+
+Run `pnpm fusion-framework-cli <command> --help` for detailed options.
+
+## API Reference
+
+The package exposes several sub-path exports for programmatic use:
+
+### `@equinor/fusion-framework-cli` (root)
+
+- `defineDevServerConfig` / `defineFusionCli` — type-safe config definition helpers
+- `loadDevServerConfig` — load and merge dev-server configuration files
+- `resolvePackage` / `resolveEntryPoint` — package and entry-point resolution
+- `RuntimeEnv` — runtime environment type used across the CLI
+
+### `@equinor/fusion-framework-cli/app`
+
+- `defineAppManifest` / `defineAppConfig` — type-safe manifest and config helpers
+- `loadAppManifest` / `loadAppConfig` — load and validate app manifest/config files
+- `createAppManifestFromPackage` — generate a manifest from `package.json`
+- `mergeAppManifests` / `mergeAppConfig` — deep-merge manifest/config objects
+- `ApiAppConfigSchema` — Zod schema for app config validation
+
+### `@equinor/fusion-framework-cli/portal`
+
+- `definePortalManifest` / `definePortalConfig` / `definePortalSchema` — type-safe helpers
+- `loadPortalManifest` / `loadPortalConfig` / `loadPortalSchema` — load and validate files
+- `createPortalManifestFromPackage` — generate a portal manifest from `package.json`
+- `validatePortalManifest` — validate a manifest against the Zod schema
+
+### `@equinor/fusion-framework-cli/bin`
+
+- `buildApplication` / `buildPortal` — programmatic Vite builds
+- `bundleApp` / `bundlePortal` — build + pack into zip
+- `uploadApplication` / `uploadPortalBundle` — upload bundles to the service
+- `tagApplication` / `tagPortal` — tag published versions
+- `initializeFramework` / `configureFramework` — set up the Fusion Framework for CLI operations
+- `FusionEnv` — enum of supported Fusion environments
+
+### `@equinor/fusion-framework-cli/utils`
+
+- `assert` / `assertFileExists` / `assertObject` — assertion helpers
+- `fileExists` / `fileExistsSync` — file-existence checks
+- `writeFile` — write files with automatic directory creation
+- `resolveAnnotations` — resolve CI/CD build annotations
+- `generateSnapshotVersion` — create timestamped snapshot versions
+
+## Configuration
+
+### Application manifest (`app.manifest.ts`)
+
+```ts
+import { defineAppManifest } from '@equinor/fusion-framework-cli/app';
+
+export default defineAppManifest((env, { base }) => ({
+  ...base,
+  // override manifest fields here
+}));
 ```
 
-**Key fields:**
-- `main`: **Required** - Points to your build output directory (CLI uses this to determine where to place built files)
-- `files`: Specifies which files to include in your app bundle
-- `scripts`: Convenient shortcuts for common CLI commands
-
-> **Note:** The CLI determines the build output location from the `main` field in your package.json. If not specified, it defaults to `dist/bundle.js`.
-
-## Documentation
+### Application config (`app.config.ts`)
 
-**Getting Started**
-- [Developing Apps](docs/application.md): Complete guide to building, configuring, and deploying Fusion applications
-- [Developing Portals](docs/portal.md): Guide to building, configuring, and publishing portal templates
-- [Dev Server](docs/dev-server.md): Understanding how the development server works, including architecture and configuration
+```ts
+import { defineAppConfig } from '@equinor/fusion-framework-cli/app';
 
-**Setup & Configuration**
-- [Authentication](docs/auth.md): Setting up authentication for local development and CI/CD environments
-- [libsecret Installation](https://equinor.github.io/fusion-framework/modules/auth/msal-node/docs/libsecret.html): Fix credential storage issues on Linux systems
-
-**Migration & Updates**
-- [Migration Guide: v10 to v11](docs/migration-v10-to-v11.md): Breaking changes, deprecated commands, and upgrade instructions
-
-**Additional Resources**
-- [CLI Command Reference](docs/application.md#commands): Detailed documentation of all available commands and options
-- [CI/CD Best Practices](docs/application.md#ci-cd): Automated workflows and deployment strategies
-- [Troubleshooting Guide](docs/application.md#troubleshooting-faq): Common issues and solutions
-
-**Internal Tools** (Fusion Core Team Only)
-- [AI Commands](docs/ai-commands.md): ⚠️ **Internal use only** - AI-powered chat, embeddings, and search commands for codebase understanding (not supported for third-party users ...yet)
-
-  ## Troubleshooting
+export default defineAppConfig((env, { base }) => ({
+  environment: { MY_VAR: 'value' },
+  endpoints: {
+    api: { url: 'https://api.example.com', scopes: ['api://scope/.default'] },
+  },
+}));
+```
 
-### Common Issues
+### Dev-server config (`dev-server.config.ts`)
 
-**Authentication & Credentials**
-- **Authentication issues?** See [Authentication Guide](docs/auth.md) for token setup and troubleshooting
-- **libsecret errors on Linux?** Install libsecret using our [installation guide](https://equinor.github.io/fusion-framework/modules/auth/msal-node/#troubleshooting)
+```ts
+import { defineDevServerConfig } from '@equinor/fusion-framework-cli';
 
-**CLI & Commands**
-- **Command not found?** Ensure `node_modules/.bin` is in your PATH or use `pnpm`/`npx`
-- **Permission errors?** Check that you have the correct access rights to Fusion services
+export default defineDevServerConfig((env, { base }) => ({
+  ...base,
+  // override dev-server options here
+}));
+```
 
-**Build & Development**
-- **Build errors?** Verify your `app.manifest.ts` and `app.config.ts` files for syntax errors
-- **Dev server not starting?** Check for port conflicts (default: 3000) or use `--port` option
-- **Missing dependencies?** Ensure all required packages are installed with `pnpm install`
+### CLI plugins (`fusion-cli.config.ts`)
 
-**Publishing & Deployment**
-- **Upload failures?** Verify your app is registered in the Fusion App Admin
-- **Environment issues?** Check that you're using the correct `--env` parameter
+```ts
+import { defineFusionCli } from '@equinor/fusion-framework-cli';
 
-### Getting Help
+export default defineFusionCli(() => ({
+  plugins: ['@equinor/fusion-framework-cli-plugin-ai'],
+}));
+```
 
-- **Detailed troubleshooting:** See our [comprehensive troubleshooting guide](docs/application.md#troubleshooting-faq)
-- **Found a bug?** Open an issue on our GitHub repository
-- **Need support?** Check the [docs folder](docs/) or reach out to the Fusion team
+## Documentation
 
+- [Developing Apps](docs/application.md) — build, configure, and deploy applications
+- [Developing Portals](docs/portal.md) — build and publish portal templates
+- [Dev Server](docs/dev-server.md) — architecture and configuration
+- [Authentication](docs/auth.md) — local and CI/CD authentication setup
+- [Migration v10 → v11](docs/migration-v10-to-v11.md) — breaking changes and upgrade steps