c8y-nitro 0.10.3 → 0.11.0

package/README.md

@@ -13,6 +13,7 @@ Nitro-powered tooling for building Cumulocity IoT microservices without manually
 - 🔥 **File-based Routing** - Auto-discovered routes from your file structure
 - 🛠️ **TypeScript First** - Full type safety with excellent DX
 - 🔄 **Auto-Bootstrap** - Automatically registers and configures your microservice in development
+- 🧪 **Testing** - Test your service in Vitest against a fake Cumulocity tenant you seed with devices, measurements, alarms, and more
 
 ## Quickstart
 
@@ -28,6 +29,7 @@ Useful entry points:
 - [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)
+- [Testing](https://schplitt.github.io/c8y-nitro/guide/testing)
 
 ## Development
 

package/dist/{apiClient-kxv5KHYJ.mjs → apiClient-GMQqcgQe.mjs}

@@ -1,7 +1,7 @@
-import { n as createC8yManifestFromNitro } from "./manifest-DV3UW9Dl.mjs";
+import { n as createC8yManifestFromNitro } from "./manifest-BhrHDm8Y.mjs";
 import { dirname, join, relative } from "node:path";
 import { mkdir, writeFile } from "node:fs/promises";
-//#region src/module/apiClient.ts
+// src/module/apiClient.ts
 /**
 * Converts route path to PascalCase function name.
 * Examples:
@@ -202,5 +202,4 @@ async function writeAPIClient(nitro, options) {
 	await writeFile(outputFile, code, "utf-8");
 	nitro.logger.success(`Generated API client with ${routes.length} routes at: ${relative(rootDir, outputFile)}`);
 }
-//#endregion
 export { writeAPIClient as t };

package/dist/{autoBootstrap-DUjHuHe_.mjs → autoBootstrap-D4vEytWW.mjs}

@@ -1,11 +1,11 @@
-import { t as createC8yManifest } from "./manifest-DV3UW9Dl.mjs";
-import { a as findMicroserviceByName, d as updateMicroservice, l as subscribeToApplication, n as createBasicAuthHeader, o as getBootstrapCredentials, r as createMicroservice } from "./c8y-api-DSs1xIIh.mjs";
-import { t as writeBootstrapCredentials } from "./env-file-BrOTmVjA.mjs";
+import { t as createC8yManifest } from "./manifest-BhrHDm8Y.mjs";
+import { h as updateMicroservice, l as findMicroserviceByName, o as createBasicAuthHeader, p as subscribeToApplication, s as createMicroservice, u as getBootstrapCredentials } from "./env-fUAhIWsI.mjs";
+import { t as writeBootstrapCredentials } from "./env-file-DWbaFlIp.mjs";
+import process from "node:process";
 import { join } from "node:path";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
-import process from "node:process";
-//#region src/module/manifestCache.ts
+// src/module/manifestCache.ts
 /**
 * Directory (inside the project's `node_modules`) where c8y-nitro persists
 * local dev state such as the last-synced manifest hash. Lives in
@@ -64,8 +64,7 @@ async function writeManifestCache(rootDir, state) {
 	};
 	await writeFile(getCacheFile(rootDir), JSON.stringify(payload, null, 2), "utf-8");
 }
-//#endregion
-//#region src/module/autoBootstrap.ts
+// src/module/autoBootstrap.ts
 const BOOTSTRAP_ENV_VARS = [
 	"C8Y_BOOTSTRAP_TENANT",
 	"C8Y_BOOTSTRAP_USER",
@@ -212,5 +211,4 @@ async function finalizeBootstrap(opts) {
 	});
 	return credentials;
 }
-//#endregion
 export { readBootstrapCredentialsFromEnv as n, syncBootstrappedMicroservice as r, autoBootstrap as t };

package/dist/{bootstrap-DrMjty-k.mjs → bootstrap-DpYAhM7C.mjs}

@@ -1,10 +1,10 @@
-import { t as createC8yManifest } from "./manifest-DV3UW9Dl.mjs";
-import { a as findMicroserviceByName, d as updateMicroservice, l as subscribeToApplication, n as createBasicAuthHeader, o as getBootstrapCredentials, r as createMicroservice } from "./c8y-api-DSs1xIIh.mjs";
-import { t as writeBootstrapCredentials } from "./env-file-BrOTmVjA.mjs";
-import { n as validateBootstrapEnv, t as loadC8yConfig } from "./config-BVQHqlgV.mjs";
+import { n as validateBootstrapEnv, t as loadC8yConfig } from "./config-Dozrdw3A.mjs";
+import { h as updateMicroservice, l as findMicroserviceByName, o as createBasicAuthHeader, p as subscribeToApplication, s as createMicroservice, u as getBootstrapCredentials } from "./env-fUAhIWsI.mjs";
+import { t as writeBootstrapCredentials } from "./env-file-DWbaFlIp.mjs";
+import { t as createC8yManifest } from "./manifest-BhrHDm8Y.mjs";
 import { defineCommand, runCommand } from "citty";
 import { consola } from "consola";
-//#region src/cli/commands/bootstrap.ts
+// src/cli/commands/bootstrap.ts
 var bootstrap_default = defineCommand({
 	meta: {
 		name: "bootstrap",
@@ -54,12 +54,11 @@ 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" })) {
-				const rolesCommand = await import("./roles-CNCObfa3.mjs").then((r) => r.default);
+				const rolesCommand = await import("./roles-DEIHe2Xt.mjs").then((r) => r.default);
 				await runCommand(rolesCommand, { rawArgs: [] });
 			}
 		}
 		consola.success("Bootstrap complete!");
 	}
 });
-//#endregion
 export { bootstrap_default as default };

package/dist/cli/index.mjs

@@ -1,6 +1,6 @@
-import { n as name, r as version, t as description } from "../package-Dqlz6AoZ.mjs";
+import { n as name, r as version, t as description } from "../package-y3p_br3i.mjs";
 import { defineCommand, runMain } from "citty";
-//#region src/cli/index.ts
+// src/cli/index.ts
 const main = defineCommand({
 	meta: {
 		name,
@@ -8,12 +8,11 @@ const main = defineCommand({
 		description
 	},
 	subCommands: {
-		bootstrap: () => import("../bootstrap-DrMjty-k.mjs").then((r) => r.default),
-		roles: () => import("../roles-CNCObfa3.mjs").then((r) => r.default),
-		options: () => import("../options-54uJmuUV.mjs").then((r) => r.default),
-		typegen: () => import("../typegen-BO_AkyNc.mjs").then((r) => r.default)
+		bootstrap: () => import("../bootstrap-DpYAhM7C.mjs").then((r) => r.default),
+		roles: () => import("../roles-DEIHe2Xt.mjs").then((r) => r.default),
+		options: () => import("../options-CgTptIpI.mjs").then((r) => r.default),
+		typegen: () => import("../typegen-Bw4VxFmA.mjs").then((r) => r.default)
 	}
 });
 runMain(main);
-//#endregion
 export {};

package/dist/{config-BVQHqlgV.mjs → config-Dozrdw3A.mjs}

@@ -1,7 +1,8 @@
+import { i as toPrefixedEnvVar, n as resolveEnvFileNames, t as applyC8yNitroEnvVars } from "./env-fUAhIWsI.mjs";
 import { dirname } from "pathe";
 import { loadConfig, loadDotenv } from "c12";
 import process from "process";
-//#region src/cli/utils/config.ts
+// src/cli/utils/config.ts
 function normalizeBaseUrl(baseUrl) {
 	return baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
 }
@@ -11,20 +12,23 @@ function normalizeBaseUrl(baseUrl) {
 */
 async function loadC8yConfig() {
 	const cwd = process.cwd();
-	const env = await loadDotenv({
-		cwd,
-		fileName: [".env", ".env.local"]
-	});
 	const { config, _configFile } = await loadConfig({
 		configFile: "nitro.config",
 		cwd
 	});
 	if (!_configFile) throw new Error("No nitro.config file found. Please ensure you have a valid nitro.config file.");
 	const configDir = dirname(_configFile);
+	const c8yOptions = config.c8y;
+	const env = await loadDotenv({
+		cwd: configDir,
+		fileName: resolveEnvFileNames(configDir, c8yOptions?.envFile),
+		interpolate: true
+	});
+	applyC8yNitroEnvVars(env);
 	return {
 		env,
 		nitroConfig: config,
-		c8yOptions: config.c8y,
+		c8yOptions,
 		configDir,
 		configFile: _configFile
 	};
@@ -46,7 +50,7 @@ const REQUIRED_BOOTSTRAP_ENV_VARS = [
 */
 function validateBootstrapEnv(env) {
 	const missing = REQUIRED_BOOTSTRAP_ENV_VARS.filter((key) => !env[key]);
-	if (missing.length > 0) throw new Error(`Missing required environment variables:\n${missing.map((k) => `  - ${k}`).join("\n")}\n\nPlease set these in your .env or .env.local file.`);
+	if (missing.length > 0) throw new Error(`Missing required environment variables:\n${missing.map((k) => `  - ${k} (or ${toPrefixedEnvVar(k)})`).join("\n")}\n\nPlease set these in your .env or .env.local file (or a file configured via \`c8y.envFile\`).`);
 	return {
 		C8Y_BASEURL: normalizeBaseUrl(env.C8Y_BASEURL),
 		C8Y_DEVELOPMENT_TENANT: env.C8Y_DEVELOPMENT_TENANT,
@@ -54,5 +58,4 @@ function validateBootstrapEnv(env) {
 		C8Y_DEVELOPMENT_PASSWORD: env.C8Y_DEVELOPMENT_PASSWORD
 	};
 }
-//#endregion
 export { validateBootstrapEnv as n, loadC8yConfig as t };

package/dist/{credentials-eKnJ7m9Y.d.mts → credentials-C_3m4LVX.d.mts}

@@ -1,5 +1,3 @@
 import { ICredentials } from "@c8y/client";
-//#region src/types/credentials.d.ts
 type TenantCredentials = Record<string, ICredentials>;
-//#endregion
 export { TenantCredentials as t };

package/dist/defaults-CrrCinRJ.mjs

@@ -0,0 +1,20 @@
+// src/testing/defaults.ts
+/**
+* Values the fake tenant uses when the plugin config leaves them out.
+*/
+const DEFAULTS = {
+	tenant: "t12345",
+	baseUrl: "https://t12345.cumulocity.test",
+	user: {
+		userName: "test-user",
+		roles: []
+	},
+	bootstrapUser: "servicebootstrap_test",
+	bootstrapPassword: "bootstrap-password",
+	developmentPassword: "test-password"
+};
+/**
+* Key under which the plugin provides its options to the test workers.
+*/
+const PROVIDE_KEY = "c8yNitroTest";
+export { PROVIDE_KEY as n, DEFAULTS as t };

package/dist/{c8y-api-DSs1xIIh.mjs → env-fUAhIWsI.mjs}

@@ -1,5 +1,9 @@
+import process from "node:process";
+import { resolve } from "pathe";
 import { Buffer } from "node:buffer";
-//#region src/cli/utils/c8y-api.ts
+import { statSync } from "node:fs";
+import { setupDotenv } from "c12";
+// src/cli/utils/c8y-api.ts
 /**
 * Creates a Basic Auth header for Cumulocity API requests.
 * Format: base64(tenant/user:password)
@@ -307,5 +311,74 @@ async function deleteTenantOption(baseUrl, category, key, authHeader) {
 		throw new Error(`Failed to delete tenant option ${category}/${key}: ${response.status} ${response.statusText}\n${errorText}`, { cause: response });
 	}
 }
-//#endregion
-export { findMicroserviceByName as a, getTenantOptionsByCategory as c, updateMicroservice as d, upsertTenantOption as f, deleteTenantOption as i, subscribeToApplication as l, createBasicAuthHeader as n, getBootstrapCredentials as o, createMicroservice as r, getCurrentApplicationSettings as s, assignUserRole as t, unassignUserRole as u };
+// src/cli/utils/env.ts
+/**
+* The project's own env files. Always loaded last so they override any
+* additional (e.g. monorepo-root) env files configured via `c8y.envFile`.
+*/
+const LOCAL_ENV_FILES = [".env", ".env.local"];
+/**
+* Env vars that also accept a `C8Y_NITRO_`-prefixed variant
+* (e.g. `C8Y_NITRO_DEVELOPMENT_USER`). The prefixed variant takes precedence,
+* so shared env files can carry c8y-nitro credentials without clashing with
+* other tools that read the generic `C8Y_*` names.
+*/
+const PREFIXABLE_ENV_VARS = [
+	"C8Y_BASEURL",
+	"C8Y_DEVELOPMENT_TENANT",
+	"C8Y_DEVELOPMENT_USER",
+	"C8Y_DEVELOPMENT_PASSWORD"
+];
+/**
+* Maps a `C8Y_*` variable name to its `C8Y_NITRO_*` variant.
+* @param name - Unprefixed variable name (e.g. `C8Y_DEVELOPMENT_USER`)
+*/
+function toPrefixedEnvVar(name) {
+	return name.replace(/^C8Y_/, "C8Y_NITRO_");
+}
+/**
+* Builds the ordered list of env files to load. Later entries override earlier
+* ones, so configured extra files (monorepo root) come first and the project's
+* own `.env`/`.env.local` last.
+*
+* Extra entries may point at a file (`../../.env`) or a directory (`../..`,
+* expanded to its `.env` and `.env.local`).
+*
+* @param cwd - Directory that relative entries are resolved against
+* @param envFile - Extra env file(s) or directory(ies) from `c8y.envFile`
+*/
+function resolveEnvFileNames(cwd, envFile) {
+	return [...(typeof envFile === "string" ? [envFile] : envFile ?? []).flatMap((entry) => {
+		const resolved = resolve(cwd, entry);
+		if (statSync(resolved, { throwIfNoEntry: false })?.isDirectory()) return LOCAL_ENV_FILES.map((fileName) => resolve(resolved, fileName));
+		return [resolved];
+	}), ...LOCAL_ENV_FILES];
+}
+/**
+* Applies `C8Y_NITRO_*` variants onto their unprefixed `C8Y_*` counterparts
+* (see {@link PREFIXABLE_ENV_VARS}). Mutates `env` in place; a set prefixed
+* variant always wins over the unprefixed value.
+* @param env - Environment variables object (e.g. `process.env` or a loaded `.env`)
+*/
+function applyC8yNitroEnvVars(env) {
+	for (const name of PREFIXABLE_ENV_VARS) {
+		const prefixed = env[toPrefixedEnvVar(name)];
+		if (prefixed) env[name] = prefixed;
+	}
+}
+/**
+* Loads the configured env files into `process.env` (existing real environment
+* variables are never overridden) and resolves `C8Y_NITRO_*` variants.
+* Used during Nitro dev mode, where only the project's own env files would be
+* picked up otherwise.
+* @param rootDir - Project root directory
+* @param envFile - Extra env file(s)/directory(ies) from `c8y.envFile`
+*/
+async function setupC8yDevEnv(rootDir, envFile) {
+	await setupDotenv({
+		cwd: rootDir,
+		fileName: resolveEnvFileNames(rootDir, envFile)
+	});
+	applyC8yNitroEnvVars(process.env);
+}
+export { assignUserRole as a, deleteTenantOption as c, getCurrentApplicationSettings as d, getTenantOptionsByCategory as f, upsertTenantOption as g, updateMicroservice as h, toPrefixedEnvVar as i, findMicroserviceByName as l, unassignUserRole as m, resolveEnvFileNames as n, createBasicAuthHeader as o, subscribeToApplication as p, setupC8yDevEnv as r, createMicroservice as s, applyC8yNitroEnvVars as t, getBootstrapCredentials as u };

package/dist/{env-file-BrOTmVjA.mjs → env-file-DWbaFlIp.mjs}

@@ -1,7 +1,7 @@
 import { join } from "node:path";
 import { readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
-//#region src/cli/utils/env-file.ts
+// src/cli/utils/env-file.ts
 /**
 * Writes or updates environment variables in a file.
 * Existing variables are overwritten, new ones are appended.
@@ -55,5 +55,4 @@ async function writeBootstrapCredentials(configDir, variables) {
 	await writeEnvVariables(targetPath, variables);
 	return targetName;
 }
-//#endregion
 export { writeBootstrapCredentials as t };

package/dist/{index-BEFoDy-y.d.mts → index-CmIQfBpj.d.mts}

@@ -1,7 +1,6 @@
-import "./credentials-eKnJ7m9Y.mjs";
+import "./credentials-C_3m4LVX.mjs";
 import { ConsumerResilienceOptions, SubscriptionApi } from "c8y-realtime";
 import { C8YTenantOptionKeysCacheConfig } from "c8y-nitro/types";
-//#region src/types/apiClient.d.ts
 interface C8YAPIClientOptions {
   /**
    * Relative directory from nitro configuration file to generate the API client into.
@@ -15,8 +14,6 @@ interface C8YAPIClientOptions {
    */
   contextPath?: string;
 }
-//#endregion
-//#region src/types/roles.generated.d.ts
 /**
  * AUTO-GENERATED by scripts/generate-roles.ts — do not edit by hand.
  *
@@ -30,8 +27,6 @@ interface C8YAPIClientOptions {
  * Cumulocity platform roles ("required roles") known from the core OpenAPI spec.
  */
 type C8YKnownRole = 'ROLE_ALARM_ADMIN' | 'ROLE_ALARM_READ' | 'ROLE_APPLICATION_MANAGEMENT_ADMIN' | 'ROLE_APPLICATION_MANAGEMENT_READ' | 'ROLE_AUDIT_ADMIN' | 'ROLE_AUDIT_READ' | 'ROLE_BINARY_ADMIN' | 'ROLE_BINARY_CREATE' | 'ROLE_BINARY_READ' | 'ROLE_BULK_OPERATION_ADMIN' | 'ROLE_BULK_OPERATION_READ' | 'ROLE_DEVICE' | 'ROLE_DEVICE_BOOTSTRAP' | 'ROLE_DEVICE_CONTROL_ADMIN' | 'ROLE_DEVICE_CONTROL_READ' | 'ROLE_EVENT_ADMIN' | 'ROLE_EVENT_READ' | 'ROLE_IDENTITY_ADMIN' | 'ROLE_IDENTITY_READ' | 'ROLE_INVENTORY_ADMIN' | 'ROLE_INVENTORY_CREATE' | 'ROLE_INVENTORY_READ' | 'ROLE_MANAGED_OBJECT_ADMIN' | 'ROLE_MANAGED_OBJECT_CREATE' | 'ROLE_MANAGED_OBJECT_READ' | 'ROLE_MEASUREMENT_ADMIN' | 'ROLE_MEASUREMENT_READ' | 'ROLE_NOTIFICATION_2_ADMIN' | 'ROLE_OPTION_MANAGEMENT_ADMIN' | 'ROLE_OPTION_MANAGEMENT_READ' | 'ROLE_RETENTION_RULE_ADMIN' | 'ROLE_RETENTION_RULE_READ' | 'ROLE_SMS_READ' | 'ROLE_SYSTEM' | 'ROLE_TENANT_ADMIN' | 'ROLE_TENANT_ALARM_ADMIN' | 'ROLE_TENANT_MANAGEMENT_ADMIN' | 'ROLE_TENANT_MANAGEMENT_CREATE' | 'ROLE_TENANT_MANAGEMENT_READ' | 'ROLE_TENANT_MANAGEMENT_UPDATE' | 'ROLE_TENANT_STATISTICS_READ' | 'ROLE_USER_MANAGEMENT_ADMIN' | 'ROLE_USER_MANAGEMENT_CREATE' | 'ROLE_USER_MANAGEMENT_OWN_ADMIN' | 'ROLE_USER_MANAGEMENT_OWN_READ' | 'ROLE_USER_MANAGEMENT_READ';
-//#endregion
-//#region src/types/roles.d.ts
 /**
  * Roles your microservice provides. Populated at runtime from the manifest's
  * `roles` field (see the module's generated `c8y-nitro.d.ts`).
@@ -43,8 +38,6 @@ interface C8YRoles$1 {}
  * other string (custom roles, or roles not yet in the generated list).
  */
 type C8YRole$1 = C8YKnownRole | (string & {});
-//#endregion
-//#region src/types/manifest.d.ts
 type C8YManifestOptions = Omit<C8YManifest, 'name' | 'version' | 'apiVersion' | 'key' | 'type' | 'provider' | 'openApiSpec'>;
 interface C8YManifest {
   /**
@@ -165,6 +158,42 @@ interface C8YManifest {
    * @example "/_openapi.json"
    */
   openApiSpec?: string;
+  /**
+   * MCP (Model Context Protocol) servers exposed by this microservice.
+   * Once the application is subscribed, Cumulocity AI Agent Manager
+   * auto-registers these entries, and MCP-aware clients (e.g., mc8yp)
+   * discover them from the manifest.
+   * @example [{ name: "my-service", url: "/service/my-service/mcp", type: "http", sendAuthentication: true }]
+   */
+  exposeMcpServers?: ExposedMcpServer[];
+}
+/**
+ * MCP server entry declared via `exposeMcpServers`.
+ */
+interface ExposedMcpServer {
+  /**
+   * Name of the MCP server as shown in AI Agent Manager.
+   * @example "my-service"
+   */
+  name: string;
+  /**
+   * Human-readable description of what the MCP server offers.
+   */
+  description?: string;
+  /**
+   * URL of the MCP endpoint, usually the full service path including the context path.
+   * @example "/service/my-service/mcp"
+   */
+  url: string;
+  /**
+   * MCP transport type. Streamable HTTP (`"http"`) is the supported transport.
+   * @example "http"
+   */
+  type: 'http' | (string & {});
+  /**
+   * Forward the calling user's authentication to the MCP server.
+   */
+  sendAuthentication?: boolean;
 }
 /**
  * Company/organization information.
@@ -367,8 +396,6 @@ interface Extension {
    */
   [key: string]: unknown;
 }
-//#endregion
-//#region src/types/zip.d.ts
 interface C8YZipOptions {
   /**
    * Name of the generated zip file
@@ -392,8 +419,6 @@ interface C8YZipOptions {
    */
   manifest?: C8YManifestOptions;
 }
-//#endregion
-//#region src/types/cache.d.ts
 interface C8yCacheOptions {
   /**
    * Cache TTL for subscribed tenant credentials in seconds.
@@ -417,8 +442,6 @@ interface C8yCacheOptions {
    */
   tenantOptions?: C8YTenantOptionKeysCacheConfig;
 }
-//#endregion
-//#region src/types/docker.d.ts
 interface C8yDockerOptions {
   /**
    * Path to a custom Dockerfile, relative to the Nitro config file location
@@ -453,8 +476,6 @@ interface C8yDockerOptions {
    */
   extraInstructions?: string[];
 }
-//#endregion
-//#region src/types/realtime.d.ts
 /**
  * Options for the Notification 2.0 realtime clients (backed by `c8y-realtime`).
  *
@@ -526,8 +547,6 @@ interface C8yRealtimeOptions {
    */
   resilience?: ConsumerResilienceOptions;
 }
-//#endregion
-//#region src/types/tenantOptions.d.ts
 /**
  * Per-key cache TTL configuration for tenant options.
  * Overwritten by generated types from manifest settings (manifest.settings[].key).
@@ -544,8 +563,6 @@ type C8YTenantOptionKey$1 = string;
  * Overwritten by generated types from the manifest.
  */
 type C8YSettingsCategory$1 = string;
-//#endregion
-//#region src/types/index.d.ts
 interface C8yDevOptions {
   /**
    * Automatically inject the configured development user into incoming requests
@@ -605,6 +622,24 @@ interface C8yNitroModuleOptions {
    * @default false
    */
   enableTenantOptionsInvalidationRoute?: boolean;
+  /**
+   * Additional `.env` file(s) to load during development and for CLI commands,
+   * for example a shared monorepo-root env file.
+   *
+   * Entries are resolved relative to the project root (absolute paths work too)
+   * and may point at a file (`'../../.env'`) or a directory (`'../..'`, which
+   * loads its `.env` and `.env.local`).
+   *
+   * Precedence (highest first): real environment variables, the project's own
+   * `.env.local` and `.env`, then the entries here (later entries override
+   * earlier ones). Bootstrap credentials are still written to the project's
+   * own env file, keeping them per-microservice in a monorepo.
+   *
+   * Only used in dev mode and by the CLI - deployed microservices get their
+   * environment from the platform.
+   * @default []
+   */
+  envFile?: string | string[];
   /**
    * Disable auto-bootstrap during development.
    * When true, the module will not automatically register the microservice
@@ -615,5 +650,4 @@ interface C8yNitroModuleOptions {
    */
   skipBootstrap?: boolean;
 }
-//#endregion
-export { C8YTenantOptionKey$1 as a, C8yDockerOptions as c, C8YManifest as d, C8YManifestOptions as f, C8YAPIClientOptions as g, C8YKnownRole as h, C8YSettingsCategory$1 as i, C8yCacheOptions as l, C8YRoles$1 as m, C8yNitroModuleOptions as n, C8YTenantOptionKeysCacheConfig$1 as o, C8YRole$1 as p, C8yOpenAPIOptions as r, C8yRealtimeOptions as s, C8yDevOptions as t, C8YZipOptions as u };
+export { C8YAPIClientOptions as _, C8YTenantOptionKey$1 as a, C8yDockerOptions as c, C8YManifest as d, C8YManifestOptions as f, C8YKnownRole as g, C8YRoles$1 as h, C8YSettingsCategory$1 as i, C8yCacheOptions as l, C8YRole$1 as m, C8yNitroModuleOptions as n, C8YTenantOptionKeysCacheConfig$1 as o, ExposedMcpServer as p, C8yOpenAPIOptions as r, C8yRealtimeOptions as s, C8yDevOptions as t, C8YZipOptions as u };

package/dist/index.d.mts

@@ -1,7 +1,6 @@
-import { n as C8yNitroModuleOptions } from "./index-BEFoDy-y.mjs";
-import { t as TenantCredentials } from "./credentials-eKnJ7m9Y.mjs";
+import { n as C8yNitroModuleOptions } from "./index-CmIQfBpj.mjs";
+import { t as TenantCredentials } from "./credentials-C_3m4LVX.mjs";
 import { NitroModule } from "nitro/types";
-//#region src/index.d.ts
 declare module 'nitro/types' {
   interface NitroOptions {
     c8y?: C8yNitroModuleOptions;
@@ -12,6 +11,5 @@ declare module 'nitro/types' {
     'c8y:tenantCredentialsUpdated': (prev: TenantCredentials | null, next: TenantCredentials) => void;
   }
 }
-declare function c8y(): NitroModule;
-//#endregion
-export { c8y, c8y as default };
+export declare function c8y(): NitroModule;
+export { c8y as default };

package/dist/index.mjs

@@ -1,7 +1,9 @@
-import { a as GENERATED_INVALIDATE_TENANT_OPTIONS_ROUTE, i as C8Y_NITRO_TYPES_FILE, n as createC8yManifestFromNitro, o as GENERATED_LIVENESS_ROUTE, r as C8Y_NITRO_TYPES_DIR, s as GENERATED_READINESS_ROUTE, t as createC8yManifest } from "./manifest-DV3UW9Dl.mjs";
-import { t as writeAPIClient } from "./apiClient-kxv5KHYJ.mjs";
-import { t as autoBootstrap } from "./autoBootstrap-DUjHuHe_.mjs";
-import { n as name } from "./package-Dqlz6AoZ.mjs";
+import { t as writeAPIClient } from "./apiClient-GMQqcgQe.mjs";
+import { a as GENERATED_INVALIDATE_TENANT_OPTIONS_ROUTE, i as C8Y_NITRO_TYPES_FILE, n as createC8yManifestFromNitro, o as GENERATED_LIVENESS_ROUTE, r as C8Y_NITRO_TYPES_DIR, s as GENERATED_READINESS_ROUTE, t as createC8yManifest } from "./manifest-BhrHDm8Y.mjs";
+import { t as autoBootstrap } from "./autoBootstrap-D4vEytWW.mjs";
+import { r as setupC8yDevEnv } from "./env-fUAhIWsI.mjs";
+import { n as name } from "./package-y3p_br3i.mjs";
+import process from "node:process";
 import { basename, join, resolve } from "node:path";
 import { copyFile, mkdir, writeFile } from "node:fs/promises";
 import { x } from "tinyexec";
@@ -15,7 +17,7 @@ import { isValidRealtimeName, toRealtimeName } from "c8y-realtime";
 import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import evlog from "evlog/nitro/v3";
-//#region src/module/docker.ts
+// src/module/docker.ts
 /**
 * Generate the Dockerfile content for a Nitro build
 * @param outputDirName - Name of the output directory (e.g., '.output')
@@ -118,8 +120,7 @@ async function createDockerImage(nitro, options = {}) {
 	nitro.logger.debug("Docker image creation complete.");
 	return imageTarPath;
 }
-//#endregion
-//#region src/module/c8yzip.ts
+// src/module/c8yzip.ts
 const spinnies = new Spinnies();
 function formatBytes(bytes) {
 	if (bytes === 0) return "0 B";
@@ -178,8 +179,7 @@ async function createC8yZip(nitro, options = {}, dockerOptions = {}) {
 	nitro.logger.log(colors.gray(`  └─ ${outputFile} (${zipSize})`));
 	nitro.logger.info("Zip file can be uploaded to Cumulocity IoT platform");
 }
-//#endregion
-//#region src/module/runtime.ts
+// src/module/runtime.ts
 function setupRuntime(nitro, manifest) {
 	nitro.logger.debug("Setting up C8Y nitro runtime");
 	const roles = manifest.roles ?? [];
@@ -216,8 +216,7 @@ export const c8yTenantOptionKeys = [${settingKeys.map((key) => `'${key}'`).join(
 	writeFileSync(typesFile, typesContent, { encoding: "utf-8" });
 	nitro.logger.debug(`Written C8Y types to ${typesFile}`);
 }
-//#endregion
-//#region src/module/runtimeConfig.ts
+// src/module/runtimeConfig.ts
 /**
 * Derive a stable, unique realtime client name from the microservice identity
 * (its `contextPath`, falling back to `name`).
@@ -266,8 +265,7 @@ async function setupRuntimeConfig(nitro, options) {
 	const probePaths = [options.manifest?.livenessProbe?.httpGet?.path, options.manifest?.readinessProbe?.httpGet?.path].filter((path) => Boolean(path));
 	nitro.options.runtimeConfig.c8yOpenApiExcludeRoutes = [...excludeInternalRoutes ? ["/_", ...probePaths] : [], ...options.openapi?.excludeRoutes ?? []];
 }
-//#endregion
-//#region src/module/registerRuntime.ts
+// src/module/registerRuntime.ts
 /**
 * Links runtime middleware, handlers, and plugins to the nitro instance.
 * Works by having the handlers in a relative path to this file.
@@ -363,8 +361,7 @@ function registerRuntime(nitro, options = {}) {
 	}
 	nitro.options.handlers.push(...handlers);
 }
-//#endregion
-//#region src/module/probeCheck.ts
+// src/module/probeCheck.ts
 function checkProbes(nitro, manifestOptions = {}) {
 	if (manifestOptions.livenessProbe?.httpGet) {
 		const probe = manifestOptions.livenessProbe.httpGet;
@@ -391,8 +388,7 @@ function checkProbeEndpoint(nitro, probe, probeType) {
 		nitro.logger.warn(`${probeType} route "${path}" exists but does not accept ${method} requests. Available methods: ${availableMethods || "none specified"}. The probe will fail at runtime.`);
 	}
 }
-//#endregion
-//#region src/index.ts
+// src/index.ts
 function c8y() {
 	return {
 		name: "c8y-nitro",
@@ -424,20 +420,24 @@ function c8y() {
 				exclude: [manifest.livenessProbe?.httpGet?.path, manifest.readinessProbe?.httpGet?.path].filter(Boolean)
 			});
 			await setupEvlog(nitro);
-			if (nitro.options.preset === "nitro-dev" && !options.skipBootstrap) await autoBootstrap(nitro);
+			if (nitro.options.preset === "nitro-dev") {
+				await setupC8yDevEnv(nitro.options.rootDir, options.envFile);
+				if (!options.skipBootstrap && !process.env.VITEST) await autoBootstrap(nitro);
+			}
 			await setupRuntimeConfig(nitro, options);
 			setupRuntime(nitro, manifest);
+			registerRuntime(nitro, options);
 			nitro.hooks.hook("dev:reload", async () => {
+				await setupC8yDevEnv(nitro.options.rootDir, options.envFile);
 				manifest = await createC8yManifestFromNitro(nitro);
 				setupRuntime(nitro, manifest);
-				if (!options.skipBootstrap) await autoBootstrap(nitro);
+				if (!options.skipBootstrap && !process.env.VITEST) await autoBootstrap(nitro);
 				if (options.apiClient) {
 					nitro.logger.debug("Generating C8Y API client");
 					await writeAPIClient(nitro, options);
 				}
 			});
 			nitro.hooks.hook("build:before", async () => {
-				registerRuntime(nitro, options);
 				if (options.manifest) checkProbes(nitro, options.manifest);
 			});
 			nitro.hooks.hook("close", async () => {
@@ -446,5 +446,4 @@ function c8y() {
 		}
 	};
 }
-//#endregion
 export { c8y, c8y as default };

package/dist/{logging-BUYT8Z2V.mjs → logging-B1PuWdiF.mjs}

@@ -1,6 +1,6 @@
 import { createError } from "evlog";
 import "evlog/nitro/v3";
-//#region src/utils/logging.ts
+// src/utils/logging.ts
 /**
 * Create a structured error for a Cumulocity microservice. Always prefer this
 * over Nitro/h3's built-in `createError`: the returned error is captured in the
@@ -53,5 +53,4 @@ import "evlog/nitro/v3";
 * @see https://www.evlog.dev
 */
 const createError$1 = createError;
-//#endregion
 export { createError$1 as t };

package/dist/{manifest-DV3UW9Dl.mjs → manifest-BhrHDm8Y.mjs}

@@ -1,5 +1,5 @@
 import { readPackage } from "pkg-types";
-//#region src/module/constants.ts
+// src/module/constants.ts
 const GENERATED_LIVENESS_ROUTE = "/_c8y_nitro/liveness";
 const GENERATED_READINESS_ROUTE = "/_c8y_nitro/readiness";
 const GENERATED_INVALIDATE_TENANT_OPTIONS_ROUTE = "/_c8y_nitro/invalidate-tenant-options";
@@ -13,8 +13,7 @@ const C8Y_NITRO_TYPES_DIR = "node_modules/.c8y-nitro";
 * File name of the generated declarations inside {@link C8Y_NITRO_TYPES_DIR}.
 */
 const C8Y_NITRO_TYPES_FILE = "types.d.ts";
-//#endregion
-//#region src/module/manifest.ts
+// src/module/manifest.ts
 const DEFAULT_OPENAPI_ROUTE = "/_openapi.json";
 const ROLE_OPTION_MANAGEMENT_READ = "ROLE_OPTION_MANAGEMENT_READ";
 /**
@@ -85,7 +84,7 @@ async function readPackageJsonFieldsForManifest(rootDir, logger) {
 * 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
+* @param logger - Optional Nitro logger (`nitro.logger`) for debug output
 */
 async function createC8yManifest(rootDir, nitroConfig = {}, logger) {
 	const { options, openApiSpec } = extractManifestInputs(nitroConfig);
@@ -108,8 +107,8 @@ async function createC8yManifest(rootDir, nitroConfig = {}, logger) {
 	}
 	const manifest = {
 		...restManifestFields,
-		...probeFields,
 		...options,
+		...probeFields,
 		...requiredRoles !== void 0 ? { requiredRoles } : {},
 		...openApiSpec ? { openApiSpec } : {},
 		provider,
@@ -131,5 +130,4 @@ async function createC8yManifest(rootDir, nitroConfig = {}, logger) {
 async function createC8yManifestFromNitro(nitro) {
 	return createC8yManifest(nitro.options.rootDir, nitro.options, nitro.logger);
 }
-//#endregion
 export { GENERATED_INVALIDATE_TENANT_OPTIONS_ROUTE as a, C8Y_NITRO_TYPES_FILE as i, createC8yManifestFromNitro as n, GENERATED_LIVENESS_ROUTE as o, C8Y_NITRO_TYPES_DIR as r, GENERATED_READINESS_ROUTE as s, createC8yManifest as t };