@projitive/mcp 1.0.7 → 1.1.1

package/output/source/prompts/taskExecution.js

@@ -0,0 +1,161 @@
+import { z } from "zod";
+function asUserPrompt(text) {
+    return {
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text,
+                },
+            },
+        ],
+    };
+}
+export function registerTaskExecutionPrompt(server) {
+    server.registerPrompt("taskExecution", {
+        title: "Task Execution",
+        description: "Primary execution prompt: select one task, execute, and verify evidence consistency",
+        argsSchema: {
+            projectPath: z.string().optional(),
+            taskId: z.string().optional(),
+        },
+    }, async ({ projectPath, taskId }) => {
+        const taskEntry = taskId && projectPath
+            ? `1) Run taskContext(projectPath="${projectPath}", taskId="${taskId}").`
+            : "1) Run taskNext().";
+        const text = [
+            "# Execute Task Workflow",
+            "",
+            "You are a Projitive task execution assistant. Here is the complete workflow:",
+            "",
+            "## Step 1: Get the Task",
+            "",
+            taskEntry,
+            "",
+            "## Step 2: Understand the Task",
+            "",
+            "After getting task context, read carefully:",
+            "",
+            "### Suggested Read Order",
+            "Read each file in order:",
+            "- Note content and location of each file",
+            "- Understand task background and motivation",
+            "- Identify task acceptance criteria",
+            "- Look for related design decisions",
+            "",
+            "### Evidence",
+            "- Candidate Files - Related file list",
+            "- Reference Locations - Where TASK/ROADMAP IDs appear",
+            "",
+            "### Lint Suggestions",
+            "Resolve any warnings before starting task execution.",
+            "",
+            "## Step 3: Execute the Task",
+            "",
+            "### Status Management",
+            "",
+            "| Current Status | Next Step | Description |",
+            "|----------------|-----------|-------------|",
+            "| TODO | \u2192 IN_PROGRESS | When starting execution |",
+            "| IN_PROGRESS | \u2192 DONE | When task is complete |",
+            "| IN_PROGRESS | \u2192 BLOCKED | When blocked |",
+            "| BLOCKED | \u2192 TODO | When blocker is resolved |",
+            "",
+            "### Execution Steps",
+            "",
+            "1. **Prepare (if status is TODO)",
+            "   - Call `taskUpdate()` to change status to IN_PROGRESS",
+            "   - Set owner (if empty)",
+            "   - Fill subState (optional, Spec v1.1.0)",
+            "",
+            "2. **Execute task content**",
+            "   - Only edit files under .projitive/",
+            "   - tasks.md - Update task status and metadata",
+            "   - designs/*.md - Add or update design documents",
+            "   - reports/*.md - Create execution reports",
+            "   - roadmap.md - Update roadmap (if needed)",
+            "",
+            "3. **Create execution report**",
+            "   - Create new report file in reports/ directory",
+            "   - Record what changes were made",
+            "   - Record why changes were made",
+            "   - Record verification results",
+            "",
+            "4. **Complete task (if status is IN_PROGRESS)",
+            "   - Confirm all acceptance criteria are met",
+            "   - Call `taskUpdate()` to change status to DONE",
+            "   - Update updatedAt timestamp",
+            "",
+            "## Step 4: Verify Changes",
+            "",
+            "After execution:",
+            "",
+            "1. **Re-run taskContext()",
+            "   - Confirm task status updated correctly",
+            "   - Confirm updatedAt timestamp updated",
+            "",
+            "2. **Check reference consistency",
+            "   - Confirm all TASK/ROADMAP IDs still valid",
+            "   - Confirm no broken links in Reference Locations",
+            "",
+            "3. **Check Lint Suggestions",
+            "   - Confirm no new warnings",
+            "   - If there are warnings, resolve them first",
+            "",
+            "4. **Continue to next task (optional)",
+            "   - Call `taskNext()` for next task",
+            "   - Repeat above workflow",
+            "",
+            "## Special Cases",
+            "",
+            "### Case 1: Encountered a blocker",
+            "",
+            "If unable to continue task execution:",
+            "1. Call `taskUpdate()` to change status to BLOCKED",
+            "2. Fill blocker field (Spec v1.1.0):",
+            "   - type: Blocker type (dependency/missing-info/technical-debt/other)",
+            "   - description: Blocker description",
+            "   - relatedLinks: Related links (optional)",
+            "3. Create a new TODO task to resolve blocker",
+            "",
+            "### Case 2: No actionable tasks",
+            "",
+            "If taskNext() returns empty:",
+            "1. Call `projectContext()` to recheck project state",
+            "2. Read design documents in designs/ directory",
+            "3. Create 1-3 new TODO tasks",
+            "",
+            "### Case 3: Need to initialize governance",
+            "",
+            "If .projitive directory does not exist:",
+            "1. Call `projectInit(projectPath=\"<project-dir>\")`",
+            "2. Then restart",
+            "",
+            "## Hard Rules (NEVER violate)",
+            "",
+            "1. **NEVER modify TASK/ROADMAP IDs**",
+            "   - Keep them immutable once assigned",
+            "   - If you need to reference, keep them as-is",
+            "",
+            "2. **Every status transition must have report evidence**",
+            "   - TODO \u2192 IN_PROGRESS: Report not required",
+            "   - IN_PROGRESS \u2192 DONE: Report REQUIRED",
+            "   - IN_PROGRESS \u2192 BLOCKED: Report recommended to explain blocker",
+            "",
+            "3. **Only edit files under .projitive/**",
+            "   - Unless task scope explicitly requires modifying other files",
+            "   - Any non-governance file edits must be explained in task summary",
+            "",
+            "4. **Always verify after updates**",
+            "   - After every taskUpdate() call",
+            "   - Re-run taskContext()",
+            "   - Confirm reference consistency",
+            "",
+            "5. **Keep updatedAt in sync**",
+            "   - Every time you update a task",
+            "   - Must update updatedAt to current time (ISO 8601 format)",
+        ].join("\n");
+        return asUserPrompt(text);
+    });
+}

