c8y-nitro 0.5.0 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # c8y-nitro
 
-Lightning fast Cumulocity IoT microservice development powered by [Nitro](https://v3.nitro.build).
+Nitro-powered tooling for building Cumulocity IoT microservices without manually stitching together bootstrap, manifest generation, packaging, and tenant-aware runtime helpers.
 
 ## Features
 
@@ -14,534 +14,37 @@ Lightning fast Cumulocity IoT microservice development powered by [Nitro](https:
 - 🛠️ **TypeScript First** - Full type safety with excellent DX
 - 🔄 **Auto-Bootstrap** - Automatically registers and configures your microservice in development
 
-## Quick Start
+## Quickstart
 
-The fastest way to get started is using the [c8y-nitro-starter](https://github.com/schplitt/c8y-nitro-starter) template:
+Start with the [Quickstart docs](https://schplitt.github.io/c8y-nitro/quickstart).
 
-```sh
-pnpm dlx giget@latest gh:schplitt/c8y-nitro-starter my-microservice
-cd my-microservice
-pnpm install
-```
-
-Configure your development tenant in `.env`:
-
-```sh
-C8Y_BASEURL=https://your-tenant.cumulocity.com
-C8Y_DEVELOPMENT_TENANT=t12345
-C8Y_DEVELOPMENT_USER=your-username
-C8Y_DEVELOPMENT_PASSWORD=your-password
-```
-
-Then start developing:
-
-```sh
-pnpm dev
-```
-
-## Installation
-
-```sh
-pnpm add c8y-nitro nitro@latest
-```
-
-## Usage
-
-Configure your Cumulocity microservice in `nitro.config.ts`:
-
-```ts
-import c8y from 'c8y-nitro'
-
-export default defineNitroConfig({
-  preset: 'node-server', // or "node-cluster", Required!
-  c8y: {
-    // c8y-nitro configuration options go here
-  },
-  modules: [c8y()],
-})
-```
-
-### Prerequisites
-
-`c8y-nitro` requires:
-
-- `preset` - must be a node preset (`node-server` or `node-cluster`)
-
-**Recommended:**
-
-- `builder: 'rolldown'` - for faster build times
-
-**Optional:**
-
-- `experimental.asyncContext: true` - enables using utility functions without passing event/request parameters
-
-## Getting Started
-
-Create a `.env` or `.env.local` file with your development tenant credentials:
-
-```sh
-C8Y_BASEURL=https://your-tenant.cumulocity.com
-C8Y_DEVELOPMENT_TENANT=t12345
-C8Y_DEVELOPMENT_USER=your-username
-C8Y_DEVELOPMENT_PASSWORD=your-password
-```
-
-Then simply run `pnpm dev` - that's it! The module will automatically:
-
-1. Check if the microservice exists on the tenant
-2. Create it if needed (or use existing one without overwriting)
-3. Subscribe your tenant to the microservice
-4. Retrieve and save bootstrap credentials to your env file
-
-After auto-bootstrap, your env file will contain:
-
-```sh
-C8Y_BOOTSTRAP_TENANT=<bootstrap-tenant-id>
-C8Y_BOOTSTRAP_USER=<bootstrap-username>
-C8Y_BOOTSTRAP_PASSWORD=<generated-password>
-```
-
-> **Manual Bootstrap**: For more control or troubleshooting, you can use the [CLI bootstrap command](#cli-commands) to manually register your microservice.
-
-> **Disable Auto-Bootstrap**: Set `skipBootstrap: true` in your c8y config to disable auto-bootstrap entirely. This is useful in CI/CD pipelines or when you want to manage bootstrap manually.
-
-## Automatic Zip Creation
-
-`c8y-nitro` automatically generates a ready-to-deploy microservice zip package after each build. The process includes:
-
-1. **Dockerfile Generation** - Creates an optimized Dockerfile using Node.js 22-slim
-2. **Docker Image Build** - Builds and saves the Docker image to `image.tar`
-3. **Manifest Generation** - Creates `cumulocity.json` from your package.json and configuration
-4. **Zip Package** - Combines `image.tar` and `cumulocity.json` into a deployable zip file
-
-> **Note**: Docker must be installed and available in your PATH.
-
-The generated zip file (default: `<package-name>-<version>.zip` in root directory) is ready to upload directly to Cumulocity.
-
-## Manifest Configuration
-
-The `cumulocity.json` manifest is automatically generated from your `package.json` and can be customized via the `manifest` option.
-
-**Auto-generated from package.json:**
-
-- `name` (scope stripped), `version` - from package fields
-- `provider.name` - from `author` field
-- `provider.domain` - from `author.url` or `homepage`
-- `provider.support` - from `bugs` or `author.email`
-- `contextPath` - defaults to package name
-
-For all available manifest options, see the [Cumulocity Microservice Manifest documentation](https://cumulocity.com/docs/microservice-sdk/general-aspects/#microservice-manifest).
-
-> **Note**: Custom roles defined in the manifest are automatically available as TypeScript types for use in middleware and runtime code during development.
-
-> **Note**: Health probe endpoints (`/_c8y_nitro/liveness` and `/_c8y_nitro/readiness`) are automatically injected if not manually defined.
-
-## Cache Configuration
-
-Credential caching can be configured to optimize performance. By default, subscribed tenant credentials are cached for 10 minutes.
-
-```ts
-export default defineNitroConfig({
-  c8y: {
-    enableTenantOptionsInvalidationRoute: false,
-    cache: {
-      credentialsTTL: 300, // Cache credentials for 5 minutes (in seconds)
-      defaultTenantOptionsTTL: 600, // Default cache for tenant options (in seconds)
-      tenantOptions: {
-        'myOption': 300, // Per-key override: 5 minutes
-        'credentials.secret': 60, // Per-key override: 1 minute
-      },
-    }
-  },
-  modules: [c8y()],
-})
-```
-
-You can also override these at runtime using environment variables:
-
-```sh
-NITRO_C8Y_CREDENTIALS_CACHE_TTL=300
-NITRO_C8Y_DEFAULT_TENANT_OPTIONS_TTL=300
-```
-
-> **Note**: The credentials cache is used by `useSubscribedTenantCredentials()` and `useDeployedTenantCredentials()` utilities. Both share the same cache.
-
-## Development User Injection
-
-During development, `c8y-nitro` automatically injects your development user credentials into all requests. This allows you to test authentication and authorization middlewares locally.
-
-The module uses the development credentials from your `.env` file:
-
-```sh
-C8Y_DEVELOPMENT_TENANT=t12345
-C8Y_DEVELOPMENT_USER=your-username
-C8Y_DEVELOPMENT_PASSWORD=your-password
-```
-
-This enables testing of access control middlewares like `hasUserRequiredRole()` and `isUserFromAllowedTenant()` without needing to manually set authorization headers.
-
-If you run a local proxy that already forwards a user session or authorization header, disable this middleware:
-
-```ts
-export default defineNitroConfig({
-  c8y: {
-    dev: {
-      injectUser: false,
-    },
-  },
-  modules: [c8y()],
-})
-```
-
-When disabled, `c8y-nitro` does not register the development user injection middleware, so incoming auth headers stay untouched.
-
-### Managing Development User Roles
-
-Use the [CLI roles command](#cli-commands) to assign or remove your microservice's custom roles to your development user:
-
-```sh
-pnpm dlx c8y-nitro roles
-```
-
-This interactive command lets you select which roles from your manifest to assign to your development user for testing.
-
-## API Client Generation
-
-For monorepo architectures, `c8y-nitro` can generate TypeScript Angular services that provide fully typed access to your microservice routes.
-
-### Configuration
-
-```ts
-export default defineNitroConfig({
-  c8y: {
-    apiClient: {
-      dir: '../ui/src/app/services', // Output directory for generated client
-      contextPath: 'my-service' // Optional: override context path
-    }
-  },
-  modules: [c8y()],
-})
-```
-
-### Generated Client
-
-The generated service creates one method per route with automatic type inference:
-
-```ts
-// Generated: my-serviceAPIClient.ts
-@Injectable({ providedIn: 'root' })
-export class GeneratedMyServiceAPIClient {
-  async GETHealth(): Promise<{ status: string }> { }
-  async GETUsersById(params: { id: string | number }): Promise<User> { }
-  async POSTUsers(body: CreateUserDto): Promise<User> { }
-}
-```
-
-### Usage in Angular
-
-```ts
-import { GeneratedMyServiceAPIClient } from './services/my-serviceAPIClient'
-
-@Component({
-  /**
-   * ...
-   */
-})
-export class MyComponent {
-  private api = inject(GeneratedMyServiceAPIClient)
+## Documentation
 
-  async ngOnInit() {
-    const health = await this.api.GETHealth()
-    const user = await this.api.GETUsersById({ id: 123 })
-  }
-}
-```
-
-> **Note**: The client regenerates automatically when routes change during development.
-
-## Logging
-
-`c8y-nitro` builds on [evlog](https://www.evlog.dev) to provide structured **wide-event logging**, one comprehensive log per request that accumulates all relevant context rather than scattering individual log lines throughout your code.
-
-evlog is automatically configured, no extra setup required. The service name is derived from your package name.
-
-### useLogger
-
-Use `useLogger(event)` in your route handlers to get a request-scoped logger. The logger accumulates context throughout the request lifetime and emits a single wide event when the response is sent.
-
-```ts
-import { defineHandler } from 'nitro/h3'
-import { useLogger } from 'c8y-nitro/utils'
-
-export default defineHandler(async (event) => {
-  const log = useLogger(event)
-
-  const user = await useUser(event)
-  log.set({ action: 'process-order', user: { id: user.userName } })
-
-  // Add more context as it becomes available
-  log.set({ order: { id: '42', total: 9999 } })
-
-  return { success: true }
-})
-```
-
-> **Note**: `useLogger` requires the `event` parameter. If you enable `experimental.asyncContext: true` in your Nitro config, you can access the logger anywhere in the call stack via `useRequest()` from `nitro/context` — see the [evlog Nitro v3 setup](https://www.evlog.dev/getting-started/installation#nitro-v3) for details.
-
-### createError
-
-Use `createError` from `c8y-nitro/utils` instead of Nitro's built-in error helper to get richer, structured error responses. This adds `why`, `fix`, and `link` fields that are:
-
-- Logged as part of the wide event so you can see exactly what went wrong without guessing
-- Returned in the JSON response body so clients can display actionable context
-
-```ts
-import { defineHandler } from 'nitro/h3'
-import { useLogger, createError } from 'c8y-nitro/utils'
-
-export default defineHandler(async (event) => {
-  const log = useLogger(event)
-  log.set({ action: 'payment', userId: 'user_123' })
-
-  throw createError({
-    message: 'Payment failed',
-    status: 402,
-    why: 'Card declined by issuer (insufficient funds)',
-    fix: 'Try a different payment method or contact your bank',
-    link: 'https://docs.example.com/payments/declined',
-  })
-})
-```
-
-The error response returned to the client:
-
-```json
-{
-  "message": "Payment failed",
-  "status": 402,
-  "data": {
-    "why": "Card declined by issuer (insufficient funds)",
-    "fix": "Try a different payment method or contact your bank",
-    "link": "https://docs.example.com/payments/declined"
-  }
-}
-```
-
-> **Tip**: Always prefer `createError` from `c8y-nitro/utils`. It ensures the error is captured in the wide log event with full context, making investigation straightforward.
-
-### createLogger (standalone)
-
-For code that runs **outside a request handler** — background jobs, queue workers, event-driven workflows, scheduled tasks — use `createLogger()` to get the same wide-event logger interface without needing an HTTP event.
-
-```ts
-import { createLogger } from 'c8y-nitro/utils'
-
-export async function processSubscriptionRenewal(tenantId: string) {
-  const log = createLogger({ job: 'subscription-renewal', tenantId })
-
-  log.set({ subscription: { id: 'sub_123', plan: 'pro' } })
-
-  // ... do work ...
-
-  log.set({ result: 'renewed' })
-  log.emit() // Must call emit() manually outside request context
-}
-```
-
-This is useful for Cumulocity notification workflows where your microservice reacts to platform events (device management, alarms, etc.) outside of the standard request/response cycle.
-
-> **Note**: Unlike `useLogger`, `createLogger` does **not** auto-emit at request end. You must call `log.emit()` manually when the work is complete.
+Full documentation is available at [schplitt.github.io/c8y-nitro](https://schplitt.github.io/c8y-nitro/).
 
-For more on wide events, structured errors, and advanced configuration (sampling, draining to Axiom/Loki, enrichers), see the [evlog documentation](https://www.evlog.dev/core-concepts/wide-events).
-
-### Logging Utilities
-
-| Function               | Description                                                   | Request Context |
-| ---------------------- | ------------------------------------------------------------- | :-------------: |
-| `useLogger(event)`     | Get the request-scoped wide-event logger                      |       ✅        |
-| `createLogger(ctx?)`   | Create a standalone wide-event logger; call `emit()` manually |       ❌        |
-| `createError(options)` | Create a structured error with `why`, `fix`, `link`           |       ❌        |
-
-## Utilities
-
-`c8y-nitro` provides several utility functions to simplify common tasks in Cumulocity microservices.
-
-To use these utilities, simply import them from `c8y-nitro/utils`:
-
-```ts
-import { useUser, useUserClient } from 'c8y-nitro/utils'
-```
-
-### Usage
-
-All utility functions that require request context accept either an `H3Event` or `ServerRequest` parameter:
-
-```ts
-// Pass the event/request parameter
-export default defineHandler(async (event) => {
-  const user = await useUser(event)
-  const client = useUserClient(event)
-  return { user }
-})
-```
+Useful entry points:
 
-**Optional: Using with `asyncContext`**
-
-If you enable `experimental.asyncContext: true` in your Nitro config, you can use Nitro's `useRequest()` to avoid passing the event through deeply nested function calls:
-
-```ts
-import { useRequest } from 'nitro/context'
-
-export default defineHandler(async (event) => {
-  // Deep nested function - no need to pass event down
-  return await someDeepFunction()
-})
-
-async function someDeepFunction() {
-  return await anotherFunction()
-}
-
-async function anotherFunction() {
-  // Use useRequest() to get the request in any nested function
-  const request = useRequest()
-  const user = await useUser(request)
-  return { user }
-}
-```
-
-### Credentials
-
-| Function                           | Description                                                        | Request Context |
-| ---------------------------------- | ------------------------------------------------------------------ | :-------------: |
-| `useSubscribedTenantCredentials()` | Get credentials for all subscribed tenants (cached, default 10min) |       ❌        |
-| `useDeployedTenantCredentials()`   | Get credentials for the deployed tenant (cached, default 10min)    |       ❌        |
-| `useUserTenantCredentials()`       | Get credentials for the current user's tenant                      |       ✅        |
-
-> **Note**: `useDeployedTenantCredentials()` shares its cache with `useSubscribedTenantCredentials()`. Both functions support `.invalidate()` and `.refresh()` methods. Invalidating or refreshing one will affect the other.
->
-> **Cache Duration**: The cache TTL is configurable via the `cache.credentialsTTL` option or `NITRO_C8Y_CREDENTIALS_CACHE_TTL` environment variable. See [Cache Configuration](#cache-configuration) for details.
-
-### Tenant Options
-
-| Function            | Description                                              | Request Context |
-| ------------------- | -------------------------------------------------------- | :-------------: |
-| `useTenantOption()` | Get a tenant option value by key (cached, default 10min) |       ❌        |
-
-Fetch tenant options (settings) configured for your microservice:
-
-```ts
-import { useTenantOption } from 'c8y-nitro/utils'
-
-export default defineHandler(async (event) => {
-  // Fetch a tenant option
-  const value = await useTenantOption('myOption')
-
-  // Fetch an encrypted secret
-  const secret = await useTenantOption('credentials.apiKey')
-
-  // Cache management
-  await useTenantOption.invalidate('myOption') // Invalidate specific key
-  const fresh = await useTenantOption.refresh('myOption') // Force refresh
-  await useTenantOption.invalidateAll() // Invalidate all accessed keys
-  await useTenantOption.refreshAll() // Refresh all accessed keys
-  return { value, secret, fresh }
-})
-```
-
-Define your settings in the manifest to get type-safe keys:
-
-```ts
-export default defineNitroConfig({
-  c8y: {
-    manifest: {
-      settings: [
-        { key: 'myOption', defaultValue: 'default' },
-        { key: 'credentials.secret', defaultValue: 'change-me' }, // Encrypted option
-      ],
-      settingsCategory: 'my-service', // Optional, defaults to contextPath/name
-      requiredRoles: ['ROLE_OPTION_MANAGEMENT_READ'], // Required for reading tenant options
-    },
-  },
-  modules: [c8y()],
-})
-```
-
-`manifest.settings[].defaultValue` is required and must be a non-empty string. `''` is rejected during manifest generation so invalid settings fail early during development/build.
-
-> **Important**: To read tenant options, your microservice **must** have the `ROLE_OPTION_MANAGEMENT_READ` role in `manifest.requiredRoles`. Without this role, API calls will fail with a 403 Forbidden error.
-
-> **Note on Encrypted Options**: Keys prefixed with `credentials.` are stored encrypted by Cumulocity. See more details [here](https://cumulocity.com/api/core/#operation/postOptionCollectionResource).
-
-> **Note on Missing Options**: If a tenant option is not set (404 Not Found), `useTenantOption()` returns `undefined` instead of throwing an error. Other errors (e.g., 403 Forbidden) are thrown normally.
-
-### Resources
-
-| Function         | Description                        | Request Context |
-| ---------------- | ---------------------------------- | :-------------: |
-| `useUser()`      | Fetch current user from Cumulocity |       ✅        |
-| `useUserRoles()` | Get roles of the current user      |       ✅        |
-
-### Client
-
-| Function                       | Description                                         | Request Context |
-| ------------------------------ | --------------------------------------------------- | :-------------: |
-| `useUserClient()`              | Create client authenticated with user's credentials |       ✅        |
-| `useUserTenantClient()`        | Create client for user's tenant (microservice user) |       ✅        |
-| `useSubscribedTenantClients()` | Create clients for all subscribed tenants           |       ❌        |
-| `useDeployedTenantClient()`    | Create client for the deployed tenant               |       ❌        |
-
-### Middleware
-
-| Function                                   | Description                               | Request Context |
-| ------------------------------------------ | ----------------------------------------- | :-------------: |
-| `hasUserRequiredRole(role\|roles)`         | Check if user has required role(s)        |       ✅        |
-| `isUserFromAllowedTenant(tenant\|tenants)` | Check if user is from allowed tenant(s)   |       ✅        |
-| `isUserFromDeployedTenant()`               | Check if user is from the deployed tenant |       ✅        |
-
-Probe requests targeting the manifest-defined `livenessProbe.httpGet.path` or `readinessProbe.httpGet.path` bypass these auth helpers so orchestration health checks are not blocked by route-wide access control.
-
-## CLI Commands
-
-| Command     | Description                                             |
-| ----------- | ------------------------------------------------------- |
-| `bootstrap` | Manually register microservice and retrieve credentials |
-| `roles`     | Manage development user roles                           |
-| `options`   | Manage tenant options on development tenant             |
-
-For more information, run:
-
-```sh
-pnpm dlx c8y-nitro -h
-```
+- [What is c8y-nitro?](https://schplitt.github.io/c8y-nitro/guide/what-is-c8y-nitro)
+- [Configuration](https://schplitt.github.io/c8y-nitro/guide/configuration)
+- [Module Options](https://schplitt.github.io/c8y-nitro/reference/module-options)
+- [Utilities](https://schplitt.github.io/c8y-nitro/reference/utilities)
 
 ## Development
 
+For contributors working on this repository:
+
 ```sh
-# Install dependencies
 pnpm install
-
-# Run dev watcher
 pnpm dev
-
-# Build for production
 pnpm build
-
-# Run tests (watch mode)
-pnpm test
-
-# Run tests once
 pnpm test:run
+pnpm lint
+pnpm typecheck
+pnpm docs:build
 ```
 
-### Testing
-
-Tests are organized in two categories:
-
-- **Unit tests** (`tests/unit/`) — Test individual functions in isolation
-- **Server tests** (`tests/server/`) — Integration tests that spin up a Nitro dev server with the c8y-nitro module
-
-Server tests use Nitro's virtual modules to mock `@c8y/client` at build time, allowing full integration testing without real Cumulocity API calls. See [AGENTS.md](AGENTS.md#server-integration-tests) for implementation details.
+Use `pnpm dev` for the package watcher, `pnpm docs:dev` for the VitePress site, and check the full contributor-facing behavior in the docs plus <AGENTS.md>.
 
 ## License
 
-MIT
+Use `pnpm dev` for the package watcher, `pnpm docs:dev` for the VitePress site, and check the full contributor-facing behavior in the docs plus <AGENTS.md>.

package/dist/{bootstrap-BSdVwFWO.mjs → bootstrap-ObaEF7rN.mjs}

@@ -1,6 +1,6 @@
-import { a as findMicroserviceByName, d as updateMicroservice, l as subscribeToApplication, n as createBasicAuthHeader, o as getBootstrapCredentials, p as createC8yManifest, r as createMicroservice } from "./c8y-api-BgTNTqHd.mjs";
-import { t as writeBootstrapCredentials } from "./env-file-B0BK-uZW.mjs";
-import { n as validateBootstrapEnv, t as loadC8yConfig } from "./config-BRnvtthI.mjs";
+import { a as findMicroserviceByName, d as updateMicroservice, l as subscribeToApplication, n as createBasicAuthHeader, o as getBootstrapCredentials, p as createC8yManifest, r as createMicroservice } from "./c8y-api-BFjK6AYb.mjs";
+import { t as writeBootstrapCredentials } from "./env-file-BrOTmVjA.mjs";
+import { n as validateBootstrapEnv, t as loadC8yConfig } from "./config-BVQHqlgV.mjs";
 import { defineCommand, runCommand } from "citty";
 import { consola } from "consola";
 //#region src/cli/commands/bootstrap.ts
@@ -12,11 +12,11 @@ var bootstrap_default = defineCommand({
 	args: {},
 	async run() {
 		consola.info("Loading configuration...");
-		const { env, c8yOptions, configDir } = await loadC8yConfig();
+		const { env, nitroConfig, configDir } = await loadC8yConfig();
 		consola.info("Validating environment variables...");
 		const envVars = validateBootstrapEnv(env);
 		consola.info("Building manifest...");
-		const manifest = await createC8yManifest(configDir, c8yOptions?.manifest);
+		const manifest = await createC8yManifest(configDir, nitroConfig);
 		consola.success(`Manifest created for: ${manifest.name} v${manifest.version}`);
 		const authHeader = createBasicAuthHeader(envVars.C8Y_DEVELOPMENT_TENANT, envVars.C8Y_DEVELOPMENT_USER, envVars.C8Y_DEVELOPMENT_PASSWORD);
 		consola.info(`Checking if microservice "${manifest.name}" exists...`);
@@ -52,7 +52,7 @@ var bootstrap_default = defineCommand({
 		});
 		consola.success(`Bootstrap credentials written to ${envFileName}`);
 		if (manifest.roles && manifest.roles.length > 0) {
-			if (await consola.prompt("Do you want to manage microservice roles for your development user?", { type: "confirm" })) await runCommand(await import("./roles-CoBPqvDv.mjs").then((r) => r.default), { rawArgs: [] });
+			if (await consola.prompt("Do you want to manage microservice roles for your development user?", { type: "confirm" })) await runCommand(await import("./roles-B58Fguop.mjs").then((r) => r.default), { rawArgs: [] });
 		}
 		consola.success("Bootstrap complete!");
 	}

package/dist/{c8y-api-BgTNTqHd.mjs → c8y-api-BFjK6AYb.mjs}

@@ -6,6 +6,29 @@ const GENERATED_READINESS_ROUTE = "/_c8y_nitro/readiness";
 const GENERATED_INVALIDATE_TENANT_OPTIONS_ROUTE = "/_c8y_nitro/invalidate-tenant-options";
 //#endregion
 //#region src/module/manifest.ts
+const DEFAULT_OPENAPI_ROUTE = "/_openapi.json";
+const ROLE_OPTION_MANAGEMENT_READ = "ROLE_OPTION_MANAGEMENT_READ";
+/**
+* Decide whether Nitro will expose an OpenAPI spec in the deployed build,
+* and if so return the configured route (with leading slash).
+* Returns null when OpenAPI is not enabled for production.
+* @param config - Nitro config (or options) to inspect
+*/
+function resolveNitroOpenApiRoute(config) {
+	if (!config.experimental?.openAPI) return null;
+	if (!config.openAPI?.production) return null;
+	return config.openAPI?.route || DEFAULT_OPENAPI_ROUTE;
+}
+/**
+* Pull the parts of a Nitro config that feed manifest generation.
+* @param config - Nitro config (or options) loaded from disk or from a Nitro instance
+*/
+function extractManifestInputs(config) {
+	return {
+		options: config.c8y?.manifest ?? {},
+		openApiSpec: resolveNitroOpenApiRoute(config) ?? void 0
+	};
+}
 function validateManifestSettings(options) {
 	const invalidSettings = options.settings?.filter((setting) => typeof setting.defaultValue !== "string" || setting.defaultValue.length === 0) ?? [];
 	if (invalidSettings.length === 0) return;
@@ -37,13 +60,18 @@ async function readPackageJsonFieldsForManifest(rootDir, logger) {
 	};
 }
 /**
-* Creates a Cumulocity manifest from rootDir and options.
-* Standalone function that can be used by CLI or module.
-* @param rootDir - Directory containing package.json
-* @param options - Manifest options
+* Create a Cumulocity manifest from a project root and its Nitro config.
+* Reads `package.json` for identity fields, takes user manifest options from
+* `nitroConfig.c8y.manifest`, and auto-injects `openApiSpec` when Nitro
+* OpenAPI is enabled for production.
+*
+* Used by both the Nitro module and the CLI commands.
+* @param rootDir - Directory containing the project's `package.json`
+* @param nitroConfig - Nitro config (or options) for this project
 * @param logger - Optional logger for debug output
 */
-async function createC8yManifest(rootDir, options = {}, logger) {
+async function createC8yManifest(rootDir, nitroConfig = {}, logger) {
+	const { options, openApiSpec } = extractManifestInputs(nitroConfig);
 	validateManifestSettings(options);
 	const { name, version, provider, ...restManifestFields } = await readPackageJsonFieldsForManifest(rootDir, logger);
 	const probeFields = {};
@@ -56,10 +84,17 @@ async function createC8yManifest(rootDir, options = {}, logger) {
 		httpGet: { path: GENERATED_READINESS_ROUTE }
 	};
 	const key = `${name}-key`;
+	let requiredRoles = options.requiredRoles ? [...options.requiredRoles] : void 0;
+	if (options.settings && options.settings.length > 0 && !requiredRoles?.includes(ROLE_OPTION_MANAGEMENT_READ)) {
+		requiredRoles = [...requiredRoles ?? [], ROLE_OPTION_MANAGEMENT_READ];
+		logger?.debug(`Auto-added ${ROLE_OPTION_MANAGEMENT_READ} to requiredRoles because manifest.settings are defined`);
+	}
 	const manifest = {
 		...restManifestFields,
 		...probeFields,
 		...options,
+		...requiredRoles !== void 0 ? { requiredRoles } : {},
+		...openApiSpec ? { openApiSpec } : {},
 		provider,
 		name,
 		version,
@@ -67,6 +102,7 @@ async function createC8yManifest(rootDir, options = {}, logger) {
 		key,
 		type: "MICROSERVICE"
 	};
+	if (openApiSpec) logger?.debug(`Auto-added openApiSpec="${openApiSpec}" to manifest (Nitro OpenAPI is enabled)`);
 	logger?.debug(`Created Cumulocity manifest: ${JSON.stringify(manifest, null, 2)}`);
 	return manifest;
 }
@@ -76,7 +112,7 @@ async function createC8yManifest(rootDir, options = {}, logger) {
 * @param nitro - The Nitro instance
 */
 async function createC8yManifestFromNitro(nitro) {
-	return createC8yManifest(nitro.options.rootDir, nitro.options.c8y?.manifest, nitro.logger);
+	return createC8yManifest(nitro.options.rootDir, nitro.options, nitro.logger);
 }
 //#endregion
 //#region src/cli/utils/c8y-api.ts