@inkeep/agents-cli 0.39.4 → 0.40.0

package/dist/utils/credentials.js

@@ -0,0 +1,132 @@
+import { KeyChainStore } from "@inkeep/agents-core/credential-stores";
+
+//#region src/utils/credentials.ts
+const CLI_SERVICE_PREFIX = "inkeep-cli";
+const DEFAULT_CREDENTIALS_KEY = "auth-credentials";
+let keychainStore = null;
+function getKeychainStore() {
+	if (!keychainStore) keychainStore = new KeyChainStore("auth", CLI_SERVICE_PREFIX);
+	return keychainStore;
+}
+/**
+* Save CLI credentials to the system keychain
+* @param credentials - The credentials to store
+* @param credentialKey - Optional key to store under (from profile's credential field). Defaults to 'auth-credentials'
+*/
+async function saveCredentials(credentials, credentialKey) {
+	const store = getKeychainStore();
+	const { available, reason } = await store.checkAvailability();
+	if (!available) throw new Error(getKeychainUnavailableMessage(reason));
+	const key = credentialKey || DEFAULT_CREDENTIALS_KEY;
+	const credentialsJson = JSON.stringify(credentials);
+	await store.set(key, credentialsJson);
+}
+/**
+* Load CLI credentials from the system keychain
+* @param credentialKey - Optional key to load from (from profile's credential field). Defaults to 'auth-credentials'
+*/
+async function loadCredentials(credentialKey) {
+	const store = getKeychainStore();
+	const key = credentialKey || DEFAULT_CREDENTIALS_KEY;
+	const credentialsJson = await store.get(key);
+	if (!credentialsJson) return null;
+	try {
+		const credentials = JSON.parse(credentialsJson);
+		if (!credentials.accessToken || !credentials.userId || !credentials.userEmail) return null;
+		return credentials;
+	} catch {
+		await store.delete(key);
+		return null;
+	}
+}
+/**
+* Clear CLI credentials from the system keychain
+* @param credentialKey - Optional key to clear (from profile's credential field). Defaults to 'auth-credentials'
+*/
+async function clearCredentials(credentialKey) {
+	const store = getKeychainStore();
+	const key = credentialKey || DEFAULT_CREDENTIALS_KEY;
+	return store.delete(key);
+}
+/**
+* Check if valid credentials exist in the keychain
+* @param credentialKey - Optional key to check (from profile's credential field). Defaults to 'auth-credentials'
+*/
+async function hasValidCredentials(credentialKey) {
+	const credentials = await loadCredentials(credentialKey);
+	if (!credentials) return false;
+	if (credentials.expiresAt) {
+		if (new Date(credentials.expiresAt) < /* @__PURE__ */ new Date()) return false;
+	}
+	return true;
+}
+/**
+* Check if credentials are expired
+*/
+function isCredentialExpired(credentials) {
+	if (!credentials.expiresAt) return false;
+	return new Date(credentials.expiresAt) < /* @__PURE__ */ new Date();
+}
+/**
+* Get time until credentials expire
+*/
+function getCredentialExpiryInfo(credentials) {
+	if (!credentials.expiresAt) return { isExpired: false };
+	const expiresAt = new Date(credentials.expiresAt);
+	const now = /* @__PURE__ */ new Date();
+	if (expiresAt < now) return {
+		isExpired: true,
+		expiresAt
+	};
+	const diffMs = expiresAt.getTime() - now.getTime();
+	const hours = Math.floor(diffMs / (1e3 * 60 * 60));
+	const minutes = Math.floor(diffMs % (1e3 * 60 * 60) / (1e3 * 60));
+	let expiresIn;
+	if (hours > 24) expiresIn = `${Math.floor(hours / 24)}d`;
+	else if (hours > 0) expiresIn = `${hours}h`;
+	else expiresIn = `${minutes}m`;
+	return {
+		isExpired: false,
+		expiresIn,
+		expiresAt
+	};
+}
+/**
+* Check if the keychain is available for storing credentials
+*/
+async function checkKeychainAvailability() {
+	return getKeychainStore().checkAvailability();
+}
+/**
+* Get a helpful error message when keychain is unavailable
+*/
+function getKeychainUnavailableMessage(reason) {
+	const platform = process.platform;
+	let message = "Unable to store credentials securely.\n\n";
+	if (reason) message += `Reason: ${reason}\n\n`;
+	message += "The Inkeep CLI requires access to the system keychain to store your login credentials securely.\n\n";
+	switch (platform) {
+		case "darwin":
+			message += "On macOS:\n";
+			message += "  1. Ensure you have Keychain Access available\n";
+			message += "  2. If prompted, click \"Allow\" or \"Always Allow\" to grant access\n";
+			message += "  3. Check System Preferences > Security & Privacy if access was denied\n";
+			break;
+		case "win32":
+			message += "On Windows:\n";
+			message += "  1. Ensure Windows Credential Manager is available\n";
+			message += "  2. Try running the CLI as administrator if access is denied\n";
+			break;
+		case "linux":
+			message += "On Linux:\n";
+			message += "  1. Ensure libsecret is installed (e.g., `sudo apt install libsecret-1-dev`)\n";
+			message += "  2. Ensure a keyring service is running (GNOME Keyring, KWallet, etc.)\n";
+			message += "  3. For headless servers, consider using an API key instead of `inkeep login`\n";
+			break;
+		default: message += "Please ensure your system has a supported keychain/credential manager available.\n";
+	}
+	return message;
+}
+
+//#endregion
+export { checkKeychainAvailability, clearCredentials, getCredentialExpiryInfo, getKeychainUnavailableMessage, hasValidCredentials, isCredentialExpired, loadCredentials, saveCredentials };