package/output/source/resources/designs.js

@@ -0,0 +1,108 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isValidRoadmapId } from "../tools/roadmap.js";
+import { isValidTaskId } from "../tools/task.js";
+export function parseDesignMetadata(markdown) {
+    const lines = markdown.split(/\r?\n/);
+    const metadata = {};
+    for (const line of lines) {
+        // Remove markdown bold markers (**)
+        const cleanLine = line.replace(/\*\*/g, "");
+        const [rawKey, ...rawValue] = cleanLine.split(":");
+        if (!rawKey || rawValue.length === 0) {
+            continue;
+        }
+        const key = rawKey.trim().toLowerCase();
+        const value = rawValue.join(":").trim();
+        if (key === "task")
+            metadata.task = value;
+        if (key === "roadmap")
+            metadata.roadmap = value;
+        if (key === "owner")
+            metadata.owner = value;
+        if (key === "status")
+            metadata.status = value;
+        if (key === "last updated")
+            metadata.lastUpdated = value;
+    }
+    return metadata;
+}
+export function validateDesignMetadata(metadata) {
+    const errors = [];
+    if (!metadata.task) {
+        errors.push("Missing Task metadata");
+    }
+    else if (!isValidTaskId(metadata.task)) {
+        errors.push(`Invalid Task metadata format: ${metadata.task}`);
+    }
+    if (metadata.roadmap && !isValidRoadmapId(metadata.roadmap)) {
+        errors.push(`Invalid Roadmap metadata format: ${metadata.roadmap}`);
+    }
+    return { ok: errors.length === 0, errors };
+}
+async function findAllMarkdownFiles(dir) {
+    const result = [];
+    async function walk(currentDir, relativeBase) {
+        const entries = await fs.readdir(currentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(fullPath, path.join(relativeBase, entry.name));
+            }
+            else if (entry.isFile() && entry.name.endsWith(".md")) {
+                result.push({
+                    filePath: fullPath,
+                    relativePath: path.join(relativeBase, entry.name),
+                });
+            }
+        }
+    }
+    await walk(dir, "");
+    return result;
+}
+export async function registerDesignFilesResources(server, repoRoot) {
+    const designsDir = path.join(repoRoot, ".projitive", "designs");
+    try {
+        // Check if design documents directory exists
+        await fs.access(designsDir);
+        // Recursively read all .md files (including subdirectories)
+        const markdownFiles = await findAllMarkdownFiles(designsDir);
+        // Register each design file as a resource
+        for (const { filePath, relativePath } of markdownFiles) {
+            // Generate designId from relative path, replace path separators with '-'
+            const designId = relativePath
+                .slice(0, -3) // Remove .md suffix
+                .replace(/[\\/]/g, "-"); // Replace path separators with '-'
+            const content = await fs.readFile(filePath, "utf-8");
+            // Register resource
+            server.registerResource(`design-${designId}`, `projitive://designs/${designId}`, {
+                title: designId,
+                description: `Design document: ${relativePath}`,
+                mimeType: "text/markdown",
+            }, async () => ({
+                contents: [
+                    {
+                        uri: `projitive://designs/${designId}`,
+                        text: content,
+                    },
+                ],
+            }));
+        }
+    }
+    catch (error) {
+        // If design documents directory doesn't exist, register a default resource
+        console.warn(`Designs directory not found at ${designsDir}, registering default design resource`);
+        server.registerResource("designs", "projitive://designs", {
+            title: "Designs",
+            description: "Design documents directory",
+            mimeType: "text/markdown",
+        }, async () => ({
+            contents: [
+                {
+                    uri: "projitive://designs",
+                    text: `# Designs Directory\n\nDesign documents not found. Please create design files in .projitive/designs/ directory.`,
+                },
+            ],
+        }));
+    }
+}

