@projitive/mcp 1.2.0 → 2.0.1

package/output/source/tools/roadmap.js

@@ -1,24 +1,120 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import { candidateFilesFromArtifacts, discoverGovernanceArtifacts, ROADMAP_LINT_CODES, renderLintSuggestions, findTextReferences } from "../common/index.js";
+import { candidateFilesFromArtifacts, discoverGovernanceArtifacts, ROADMAP_LINT_CODES, renderLintSuggestions, findTextReferences, ensureStore, loadRoadmapsFromStore, upsertRoadmapInStore, getStoreVersion, getMarkdownViewState, markMarkdownViewBuilt, } from "../common/index.js";
 import { asText, evidenceSection, guidanceSection, lintSection, nextCallSection, renderErrorMarkdown, renderToolResponseMarkdown, summarySection, } from "../common/index.js";
 import { resolveGovernanceDir, toProjectPath } from "./project.js";
 import { loadTasks } from "./task.js";
 export const ROADMAP_ID_REGEX = /^ROADMAP-\d{4}$/;
+export const ROADMAP_MARKDOWN_FILE = "roadmap.md";
+function nowIso() {
+    return new Date().toISOString();
+}
+function toRoadmapIdNumericSuffix(roadmapId) {
+    const match = roadmapId.match(/^(?:ROADMAP-)(\d{4})$/);
+    if (!match) {
+        return -1;
+    }
+    return Number.parseInt(match[1], 10);
+}
+function sortMilestonesNewestFirst(milestones) {
+    return [...milestones].sort((a, b) => {
+        const updatedAtDelta = new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime();
+        if (Number.isFinite(updatedAtDelta) && updatedAtDelta !== 0) {
+            return updatedAtDelta;
+        }
+        const idDelta = toRoadmapIdNumericSuffix(b.id) - toRoadmapIdNumericSuffix(a.id);
+        if (idDelta !== 0) {
+            return idDelta;
+        }
+        return b.id.localeCompare(a.id);
+    });
+}
+function normalizeMilestone(raw) {
+    return {
+        id: String(raw.id),
+        title: String(raw.title),
+        status: raw.status === "done" ? "done" : "active",
+        time: typeof raw.time === "string" && raw.time.trim().length > 0 ? raw.time.trim() : undefined,
+        updatedAt: typeof raw.updatedAt === "string" && Number.isFinite(new Date(raw.updatedAt).getTime()) ? raw.updatedAt : nowIso(),
+    };
+}
+function normalizeAndSortMilestones(milestones) {
+    return sortMilestonesNewestFirst(milestones
+        .filter((item) => isValidRoadmapId(item.id))
+        .map((item) => normalizeMilestone(item)));
+}
+export function renderRoadmapMarkdown(milestones) {
+    const lines = sortMilestonesNewestFirst(milestones).map((item) => {
+        const checkbox = item.status === "done" ? "x" : " ";
+        const timeText = item.time ? ` (time: ${item.time})` : "";
+        return `- [${checkbox}] ${item.id}: ${item.title}${timeText}`;
+    });
+    return [
+        "# Roadmap",
+        "",
+        "This file is generated from .projitive sqlite tables by Projitive MCP. Manual edits will be overwritten.",
+        "",
+        "## Active Milestones",
+        ...(lines.length > 0 ? lines : ["- (no milestones)"]),
+        "",
+    ].join("\n");
+}
+function resolveRoadmapArtifactPaths(governanceDir) {
+    return {
+        roadmapPath: path.join(governanceDir, ".projitive"),
+        markdownPath: path.join(governanceDir, ROADMAP_MARKDOWN_FILE),
+    };
+}
+async function syncRoadmapMarkdownView(roadmapPath, markdownPath, markdown, force = false) {
+    const sourceVersion = await getStoreVersion(roadmapPath, "roadmaps");
+    const viewState = await getMarkdownViewState(roadmapPath, "roadmaps_markdown");
+    const markdownExists = await fs.access(markdownPath).then(() => true).catch(() => false);
+    const shouldWrite = force
+        || !markdownExists
+        || viewState.dirty
+        || viewState.lastSourceVersion !== sourceVersion;
+    if (!shouldWrite) {
+        return;
+    }
+    await fs.writeFile(markdownPath, markdown, "utf-8");
+    await markMarkdownViewBuilt(roadmapPath, "roadmaps_markdown", sourceVersion);
+}
+export async function loadRoadmapDocument(inputPath) {
+    return loadRoadmapDocumentWithOptions(inputPath, false);
+}
+export async function loadRoadmapDocumentWithOptions(inputPath, forceViewSync) {
+    const governanceDir = await resolveGovernanceDir(inputPath);
+    const { roadmapPath, markdownPath } = resolveRoadmapArtifactPaths(governanceDir);
+    await ensureStore(roadmapPath);
+    const milestones = normalizeAndSortMilestones(await loadRoadmapsFromStore(roadmapPath));
+    const normalizedMilestones = normalizeAndSortMilestones(milestones);
+    const markdown = renderRoadmapMarkdown(normalizedMilestones);
+    await syncRoadmapMarkdownView(roadmapPath, markdownPath, markdown, forceViewSync);
+    return {
+        roadmapPath,
+        markdownPath,
+        markdown,
+        milestones: normalizedMilestones,
+    };
+}
+export async function loadRoadmapIds(inputPath) {
+    const { milestones } = await loadRoadmapDocument(inputPath);
+    return milestones.map((item) => item.id);
+}
 function collectRoadmapLintSuggestionItems(roadmapIds, tasks) {
     const suggestions = [];
     if (roadmapIds.length === 0) {
         suggestions.push({
             code: ROADMAP_LINT_CODES.IDS_EMPTY,
-            message: "No roadmap IDs found in roadmap.md.",
+            message: "No roadmap IDs found in .projitive roadmap table.",
             fixHint: "Add at least one ROADMAP-xxxx milestone.",
         });
     }
     if (tasks.length === 0) {
         suggestions.push({
             code: ROADMAP_LINT_CODES.TASKS_EMPTY,
-            message: "No tasks found in tasks.md.",
+            message: "No tasks found in .projitive task table.",
             fixHint: "Add task cards and bind roadmapRefs for traceability.",
         });
         return suggestions;
@@ -56,17 +152,6 @@ export function collectRoadmapLintSuggestions(roadmapIds, tasks) {
 export function isValidRoadmapId(id) {
     return ROADMAP_ID_REGEX.test(id);
 }
-async function readRoadmapIds(governanceDir) {
-    const roadmapPath = path.join(governanceDir, "roadmap.md");
-    try {
-        const markdown = await fs.readFile(roadmapPath, "utf-8");
-        const matches = markdown.match(/ROADMAP-\d{4}/g) ?? [];
-        return Array.from(new Set(matches));
-    }
-    catch {
-        return [];
-    }
-}
 export function registerRoadmapTools(server) {
     server.registerTool("roadmapList", {
         title: "Roadmap List",
@@ -76,7 +161,7 @@ export function registerRoadmapTools(server) {
         },
     }, async ({ projectPath }) => {
         const governanceDir = await resolveGovernanceDir(projectPath);
-        const roadmapIds = await readRoadmapIds(governanceDir);
+        const roadmapIds = await loadRoadmapIds(governanceDir);
         const { tasks } = await loadTasks(governanceDir);
         const lintSuggestions = collectRoadmapLintSuggestions(roadmapIds, tasks);
         const markdown = renderToolResponseMarkdown({
@@ -122,7 +207,7 @@ export function registerRoadmapTools(server) {
         const referenceLocations = (await Promise.all(fileCandidates.map((file) => findTextReferences(file, roadmapId)))).flat();
         const { tasks } = await loadTasks(governanceDir);
         const relatedTasks = tasks.filter((task) => task.roadmapRefs.includes(roadmapId));
-        const roadmapIds = await readRoadmapIds(governanceDir);
+        const roadmapIds = await loadRoadmapIds(governanceDir);
         const lintSuggestionItems = collectRoadmapLintSuggestionItems(roadmapIds, tasks);
         if (relatedTasks.length === 0) {
             lintSuggestionItems.push({
@@ -159,4 +244,69 @@ export function registerRoadmapTools(server) {
         });
         return asText(markdown);
     });
+    server.registerTool("roadmapUpdate", {
+        title: "Roadmap Update",
+        description: "Update one roadmap milestone fields incrementally in sqlite table",
+        inputSchema: {
+            projectPath: z.string(),
+            roadmapId: z.string(),
+            updates: z.object({
+                title: z.string().optional(),
+                status: z.enum(["active", "done"]).optional(),
+                time: z.string().optional(),
+            }),
+        },
+    }, async ({ projectPath, roadmapId, updates }) => {
+        if (!isValidRoadmapId(roadmapId)) {
+            return {
+                ...asText(renderErrorMarkdown("roadmapUpdate", `Invalid roadmap ID format: ${roadmapId}`, ["expected format: ROADMAP-0001", "retry with a valid roadmap ID"], `roadmapUpdate(projectPath="${projectPath}", roadmapId="ROADMAP-0001", updates={...})`)),
+                isError: true,
+            };
+        }
+        const governanceDir = await resolveGovernanceDir(projectPath);
+        const doc = await loadRoadmapDocument(governanceDir);
+        const existing = doc.milestones.find((item) => item.id === roadmapId);
+        if (!existing) {
+            return {
+                ...asText(renderErrorMarkdown("roadmapUpdate", `Roadmap milestone not found: ${roadmapId}`, ["run roadmapList to discover existing roadmap IDs", "retry with an existing roadmap ID"], `roadmapList(projectPath="${toProjectPath(governanceDir)}")`)),
+                isError: true,
+            };
+        }
+        const updated = {
+            ...existing,
+            title: updates.title ?? existing.title,
+            status: updates.status ?? existing.status,
+            time: updates.time ?? existing.time,
+            updatedAt: nowIso(),
+        };
+        await upsertRoadmapInStore(doc.roadmapPath, updated);
+        const refreshed = await loadRoadmapDocumentWithOptions(governanceDir, true);
+        const markdown = renderToolResponseMarkdown({
+            toolName: "roadmapUpdate",
+            sections: [
+                summarySection([
+                    `- governanceDir: ${governanceDir}`,
+                    `- roadmapId: ${roadmapId}`,
+                    `- newStatus: ${updated.status}`,
+                    `- updatedAt: ${updated.updatedAt}`,
+                ]),
+                evidenceSection([
+                    "### Updated Milestone",
+                    `- ${updated.id} | ${updated.status} | ${updated.title}${updated.time ? ` | time=${updated.time}` : ""}`,
+                    "",
+                    `### Roadmap Count`,
+                    `- total: ${refreshed.milestones.length}`,
+                ]),
+                guidanceSection([
+                    "Milestone updated successfully.",
+                    "Re-run roadmapContext to verify linked task traceability.",
+                    "SQLite is source of truth; roadmap.md is a generated view and may be overwritten.",
+                    "Call `syncViews(projectPath=..., views=[\"roadmap\"], force=true)` when immediate markdown materialization is required.",
+                ]),
+                lintSection([]),
+                nextCallSection(`roadmapContext(projectPath="${toProjectPath(governanceDir)}", roadmapId="${roadmapId}")`),
+            ],
+        });
+        return asText(markdown);
+    });
 }

package/output/source/tools/roadmap.test.js

@@ -2,7 +2,7 @@ import { describe, it, expect, beforeAll, afterAll } from "vitest";
 import fs from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
-import { isValidRoadmapId, collectRoadmapLintSuggestions } from "./roadmap.js";
+import { isValidRoadmapId, collectRoadmapLintSuggestions, loadRoadmapDocument, renderRoadmapMarkdown } from "./roadmap.js";
 describe("roadmap module", () => {
     let tempDir;
     beforeAll(async () => {
@@ -15,14 +15,10 @@ describe("roadmap module", () => {
         it("should validate correct roadmap IDs", () => {
             expect(isValidRoadmapId("ROADMAP-0001")).toBe(true);
             expect(isValidRoadmapId("ROADMAP-1234")).toBe(true);
-            expect(isValidRoadmapId("ROADMAP-9999")).toBe(true);
         });
         it("should reject invalid roadmap IDs", () => {
             expect(isValidRoadmapId("roadmap-0001")).toBe(false);
-            expect(isValidRoadmapId("ROADMAP-001")).toBe(false);
-            expect(isValidRoadmapId("ROADMAP-00001")).toBe(false);
             expect(isValidRoadmapId("TASK-0001")).toBe(false);
-            expect(isValidRoadmapId("")).toBe(false);
             expect(isValidRoadmapId("invalid")).toBe(false);
         });
     });
@@ -36,8 +32,7 @@ describe("roadmap module", () => {
             expect(suggestions.some(s => s.includes("TASKS_EMPTY"))).toBe(true);
         });
         it("should return lint suggestion for tasks without roadmap refs", () => {
-            const tasks = [
-                {
+            const tasks = [{
                     id: "TASK-0001",
                     title: "Test Task",
                     status: "TODO",
@@ -46,58 +41,27 @@ describe("roadmap module", () => {
                     updatedAt: "2026-01-01T00:00:00.000Z",
                     links: [],
                     roadmapRefs: [],
-                },
-            ];
+                }];
             const suggestions = collectRoadmapLintSuggestions(["ROADMAP-0001"], tasks);
             expect(suggestions.some(s => s.includes("TASK_REFS_EMPTY"))).toBe(true);
         });
-        it("should return lint suggestion for unknown roadmap refs", () => {
-            const tasks = [
-                {
-                    id: "TASK-0001",
-                    title: "Test Task",
-                    status: "TODO",
-                    owner: "ai-copilot",
-                    summary: "Test",
-                    updatedAt: "2026-01-01T00:00:00.000Z",
-                    links: [],
-                    roadmapRefs: ["ROADMAP-9999"],
-                },
-            ];
-            const suggestions = collectRoadmapLintSuggestions(["ROADMAP-0001"], tasks);
-            expect(suggestions.some(s => s.includes("UNKNOWN_REFS"))).toBe(true);
-        });
-        it("should return lint suggestion for roadmaps with no linked tasks", () => {
-            const tasks = [
-                {
-                    id: "TASK-0001",
-                    title: "Test Task",
-                    status: "TODO",
-                    owner: "ai-copilot",
-                    summary: "Test",
-                    updatedAt: "2026-01-01T00:00:00.000Z",
-                    links: [],
-                    roadmapRefs: ["ROADMAP-0001"],
-                },
-            ];
-            const suggestions = collectRoadmapLintSuggestions(["ROADMAP-0001", "ROADMAP-0002"], tasks);
-            expect(suggestions.some(s => s.includes("ZERO_LINKED_TASKS"))).toBe(true);
+        it("loads from sqlite and rewrites roadmap markdown view", async () => {
+            const governanceDir = path.join(tempDir, ".projitive-db");
+            await fs.mkdir(governanceDir, { recursive: true });
+            await fs.writeFile(path.join(governanceDir, ".projitive"), "", "utf-8");
+            const doc = await loadRoadmapDocument(governanceDir);
+            expect(doc.roadmapPath.endsWith(".projitive")).toBe(true);
+            expect(doc.markdownPath.endsWith("roadmap.md")).toBe(true);
+            const markdown = await fs.readFile(path.join(governanceDir, "roadmap.md"), "utf-8");
+            expect(markdown).toContain("generated from .projitive sqlite tables");
         });
-        it("should return no lint suggestions for valid setup", () => {
-            const tasks = [
-                {
-                    id: "TASK-0001",
-                    title: "Test Task",
-                    status: "TODO",
-                    owner: "ai-copilot",
-                    summary: "Test",
-                    updatedAt: "2026-01-01T00:00:00.000Z",
-                    links: [],
-                    roadmapRefs: ["ROADMAP-0001"],
-                },
-            ];
-            const suggestions = collectRoadmapLintSuggestions(["ROADMAP-0001"], tasks);
-            expect(suggestions.length).toBe(0);
+        it("renders milestones in newest-first order", () => {
+            const markdown = renderRoadmapMarkdown([
+                { id: "ROADMAP-0001", title: "Older", status: "active", updatedAt: "2026-01-01T00:00:00.000Z" },
+                { id: "ROADMAP-0002", title: "Newer", status: "done", updatedAt: "2026-02-01T00:00:00.000Z" },
+            ]);
+            expect(markdown.indexOf("ROADMAP-0002")).toBeLessThan(markdown.indexOf("ROADMAP-0001"));
+            expect(markdown).toContain("[x] ROADMAP-0002");
         });
     });
 });