feat: project wiki

src/__tests__/project-wiki-command.spec.ts

@@ -0,0 +1,88 @@
+import { getCommands, getCommand } from "../services/command/commands"
+import { ensureProjectWikiCommandExists } from "../core/tools/helpers/projectWikiHelpers"
+import { projectWikiCommandName } from "../core/tools/helpers/projectWikiHelpers"
+
+describe("Project Wiki Command Integration", () => {
+	const testCwd = process.cwd()
+
+	describe("动态命令初始化", () => {
+		it("应该能够初始化 project-wiki 命令而不抛出错误", async () => {
+			// 测试 ensureProjectWikiCommandExists 函数
+			await expect(ensureProjectWikiCommandExists()).resolves.not.toThrow()
+		})
+
+		it("getCommands() 应该包含 project-wiki 命令", async () => {
+			// 确保命令已初始化
+			await ensureProjectWikiCommandExists()
+
+			// 获取所有命令
+			const commands = await getCommands(testCwd)
+
+			// 验证命令列表是数组
+			expect(Array.isArray(commands)).toBe(true)
+
+			// 查找 project-wiki 命令
+			const projectWikiCommand = commands.find((cmd) => cmd.name === projectWikiCommandName)
+
+			// 验证 project-wiki 命令存在
+			expect(projectWikiCommand).toBeDefined()
+
+			if (projectWikiCommand) {
+				expect(projectWikiCommand.name).toBe(projectWikiCommandName)
+				expect(projectWikiCommand.source).toBe("global")
+				expect(typeof projectWikiCommand.content).toBe("string")
+				expect(projectWikiCommand.content.length).toBeGreaterThan(0)
+				expect(projectWikiCommand.filePath).toContain("project-wiki.md")
+			}
+		})
+
+		it("getCommand() 应该能够获取 project-wiki 命令", async () => {
+			// 确保命令已初始化
+			await ensureProjectWikiCommandExists()
+
+			// 获取特定命令
+			const command = await getCommand(testCwd, projectWikiCommandName)
+
+			// 验证命令存在且正确
+			expect(command).toBeDefined()
+			expect(command?.name).toBe(projectWikiCommandName)
+			expect(command?.source).toBe("global")
+			expect(typeof command?.content).toBe("string")
+			expect(command?.content.length).toBeGreaterThan(0)
+		})
+	})
+
+	describe("错误处理机制", () => {
+		it("即使 ensureProjectWikiCommandExists 失败，getCommands 也应该正常工作", async () => {
+			// 这个测试验证错误隔离机制
+			// 即使动态命令初始化失败，其他命令仍应正常工作
+			const commands = await getCommands(testCwd)
+
+			// 应该返回数组（可能为空，但不应该抛出错误）
+			expect(Array.isArray(commands)).toBe(true)
+		})
+
+		it("应该能够处理重复的命令初始化调用", async () => {
+			// 多次调用应该不会出错
+			await expect(ensureProjectWikiCommandExists()).resolves.not.toThrow()
+			await expect(ensureProjectWikiCommandExists()).resolves.not.toThrow()
+			await expect(ensureProjectWikiCommandExists()).resolves.not.toThrow()
+		})
+	})
+
+	describe("命令内容验证", () => {
+		it("project-wiki 命令应该包含预期的内容结构", async () => {
+			await ensureProjectWikiCommandExists()
+			const command = await getCommand(testCwd, projectWikiCommandName)
+
+			expect(command).toBeDefined()
+			if (command) {
+				// 验证命令内容包含预期的关键词（中文内容）
+				const content = command.content
+				expect(content).toContain("项目")
+				expect(content).toContain("wiki")
+				expect(content).toContain("分析")
+			}
+		})
+	})
+})

