@projitive/mcp 1.0.0-beta.1

package/output/projitive.test.js

@@ -0,0 +1,46 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { discoverProjects, hasProjectMarker, resolveGovernanceDir } from "./projitive.js";
+const tempPaths = [];
+async function createTempDir() {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "projitive-mcp-test-"));
+    tempPaths.push(dir);
+    return dir;
+}
+afterEach(async () => {
+    await Promise.all(tempPaths.splice(0).map(async (dir) => {
+        await fs.rm(dir, { recursive: true, force: true });
+    }));
+});
+describe("projitive module", () => {
+    it("does not treat marker directory as a valid project marker", async () => {
+        const root = await createTempDir();
+        const dirMarkerPath = path.join(root, ".projitive");
+        await fs.mkdir(dirMarkerPath, { recursive: true });
+        const hasMarker = await hasProjectMarker(root);
+        expect(hasMarker).toBe(false);
+    });
+    it("resolves governance dir by walking upwards for .projitive", async () => {
+        const root = await createTempDir();
+        const governanceDir = path.join(root, "repo", "governance");
+        const deepDir = path.join(governanceDir, "nested", "module");
+        await fs.mkdir(deepDir, { recursive: true });
+        await fs.writeFile(path.join(governanceDir, ".projitive"), "", "utf-8");
+        const resolved = await resolveGovernanceDir(deepDir);
+        expect(resolved).toBe(governanceDir);
+    });
+    it("discovers projects by marker file", async () => {
+        const root = await createTempDir();
+        const p1 = path.join(root, "a");
+        const p2 = path.join(root, "b", "c");
+        await fs.mkdir(p1, { recursive: true });
+        await fs.mkdir(p2, { recursive: true });
+        await fs.writeFile(path.join(p1, ".projitive"), "", "utf-8");
+        await fs.writeFile(path.join(p2, ".projitive"), "", "utf-8");
+        const projects = await discoverProjects(root, 4);
+        expect(projects).toContain(p1);
+        expect(projects).toContain(p2);
+    });
+});

package/output/readme.js

@@ -0,0 +1,26 @@
+export function parseRequiredReading(markdown) {
+    const lines = markdown.split(/\r?\n/);
+    const result = [];
+    let inSection = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (/^##\s+(Required Reading for Agents|Agent 必读)$/i.test(trimmed)) {
+            inSection = true;
+            continue;
+        }
+        if (inSection && trimmed.startsWith("## ")) {
+            break;
+        }
+        if (!inSection || !trimmed.startsWith("- ")) {
+            continue;
+        }
+        const payload = trimmed.replace(/^-\s+/, "");
+        if (payload.startsWith("Local:")) {
+            result.push({ source: "Local", value: payload.replace("Local:", "").trim() });
+        }
+        if (payload.startsWith("External:")) {
+            result.push({ source: "External", value: payload.replace("External:", "").trim() });
+        }
+    }
+    return result;
+}

package/output/reports.js

@@ -0,0 +1,36 @@
+import { isValidRoadmapId } from "./roadmap.js";
+import { isValidTaskId } from "./tasks.js";
+export function parseReportMetadata(markdown) {
+    const lines = markdown.split(/\r?\n/);
+    const metadata = {};
+    for (const line of lines) {
+        const [rawKey, ...rawValue] = line.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 === "date")
+            metadata.date = value;
+    }
+    return metadata;
+}
+export function validateReportMetadata(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 };
+}

package/output/roadmap.js

@@ -0,0 +1,4 @@
+export const ROADMAP_ID_REGEX = /^ROADMAP-\d{4}$/;
+export function isValidRoadmapId(id) {
+    return ROADMAP_ID_REGEX.test(id);
+}

package/output/tasks.js

