roadmap-skill 0.2.7 → 0.2.9

package/README.md

@@ -41,10 +41,7 @@
 ## Quick Start (Zero Config)
 
 ```bash
-# Option 1: Launch Web Kanban
-npx roadmap-skill-web
-
-# Option 2: Integrate with your AI assistant (MCP config below)
+# Integrate with your AI assistant (MCP config below)
 ```
 
 <details>
@@ -246,6 +243,31 @@ Follow Windsurf MCP documentation and use:
 
 </details>
 
+<details>
+<summary><b>Codex CLI / Codex IDE</b></summary>
+
+**One-liner (recommended):**
+
+```bash
+codex mcp add roadmap -- npx -y roadmap-skill
+```
+
+**Manual config** — edit `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.roadmap]
+command = "npx"
+args = ["-y", "roadmap-skill"]
+```
+
+> **Windows**: No `cmd /c` wrapper needed — Codex handles the subprocess directly.
+
+> **Server name**: Must match `^[a-zA-Z0-9_-]+$`. Names with spaces or parentheses are rejected.
+
+> **Note**: Both Codex CLI and the Codex VSCode extension share the same `~/.codex/config.toml`. A syntax error breaks both.
+
+</details>
+
 </details>
 
 <br>
@@ -321,7 +343,6 @@ npm install -g roadmap-skill
 ### Use Without Installing
 
 ```bash
-npx roadmap-skill-web      # Web Kanban only
 npx roadmap-skill          # Full MCP server
 ```
 

package/README.zh.md

@@ -41,10 +41,7 @@
 ## 零配置快速开始
 
 ```bash
-# 方式一：启动 Web 看板
-npx roadmap-skill-web
-
-# 方式二：集成到你的 AI 助手（MCP 配置如下）
+# 集成到你的 AI 助手（MCP 配置如下）
 ```
 
 <details>
@@ -244,6 +241,28 @@ Follow Windsurf MCP documentation and use:
 }
 ```
 
+</details>
+<details>
+<summary><b>Codex CLI / Codex IDE</b></summary>
+
+**一键安装（推荐）：**
+
+```bash
+codex mcp add roadmap -- npx -y roadmap-skill
+```
+
+**手动配置** — 编辑 `~/.codex/config.toml`：
+
+```toml
+[mcp_servers.roadmap]
+command = "npx"
+args = ["-y", "roadmap-skill"]
+```
+
+> **Windows**：无需 `cmd /c` 包装 — Codex 会直接管理子进程。
+> **服务器名称**：必须匹配 `^[a-zA-Z0-9_-]+$`，含空格或括号的名称会被拒绝。
+> **注意**：Codex CLI 和 Codex VSCode 扩展共享同一个 `~/.codex/config.toml`，语法错误会同时影响两者。
+
 </details>
 
 </details>
@@ -321,7 +340,6 @@ npm install -g roadmap-skill
 ### 免安装使用
 
 ```bash