src/core/tools/__tests__/projectWikiHelpers.spec.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect, vi, beforeEach } from "vitest"
+import { ensureProjectWikiCommandExists } from "../helpers/projectWikiHelpers"
+import { promises as fs } from "fs"
+import * as path from "path"
+import * as os from "os"
+
+// Mock fs module
+vi.mock("fs")
+const mockedFs = vi.mocked(fs)
+
+describe("projectWikiHelpers", () => {
+	const globalCommandsDir = path.join(os.homedir(), ".roo", "commands")
+	const projectWikiFile = path.join(globalCommandsDir, "project-wiki.md")
+	const subTaskDir = path.join(globalCommandsDir, "subtasks")
+
+	beforeEach(() => {
+		vi.clearAllMocks()
+	})
+
+	it("should successfully create wiki command files", async () => {
+		// Mock file system operations
+		mockedFs.mkdir.mockResolvedValue(undefined)
+		mockedFs.access.mockRejectedValue(new Error("File not found"))
+		mockedFs.rm.mockResolvedValue(undefined)
+		mockedFs.writeFile.mockResolvedValue(undefined)
+		mockedFs.readdir.mockResolvedValue([
+			"01_Project_Overview_Analysis.md",
+			"02_Overall_Architecture_Analysis.md",
+		] as any)
+
+		// Execute function
+		await expect(ensureProjectWikiCommandExists()).resolves.not.toThrow()
+
+		// Verify calls
+		expect(mockedFs.mkdir).toHaveBeenCalledWith(globalCommandsDir, { recursive: true })
+		expect(mockedFs.writeFile).toHaveBeenCalledTimes(10) // 1 main file + 9 subtask files
+	})
+
+	it("should skip creation when files already exist", async () => {
+		// Mock existing files
+		mockedFs.mkdir.mockResolvedValue(undefined)
+		mockedFs.access.mockResolvedValue(undefined)
+		mockedFs.stat.mockResolvedValue({
+			isDirectory: () => true,
+		} as any)
+		mockedFs.readdir.mockResolvedValue(["01_Project_Overview_Analysis.md"] as any)
+
+		// Execute function
+		await expect(ensureProjectWikiCommandExists()).resolves.not.toThrow()
+
+		// Verify no write operations were called
+		expect(mockedFs.writeFile).not.toHaveBeenCalled()
+	})
+
+	it("should generate all wiki files correctly", async () => {
+		// Read the modified projectWikiHelpers.ts file to test the generateWikiFiles function
+		// generateWikiFiles is an internal function and not exported, so we test ensureProjectWikiCommandExists instead
+		// This will indirectly test the functionality of generateWikiFiles
+		expect(true).toBe(true) // Placeholder test
+	})
+})

src/core/tools/helpers/projectWikiHelpers.ts