package/output/source/resources/designs.test.js

@@ -0,0 +1,154 @@
+import { describe, expect, it } from "vitest";
+import { parseDesignMetadata, validateDesignMetadata } from "./designs.js";
+describe("designs module", () => {
+    describe("parseDesignMetadata", () => {
+        it("parses task metadata from markdown", () => {
+            const markdown = [
+                "# Design Document",
+                "",
+                "**Task:** TASK-0001",
+                "**Owner:** ai-copilot",
+                "**Status:** Draft",
+                "**Last Updated:** 2026-02-22",
+                "",
+                "Some content here",
+            ].join("\n");
+            const metadata = parseDesignMetadata(markdown);
+            expect(metadata.task).toBe("TASK-0001");
+            expect(metadata.owner).toBe("ai-copilot");
+            expect(metadata.status).toBe("Draft");
+            expect(metadata.lastUpdated).toBe("2026-02-22");
+        });
+        it("parses roadmap metadata from markdown", () => {
+            const markdown = [
+                "# Design Document",
+                "",
+                "**Roadmap:** ROADMAP-0001",
+                "",
+                "Some content here",
+            ].join("\n");
+            const metadata = parseDesignMetadata(markdown);
+            expect(metadata.roadmap).toBe("ROADMAP-0001");
+        });
+        it("returns empty object for markdown without metadata", () => {
+            const markdown = [
+                "# Simple Design",
+                "",
+                "No metadata here",
+            ].join("\n");
+            const metadata = parseDesignMetadata(markdown);
+            expect(metadata).toEqual({});
+        });
+        it("handles empty string", () => {
+            const metadata = parseDesignMetadata("");
+            expect(metadata).toEqual({});
+        });
+        it("handles malformed metadata lines", () => {
+            const markdown = [
+                "# Report",
+                "",
+                "Task without colon",
+                "Not a metadata line",
+                ":",
+                "Task:",
+            ].join("\n");
+            const metadata = parseDesignMetadata(markdown);
+            expect(metadata).toBeDefined();
+        });
+        it("parses metadata in different formats", () => {
+            const markdown = [
+                "Task: TASK-0001",
+                "task: TASK-0002",
+                "TASK: TASK-0003",
+                "  task  :  TASK-0004  ",
+            ].join("\n");
+            const metadata = parseDesignMetadata(markdown);
+            expect(metadata.task).toBeDefined();
+        });
+    });
+    describe("validateDesignMetadata", () => {
+        it("validates correct task metadata", () => {
+            const metadata = {
+                task: "TASK-0001",
+                owner: "ai-copilot",
+                status: "Draft",
+                lastUpdated: "2026-02-22",
+            };
+            const result = validateDesignMetadata(metadata);
+            expect(result.ok).toBe(true);
+            expect(result.errors).toEqual([]);
+        });
+        it("rejects missing task metadata", () => {
+            const metadata = {
+                owner: "ai-copilot",
+            };
+            const result = validateDesignMetadata(metadata);
+            expect(result.ok).toBe(false);
+            expect(result.errors).toContain("Missing Task metadata");
+        });
+        it("rejects invalid task ID format", () => {
+            const metadata = {
+                task: "invalid-format",
+            };
+            const result = validateDesignMetadata(metadata);
+            expect(result.ok).toBe(false);
+            expect(result.errors.some((e) => e.includes("Invalid Task"))).toBe(true);
+        });
+        it("validates optional roadmap metadata", () => {
+            const metadata = {
+                task: "TASK-0001",
+                roadmap: "ROADMAP-0001",
+            };
+            const result = validateDesignMetadata(metadata);
+            expect(result.ok).toBe(true);
+        });
+        it("rejects invalid roadmap ID format", () => {
+            const metadata = {
+                task: "TASK-0001",
+                roadmap: "invalid-roadmap",
+            };
+            const result = validateDesignMetadata(metadata);
+            expect(result.ok).toBe(false);
+            expect(result.errors.some((e) => e.includes("Invalid Roadmap"))).toBe(true);
+        });
+        it("handles empty metadata object", () => {
+            const metadata = {};
+            const result = validateDesignMetadata(metadata);
+            expect(result.ok).toBe(false);
+            expect(result.errors.length).toBeGreaterThan(0);
+        });
+        it("collects multiple validation errors", () => {
+            const metadata = {
+                task: "invalid-task",
+                roadmap: "invalid-roadmap",
+            };
+            const result = validateDesignMetadata(metadata);
+            expect(result.ok).toBe(false);
+            expect(result.errors.length).toBeGreaterThan(1);
+        });
+    });
+    describe("integration", () => {
+        it("parses and validates complete design metadata", () => {
+            const markdown = [
+                "# Design Completion Report",
+                "",
+                "**Task:** TASK-0001",
+                "**Roadmap:** ROADMAP-0002",
+                "**Owner:** ai-copilot",
+                "**Status:** Completed",
+                "**Last Updated:** 2026-02-22",
+                "",
+                "## Summary",
+                "Design completed successfully",
+            ].join("\n");
+            const metadata = parseDesignMetadata(markdown);
+            const validation = validateDesignMetadata(metadata);
+            expect(metadata.task).toBe("TASK-0001");
+            expect(metadata.roadmap).toBe("ROADMAP-0002");
+            expect(metadata.owner).toBe("ai-copilot");
+            expect(metadata.status).toBe("Completed");
+            expect(metadata.lastUpdated).toBe("2026-02-22");
+            expect(validation.ok).toBe(true);
+        });
+    });
+});