-npx roadmap-skill-web      # 仅启动 Web 看板
 npx roadmap-skill          # 完整 MCP 服务器
 ```
 

package/dist/index.js

@@ -276,7 +276,7 @@ var ProjectStorage = class {
           if (filters.searchText && !task.title.toLowerCase().includes(filters.searchText.toLowerCase()) && !task.description.toLowerCase().includes(filters.searchText.toLowerCase())) {
             continue;
           }
-          if (filters.includeCompleted === false && task.status === "done") {
+          if (filters.includeCompleted !== true && task.status === "done") {
             continue;
           }
           results.push({ task, project: data.project });
@@ -345,15 +345,37 @@ var storage = new ProjectStorage();
 // src/tools/project-tools.ts
 var ProjectTypeEnum = z.enum(["roadmap", "skill-tree", "kanban"]);
 var ProjectStatusEnum = z.enum(["active", "completed", "archived"]);
+function toProjectSummary(project, taskCount) {
+  return {
+    id: project.id,
+    name: project.name,
+    projectType: project.projectType,
+    status: project.status,
+    targetDate: project.targetDate,
+    taskCount
+  };
+}
+function toTaskSummary(task) {
+  return {
+    id: task.id,
+    title: task.title,
+    status: task.status,
+    priority: task.priority,
+    dueDate: task.dueDate,
+    assignee: task.assignee,
+    tags: task.tags
+  };
+}
 var createProjectTool = {
   name: "create_project",
-  description: "Create a new project roadmap",
+  description: "Create a new project roadmap. Returns summary by default; set verbose=true for full data.",
   inputSchema: z.object({
     name: z.string().min(1, "Project name is required"),
     description: z.string(),
     projectType: ProjectTypeEnum,
     startDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be in YYYY-MM-DD format"),
-    targetDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be in YYYY-MM-DD format")
+    targetDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be in YYYY-MM-DD format"),
+    verbose: z.boolean().optional()
   }),
   async execute(input) {
     try {
@@ -367,7 +389,7 @@ var createProjectTool = {
       const projectData = await storage.createProject(projectInput);
       return {
         success: true,
-        data: projectData
+        data: input.verbose ? projectData : toProjectSummary(projectData.project, 0)
       };
     } catch (error) {
       return {
@@ -379,14 +401,16 @@ var createProjectTool = {
 };
 var listProjectsTool = {
   name: "list_projects",
-  description: "List all projects with their task and milestone counts",
-  inputSchema: z.object({}),
-  async execute() {
+  description: "List all projects. Returns summaries by default; set verbose=true for full project data.",
+  inputSchema: z.object({
+    verbose: z.boolean().optional()
+  }),
+  async execute(input) {
     try {
       const projects = await storage.listProjects();
       return {
         success: true,
-        data: projects
+        data: input.verbose ? projects : projects.map((p) => toProjectSummary(p.project, p.taskCount))
       };
     } catch (error) {
       return {
@@ -398,9 +422,10 @@ var listProjectsTool = {
 };
 var getProjectTool = {
   name: "get_project",
-  description: "Get a project by ID with all its data (tasks, tags, milestones)",
+  description: "Get a project by ID with all its data (tasks, tags, milestones). Tasks are returned as summaries by default; set verbose=true for full task data.",
   inputSchema: z.object({
-    projectId: z.string().min(1, "Project ID is required")
+    projectId: z.string().min(1, "Project ID is required"),
+    verbose: z.boolean().optional()
   }),
   async execute(input) {
     try {
@@ -413,7 +438,10 @@ var getProjectTool = {
       }
       return {
         success: true,
-        data: projectData
+        data: input.verbose ? projectData : {
+          ...projectData,
+          tasks: projectData.tasks.map(toTaskSummary)
+        }
       };
     } catch (error) {
       return {
@@ -425,7 +453,7 @@ var getProjectTool = {
 };
 var updateProjectTool = {
   name: "update_project",
-  description: "Update an existing project",
+  description: "Update an existing project. Returns summary by default; set verbose=true for full data.",
   inputSchema: z.object({
     projectId: z.string().min(1, "Project ID is required"),
     name: z.string().min(1).optional(),
@@ -433,11 +461,12 @@ var updateProjectTool = {
     projectType: ProjectTypeEnum.optional(),
     status: ProjectStatusEnum.optional(),
     startDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
-    targetDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional()
+    targetDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+    verbose: z.boolean().optional()
   }),
   async execute(input) {
     try {
-      const { projectId, ...updateData } = input;
+      const { projectId, verbose, ...updateData } = input;
       if (Object.keys(updateData).length === 0) {
         return {
           success: false,
@@ -454,7 +483,7 @@ var updateProjectTool = {
       }
       return {
         success: true,
-        data: projectData
+        data: verbose ? projectData : toProjectSummary(projectData.project, projectData.tasks.length)
       };
     } catch (error) {
       return {
@@ -573,9 +602,18 @@ var TagService = class {
           code: "NOT_FOUND"
         };
       }
+      const taskTagCounts = /* @__PURE__ */ new Map();
+      for (const task of projectData.tasks) {
+        for (const tagId of task.tags) {
+          taskTagCounts.set(tagId, (taskTagCounts.get(tagId) ?? 0) + 1);
+        }
+      }
       return {
         success: true,
-        data: projectData.tags
+        data: projectData.tags.map((tag) => ({
+          ...tag,
+          taskCount: taskTagCounts.get(tag.id) ?? 0
+        }))
       };
     } catch (error) {
       return {
@@ -1096,9 +1134,20 @@ init_esm_shims();
 // src/tools/task-tools.ts
 var TaskStatusEnum = z2.enum(["todo", "in-progress", "review", "done"]);
 var TaskPriorityEnum = z2.enum(["low", "medium", "high", "critical"]);
+function toTaskSummary2(task) {
+  return {
+    id: task.id,
+    title: task.title,
+    status: task.status,
+    priority: task.priority,
+    dueDate: task.dueDate,
+    assignee: task.assignee,
+    tags: task.tags
+  };
+}
 var createTaskTool = {
   name: "create_task",
-  description: "Create a new task in a project",
+  description: "Create a new task in a project. Returns summary by default; set verbose=true for full data.",
   inputSchema: z2.object({
     projectId: z2.string().min(1, "Project ID is required"),
     title: z2.string().min(1, "Task title is required"),
@@ -1106,7 +1155,8 @@ var createTaskTool = {
     priority: TaskPriorityEnum.default("medium"),
     tags: z2.array(z2.string()).default([]),
     dueDate: z2.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
-    assignee: z2.string().optional()
+    assignee: z2.string().optional(),
+    verbose: z2.boolean().optional()
   }),
   async execute(input) {
     const result = await TaskService.create(input.projectId, {
@@ -1117,12 +1167,16 @@ var createTaskTool = {
       dueDate: input.dueDate,
       assignee: input.assignee
     });
-    return result;
+    if (!result.success) return result;
+    return {
+      success: true,
+      data: input.verbose ? result.data : toTaskSummary2(result.data)
+    };
   }
 };
 var listTasksTool = {
   name: "list_tasks",
-  description: "List tasks with optional filters",
+  description: "List tasks with optional filters. By default, completed (done) tasks are excluded. Set includeCompleted=true to include them. Returns summaries by default; set verbose=true for full task data.",
   inputSchema: z2.object({
     projectId: z2.string().optional(),
     status: TaskStatusEnum.optional(),
@@ -1131,7 +1185,8 @@ var listTasksTool = {
     assignee: z2.string().optional(),
     dueBefore: z2.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
     dueAfter: z2.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
-    includeCompleted: z2.boolean().optional()
+    includeCompleted: z2.boolean().optional(),
+    verbose: z2.boolean().optional()
   }),
   async execute(input) {
     try {
@@ -1145,9 +1200,10 @@ var listTasksTool = {
         dueAfter: input.dueAfter,
         includeCompleted: input.includeCompleted
       });
+      const tasks = results.map((r) => r.task);
       return {
         success: true,
-        data: results
+        data: input.verbose ? tasks : tasks.map(toTaskSummary2)
       };
     } catch (error) {
       return {
@@ -1171,7 +1227,7 @@ var getTaskTool = {
 };
 var updateTaskTool = {
   name: "update_task",
-  description: "Update an existing task",
+  description: "Update an existing task. Returns summary by default; set verbose=true for full data.",
   inputSchema: z2.object({
     projectId: z2.string().min(1, "Project ID is required"),
     taskId: z2.string().min(1, "Task ID is required"),
@@ -1181,12 +1237,17 @@ var updateTaskTool = {
     priority: TaskPriorityEnum.optional(),
     tags: z2.array(z2.string()).optional(),
     dueDate: z2.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().nullable(),
-    assignee: z2.string().optional().nullable()
+    assignee: z2.string().optional().nullable(),
+    verbose: z2.boolean().optional()
   }),
   async execute(input) {
-    const { projectId, taskId, ...updateData } = input;
+    const { projectId, taskId, verbose, ...updateData } = input;
     const result = await TaskService.update(projectId, taskId, updateData);
-    return result;
+    if (!result.success) return result;
+    return {
+      success: true,
+      data: verbose ? result.data : toTaskSummary2(result.data)
+    };
   }
 };
 var deleteTaskTool = {
@@ -1209,22 +1270,31 @@ var deleteTaskTool = {
 };
 var batchUpdateTasksTool = {
   name: "batch_update_tasks",
-  description: "Update multiple tasks at once",
+  description: "Update multiple tasks at once. Returns summaries by default; set verbose=true for full task data.",
   inputSchema: z2.object({
     projectId: z2.string().min(1, "Project ID is required"),
     taskIds: z2.array(z2.string()).min(1, "At least one task ID is required"),
     status: TaskStatusEnum.optional(),
     priority: TaskPriorityEnum.optional(),
     tags: z2.array(z2.string()).optional(),
-    tagOperation: z2.enum(["add", "remove", "replace"]).default("replace")
+    tagOperation: z2.enum(["add", "remove", "replace"]).default("replace"),
+    verbose: z2.boolean().optional()
   }),
   async execute(input) {
-    const { projectId, taskIds, tagOperation, ...restData } = input;
+    const { projectId, taskIds, tagOperation, verbose, ...restData } = input;
     const result = await TaskService.batchUpdate(projectId, taskIds, {
       ...restData,
       tagOperation
     });
-    return result;
+    if (!result.success) return result;
+    return {
+      success: true,
+      data: {
+        updatedTasks: verbose ? result.data.updatedTasks : result.data.updatedTasks.map(toTaskSummary2),
+        updatedCount: result.data.updatedCount,
+        notFoundIds: result.data.notFoundIds
+      }
+    };
   }
 };
 
@@ -1341,7 +1411,7 @@ function resolveAppPath() {
   for (const { path: candidatePath, source } of candidates) {
     const indexPath = path4.join(candidatePath, "index.html");
     if (existsSync(indexPath)) {
-      console.log(`[roadmap-skill] Static files found at: ${candidatePath} (via ${source})`);
+      console.error(`[roadmap-skill] Static files found at: ${candidatePath} (via ${source})`);
       return candidatePath;
     }
   }
@@ -1549,7 +1619,7 @@ function createServer(port = 7860) {
     });
     const server = app.listen(port, "127.0.0.1");
     server.once("listening", () => {
-      console.log(`Web interface server running at http://localhost:${port}`);
+      console.error(`Web interface server running at http://localhost:${port}`);
       resolve(server);
     });
     server.once("error", (error) => {
@@ -2076,12 +2146,12 @@ init_esm_shims();
 init_esm_shims();
 var projectPrompts = [
   {
-    name: "recommendNextTasks",
+    name: "suggest-tasks",
     description: "Intelligently recommend the next priority tasks based on urgency, due dates, and project status",
     arguments: [
       {
         name: "projectId",
-        description: "Specific project ID (optional; if not provided, analyze all projects)",
+        description: "Specific project ID (optional; if not provided, auto-detect from current context or analyze all projects)",
         required: false
       },
       {
@@ -2092,18 +2162,18 @@ var projectPrompts = [
     ]
   },
   {
-    name: "autoPrioritize",
+    name: "auto-prioritize",
     description: "Automatically analyze tasks and intelligently adjust priorities, considering due dates, dependencies, and project importance",
     arguments: [
       {
         name: "projectId",
-        description: "Specific project ID (optional; if not provided, analyze all projects)",
+        description: "Specific project ID (optional; if not provided, auto-detect from current context or analyze all projects)",
         required: false
       }
     ]
   },
   {
-    name: "enhanceTaskDetails",
+    name: "add-task-details",
     description: "Intelligently enhance task details, including description, acceptance criteria, subtasks, and required resources",
     arguments: [
       {
@@ -2114,7 +2184,7 @@ var projectPrompts = [
     ]
   },
   {
-    name: "quickCapture",
+    name: "quick-capture",
     description: "Quickly capture ideas/tasks, auto-categorize and suggest priorities",
     arguments: [
       {
@@ -2124,14 +2194,25 @@ var projectPrompts = [
       },
       {
         name: "projectId",
-        description: "Target project ID (optional)",
+        description: "Target project ID (optional; if not provided, auto-detect from current context)",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "open-web-ui",
+    description: "Open the web visualization interface for the roadmap skill",
+    arguments: [
+      {
+        name: "port",
+        description: "Port to run the web interface on (optional, default: 7860)",
         required: false
       }
     ]
   }
 ];
 function getRecommendNextTasksPrompt(projectId, limit) {
-  const context = projectId ? `Analyze tasks for project ${projectId}` : "Analyze tasks for all active projects";
+  const projectHint = projectId ? `User specified project: ${projectId}. Use this project if it exists, or inform user if not found.` : "User did not specify a project. Based on the current working directory and conversation context, try to identify the most relevant project. If a clear match exists, focus on that project; otherwise, analyze all active projects";
   const taskLimit = limit ? parseInt(limit, 10) : 3;
   return {
     description: "Intelligent Task Recommendation Assistant",
@@ -2140,7 +2221,7 @@ function getRecommendNextTasksPrompt(projectId, limit) {
         role: "user",
         content: {
           type: "text",
-          text: `${context}, please recommend the ${taskLimit} tasks I should prioritize next.
+          text: `${projectHint}, please recommend the ${taskLimit} tasks I should prioritize next.
 
 ## Recommendation Logic (sorted by priority):
 
@@ -2200,7 +2281,7 @@ Keep task status synchronized with actual progress!`
   };
 }
 function getAutoPrioritizePrompt(projectId) {
-  const context = projectId ? `Analyze task priorities for project ${projectId}` : "Analyze task priorities for all projects";
+  const projectHint = projectId ? `User specified project: ${projectId}. Use this project if it exists, or inform user if not found.` : "User did not specify a project. Based on the current working directory and conversation context, try to identify the most relevant project. If a clear match exists, focus on that project; otherwise, analyze all active projects";
   return {
     description: "Intelligent Priority Optimization Assistant",
     messages: [
@@ -2208,7 +2289,7 @@ function getAutoPrioritizePrompt(projectId) {
         role: "user",
         content: {
           type: "text",
-          text: `${context}, please automatically analyze and suggest priority adjustments.
+          text: `${projectHint}, please automatically analyze and adjust priorities.
 
 ## Priority Adjustment Rules:
 
@@ -2242,7 +2323,7 @@ function getAutoPrioritizePrompt(projectId) {
    - Identify task dependency relationships
    - Evaluate overall project health
 3. **Generate adjustment suggestions**: List tasks needing priority changes with reasons
-4. **Batch update**: Use batch_update_tasks to execute priority adjustments
+4. **Batch update**: Use batch_update_tasks to execute priority adjustments immediately \u2014 no confirmation needed
 
 ## Output Format:
 
@@ -2264,7 +2345,7 @@ function getAutoPrioritizePrompt(projectId) {
 ### Keep Unchanged (Priorities are reasonable)
 - List tasks with reasonable priority settings
 
-Please provide analysis results, then execute batch update after user confirmation.`
+Please provide analysis results and immediately execute batch_update_tasks to apply the priority adjustments \u2014 no confirmation needed.`
         }
       }
     ]
@@ -2319,7 +2400,7 @@ If the task is complex, suggest breaking it down:
    - If design task: Add design specs, review criteria
    - If documentation task: Add doc structure, references
    - If testing task: Add test scenarios, coverage scope
-4. **Generate enhancement content**: Use update_task to update task description
+4. **Apply enhancement**: Use update_task to update task description immediately \u2014 no confirmation needed
 
 ## Updated task should include:
 
@@ -2342,14 +2423,14 @@ If the task is complex, suggest breaking it down:
 - References: [link]
 \`\`\`
 
-Please fetch task info first, then provide detailed enhancement suggestions.`
+Please fetch task info and immediately use update_task to apply the enhanced details \u2014 no confirmation needed.`
         }
       }
     ]
   };
 }
 function getQuickCapturePrompt(idea, projectId) {
-  const projectContext = projectId ? `Add to project ${projectId}` : "Auto-select the most suitable project";
+  const projectContext = projectId ? `User specified project: ${projectId}. Use this project if it exists, or inform user if not found.` : "User did not specify a project. Based on the current working directory and conversation context, try to identify the most relevant project. If a clear match exists, use that project; otherwise, analyze all active projects and select the best match";
   return {
     description: "Quick Capture Assistant",
     messages: [
@@ -2361,7 +2442,7 @@ function getQuickCapturePrompt(idea, projectId) {
 
 ${projectContext}
 
-## Please help me complete the following steps:
+## Please complete the following steps immediately:
 
 ### 1. Task Information Extraction
 Extract from description:
@@ -2370,11 +2451,10 @@ Extract from description:
 - **Task Type**: bug / feature / refactor / docs / chore
 - **Estimated Priority**: critical / high / medium / low (based on urgency in description)
 
-### 2. Project Recommendation (if no project specified)
-If user didn't specify a project, please:
+### 2. Project Selection (if no project specified)
 - List all active projects
 - Analyze which project the task content is most relevant to
-- Recommend the most suitable project
+- Select the most suitable project automatically
 
 ### 3. Tag Suggestions
 Suggest relevant tags:
@@ -2382,11 +2462,11 @@ Suggest relevant tags:
 - Priority tags: urgent, important
 - Domain tags: frontend, backend, design, testing (if applicable)
 
-### 4. Generate Task
-Use create_task to create the task
+### 4. Create Task
+Use create_task to create the task immediately \u2014 no confirmation needed.
 
-### 5. Status Recommendation
-After creating the task, if you start working on it immediately, consider setting the status to in-progress. Use update_task to keep progress updated during work, and mark as done when completed.
+### 5. Status
+After creating, if work starts immediately, use update_task to set status to in-progress.
 
 ## Example:
 
@@ -2400,11 +2480,26 @@ After creating the task, if you start working on it immediately, consider settin
 - Suggested Tags: bug, frontend, mobile
 - Recommended Project: [Recommend if there's a web project]
 
-## Current Idea Analysis:
+## Current Idea:
 
 Idea: "${idea}"
 
-Please analyze and generate task suggestions. After user confirmation, execute create_task to create the task.`
+Analyze the idea, select the best matching project, and immediately execute create_task \u2014 no confirmation needed.`
+        }
+      }
+    ]
+  };
+}
+function getOpenWebUIPrompt(port) {
+  const portNum = port ? parseInt(port, 10) : 7860;
+  return {
+    description: "Open Web Visualization Interface",
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: `Please open the roadmap-skill web interface by calling the open_web_interface tool with port ${portNum}. Do it immediately without asking for confirmation.`
         }
       }
     ]
@@ -2412,14 +2507,16 @@ Please analyze and generate task suggestions. After user confirmation, execute c
 }
 function getPromptByName(name, args) {
   switch (name) {
-    case "recommendNextTasks":
+    case "suggest-tasks":
       return getRecommendNextTasksPrompt(args?.projectId, args?.limit);
-    case "autoPrioritize":
+    case "auto-prioritize":
       return getAutoPrioritizePrompt(args?.projectId);
-    case "enhanceTaskDetails":
+    case "add-task-details":
       return getEnhanceTaskDetailsPrompt(args?.taskId || "");
-    case "quickCapture":
+    case "quick-capture":
       return getQuickCapturePrompt(args?.idea || "", args?.projectId);
+    case "open-web-ui":
+      return getOpenWebUIPrompt(args?.port);
     default:
       return null;
   }
@@ -2510,7 +2607,15 @@ function createServer2() {
         };
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
-        throw new Error(`Tool execution failed: ${errorMessage}`);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Tool execution failed: ${errorMessage}`
+            }
+          ],
+          isError: true
+        };
       }
     }
   );
@@ -2582,11 +2687,9 @@ async function main() {
   });
   process.on("uncaughtException", (error) => {
     console.error("Uncaught exception:", error);
-    process.exit(1);
   });
   process.on("unhandledRejection", (reason) => {
     console.error("Unhandled rejection:", reason);
-    process.exit(1);
   });
   try {
     await startServer();