@@ -0,0 +1,178 @@
+import { promises as fs } from "fs"
+import * as path from "path"
+import * as os from "os"
+import { PROJECT_WIKI_TEMPLATE } from "./wiki-prompts/project-wiki"
+import { PROJECT_OVERVIEW_ANALYSIS_TEMPLATE } from "./wiki-prompts/subtasks/01_Project_Overview_Analysis"
+import { OVERALL_ARCHITECTURE_ANALYSIS_TEMPLATE } from "./wiki-prompts/subtasks/02_Overall_Architecture_Analysis"
+import { SERVICE_DEPENDENCIES_ANALYSIS_TEMPLATE } from "./wiki-prompts/subtasks/03_Service_Dependencies_Analysis"
+import { DATA_FLOW_INTEGRATION_ANALYSIS_TEMPLATE } from "./wiki-prompts/subtasks/04_Data_Flow_Integration_Analysis"
+import { SERVICE_ANALYSIS_TEMPLATE } from "./wiki-prompts/subtasks/05_Service_Analysis_Template"
+import { DATABASE_SCHEMA_ANALYSIS_TEMPLATE } from "./wiki-prompts/subtasks/06_Database_Schema_Analysis"
+import { API_INTERFACE_ANALYSIS_TEMPLATE } from "./wiki-prompts/subtasks/07_API_Interface_Analysis"
+import { DEPLOY_ANALYSIS_TEMPLATE } from "./wiki-prompts/subtasks/08_Deploy_Analysis"
+import { PROJECT_RULES_GENERATION_TEMPLATE } from "./wiki-prompts/subtasks/09_Project_Rules_Generation"
+import { ILogger, createLogger } from "../../../utils/logger"
+
+// Safely get home directory
+function getHomeDir(): string {
+	const homeDir = os.homedir()
+	if (!homeDir) {
+		throw new Error("Unable to determine home directory")
+	}
+	return homeDir
+}
+
+// Get global commands directory path
+function getGlobalCommandsDir(): string {
+	return path.join(getHomeDir(), ".roo", "commands")
+}
+
+export const projectWikiCommandName = "project-wiki"
+export const projectWikiCommandDescription = `Analyze project deeply and generate a comprehensive project wiki.`
+
+const logger: ILogger = createLogger("ProjectWikiHelpers")
+
+// Unified error handling function, preserving stack information
+function formatError(error: unknown): string {
+	if (error instanceof Error) {
+		return error.stack || error.message
+	}
+	return String(error)
+}
+
+const mainFileName: string = projectWikiCommandName + ".md"
+// Template data mapping
+const TEMPLATES = {
+	[mainFileName]: PROJECT_WIKI_TEMPLATE,
+	"01_Project_Overview_Analysis.md": PROJECT_OVERVIEW_ANALYSIS_TEMPLATE,
+	"02_Overall_Architecture_Analysis.md": OVERALL_ARCHITECTURE_ANALYSIS_TEMPLATE,
+	"03_Service_Dependencies_Analysis.md": SERVICE_DEPENDENCIES_ANALYSIS_TEMPLATE,
+	"04_Data_Flow_Integration_Analysis.md": DATA_FLOW_INTEGRATION_ANALYSIS_TEMPLATE,
+	"05_Service_Analysis_Template.md": SERVICE_ANALYSIS_TEMPLATE,
+	"06_Database_Schema_Analysis.md": DATABASE_SCHEMA_ANALYSIS_TEMPLATE,
+	"07_API_Interface_Analysis.md": API_INTERFACE_ANALYSIS_TEMPLATE,
+	"08_Deploy_Analysis.md": DEPLOY_ANALYSIS_TEMPLATE,
+	"09_Project_Rules_Generation.md": PROJECT_RULES_GENERATION_TEMPLATE,
+}
+
+export async function ensureProjectWikiCommandExists() {
+	const startTime = Date.now()
+	logger.info("[projectWikiHelpers] Starting ensureProjectWikiCommandExists...")
+
+	try {
+		const globalCommandsDir = getGlobalCommandsDir()
+		await fs.mkdir(globalCommandsDir, { recursive: true })
+
+		const projectWikiFile = path.join(globalCommandsDir, `${projectWikiCommandName}.md`)
+		const subTaskDir = path.join(globalCommandsDir, "subtasks")
+
+		// Check if setup is needed
+		const needsSetup = await checkIfSetupNeeded(projectWikiFile, subTaskDir)
+		if (!needsSetup) {
+			logger.info("[projectWikiHelpers] project-wiki command already exists")
+			return
+		}
+
+		logger.info("[projectWikiHelpers] Setting up project-wiki command...")
+
+		// Clean up existing files
+		await Promise.allSettled([
+			fs.rm(projectWikiFile, { force: true }),
+			fs.rm(subTaskDir, { recursive: true, force: true }),
+		])
+
+		// Generate Wiki files
+		await generateWikiCommandFiles(projectWikiFile, subTaskDir)
+
+		const duration = Date.now() - startTime
+		logger.info(`[projectWikiHelpers] project-wiki command setup completed in ${duration}ms`)
+	} catch (error) {
+		const errorMsg = formatError(error)
+		throw new Error(`Failed to setup project-wiki command: ${errorMsg}`)
+	}
+}
+
+// Optimized file checking logic, using Promise.allSettled to improve performance
+async function checkIfSetupNeeded(projectWikiFile: string, subTaskDir: string): Promise<boolean> {
+	try {
+		const [mainFileResult, subDirResult] = await Promise.allSettled([
+			fs.access(projectWikiFile, fs.constants.F_OK | fs.constants.R_OK | fs.constants.W_OK),
+			fs.stat(subTaskDir),
+		])
+
+		// If main file doesn't exist, setup is needed
+		if (mainFileResult.status === "rejected") {
+			logger.info("[projectWikiHelpers] projectWikiFile not accessible:", formatError(mainFileResult.reason))
+			return true
+		}
+
+		// If subtask directory doesn't exist or is not a directory, setup is needed
+		if (subDirResult.status === "rejected") {
+			logger.info("[projectWikiHelpers] subTaskDir not accessible:", formatError(subDirResult.reason))
+			return true
+		}
+
+		if (!subDirResult.value.isDirectory()) {
+			logger.info("[projectWikiHelpers] subTaskDir exists but is not a directory")
+			return true
+		}
+
+		// Check if subtask directory has .md files
+		const subTaskFiles = await fs.readdir(subTaskDir)
+		const mdFiles = subTaskFiles.filter((file) => file.endsWith(".md"))
+		return mdFiles.length === 0
+	} catch (error) {
+		logger.error("[projectWikiHelpers] Error checking setup status:", formatError(error))
+		return true
+	}
+}
+
+// Generate Wiki files
+async function generateWikiCommandFiles(projectWikiFile: string, subTaskDir: string): Promise<void> {
+	try {
+		// Generate main file
+		const mainTemplate = TEMPLATES[mainFileName]
+		if (!mainTemplate) {
+			throw new Error("Main template not found")
+		}
+
+		await fs.writeFile(projectWikiFile, mainTemplate, "utf-8")
+		logger.info(`[projectWikiHelpers] Generated main wiki file: ${projectWikiFile}`)
+
+		// Create subtask directory
+		await fs.mkdir(subTaskDir, { recursive: true })
+
+		// Generate subtask files
+		const subTaskFiles = Object.keys(TEMPLATES).filter((file) => file !== mainFileName)
+		const generateResults = await Promise.allSettled(
+			subTaskFiles.map(async (file) => {
+				const template = TEMPLATES[file as keyof typeof TEMPLATES]
+				if (!template) {
+					throw new Error(`Template not found for file: ${file}`)
+				}
+
+				const targetFile = path.join(subTaskDir, file)
+				await fs.writeFile(targetFile, template, "utf-8")
+				return file
+			}),
+		)
+
+		// Count generation results
+		const successful = generateResults.filter((result) => result.status === "fulfilled")
+		const failed = generateResults.filter((result) => result.status === "rejected")
+
+		logger.info(`[projectWikiHelpers] Successfully generated ${successful.length} subtask files`)
+
+		if (failed.length > 0) {
+			logger.warn(`[projectWikiHelpers] Failed to generate ${failed.length} subtask files:`)
+			failed.forEach((result, index) => {
+				if (result.status === "rejected") {
+					logger.warn(`  - ${subTaskFiles[generateResults.indexOf(result)]}: ${formatError(result.reason)}`)
+				}
+			})
+		}
+	} catch (error) {
+		const errorMsg = formatError(error)
+		throw new Error(`Failed to generate wiki files: ${errorMsg}`)
+	}
+}