package/output/source/resources/governance.js

@@ -0,0 +1,40 @@
+// Governance resource management
+import { readMarkdownOrFallback } from "../common/utils.js";
+export function registerGovernanceResources(server, repoRoot) {
+    server.registerResource("governanceWorkspace", "projitive://governance/workspace", {
+        title: "Governance Workspace",
+        description: "Primary governance README under .projitive",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "projitive://governance/workspace",
+                text: await readMarkdownOrFallback(".projitive/README.md", "Governance Workspace", repoRoot),
+            },
+        ],
+    }));
+    server.registerResource("governanceTasks", "projitive://governance/tasks", {
+        title: "Governance Tasks",
+        description: "Current task pool and status under .projitive/tasks.md",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "projitive://governance/tasks",
+                text: await readMarkdownOrFallback(".projitive/tasks.md", "Governance Tasks", repoRoot),
+            },
+        ],
+    }));
+    server.registerResource("governanceRoadmap", "projitive://governance/roadmap", {
+        title: "Governance Roadmap",
+        description: "Current roadmap under .projitive/roadmap.md",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "projitive://governance/roadmap",
+                text: await readMarkdownOrFallback(".projitive/roadmap.md", "Governance Roadmap", repoRoot),
+            },
+        ],
+    }));
+}

package/output/source/resources/index.js

@@ -0,0 +1,6 @@
+import { registerGovernanceResources } from "./governance.js";
+import { registerDesignFilesResources } from "./designs.js";
+export function registerResources(server, repoRoot) {
+    registerGovernanceResources(server, repoRoot);
+    registerDesignFilesResources(server, repoRoot);
+}

package/output/source/resources/readme.test.js