package/dist/utils/environment-loader.js

@@ -0,0 +1,28 @@
+import { importWithTypeScriptSupport } from "./tsx-loader.js";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+//#region src/utils/environment-loader.ts
+/**
+* Load environment credentials from the environments directory
+* @param projectDir - Path to the project directory
+* @param env - Environment name (e.g., 'development', 'production')
+* @returns Object containing credentials or null if not found
+*/
+async function loadEnvironmentCredentials(projectDir, env) {
+	const envFilePath = join(join(projectDir, "environments"), `${env}.env.ts`);
+	if (!existsSync(envFilePath)) throw new Error(`Environment file not found: ${envFilePath}\nMake sure you have a ${env}.env.ts file in the environments directory.`);
+	try {
+		const envModule = await importWithTypeScriptSupport(envFilePath);
+		const exports = Object.keys(envModule);
+		if (exports.length === 0) throw new Error(`No exports found in environment file: ${envFilePath}`);
+		const envSettings = envModule[exports[0]];
+		if (!envSettings || typeof envSettings !== "object") throw new Error(`Invalid environment settings in ${envFilePath}. Expected an object with credentials.`);
+		return envSettings.credentials || {};
+	} catch (error) {
+		throw new Error(`Failed to load environment file ${envFilePath}: ${error.message}`);
+	}
+}
+
+//#endregion
+export { loadEnvironmentCredentials };

package/dist/utils/file-finder.js

@@ -0,0 +1,62 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+//#region src/utils/file-finder.ts
+/**
+* Recursively find all TypeScript files in a directory, excluding specified directories
+* @param rootDir - Root directory to search
+* @param excludeDirs - Array of directory names to exclude (relative to root)
+* @returns Array of file paths
+*/
+function findAllTypeScriptFiles(rootDir, excludeDirs = []) {
+	const tsFiles = [];
+	function scanDirectory(dir) {
+		if (!existsSync(dir)) return;
+		const items = readdirSync(dir);
+		for (const item of items) {
+			const fullPath = join(dir, item);
+			const relativePath = relative(rootDir, fullPath);
+			if (excludeDirs.some((excludeDir) => relativePath === excludeDir || relativePath.startsWith(`${excludeDir}/`))) continue;
+			const stat = statSync(fullPath);
+			if (stat.isDirectory()) scanDirectory(fullPath);
+			else if (stat.isFile() && item.endsWith(".ts")) tsFiles.push(fullPath);
+		}
+	}
+	scanDirectory(rootDir);
+	return tsFiles.sort();
+}
+/**
+* Categorize TypeScript files by their likely purpose based on filename and location
+* @param files - Array of file paths
+* @param rootDir - Root directory for relative path calculation
+* @returns Object with categorized files
+*/
+function categorizeTypeScriptFiles(files, rootDir) {
+	const indexFile = files.find((file) => file.endsWith("/index.ts") || file === join(rootDir, "index.ts")) || null;
+	const configFiles = [];
+	const agentFiles = [];
+	const subAgentFiles = [];
+	const toolFiles = [];
+	const otherFiles = [];
+	for (const file of files) {
+		const fileName = file.split("/").pop() || "";
+		const relativePath = relative(rootDir, file);
+		if (file === indexFile) continue;
+		if (fileName.includes(".config.") || fileName.includes(".env.") || fileName === "inkeep.config.ts") configFiles.push(file);
+		else if (fileName.includes(".agent.") || relativePath.includes("agent/")) agentFiles.push(file);
+		else if (fileName.includes("agent") || fileName.includes("Agent") || relativePath.includes("agents/")) agentFiles.push(file);
+		else if (fileName.includes("tool") || fileName.includes("Tool") || relativePath.includes("tools/")) toolFiles.push(file);
+		else otherFiles.push(file);
+	}
+	return {
+		indexFile,
+		configFiles,
+		agentFiles,
+		subAgentFiles,
+		toolFiles,
+		otherFiles
+	};
+}
+
+//#endregion
+export { categorizeTypeScriptFiles, findAllTypeScriptFiles };