src/core/tools/helpers/wiki-prompts/project-wiki.ts

@@ -0,0 +1,24 @@
+import * as os from "os"
+import * as path from "path"
+import { WIKI_OUTPUT_DIR } from "./subtasks/constants"
+
+const subtaskDir = path.join(os.homedir(), ".roo", "commands", "subtasks") + path.sep
+export const PROJECT_WIKI_TEMPLATE = `---
+description: "深度分析项目，生成技术文档"
+---
+您是一位专业的技术作家和软件架构师。
+以下每个文件中的内容都是一个任务，按顺序作为指令严格逐个执行:
+
+[项目概览分析](${subtaskDir}01_Project_Overview_Analysis.md)
+[整体架构分析](${subtaskDir}02_Overall_Architecture_Analysis.md)
+[服务依赖分析](${subtaskDir}03_Service_Dependencies_Analysis.md)
+[数据流分析](${subtaskDir}04_Data_Flow_Integration_Analysis.md)
+[服务模块分析](${subtaskDir}05_Service_Analysis_Template.md)
+[数据库分析](${subtaskDir}06_Database_Schema_Analysis.md)
+[API分析](${subtaskDir}07_API_Interface_Analysis.md)
+[部署分析](${subtaskDir}08_Deploy_Analysis.md)
+[Rues生成](${subtaskDir}09_Project_Rules_Generation.md)
+注意：
+1、如果未发现上述文件，直接退出报错即可，禁止自作主张！
+2、一切以实际项目为准，禁止无中生有！
+3、最终产物是${WIKI_OUTPUT_DIR}目录下的若干个技术文档，生成完成后，为它们在${WIKI_OUTPUT_DIR}目录下创建一个index.md 文件，内容是前面技术文档的简洁目录,index.md控制20行左右；`