@@ -0,0 +1,167 @@
+import { describe, expect, it } from "vitest";
+import { parseRequiredReading, } from "./readme.js";
+describe("readme module", () => {
+    describe("parseRequiredReading", () => {
+        it("parses local and external required reading items", () => {
+            const markdown = [
+                "# Project README",
+                "",
+                "Some intro content",
+                "",
+                "## Required Reading for Agents",
+                "",
+                "- Local: ./design/README.md",
+                "- Local: .projitive/tasks.md",
+                "- External: https://example.com/docs",
+                "",
+                "## Other Section",
+                "",
+                "More content here",
+            ].join("\n");
+            const result = parseRequiredReading(markdown);
+            expect(result.length).toBe(3);
+            expect(result[0]).toEqual({
+                source: "Local",
+                value: "./design/README.md",
+            });
+            expect(result[1]).toEqual({
+                source: "Local",
+                value: ".projitive/tasks.md",
+            });
+            expect(result[2]).toEqual({
+                source: "External",
+                value: "https://example.com/docs",
+            });
+        });
+        it("parses Chinese section header", () => {
+            const markdown = [
+                "# 项目 README",
+                "",
+                "## Agent 必读",
+                "",
+                "- Local: ./docs/guide.md",
+                "",
+                "## 其他部分",
+            ].join("\n");
+            const result = parseRequiredReading(markdown);
+            expect(result.length).toBe(1);
+            expect(result[0].source).toBe("Local");
+            expect(result[0].value).toBe("./docs/guide.md");
+        });
+        it("returns empty array when no required reading section", () => {
+            const markdown = [
+                "# Simple README",
+                "",
+                "No required reading here",
+                "",
+                "## Other Section",
+            ].join("\n");
+            const result = parseRequiredReading(markdown);
+            expect(result).toEqual([]);
+        });
+        it("returns empty array for empty string", () => {
+            const result = parseRequiredReading("");
+            expect(result).toEqual([]);
+        });
+        it("ignores non-list items in required reading section", () => {
+            const markdown = [
+                "## Required Reading for Agents",
+                "",
+                "Some paragraph text here",
+                "- Local: valid-item.md",
+                "Another paragraph",
+                "- External: https://valid.com",
+                "",
+                "## Next Section",
+            ].join("\n");
+            const result = parseRequiredReading(markdown);
+            expect(result.length).toBe(2);
+            expect(result[0].value).toBe("valid-item.md");
+            expect(result[1].value).toBe("https://valid.com");
+        });
+        it("handles items with whitespace variations", () => {
+            const markdown = [
+                "## Required Reading for Agents",
+                "",
+                "- Local:  ./path/with/spaces.md  ",
+                "-  External:   https://example.com  ",
+            ].join("\n");
+            const result = parseRequiredReading(markdown);
+            expect(result.length).toBe(2);
+            expect(result[0].value).toBe("./path/with/spaces.md");
+            expect(result[1].value).toBe("https://example.com");
+        });
+        it("ignores items without Local: or External: prefix", () => {
+            const markdown = [
+                "## Required Reading for Agents",
+                "",
+                "- Local: valid.md",
+                "- Invalid: this is ignored",
+                "- Just a plain list item",
+                "- External: https://valid.com",
+            ].join("\n");
+            const result = parseRequiredReading(markdown);
+            expect(result.length).toBe(2);
+            expect(result.every((item) => item.source === "Local" || item.source === "External")).toBe(true);
+        });
+        it("stops at next section header", () => {
+            const markdown = [
+                "## Required Reading for Agents",
+                "",
+                "- Local: before.md",
+                "",
+                "## Another Section",
+                "",
+                "- Local: after.md",
+            ].join("\n");
+            const result = parseRequiredReading(markdown);
+            expect(result.length).toBe(1);
+            expect(result[0].value).toBe("before.md");
+        });
+        it("handles multiple required reading sections (takes first one)", () => {
+            const markdown = [
+                "## Required Reading for Agents",
+                "",
+                "- Local: first.md",
+                "",
+                "## Other Section",
+                "",
+                "## Required Reading for Agents",
+                "",
+                "- Local: second.md",
+            ].join("\n");
+            const result = parseRequiredReading(markdown);
+            expect(result.length).toBe(1);
+            expect(result[0].value).toBe("first.md");
+        });
+    });
+    describe("edge cases", () => {
+        it("handles markdown with just the section", () => {
+            const markdown = "## Required Reading for Agents";
+            const result = parseRequiredReading(markdown);
+            expect(result).toEqual([]);
+        });
+        it("handles section with empty lines", () => {
+            const markdown = [
+                "## Required Reading for Agents",
+                "",
+                "",
+                "- Local: item.md",
+                "",
+                "",
+            ].join("\n");
+            const result = parseRequiredReading(markdown);
+            expect(result.length).toBe(1);
+            expect(result[0].value).toBe("item.md");
+        });
+        it("handles mixed case section headers", () => {
+            const markdown = [
+                "## required reading for agents",
+                "",
+                "- Local: lowercase.md",
+            ].join("\n");
+            const result = parseRequiredReading(markdown);
+            expect(result.length).toBe(1);
+        });
+    });
+});

package/output/source/{reports.js → resources/reports.js}

@@ -1,10 +1,12 @@
-import { isValidRoadmapId } from "./roadmap.js";
-import { isValidTaskId } from "./tasks.js";
+import { isValidRoadmapId } from "../tools/roadmap.js";
+import { isValidTaskId } from "../tools/task.js";
 export function parseReportMetadata(markdown) {
     const lines = markdown.split(/\r?\n/);
     const metadata = {};
     for (const line of lines) {
-        const [rawKey, ...rawValue] = line.split(":");
+        // Remove markdown bold markers (**)
+        const cleanLine = line.replace(/\*\*/g, "");
+        const [rawKey, ...rawValue] = cleanLine.split(":");
         if (!rawKey || rawValue.length === 0) {
             continue;
         }