@@ -0,0 +1,242 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { catchIt } from "./helpers/catch/index.js";
+import { resolveGovernanceDir } from "./projitive.js";
+import { isValidRoadmapId } from "./roadmap.js";
+export const TASKS_START = "<!-- PROJITIVE:TASKS:START -->";
+export const TASKS_END = "<!-- PROJITIVE:TASKS:END -->";
+export const ALLOWED_STATUS = ["TODO", "IN_PROGRESS", "BLOCKED", "DONE"];
+export const TASK_ID_REGEX = /^TASK-\d{4}$/;
+export function nowIso() {
+    return new Date().toISOString();
+}
+export function isValidTaskId(id) {
+    return TASK_ID_REGEX.test(id);
+}
+export function taskPriority(status) {
+    if (status === "IN_PROGRESS") {
+        return 2;
+    }
+    if (status === "TODO") {
+        return 1;
+    }
+    return 0;
+}
+export function toTaskUpdatedAtMs(updatedAt) {
+    const timestamp = new Date(updatedAt).getTime();
+    return Number.isFinite(timestamp) ? timestamp : 0;
+}
+export function rankActionableTaskCandidates(candidates) {
+    return [...candidates].sort((a, b) => {
+        if (b.projectScore !== a.projectScore) {
+            return b.projectScore - a.projectScore;
+        }
+        if (b.taskPriority !== a.taskPriority) {
+            return b.taskPriority - a.taskPriority;
+        }
+        if (b.taskUpdatedAtMs !== a.taskUpdatedAtMs) {
+            return b.taskUpdatedAtMs - a.taskUpdatedAtMs;
+        }
+        if (a.governanceDir !== b.governanceDir) {
+            return a.governanceDir.localeCompare(b.governanceDir);
+        }
+        return a.task.id.localeCompare(b.task.id);
+    });
+}
+export function normalizeTask(task) {
+    const normalizedRoadmapRefs = Array.isArray(task.roadmapRefs)
+        ? task.roadmapRefs.map(String).filter((value) => isValidRoadmapId(value))
+        : [];
+    const inputHooks = task.hooks ?? {};
+    const normalizedHooks = {};
+    for (const key of ["onAssigned", "onCompleted", "onBlocked", "onReopened"]) {
+        const value = inputHooks[key];
+        if (typeof value === "string" && value.trim().length > 0) {
+            normalizedHooks[key] = value;
+        }
+    }
+    return {
+        id: String(task.id),
+        title: String(task.title),
+        status: ALLOWED_STATUS.includes(task.status) ? task.status : "TODO",
+        owner: task.owner ? String(task.owner) : "",
+        summary: task.summary ? String(task.summary) : "",
+        updatedAt: task.updatedAt ? String(task.updatedAt) : nowIso(),
+        links: Array.isArray(task.links) ? task.links.map(String) : [],
+        roadmapRefs: Array.from(new Set(normalizedRoadmapRefs)),
+        hooks: normalizedHooks,
+    };
+}
+export async function parseTasksBlock(markdown) {
+    const start = markdown.indexOf(TASKS_START);
+    const end = markdown.indexOf(TASKS_END);
+    if (start === -1 || end === -1 || end <= start) {
+        return [];
+    }
+    const body = markdown.slice(start + TASKS_START.length, end).trim();
+    if (!body || body === "(no tasks)") {
+        return [];
+    }
+    const sections = body
+        .split(/\n(?=##\s+TASK-\d{4}\s+\|\s+(?:TODO|IN_PROGRESS|BLOCKED|DONE)\s+\|)/g)
+        .map((section) => section.trim())
+        .filter((section) => section.startsWith("## TASK-"));
+    const tasks = [];
+    for (const section of sections) {
+        const lines = section.split(/\r?\n/);
+        const header = lines[0]?.match(/^##\s+(TASK-\d{4})\s+\|\s+(TODO|IN_PROGRESS|BLOCKED|DONE)\s+\|\s+(.+)$/);
+        if (!header) {
+            continue;
+        }
+        const [, id, statusRaw, title] = header;
+        const status = statusRaw;
+        const taskDraft = {
+            id,
+            title: title.trim(),
+            status,
+            owner: "",
+            summary: "",
+            updatedAt: nowIso(),
+            links: [],
+            roadmapRefs: [],
+            hooks: {},
+        };
+        let inLinks = false;
+        let inHooks = false;
+        for (const line of lines.slice(1)) {
+            const trimmed = line.trim();
+            if (!trimmed) {
+                continue;
+            }
+            if (trimmed.startsWith("- owner:")) {
+                taskDraft.owner = trimmed.replace("- owner:", "").trim();
+                inLinks = false;
+                inHooks = false;
+                continue;
+            }
+            if (trimmed.startsWith("- summary:")) {
+                taskDraft.summary = trimmed.replace("- summary:", "").trim();
+                inLinks = false;
+                inHooks = false;
+                continue;
+            }
+            if (trimmed.startsWith("- updatedAt:")) {
+                taskDraft.updatedAt = trimmed.replace("- updatedAt:", "").trim();
+                inLinks = false;
+                inHooks = false;
+                continue;
+            }
+            if (trimmed.startsWith("- roadmapRefs:")) {
+                const payload = trimmed.replace("- roadmapRefs:", "").trim();
+                const refs = payload === "(none)"
+                    ? []
+                    : payload
+                        .split(",")
+                        .map((value) => value.trim())
+                        .filter((value) => value.length > 0);
+                taskDraft.roadmapRefs = refs;
+                inLinks = false;
+                inHooks = false;
+                continue;
+            }
+            if (trimmed === "- links:") {
+                inLinks = true;
+                inHooks = false;
+                continue;
+            }
+            if (trimmed === "- hooks:") {
+                inLinks = false;
+                inHooks = true;
+                continue;
+            }
+            const nestedItem = trimmed.match(/^-\s+(.+)$/);
+            if (!nestedItem) {
+                continue;
+            }
+            const nestedValue = nestedItem[1].trim();
+            if (nestedValue === "(none)") {
+                continue;
+            }
+            if (inLinks) {
+                taskDraft.links = [...(taskDraft.links ?? []), nestedValue];
+                continue;
+            }
+            if (inHooks) {
+                const hookMatch = nestedValue.match(/^(onAssigned|onCompleted|onBlocked|onReopened):\s+(.+)$/);
+                if (hookMatch) {
+                    const [, hookKey, hookPath] = hookMatch;
+                    taskDraft.hooks = {
+                        ...(taskDraft.hooks ?? {}),
+                        [hookKey]: hookPath.trim(),
+                    };
+                }
+            }
+        }
+        tasks.push(normalizeTask(taskDraft));
+    }
+    return tasks;
+}
+export function renderTasksMarkdown(tasks) {
+    const sections = tasks.map((task) => {
+        const roadmapRefs = task.roadmapRefs.length > 0 ? task.roadmapRefs.join(", ") : "(none)";
+        const links = task.links.length > 0
+            ? ["- links:", ...task.links.map((link) => `  - ${link}`)]
+            : ["- links:", "  - (none)"];
+        const hookEntries = Object.entries(task.hooks)
+            .filter(([, value]) => typeof value === "string" && value.trim().length > 0)
+            .map(([key, value]) => `  - ${key}: ${value}`);
+        const hooks = hookEntries.length > 0
+            ? ["- hooks:", ...hookEntries]
+            : ["- hooks:", "  - (none)"];
+        return [
+            `## ${task.id} | ${task.status} | ${task.title}`,
+            `- owner: ${task.owner || "(none)"}`,
+            `- summary: ${task.summary || "(none)"}`,
+            `- updatedAt: ${task.updatedAt}`,
+            `- roadmapRefs: ${roadmapRefs}`,
+            ...links,
+            ...hooks,
+        ].join("\n");
+    });
+    return [
+        "# Tasks",
+        "",
+        "本文件由 Projitive MCP 维护，手动编辑请保持 Markdown 结构合法。",
+        "",
+        TASKS_START,
+        ...(sections.length > 0 ? sections : ["(no tasks)"]),
+        TASKS_END,
+        "",
+    ].join("\n");
+}
+export async function ensureTasksFile(inputPath) {
+    const governanceDir = await resolveGovernanceDir(inputPath);
+    const tasksPath = path.join(governanceDir, "tasks.md");
+    await fs.mkdir(governanceDir, { recursive: true });
+    const accessResult = await catchIt(fs.access(tasksPath));
+    if (accessResult.isError()) {
+        await fs.writeFile(tasksPath, renderTasksMarkdown([]), "utf-8");
+    }
+    return tasksPath;
+}
+export async function loadTasks(inputPath) {
+    const tasksPath = await ensureTasksFile(inputPath);
+    const markdown = await fs.readFile(tasksPath, "utf-8");
+    return { tasksPath, tasks: await parseTasksBlock(markdown) };
+}
+export async function saveTasks(tasksPath, tasks) {
+    const normalized = tasks.map((task) => normalizeTask(task));
+    await fs.writeFile(tasksPath, renderTasksMarkdown(normalized), "utf-8");
+}
+export function validateTransition(from, to) {
+    if (from === to) {
+        return true;
+    }
+    const allowed = {
+        TODO: new Set(["IN_PROGRESS", "BLOCKED"]),
+        IN_PROGRESS: new Set(["BLOCKED", "DONE"]),
+        BLOCKED: new Set(["IN_PROGRESS", "TODO"]),
+        DONE: new Set(),
+    };
+    return allowed[from].has(to);
+}

package/output/tasks.test.js

@@ -0,0 +1,78 @@
+import { describe, expect, it } from "vitest";
+import { TASKS_END, TASKS_START, isValidTaskId, normalizeTask, parseTasksBlock, rankActionableTaskCandidates, renderTasksMarkdown, taskPriority, toTaskUpdatedAtMs, validateTransition, } from "./tasks.js";
+function buildCandidate(partial) {
+    const task = normalizeTask({
+        id: partial.id,
+        title: partial.title,
+        status: partial.status,
+        updatedAt: partial.task?.updatedAt ?? "2026-01-01T00:00:00.000Z",
+    });
+    return {
+        governanceDir: partial.governanceDir ?? "/workspace/a",
+        tasksPath: partial.tasksPath ?? "/workspace/a/tasks.md",
+        task,
+        projectScore: partial.projectScore ?? 1,
+        projectLatestUpdatedAt: partial.projectLatestUpdatedAt ?? "2026-01-01T00:00:00.000Z",
+        taskUpdatedAtMs: partial.taskUpdatedAtMs ?? toTaskUpdatedAtMs(task.updatedAt),
+        taskPriority: partial.taskPriority ?? taskPriority(task.status),
+    };
+}
+describe("tasks module", () => {
+    it("parses markdown task block and normalizes task fields", async () => {
+        const markdown = [
+            "# Tasks",
+            TASKS_START,
+            "## TASK-0001 | TODO | hello",
+            "- owner: alice",
+            "- summary: first task",
+            "- updatedAt: 2026-02-17T00:00:00.000Z",
+            "- roadmapRefs: ROADMAP-0001",
+            "- links:",
+            "  - ./designs/example.md",
+            "- hooks:",
+            "  - onAssigned: ./hooks/on_task_assigned.md",
+            TASKS_END,
+        ].join("\n");
+        const tasks = await parseTasksBlock(markdown);
+        expect(tasks).toHaveLength(1);
+        expect(tasks[0].id).toBe("TASK-0001");
+        expect(tasks[0].status).toBe("TODO");
+        expect(tasks[0].roadmapRefs).toEqual(["ROADMAP-0001"]);
+        expect(tasks[0].hooks).toEqual({ onAssigned: "./hooks/on_task_assigned.md" });
+    });
+    it("renders markdown containing markers", () => {
+        const task = normalizeTask({ id: "TASK-0002", title: "render", status: "IN_PROGRESS" });
+        const markdown = renderTasksMarkdown([task]);
+        expect(markdown.includes(TASKS_START)).toBe(true);
+        expect(markdown.includes(TASKS_END)).toBe(true);
+        expect(markdown.includes("## TASK-0002 | IN_PROGRESS | render")).toBe(true);
+    });
+    it("validates task IDs", () => {
+        expect(isValidTaskId("TASK-0001")).toBe(true);
+        expect(isValidTaskId("TASK-001")).toBe(false);
+    });
+    it("allows and rejects expected transitions", () => {
+        expect(validateTransition("TODO", "IN_PROGRESS")).toBe(true);
+        expect(validateTransition("IN_PROGRESS", "DONE")).toBe(true);
+        expect(validateTransition("DONE", "IN_PROGRESS")).toBe(false);
+    });
+    it("assigns priority for actionable statuses", () => {
+        expect(taskPriority("IN_PROGRESS")).toBe(2);
+        expect(taskPriority("TODO")).toBe(1);
+        expect(taskPriority("BLOCKED")).toBe(0);
+    });
+    it("returns zero timestamp for invalid date", () => {
+        expect(toTaskUpdatedAtMs("invalid")).toBe(0);
+    });
+    it("ranks by project score, then task priority, then recency", () => {
+        const candidates = [
+            buildCandidate({ id: "TASK-0001", title: "A", status: "TODO", projectScore: 2 }),
+            buildCandidate({ id: "TASK-0002", title: "B", status: "IN_PROGRESS", projectScore: 2 }),
+            buildCandidate({ id: "TASK-0003", title: "C", status: "IN_PROGRESS", projectScore: 3 }),
+        ];
+        const ranked = rankActionableTaskCandidates(candidates);
+        expect(ranked[0].task.id).toBe("TASK-0003");
+        expect(ranked[1].task.id).toBe("TASK-0002");
+        expect(ranked[2].task.id).toBe("TASK-0001");
+    });
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@projitive/mcp",
+  "version": "1.0.0-beta.1",
+  "description": "Projitive MCP Server for project and task discovery/update",
+  "license": "ISC",
+  "author": "",
+  "type": "module",
+  "main": "./output/index.js",
+  "types": "./output/index.d.ts",
+  "scripts": {
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "dev": "tsc -p tsconfig.json --watch"
+  },
+  "files": [
+    "output"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.5",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}