package/dist/utils/json-comparator.js

@@ -0,0 +1,185 @@
+//#region src/utils/json-comparator.ts
+/**
+* Compare two JSON objects for structural equivalence
+* Handles arrays with different ordering and nested objects
+*/
+function compareJsonObjects(obj1, obj2, options = {}) {
+	const { ignoreArrayOrder = true, ignoreCase = false, ignoreWhitespace = false, ignorePaths = [] } = options;
+	const differences = [];
+	const stats = {
+		totalKeys: 0,
+		differentKeys: 0,
+		missingKeys: 0,
+		extraKeys: 0
+	};
+	function normalizeValue(value) {
+		if (typeof value === "string") {
+			let normalized = value;
+			if (ignoreCase) normalized = normalized.toLowerCase();
+			if (ignoreWhitespace) normalized = normalized.trim().replace(/\s+/g, " ");
+			return normalized;
+		}
+		return value;
+	}
+	function shouldIgnorePath(path) {
+		return ignorePaths.some((ignorePath) => {
+			if (ignorePath.endsWith("*")) return path.startsWith(ignorePath.slice(0, -1));
+			return path === ignorePath;
+		});
+	}
+	function compareValues(value1, value2, path = "") {
+		if (shouldIgnorePath(path)) return true;
+		if (value1 === null || value1 === void 0) {
+			if (value2 === null || value2 === void 0) return true;
+			differences.push({
+				path,
+				type: "different",
+				value1,
+				value2,
+				description: `Null/undefined mismatch: ${value1} vs ${value2}`
+			});
+			return false;
+		}
+		if (value2 === null || value2 === void 0) {
+			differences.push({
+				path,
+				type: "different",
+				value1,
+				value2,
+				description: `Null/undefined mismatch: ${value1} vs ${value2}`
+			});
+			return false;
+		}
+		if (typeof value1 !== typeof value2) {
+			differences.push({
+				path,
+				type: "type_mismatch",
+				value1,
+				value2,
+				description: `Type mismatch: ${typeof value1} vs ${typeof value2}`
+			});
+			return false;
+		}
+		if (typeof value1 !== "object") {
+			if (normalizeValue(value1) !== normalizeValue(value2)) {
+				differences.push({
+					path,
+					type: "different",
+					value1,
+					value2,
+					description: `Value mismatch: ${value1} vs ${value2}`
+				});
+				return false;
+			}
+			return true;
+		}
+		if (Array.isArray(value1) && Array.isArray(value2)) {
+			if (value1.length !== value2.length) {
+				differences.push({
+					path,
+					type: "different",
+					value1: value1.length,
+					value2: value2.length,
+					description: `Array length mismatch: ${value1.length} vs ${value2.length}`
+				});
+				return false;
+			}
+			if (ignoreArrayOrder) {
+				const sorted1 = [...value1].sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+				const sorted2 = [...value2].sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+				for (let i = 0; i < sorted1.length; i++) compareValues(sorted1[i], sorted2[i], `${path}[${i}]`);
+			} else for (let i = 0; i < value1.length; i++) compareValues(value1[i], value2[i], `${path}[${i}]`);
+			return true;
+		}
+		if (typeof value1 === "object" && typeof value2 === "object") {
+			const keys1 = Object.keys(value1);
+			const keys2 = Object.keys(value2);
+			const allKeys = new Set([...keys1, ...keys2]);
+			stats.totalKeys += allKeys.size;
+			for (const key of allKeys) {
+				const currentPath = path ? `${path}.${key}` : key;
+				if (!keys1.includes(key)) {
+					differences.push({
+						path: currentPath,
+						type: "missing",
+						value2: value2[key],
+						description: `Missing key in first object: ${key}`
+					});
+					stats.missingKeys++;
+					continue;
+				}
+				if (!keys2.includes(key)) {
+					differences.push({
+						path: currentPath,
+						type: "extra",
+						value1: value1[key],
+						description: `Extra key in first object: ${key}`
+					});
+					stats.extraKeys++;
+					continue;
+				}
+				if (!compareValues(value1[key], value2[key], currentPath)) stats.differentKeys++;
+			}
+			return true;
+		}
+		return true;
+	}
+	compareValues(obj1, obj2);
+	return {
+		isEqual: differences.length === 0,
+		differences,
+		stats
+	};
+}
+/**
+* Create a normalized version of a JSON object for comparison
+* This can be useful for creating a canonical representation
+*/
+function normalizeJsonObject(obj, options = {}) {
+	const { ignoreArrayOrder = true, ignoreCase = false, ignoreWhitespace = false } = options;
+	function normalizeValue(value) {
+		if (typeof value === "string") {
+			let normalized = value;
+			if (ignoreCase) normalized = normalized.toLowerCase();
+			if (ignoreWhitespace) normalized = normalized.trim().replace(/\s+/g, " ");
+			return normalized;
+		}
+		if (Array.isArray(value)) {
+			const normalizedArray = value.map(normalizeValue);
+			if (ignoreArrayOrder) return normalizedArray.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+			return normalizedArray;
+		}
+		if (typeof value === "object" && value !== null) {
+			const normalizedObj = {};
+			const sortedKeys = Object.keys(value).sort();
+			for (const key of sortedKeys) normalizedObj[key] = normalizeValue(value[key]);
+			return normalizedObj;
+		}
+		return value;
+	}
+	return normalizeValue(obj);
+}
+/**
+* Get a summary of differences in a human-readable format
+*/
+function getDifferenceSummary(result) {
+	if (result.isEqual) return "✅ Objects are equivalent";
+	const { differences, stats } = result;
+	const summary = [`❌ Objects differ (${differences.length} differences found)`];
+	summary.push(`📊 Statistics:`);
+	summary.push(`  • Total keys: ${stats.totalKeys}`);
+	summary.push(`  • Different values: ${stats.differentKeys}`);
+	summary.push(`  • Missing keys: ${stats.missingKeys}`);
+	summary.push(`  • Extra keys: ${stats.extraKeys}`);
+	if (differences.length > 0) {
+		summary.push(`\n🔍 Differences:`);
+		differences.slice(0, 10).forEach((diff, index) => {
+			summary.push(`  ${index + 1}. ${diff.path}: ${diff.description}`);
+		});
+		if (differences.length > 10) summary.push(`  ... and ${differences.length - 10} more differences`);
+	}
+	return summary.join("\n");
+}
+
+//#endregion
+export { compareJsonObjects, getDifferenceSummary, normalizeJsonObject };

