@inkeep/agents-cli 0.51.0 → 0.53.0

package/dist/commands/pull-v4/introspect/index.js

@@ -0,0 +1,365 @@
+import { ManagementApiClient } from "../../../api.js";
+import { initializeCommand } from "../../../utils/cli-pipeline.js";
+import { performBackgroundVersionCheck } from "../../../utils/background-version-check.js";
+import { loadProject } from "../../../utils/project-loader.js";
+import { extractSubAgents } from "../component-registry.js";
+import { introspectGenerate } from "../introspect-generator.js";
+import { join, resolve } from "node:path";
+import * as p from "@clack/prompts";
+import { existsSync, mkdirSync } from "node:fs";
+import { EventEmitter } from "node:events";
+import { styleText } from "node:util";
+
+//#region src/commands/pull-v4/introspect/index.ts
+/**
+* Pull v3 - Clean, efficient project generation
+*
+* Step 1: Validate and compile existing code
+* Step 2: Compare project with DB to detect ALL changes
+* Step 3: Classify changes as new vs modified components
+* Step 4: Generate new components deterministically
+* Step 5: Use LLM to correct modified components
+*/
+EventEmitter.defaultMaxListeners = 20;
+/**
+* Create project directory structure
+*/
+function createProjectStructure(projectRoot) {
+	mkdirSync(projectRoot, { recursive: true });
+	return {
+		projectRoot,
+		agentsDir: join(projectRoot, "agents"),
+		toolsDir: join(projectRoot, "tools"),
+		dataComponentsDir: join(projectRoot, "data-components"),
+		artifactComponentsDir: join(projectRoot, "artifact-components"),
+		statusComponentsDir: join(projectRoot, "status-components"),
+		environmentsDir: join(projectRoot, "environments"),
+		credentialsDir: join(projectRoot, "credentials"),
+		contextConfigsDir: join(projectRoot, "context-configs"),
+		externalAgentsDir: join(projectRoot, "external-agents"),
+		skillsDir: join(projectRoot, "skills")
+	};
+}
+/**
+* Enrich canDelegateTo references with component type information
+*/
+function enrichCanDelegateToWithTypes(project) {
+	const agentsIdSet = new Set(project.agents ? Object.keys(project.agents) : []);
+	const subAgentsIdSet = new Set(Object.keys(extractSubAgents(project)));
+	const externalAgentsIdSet = new Set(project.externalAgents ? Object.keys(project.externalAgents) : []);
+	function enrichCanDelegateToArray(canDelegateTo) {
+		return canDelegateTo.map((item) => {
+			if (typeof item !== "string") return item;
+			if (agentsIdSet.has(item)) return { agentId: item };
+			if (subAgentsIdSet.has(item)) return { subAgentId: item };
+			if (externalAgentsIdSet.has(item)) return { externalAgentId: item };
+			return item;
+		});
+	}
+	if (project.agents) {
+		for (const agentData of Object.values(project.agents)) if (agentData.subAgents) {
+			for (const subAgentData of Object.values(agentData.subAgents)) if (subAgentData.canDelegateTo) subAgentData.canDelegateTo = enrichCanDelegateToArray(subAgentData.canDelegateTo);
+		}
+	}
+}
+/**
+* Main pull v4 command
+* @returns PullResult when in batch mode, otherwise void (exits process)
+*/
+async function pullV4Command(options) {
+	if (options.all) {
+		await pullAllProjects(options);
+		return;
+	}
+	const batchMode = options._batchMode ?? false;
+	const originalLogLevel = process.env.LOG_LEVEL;
+	process.env.LOG_LEVEL = "silent";
+	const restoreLogLevel = () => {
+		if (originalLogLevel !== void 0) process.env.LOG_LEVEL = originalLogLevel;
+		else delete process.env.LOG_LEVEL;
+	};
+	if (!batchMode) performBackgroundVersionCheck();
+	console.log(styleText("blue", "\nInkeep Pull:"));
+	if (options.introspect) console.log(styleText("gray", "  Introspect mode • Complete regeneration • No comparison needed"));
+	else console.log(styleText("gray", "  Smart comparison • Detect all changes • Targeted updates"));
+	const s = p.spinner();
+	try {
+		const { config, isCI } = await initializeCommand({
+			configPath: options.config,
+			profileName: options.profile,
+			tag: options.tag,
+			showSpinner: true,
+			spinnerText: "Loading configuration...",
+			logConfig: true,
+			quiet: options.quiet
+		});
+		s.start("Detecting project...");
+		let projectDir;
+		let projectId;
+		let localProjectForId = null;
+		const currentDir = process.cwd();
+		if (existsSync(join(currentDir, "index.ts"))) {
+			projectDir = currentDir;
+			s.start("Loading local project...");
+			try {
+				localProjectForId = await loadProject(projectDir);
+				const localProjectId = localProjectForId.getId();
+				if (options.project) {
+					if (localProjectId !== options.project) {
+						s.stop("Project ID mismatch");
+						console.error(styleText("red", `Local project ID "${localProjectId}" doesn't match --project "${options.project}"`));
+						console.error(styleText("yellow", "Either remove --project flag or ensure it matches the local project ID"));
+						if (batchMode) return {
+							success: false,
+							error: "Project ID mismatch"
+						};
+						process.exit(1);
+					}
+				}
+				projectId = localProjectId;
+				s.stop(`Using local project: ${projectId}`);
+			} catch (error) {
+				s.stop("Failed to load local project");
+				throw new Error(`Could not load local project: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		} else {
+			if (!options.project) {
+				s.stop("No index.ts found in current directory");
+				console.error(styleText("yellow", "Please run this command from a directory containing index.ts or use --project <project-id>"));
+				if (batchMode) return {
+					success: false,
+					error: "No index.ts found and no --project specified"
+				};
+				process.exit(1);
+			}
+			const projectPath = resolve(currentDir, options.project);
+			if (existsSync(join(projectPath, "index.ts"))) {
+				projectDir = projectPath;
+				s.start("Loading project from specified path...");
+				try {
+					localProjectForId = await loadProject(projectDir);
+					projectId = localProjectForId.getId();
+					s.stop(`Using project from path: ${projectId}`);
+				} catch (error) {
+					s.stop("Failed to load project from path");
+					throw new Error(`Could not load project from ${projectPath}: ${error instanceof Error ? error.message : String(error)}`);
+				}
+			} else {
+				projectId = options.project;
+				projectDir = join(currentDir, projectId);
+				s.stop(`Creating new project directory: ${projectDir}`);
+			}
+		}
+		s.start(`Fetching project: ${projectId}`);
+		const remoteProject = await (await ManagementApiClient.create(config.agentsApiUrl, options.config, config.tenantId, projectId, isCI, config.agentsApiKey)).getFullProject(projectId);
+		if (options.debug && remoteProject.functions) {
+			console.log(styleText("gray", "   📋 Project-level functions from API:"), Object.keys(remoteProject.functions));
+			Object.entries(remoteProject.functions).forEach(([id, data]) => {
+				console.log(styleText("gray", `      ${id}: has name=${!!data.name}, has description=${!!data.description}`));
+			});
+		}
+		if (remoteProject.agents) for (const [agentId, agentData] of Object.entries(remoteProject.agents)) {
+			if (agentData.functionTools) {
+				remoteProject.functionTools = remoteProject.functionTools || {};
+				Object.assign(remoteProject.functionTools, agentData.functionTools);
+				if (options.debug) console.log(styleText("gray", `   Hoisted functionTools from agent ${agentId}: ${Object.keys(agentData.functionTools).join(", ")}`));
+			}
+			if (agentData.functions) {
+				remoteProject.functions = remoteProject.functions || {};
+				Object.entries(agentData.functions).forEach(([funcId, funcData]) => {
+					if (!remoteProject.functions[funcId]) remoteProject.functions[funcId] = {
+						id: funcData.id,
+						inputSchema: funcData.inputSchema,
+						executeCode: funcData.executeCode,
+						dependencies: funcData.dependencies
+					};
+				});
+			}
+		}
+		if (remoteProject.agents && remoteProject.tools) {
+			const projectToolIds = Object.keys(remoteProject.tools);
+			for (const agentData of Object.values(remoteProject.agents)) if (agentData.tools) {
+				const agentSpecificTools = Object.fromEntries(Object.entries(agentData.tools).filter(([toolId]) => !projectToolIds.includes(toolId)));
+				if (Object.keys(agentSpecificTools).length > 0) agentData.tools = agentSpecificTools;
+				else delete agentData.tools;
+			}
+		}
+		enrichCanDelegateToWithTypes(remoteProject);
+		s.message("Project data fetched");
+		if (options.json) {
+			console.log(JSON.stringify(remoteProject, null, 2));
+			restoreLogLevel();
+			return;
+		}
+		const paths = createProjectStructure(projectDir);
+		if (remoteProject.skills && Object.keys(remoteProject.skills).length) {
+			const { generateSkills } = await import("../generators/skill-generator.js");
+			await generateSkills(remoteProject.skills, paths.skillsDir);
+		}
+		s.start("Starting generating files...");
+		await introspectGenerate({
+			project: remoteProject,
+			paths,
+			debug: options.debug
+		});
+		s.stop("All files generated");
+		console.log(styleText("green", "\nProject synced successfully!"));
+		console.log(styleText("gray", `   Location: ${paths.projectRoot}`));
+		console.log(styleText("gray", `   Environment: ${options.env || "development"}`));
+		console.log(styleText("yellow", "⚠️  If you encounter broken code after running `inkeep pull`, please report it at https://github.com/inkeep/agents/issues."));
+		restoreLogLevel();
+		if (batchMode) return { success: true };
+		process.exit(0);
+	} catch (error) {
+		const message = error instanceof Error ? error.stack : String(error);
+		s.stop();
+		console.error(styleText("red", `\nError: ${message}`));
+		if (options.debug && error instanceof Error) console.error(styleText("red", error.stack || ""));
+		restoreLogLevel();
+		if (batchMode) return {
+			success: false,
+			error: message
+		};
+		process.exit(1);
+	}
+}
+/**
+* Pull all projects for the current tenant
+* Uses smart comparison with LLM merging for existing projects, introspect for new projects
+*/
+async function pullAllProjects(options) {
+	console.log(styleText("blue", "\n🔄 Batch Pull: Sequential processing with smart comparison\n"));
+	console.log(styleText("gray", "  • Existing projects: Smart comparison + LLM merging + confirmation prompts"));
+	console.log(styleText("gray", "  • New projects: Fresh generation with introspect mode\n"));
+	performBackgroundVersionCheck();
+	const { config, isCI } = await initializeCommand({
+		configPath: options.config,
+		profileName: options.profile,
+		tag: options.tag,
+		showSpinner: true,
+		spinnerText: "Loading configuration...",
+		logConfig: true,
+		quiet: options.quiet
+	});
+	const s = p.spinner();
+	try {
+		s.start("Fetching project list from API...");
+		const projects = await (await ManagementApiClient.create(config.agentsApiUrl, options.config, config.tenantId, void 0, isCI, config.agentsApiKey)).listAllProjects();
+		s.stop(`Found ${projects.length} project(s)`);
+		if (!projects.length) {
+			console.log(styleText("yellow", "No projects found for this tenant."));
+			process.exit(0);
+		}
+		const existingProjects = [];
+		const newProjects = [];
+		for (const project of projects) if (existsSync(join(join(process.cwd(), project.id), "index.ts"))) existingProjects.push(project);
+		else newProjects.push(project);
+		console.log(styleText("gray", "\nProjects to pull:\n"));
+		if (existingProjects.length > 0) {
+			console.log(styleText("cyan", "  Existing (smart comparison):"));
+			for (const project of existingProjects) console.log(styleText("gray", `    • ${project.name || project.id} (${project.id})`));
+		}
+		if (newProjects.length > 0) {
+			console.log(styleText("cyan", "  New (introspect):"));
+			for (const project of newProjects) console.log(styleText("gray", `    • ${project.name || project.id} (${project.id})`));
+		}
+		console.log();
+		const results = [];
+		const total = projects.length;
+		for (let i = 0; i < projects.length; i++) {
+			const project = projects[i];
+			const progress = `[${i + 1}/${total}]`;
+			console.log(styleText("cyan", `\n${"─".repeat(60)}`));
+			console.log(styleText("cyan", `${progress} Pulling ${project.name || project.id}...`));
+			const result = await pullSingleProject(project.id, project.name, options, config, isCI);
+			results.push(result);
+			if (result.success) console.log(styleText("green", `\n  ✓ ${result.projectName || result.projectId} → ${result.targetDir}`));
+			else console.log(styleText("red", `\n  ✗ ${result.projectName || result.projectId}: ${result.error}`));
+		}
+		const succeeded = results.filter((r) => r.success).length;
+		const failed = results.filter((r) => !r.success).length;
+		console.log(styleText("cyan", `\n${"═".repeat(60)}`));
+		console.log(styleText("cyan", "📊 Batch Pull Summary:"));
+		console.log(styleText("green", `  ✓ Succeeded: ${succeeded}`));
+		if (failed > 0) {
+			console.log(styleText("red", `  ✗ Failed: ${failed}`));
+			console.log(styleText("red", "\nFailed projects:"));
+			for (const result of results) if (!result.success) console.log(styleText("red", `  • ${result.projectId}: ${result.error}`));
+		}
+		process.exit(failed > 0 ? 1 : 0);
+	} catch (error) {
+		s.stop();
+		console.error(styleText("red", `\nError: ${error instanceof Error ? error.message : String(error)}`));
+		process.exit(1);
+	}
+}
+/**
+* Pull a single project (used by batch operations)
+* Uses smart comparison flow for existing projects, introspect for new projects
+*/
+async function pullSingleProject(projectId, projectName, options, config, isCI) {
+	const targetDir = join(process.cwd(), projectId);
+	const hasExistingProject = existsSync(join(targetDir, "index.ts"));
+	try {
+		if (hasExistingProject) {
+			console.log(styleText("gray", `   📂 Existing project found - using smart comparison mode`));
+			const originalDir = process.cwd();
+			process.chdir(targetDir);
+			try {
+				const result = await pullV4Command({
+					...options,
+					project: projectId,
+					all: false,
+					_batchMode: true
+				});
+				process.chdir(originalDir);
+				if (result && typeof result === "object") return {
+					projectId,
+					projectName,
+					targetDir,
+					success: result.success,
+					error: result.error
+				};
+				return {
+					projectId,
+					projectName,
+					targetDir,
+					success: true
+				};
+			} catch (error) {
+				process.chdir(originalDir);
+				throw error;
+			}
+		}
+		console.log(styleText("gray", `   🆕 New project - using introspect mode`));
+		const originalLogLevel = process.env.LOG_LEVEL;
+		process.env.LOG_LEVEL = "silent";
+		const restoreLogLevel = () => {
+			if (originalLogLevel !== void 0) process.env.LOG_LEVEL = originalLogLevel;
+			else delete process.env.LOG_LEVEL;
+		};
+		const remoteProject = await (await ManagementApiClient.create(config.agentsApiUrl, options.config, config.tenantId, projectId, isCI, config.agentsApiKey)).getFullProject(projectId);
+		await introspectGenerate({
+			project: remoteProject,
+			paths: createProjectStructure(targetDir)
+		});
+		restoreLogLevel();
+		return {
+			projectId,
+			projectName: projectName || remoteProject.name,
+			targetDir,
+			success: true
+		};
+	} catch (error) {
+		return {
+			projectId,
+			projectName,
+			targetDir,
+			success: false,
+			error: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+
+//#endregion
+export { createProjectStructure, enrichCanDelegateToWithTypes, pullV4Command };

package/dist/commands/pull-v4/introspect/test-helpers.js

@@ -0,0 +1,143 @@
+import { createTwoFilesPatch } from "../../../node_modules/.pnpm/diff@8.0.3/node_modules/diff/libesm/patch/create.js";
+import "../../../node_modules/.pnpm/diff@8.0.3/node_modules/diff/libesm/index.js";
+import { join } from "node:path";
+import fs from "node:fs";
+import { tmpdir } from "node:os";
+
+//#region src/commands/pull-v4/introspect/test-helpers.ts
+const beforeCredentialContent = `import { credential } from '@inkeep/agents-sdk';
+
+const keepMe = () => 'keep-me';
+
+export const apiCredentials = credential({
+  id: 'api-credentials',
+  name: 'Old API Credentials',
+  type: 'bearer',
+  credentialStoreId: 'main-store'
+});
+`.trimStart();
+function createTestEnvironment() {
+	const testDir = join(tmpdir(), `introspect-v4-test-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`);
+	fs.mkdirSync(testDir, { recursive: true });
+	return {
+		testDir,
+		projectPaths: {
+			projectRoot: testDir,
+			agentsDir: join(testDir, "agents"),
+			toolsDir: join(testDir, "tools"),
+			dataComponentsDir: join(testDir, "data-components"),
+			artifactComponentsDir: join(testDir, "artifact-components"),
+			statusComponentsDir: join(testDir, "status-components"),
+			environmentsDir: join(testDir, "environments"),
+			credentialsDir: join(testDir, "credentials"),
+			contextConfigsDir: join(testDir, "context-configs"),
+			externalAgentsDir: join(testDir, "external-agents")
+		}
+	};
+}
+function cleanupTestEnvironment(testDir) {
+	fs.rmSync(testDir, {
+		recursive: true,
+		force: true
+	});
+}
+function getTestPath() {
+	return `../__tests__/__snapshots__/introspect/${expect.getState().currentTestName?.split(" > ").at(-1)}`;
+}
+function createProjectFixture() {
+	return {
+		id: "support-project",
+		name: "Support Project",
+		description: "Support project for introspect v4 tests",
+		models: { base: { model: "gpt-4o-mini" } },
+		credentialReferences: { "api-credentials": {
+			id: "api-credentials",
+			name: "API Credentials",
+			type: "bearer",
+			credentialStoreId: "main-store",
+			retrievalParams: { key: "token" }
+		} },
+		dataComponents: { "customer-profile": {
+			id: "customer-profile",
+			name: "Customer Profile",
+			description: "Customer profile data component",
+			props: {
+				type: "object",
+				properties: {
+					fullName: { type: "string" },
+					avatarUrl: { type: "string" }
+				}
+			},
+			render: {
+				component: "<img src=\"{{avatarUrl}}\" alt=\"{{fullName}}\" />",
+				mockData: {
+					fullName: "Ada Lovelace",
+					avatarUrl: "https://example.com/avatar.png"
+				}
+			}
+		} },
+		artifactComponents: { "ticket-summary": {
+			id: "ticket-summary",
+			name: "Ticket Summary",
+			props: {
+				type: "object",
+				properties: { title: { type: "string" } }
+			}
+		} },
+		agents: { "support-agent": {
+			id: "support-agent",
+			name: "Support Agent",
+			defaultSubAgentId: "tier-one",
+			subAgents: { "tier-one": {
+				id: "tier-one",
+				name: "Tier One"
+			} },
+			contextConfig: {
+				id: "support-context",
+				headersSchema: {
+					type: "object",
+					properties: { user_id: { type: "string" } }
+				},
+				contextVariables: { userInfo: {
+					id: "user-info",
+					name: "User Information",
+					trigger: "initialization",
+					fetchConfig: {
+						url: "https://api.example.com/users/${headersSchema.toTemplate(\"user_id\")}",
+						method: "GET"
+					},
+					responseSchema: {
+						type: "object",
+						properties: { name: { type: "string" } }
+					},
+					defaultValue: "Unable to fetch user information"
+				} }
+			},
+			triggers: { "github-webhook": {
+				id: "github-webhook",
+				name: "GitHub Webhook",
+				messageTemplate: "New webhook event"
+			} },
+			statusUpdates: {
+				numEvents: 1,
+				statusComponents: [{
+					id: "tool-summary",
+					type: "tool_summary",
+					description: "Tool summary status component",
+					detailsSchema: {
+						type: "object",
+						properties: { tool_name: { type: "string" } }
+					}
+				}]
+			}
+		} },
+		createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+async function createUnifiedDiff(filePath, before, after) {
+	return createTwoFilesPatch(filePath, filePath, before, after, "before", "after", { context: 3 });
+}
+
+//#endregion
+export { beforeCredentialContent, cleanupTestEnvironment, createProjectFixture, createTestEnvironment, createUnifiedDiff, getTestPath };