package/dist/utils/json-comparison.js

@@ -0,0 +1,232 @@
+import chalk from "chalk";
+
+//#region src/utils/json-comparison.ts
+/**
+* Deep compare two FullProjectDefinition objects
+*
+* Ignores timestamp fields (createdAt, updatedAt) and provides detailed
+* error messages about specific differences.
+*
+* @param original - The original project definition from the backend
+* @param generated - The generated project definition from loaded TypeScript
+* @returns Comparison result with matches boolean and list of differences
+*/
+function compareProjectDefinitions(original, generated) {
+	const differences = [];
+	const warnings = [];
+	const dbGeneratedFields = ["agentToolRelationId"];
+	const sdkGeneratedFields = ["type"];
+	const contextFields = [
+		"tenantId",
+		"projectId",
+		"agentId"
+	];
+	const cosmenticFields = ["imageUrl"];
+	const allIgnoredFields = [
+		...dbGeneratedFields,
+		...sdkGeneratedFields,
+		...contextFields,
+		...cosmenticFields
+	];
+	const isEmpty = (value) => {
+		if (value === void 0 || value === null) return true;
+		if (Array.isArray(value) && value.length === 0) return true;
+		if (typeof value === "object" && Object.keys(value).length === 0) return true;
+		return false;
+	};
+	const isSchemaField = (path) => {
+		return path.endsWith(".props") || path.endsWith(".schema") || path.endsWith("Schema") || path.includes(".props.") || path.includes(".schema.");
+	};
+	const hasContent = (value) => {
+		if (!value || typeof value !== "object") return false;
+		if (Array.isArray(value)) return value.length > 0;
+		return Object.keys(value).length > 0;
+	};
+	const comparePrimitive = (path, a, b) => {
+		if (a === b) return true;
+		if (isSchemaField(path)) {
+			const aHasContent = hasContent(a);
+			const bHasContent = hasContent(b);
+			if (aHasContent !== bHasContent) return false;
+			if (!aHasContent && !bHasContent) return true;
+		} else if (isEmpty(a) && isEmpty(b)) return true;
+		if (path.includes("credential") || path.endsWith("ReferenceId")) {
+			if (typeof a === "string" && typeof b === "object" && b !== null && "id" in b) return a === b.id;
+			if (typeof b === "string" && typeof a === "object" && a !== null && "id" in a) return b === a.id;
+		}
+		if (typeof a !== typeof b) {
+			differences.push(`Type mismatch at ${path}: ${typeof a} vs ${typeof b}`);
+			return false;
+		}
+		if (a !== b) {
+			differences.push(`Value mismatch at ${path}: "${a}" vs "${b}"`);
+			return false;
+		}
+		return true;
+	};
+	const compareArrays = (path, a, b) => {
+		if (a.length !== b.length) {
+			differences.push(`Array length mismatch at ${path}: ${a.length} vs ${b.length}`);
+			return false;
+		}
+		if ([
+			"canDelegateTo",
+			"canTransferTo",
+			"canUse",
+			"tools",
+			"functionTools",
+			"dataComponents",
+			"artifactComponents"
+		].some((pattern) => path.includes(pattern))) {
+			const allIgnoredFields$1 = [
+				...dbGeneratedFields,
+				...sdkGeneratedFields,
+				...contextFields
+			];
+			const filterIgnoredFields = (item) => {
+				if (typeof item === "object" && item !== null) {
+					const filtered = { ...item };
+					allIgnoredFields$1.forEach((field) => delete filtered[field]);
+					return JSON.stringify(filtered);
+				}
+				return item;
+			};
+			const aSet = new Set(a.map(filterIgnoredFields));
+			const bSet = new Set(b.map(filterIgnoredFields));
+			if (aSet.size !== bSet.size) {
+				differences.push(`Array content mismatch at ${path}: different unique elements`);
+				return false;
+			}
+			for (const item of aSet) if (!bSet.has(item)) {
+				differences.push(`Array content mismatch at ${path}: missing element ${item}`);
+				return false;
+			}
+			return true;
+		}
+		let allMatch = true;
+		for (let i = 0; i < a.length; i++) if (!compareValues(`${path}[${i}]`, a[i], b[i])) allMatch = false;
+		return allMatch;
+	};
+	const compareObjects = (path, a, b) => {
+		const ignoredFields = ["createdAt", "updatedAt"];
+		const aKeys = Object.keys(a || {}).filter((k) => !ignoredFields.includes(k));
+		const bKeys = Object.keys(b || {}).filter((k) => !ignoredFields.includes(k));
+		const missingInB = aKeys.filter((k) => !bKeys.includes(k) && a[k] !== null && !(Array.isArray(a[k]) && a[k].length === 0) && !(typeof a[k] === "object" && a[k] !== null && Object.keys(a[k]).length === 0) && !allIgnoredFields.includes(k) && k !== "$schema" && !(k === "properties" && path.includes(".schema")) && !(k === "required" && path.includes(".schema")) && !(k === "additionalProperties" && path.includes(".schema")));
+		const extraInB = bKeys.filter((k) => !aKeys.includes(k) && b[k] !== null && !(Array.isArray(b[k]) && b[k].length === 0) && !(typeof b[k] === "object" && b[k] !== null && Object.keys(b[k]).length === 0) && !allIgnoredFields.includes(k) && k !== "$schema" && !(k === "additionalProperties" && path.includes(".props")));
+		if (missingInB.length > 0) differences.push(`Missing keys in generated at ${path}: ${missingInB.join(", ")}`);
+		if (extraInB.length > 0) {
+			const meaningfulExtraKeys = [];
+			const emptyExtraKeys = [];
+			for (const key of extraInB) {
+				const value = b[key];
+				if (value === null || value === void 0 || value === "" || Array.isArray(value) && value.length === 0 || typeof value === "object" && value !== null && Object.keys(value).length === 0) emptyExtraKeys.push(key);
+				else meaningfulExtraKeys.push(key);
+			}
+			if (meaningfulExtraKeys.length > 0) differences.push(`Extra keys in generated at ${path}: ${meaningfulExtraKeys.join(", ")}`);
+			if (emptyExtraKeys.length > 0) warnings.push(`Extra keys in generated at ${path}: ${emptyExtraKeys.join(", ")}`);
+		}
+		let allMatch = true;
+		for (const key of aKeys) if (bKeys.includes(key)) {
+			if (!compareValues(`${path}.${key}`, a[key], b[key])) allMatch = false;
+		}
+		return allMatch && missingInB.length === 0;
+	};
+	const compareValues = (path, a, b) => {
+		if ((path.match(/\./g) || []).length > 50) {
+			warnings.push(`Max comparison depth reached at ${path}`);
+			return true;
+		}
+		if (a === null && b === null) return true;
+		if (a === void 0 && b === void 0) return true;
+		if (a === null && b === void 0 || a === void 0 && b === null) return true;
+		if (Array.isArray(a) && a.length === 0 && b === void 0) return true;
+		if (a === void 0 && Array.isArray(b) && b.length === 0) return true;
+		if (typeof a === "object" && a !== null && Object.keys(a).length === 0 && b === void 0) return true;
+		if (a === void 0 && typeof b === "object" && b !== null && Object.keys(b).length === 0) return true;
+		if (path.includes(".models") && typeof a === "object" && a !== null && b === void 0) {
+			if (a.model || a.provider || typeof a === "object" && (a.base || a.fast || a.smart)) {
+				warnings.push(`Model inheritance at ${path}: API has explicit model config, generator uses inheritance (this is expected)`);
+				return true;
+			}
+		}
+		if (path.includes(".models") && a === void 0 && typeof b === "object" && b !== null) {
+			if (b.model || b.provider || typeof b === "object" && (b.base || b.fast || b.smart)) {
+				warnings.push(`Model inheritance at ${path}: generator has explicit model config, API uses inheritance (this is expected)`);
+				return true;
+			}
+		}
+		if (Array.isArray(a) && Array.isArray(b)) return compareArrays(path, a, b);
+		if (Array.isArray(a) !== Array.isArray(b)) {
+			differences.push(`Array type mismatch at ${path}`);
+			return false;
+		}
+		if (typeof a === "object" && typeof b === "object") return compareObjects(path, a, b);
+		return comparePrimitive(path, a, b);
+	};
+	comparePrimitive("id", original.id, generated.id);
+	comparePrimitive("name", original.name, generated.name);
+	if (original.description || generated.description) {
+		const origDesc = original.description || "";
+		const genDesc = generated.description || "";
+		if (origDesc !== genDesc) comparePrimitive("description", origDesc, genDesc);
+	}
+	if (original.models || generated.models) compareValues("models", original.models, generated.models);
+	if (original.stopWhen || generated.stopWhen) compareValues("stopWhen", original.stopWhen, generated.stopWhen);
+	const originalAgentIds = Object.keys(original.agents || {});
+	const generatedAgentIds = Object.keys(generated.agents || {});
+	if (originalAgentIds.length !== generatedAgentIds.length) differences.push(`Agent count mismatch: ${originalAgentIds.length} vs ${generatedAgentIds.length}`);
+	for (const agentId of originalAgentIds) if (!generatedAgentIds.includes(agentId)) differences.push(`Missing agent in generated: ${agentId}`);
+	else compareValues(`agents.${agentId}`, original.agents?.[agentId], generated.agents?.[agentId]);
+	for (const agentId of generatedAgentIds) if (!originalAgentIds.includes(agentId)) warnings.push(`Extra agent in generated: ${agentId}`);
+	const originalToolIds = Object.keys(original.tools || {});
+	const generatedToolIds = Object.keys(generated.tools || {});
+	if (originalToolIds.length !== generatedToolIds.length) differences.push(`Tool count mismatch: ${originalToolIds.length} vs ${generatedToolIds.length}`);
+	for (const toolId of originalToolIds) if (!generatedToolIds.includes(toolId)) differences.push(`Missing tool in generated: ${toolId}`);
+	else compareValues(`tools.${toolId}`, original.tools?.[toolId], generated.tools?.[toolId]);
+	if (original.functions || generated.functions) {
+		const originalFunctionIds = Object.keys(original.functions || {});
+		const generatedFunctionIds = Object.keys(generated.functions || {});
+		for (const functionId of originalFunctionIds) if (!generatedFunctionIds.includes(functionId)) differences.push(`Missing function in generated: ${functionId}`);
+		else compareValues(`functions.${functionId}`, original.functions?.[functionId], generated.functions?.[functionId]);
+	}
+	if (original.functionTools || generated.functionTools) {
+		const originalFunctionToolIds = Object.keys(original.functionTools || {});
+		const generatedFunctionToolIds = Object.keys(generated.functionTools || {});
+		if (originalFunctionToolIds.length !== generatedFunctionToolIds.length) differences.push(`Function tool count mismatch: ${originalFunctionToolIds.length} vs ${generatedFunctionToolIds.length}`);
+		for (const functionToolId of originalFunctionToolIds) if (!generatedFunctionToolIds.includes(functionToolId)) differences.push(`Missing function tool in generated: ${functionToolId}`);
+		else compareValues(`functionTools.${functionToolId}`, original.functionTools?.[functionToolId], generated.functionTools?.[functionToolId]);
+		for (const functionToolId of generatedFunctionToolIds) if (!originalFunctionToolIds.includes(functionToolId)) warnings.push(`Extra function tool in generated: ${functionToolId}`);
+	}
+	if (original.dataComponents || generated.dataComponents) {
+		const originalComponentIds = Object.keys(original.dataComponents || {});
+		const generatedComponentIds = Object.keys(generated.dataComponents || {});
+		for (const componentId of originalComponentIds) if (!generatedComponentIds.includes(componentId)) differences.push(`Missing data component in generated: ${componentId}`);
+		else compareValues(`dataComponents.${componentId}`, original.dataComponents?.[componentId], generated.dataComponents?.[componentId]);
+	}
+	if (original.artifactComponents || generated.artifactComponents) {
+		const originalArtifactIds = Object.keys(original.artifactComponents || {});
+		const generatedArtifactIds = Object.keys(generated.artifactComponents || {});
+		for (const artifactId of originalArtifactIds) if (!generatedArtifactIds.includes(artifactId)) differences.push(`Missing artifact component in generated: ${artifactId}`);
+		else compareValues(`artifactComponents.${artifactId}`, original.artifactComponents?.[artifactId], generated.artifactComponents?.[artifactId]);
+	}
+	if (original.credentialReferences || generated.credentialReferences) {
+		const originalCredIds = Object.keys(original.credentialReferences || {});
+		const generatedCredIds = Object.keys(generated.credentialReferences || {});
+		for (const credId of originalCredIds) if (!generatedCredIds.includes(credId)) differences.push(`Missing credential reference in generated: ${credId}`);
+		else {
+			const origCred = { ...original.credentialReferences?.[credId] || {} };
+			const genCred = { ...generated.credentialReferences?.[credId] || {} };
+			delete origCred.usedBy;
+			delete genCred.usedBy;
+			compareValues(`credentialReferences.${credId}`, origCred, genCred);
+		}
+	}
+	return {
+		matches: differences.length === 0,
+		differences,
+		warnings
+	};
+}
+
+//#endregion
+export { compareProjectDefinitions };