@projitive/mcp 1.2.0 → 2.0.1

package/output/source/tools/project.js

@@ -2,9 +2,10 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
 import { z } from "zod";
-import { discoverGovernanceArtifacts, catchIt, PROJECT_LINT_CODES, renderLintSuggestions } from "../common/index.js";
-import { asText, evidenceSection, guidanceSection, lintSection, nextCallSection, renderToolResponseMarkdown, summarySection, } from "../common/index.js";
-import { collectTaskLintSuggestions, loadTasksDocument } from "./task.js";
+import { discoverGovernanceArtifacts, catchIt, PROJECT_LINT_CODES, renderLintSuggestions, ensureStore, replaceRoadmapsInStore, replaceTasksInStore, markMarkdownViewDirty, loadTaskStatusStatsFromStore, loadRoadmapIdsFromStore, } from "../common/index.js";
+import { asText, evidenceSection, getDefaultToolTemplateMarkdown, guidanceSection, lintSection, nextCallSection, renderToolResponseMarkdown, summarySection, } from "../common/index.js";
+import { collectTaskLintSuggestions, loadTasksDocument, loadTasksDocumentWithOptions, renderTasksMarkdown } from "./task.js";
+import { loadRoadmapDocumentWithOptions, renderRoadmapMarkdown } from "./roadmap.js";
 export const PROJECT_MARKER = ".projitive";
 const DEFAULT_GOVERNANCE_DIR = ".projitive";
 const ignoreNames = new Set(["node_modules", ".git", ".next", "dist", "build"]);
@@ -109,49 +110,45 @@ function renderArtifactsMarkdown(artifacts) {
     return rows.join("\n");
 }
 async function readTasksSnapshot(governanceDir) {
-    const tasksPath = path.join(governanceDir, "tasks.md");
-    const markdown = await fs.readFile(tasksPath, "utf-8").catch(() => undefined);
-    if (typeof markdown !== "string") {
+    const tasksPath = path.join(governanceDir, PROJECT_MARKER);
+    const exists = await fs.access(tasksPath).then(() => true).catch(() => false);
+    if (!exists) {
         return {
-            tasksPath,
             exists: false,
-            tasks: [],
             lintSuggestions: renderLintSuggestions([
                 {
                     code: PROJECT_LINT_CODES.TASKS_FILE_MISSING,
-                    message: "tasks.md is missing.",
+                    message: "governance store is missing.",
                     fixHint: "Initialize governance tasks structure first.",
                 },
             ]),
+            todo: 0,
+            inProgress: 0,
+            blocked: 0,
+            done: 0,
+            total: 0,
+            latestUpdatedAt: "(unknown)",
+            score: 0,
         };
     }
-    const { parseTasksBlock } = await import("./task.js");
-    const tasks = await parseTasksBlock(markdown);
-    return { tasksPath, exists: true, tasks, lintSuggestions: collectTaskLintSuggestions(tasks, markdown) };
-}
-function latestTaskUpdatedAt(tasks) {
-    const timestamps = tasks
-        .map((task) => new Date(task.updatedAt).getTime())
-        .filter((value) => Number.isFinite(value));
-    if (timestamps.length === 0) {
-        return "(unknown)";
-    }
-    return new Date(Math.max(...timestamps)).toISOString();
-}
-function actionableScore(tasks) {
-    return tasks.filter((task) => task.status === "IN_PROGRESS").length * 2
-        + tasks.filter((task) => task.status === "TODO").length;
+    await ensureStore(tasksPath);
+    const stats = await loadTaskStatusStatsFromStore(tasksPath);
+    return {
+        exists: true,
+        lintSuggestions: [],
+        todo: stats.todo,
+        inProgress: stats.inProgress,
+        blocked: stats.blocked,
+        done: stats.done,
+        total: stats.total,
+        latestUpdatedAt: stats.latestUpdatedAt || "(unknown)",
+        score: stats.inProgress * 2 + stats.todo,
+    };
 }
 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 [];
-    }
+    const dbPath = path.join(governanceDir, PROJECT_MARKER);
+    await ensureStore(dbPath);
+    return loadRoadmapIdsFromStore(dbPath);
 }
 export async function hasProjectMarker(dirPath) {
     const markerPath = path.join(dirPath, PROJECT_MARKER);
@@ -248,6 +245,21 @@ export async function discoverProjectsAcrossRoots(rootPaths, maxDepth) {
     const perRootResults = await Promise.all(rootPaths.map((rootPath) => discoverProjects(rootPath, maxDepth)));
     return Array.from(new Set(perRootResults.flat())).sort();
 }
+const DEFAULT_TOOL_TEMPLATE_NAMES = [
+    "projectInit",
+    "projectScan",
+    "projectNext",
+    "projectLocate",
+    "projectContext",
+    "syncViews",
+    "taskList",
+    "taskNext",
+    "taskContext",
+    "taskUpdate",
+    "roadmapList",
+    "roadmapContext",
+    "roadmapUpdate",
+];
 async function pathExists(targetPath) {
     const accessResult = await catchIt(fs.access(targetPath));
     return !accessResult.isError();
@@ -267,51 +279,62 @@ function defaultReadmeMarkdown(governanceDirName) {
         `This directory (\`${governanceDirName}/\`) is the governance root for this project.`,
         "",
         "## Conventions",
-        "- Keep roadmap/task/design/report files in markdown.",
+        "- Keep roadmap/task source of truth in .projitive sqlite tables.",
+        "- Treat roadmap.md/tasks.md as generated views from sqlite.",
         "- Keep IDs stable (TASK-xxxx / ROADMAP-xxxx).",
         "- Update report evidence before status transitions.",
     ].join("\n");
 }
-function defaultRoadmapMarkdown() {
-    return [
-        "# Roadmap",
-        "",
-        "## Active Milestones",
-        "- [ ] ROADMAP-0001: Bootstrap governance baseline (time: 2026-Q1)",
-    ].join("\n");
+function defaultRoadmapMarkdown(milestones = defaultRoadmapMilestones()) {
+    return renderRoadmapMarkdown(milestones);
 }
-function defaultTasksMarkdown() {
-    const updatedAt = new Date().toISOString();
-    return [
-        "# Tasks",
-        "",
-        "<!-- PROJITIVE:TASKS:START -->",
-        "## TASK-0001 | TODO | Bootstrap governance workspace",
-        "- owner: unassigned",
-        "- summary: Create initial governance artifacts and confirm task execution loop.",
-        `- updatedAt: ${updatedAt}`,
-        "- roadmapRefs: ROADMAP-0001",
-        "- links:",
-        "  - (none)",
-        "<!-- PROJITIVE:TASKS:END -->",
-    ].join("\n");
+function defaultTasksMarkdown(updatedAt = new Date().toISOString()) {
+    return renderTasksMarkdown([
+        {
+            id: "TASK-0001",
+            title: "Bootstrap governance workspace",
+            status: "TODO",
+            owner: "unassigned",
+            summary: "Create initial governance artifacts and confirm task execution loop.",
+            updatedAt,
+            links: [],
+            roadmapRefs: ["ROADMAP-0001"],
+        },
+    ]);
+}
+function defaultRoadmapMilestones() {
+    return [{
+            id: "ROADMAP-0001",
+            title: "Bootstrap governance baseline",
+            status: "active",
+            time: "2026-Q1",
+            updatedAt: new Date().toISOString(),
+        }];
 }
-function defaultNoTaskDiscoveryHookMarkdown() {
+function defaultTemplateReadmeMarkdown() {
     return [
-        "Objective:",
-        "- When no actionable task exists, proactively discover meaningful work and convert it into TODO tasks.",
+        "# Template Guide",
+        "",
+        "This directory stores response templates (one file per tool).",
         "",
-        "Checklist:",
-        "- Check whether code violates project guides/specs; create tasks for each actionable gap.",
-        "- Check test coverage improvement opportunities; create tasks for high-value missing tests.",
-        "- Check development/testing workflow bottlenecks; create tasks for reliability and speed improvements.",
-        "- Check TODO/FIXME/HACK comments; turn feasible items into governed tasks.",
-        "- Check dependency/security hygiene and stale tooling; create tasks where upgrades are justified.",
+        "How to enable:",
+        "- Set env `PROJITIVE_MESSAGE_TEMPLATE_PATH` to a template directory.",
+        "- Example: .projitive/templates/tools",
         "",
-        "Output Format:",
-        "- Candidate findings (3-10)",
-        "- Proposed tasks (TASK-xxxx style)",
-        "- Priority rationale",
+        "Rule:",
+        "- Prefer one template per tool: <toolName>.md (e.g. taskNext.md).",
+        "- Template directory mode only loads <toolName>.md files.",
+        "- If a tool template file is missing, Projitive will auto-generate that file before rendering.",
+        "- Include {{content}} to render original tool output.",
+        "- If {{content}} is missing, original output is appended after template text.",
+        "",
+        "Basic Variables:",
+        "- {{tool_name}}",
+        "- {{summary}}",
+        "- {{evidence}}",
+        "- {{guidance}}",
+        "- {{next_call}}",
+        "- {{content}}",
     ].join("\n");
 }
 export async function initializeProjectStructure(inputPath, governanceDir, force = false) {
@@ -326,24 +349,49 @@ export async function initializeProjectStructure(inputPath, governanceDir, force
     }
     const governancePath = path.join(projectPath, governanceDirName);
     const directories = [];
-    const requiredDirectories = [governancePath, path.join(governancePath, "designs"), path.join(governancePath, "reports"), path.join(governancePath, "hooks")];
+    const requiredDirectories = [
+        governancePath,
+        path.join(governancePath, "designs"),
+        path.join(governancePath, "reports"),
+        path.join(governancePath, "templates"),
+        path.join(governancePath, "templates", "tools"),
+    ];
     for (const dirPath of requiredDirectories) {
         const exists = await pathExists(dirPath);
         await fs.mkdir(dirPath, { recursive: true });
         directories.push({ path: dirPath, action: exists ? "skipped" : "created" });
     }
     const markerPath = path.join(governancePath, PROJECT_MARKER);
-    const files = await Promise.all([
-        writeTextFile(markerPath, "", force),
+    const defaultRoadmapData = defaultRoadmapMilestones();
+    const defaultTaskUpdatedAt = new Date().toISOString();
+    const markerExists = await pathExists(markerPath);
+    await ensureStore(markerPath);
+    if (force || !markerExists) {
+        await replaceRoadmapsInStore(markerPath, defaultRoadmapData);
+        await replaceTasksInStore(markerPath, [
+            {
+                id: "TASK-0001",
+                title: "Bootstrap governance workspace",
+                status: "TODO",
+                owner: "unassigned",
+                summary: "Create initial governance artifacts and confirm task execution loop.",
+                updatedAt: defaultTaskUpdatedAt,
+                links: [],
+                roadmapRefs: ["ROADMAP-0001"],
+            },
+        ]);
+    }
+    const baseFiles = await Promise.all([
         writeTextFile(path.join(governancePath, "README.md"), defaultReadmeMarkdown(governanceDirName), force),
-        writeTextFile(path.join(governancePath, "roadmap.md"), defaultRoadmapMarkdown(), force),
-        writeTextFile(path.join(governancePath, "tasks.md"), defaultTasksMarkdown(), force),
-        writeTextFile(path.join(governancePath, "hooks", "task_no_actionable.md"), defaultNoTaskDiscoveryHookMarkdown(), force),
+        writeTextFile(path.join(governancePath, "roadmap.md"), defaultRoadmapMarkdown(defaultRoadmapData), force),
+        writeTextFile(path.join(governancePath, "tasks.md"), defaultTasksMarkdown(defaultTaskUpdatedAt), force),
+        writeTextFile(path.join(governancePath, "templates", "README.md"), defaultTemplateReadmeMarkdown(), force),
     ]);
+    const toolTemplateFiles = await Promise.all(DEFAULT_TOOL_TEMPLATE_NAMES.map((toolName) => writeTextFile(path.join(governancePath, "templates", "tools", `${toolName}.md`), getDefaultToolTemplateMarkdown(toolName), force)));
+    const files = [...baseFiles, ...toolTemplateFiles];
     return {
         projectPath,
         governanceDir: governancePath,
-        markerPath,
         directories,
         files,
     };
@@ -370,7 +418,6 @@ export function registerProjectTools(server) {
                 summarySection([
                     `- projectPath: ${initialized.projectPath}`,
                     `- governanceDir: ${initialized.governanceDir}`,
-                    `- markerPath: ${initialized.markerPath}`,
                     `- force: ${force === true ? "true" : "false"}`,
                 ]),
                 evidenceSection([
@@ -387,8 +434,8 @@ export function registerProjectTools(server) {
                     "- Continue with projectContext and taskList for execution.",
                 ]),
                 lintSection([
-                    "- After init, fill owner/roadmapRefs/links in tasks.md before marking DONE.",
-                    "- Keep task source-of-truth inside marker block only.",
+                    "- After init, fill owner/roadmapRefs/links in .projitive task table before marking DONE.",
+                    "- Keep task source-of-truth inside sqlite tables.",
                 ]),
                 nextCallSection(`projectContext(projectPath=\"${initialized.projectPath}\")`),
             ],
@@ -442,23 +489,18 @@ export function registerProjectTools(server) {
         const projects = await discoverProjectsAcrossRoots(roots, depth);
         const snapshots = await Promise.all(projects.map(async (governanceDir) => {
             const snapshot = await readTasksSnapshot(governanceDir);
-            const inProgress = snapshot.tasks.filter((task) => task.status === "IN_PROGRESS").length;
-            const todo = snapshot.tasks.filter((task) => task.status === "TODO").length;
-            const blocked = snapshot.tasks.filter((task) => task.status === "BLOCKED").length;
-            const done = snapshot.tasks.filter((task) => task.status === "DONE").length;
-            const actionable = inProgress + todo;
+            const actionable = snapshot.inProgress + snapshot.todo;
             return {
                 governanceDir,
-                tasksPath: snapshot.tasksPath,
                 tasksExists: snapshot.exists,
                 lintSuggestions: snapshot.lintSuggestions,
-                inProgress,
-                todo,
-                blocked,
-                done,
+                inProgress: snapshot.inProgress,
+                todo: snapshot.todo,
+                blocked: snapshot.blocked,
+                done: snapshot.done,
                 actionable,
-                latestUpdatedAt: latestTaskUpdatedAt(snapshot.tasks),
-                score: actionableScore(snapshot.tasks),
+                latestUpdatedAt: snapshot.latestUpdatedAt,
+                score: snapshot.score,
             };
         }));
         const ranked = snapshots
@@ -470,6 +512,10 @@ export function registerProjectTools(server) {
             return b.latestUpdatedAt.localeCompare(a.latestUpdatedAt);
         })
             .slice(0, limit ?? 10);
+        if (ranked[0]) {
+            const topDoc = await loadTasksDocument(ranked[0].governanceDir);
+            ranked[0].lintSuggestions = collectTaskLintSuggestions(topDoc.tasks);
+        }
         const markdown = renderToolResponseMarkdown({
             toolName: "projectNext",
             sections: [
@@ -483,12 +529,12 @@ export function registerProjectTools(server) {
                 ]),
                 evidenceSection([
                     "- rankedProjects:",
-                    ...ranked.map((item, index) => `${index + 1}. ${item.governanceDir} | actionable=${item.actionable} | in_progress=${item.inProgress} | todo=${item.todo} | blocked=${item.blocked} | done=${item.done} | latest=${item.latestUpdatedAt} | tasksPath=${item.tasksPath}${item.tasksExists ? "" : " (missing)"}`),
+                    ...ranked.map((item, index) => `${index + 1}. ${item.governanceDir} | actionable=${item.actionable} | in_progress=${item.inProgress} | todo=${item.todo} | blocked=${item.blocked} | done=${item.done} | latest=${item.latestUpdatedAt}${item.tasksExists ? "" : " | store=missing"}`),
                 ]),
                 guidanceSection([
                     "- Pick top 1 project and call `projectContext` with its projectPath.",
                     "- Then call `taskList` and `taskContext` to continue execution.",
-                    "- If `tasksPath` is missing, create tasks.md using project convention before task-level operations.",
+                    "- If governance store is missing, initialize governance before task-level operations.",
                 ]),
                 lintSection(ranked[0]?.lintSuggestions ?? []),
                 nextCallSection(ranked[0]
@@ -508,7 +554,6 @@ export function registerProjectTools(server) {
         const resolvedFrom = normalizePath(inputPath);
         const governanceDir = await resolveGovernanceDir(resolvedFrom);
         const projectPath = toProjectPath(governanceDir);
-        const markerPath = path.join(governanceDir, ".projitive");
         const markdown = renderToolResponseMarkdown({
             toolName: "projectLocate",
             sections: [
@@ -516,7 +561,6 @@ export function registerProjectTools(server) {
                     `- resolvedFrom: ${resolvedFrom}`,
                     `- projectPath: ${projectPath}`,
                     `- governanceDir: ${governanceDir}`,
-                    `- markerPath: ${markerPath}`,
                 ]),
                 guidanceSection(["- Call `projectContext` with this projectPath to get task and roadmap summaries."]),
                 lintSection(["- Run `projectContext` to get governance/module lint suggestions for this project."]),
@@ -525,6 +569,61 @@ export function registerProjectTools(server) {
         });
         return asText(markdown);
     });
+    server.registerTool("syncViews", {
+        title: "Sync Views",
+        description: "Materialize markdown views from .projitive sqlite tables (tasks.md / roadmap.md)",
+        inputSchema: {
+            projectPath: z.string(),
+            views: z.array(z.enum(["tasks", "roadmap"])).optional(),
+            force: z.boolean().optional(),
+        },
+    }, async ({ projectPath, views, force }) => {
+        const governanceDir = await resolveGovernanceDir(projectPath);
+        const dbPath = path.join(governanceDir, PROJECT_MARKER);
+        const selectedViews = views && views.length > 0
+            ? Array.from(new Set(views))
+            : ["tasks", "roadmap"];
+        const forceSync = force === true;
+        if (forceSync) {
+            if (selectedViews.includes("tasks")) {
+                await markMarkdownViewDirty(dbPath, "tasks_markdown");
+            }
+            if (selectedViews.includes("roadmap")) {
+                await markMarkdownViewDirty(dbPath, "roadmaps_markdown");
+            }
+        }
+        let taskCount;
+        let roadmapCount;
+        if (selectedViews.includes("tasks")) {
+            const taskDoc = await loadTasksDocumentWithOptions(governanceDir, forceSync);
+            taskCount = taskDoc.tasks.length;
+        }
+        if (selectedViews.includes("roadmap")) {
+            const roadmapDoc = await loadRoadmapDocumentWithOptions(governanceDir, forceSync);
+            roadmapCount = roadmapDoc.milestones.length;
+        }
+        const markdown = renderToolResponseMarkdown({
+            toolName: "syncViews",
+            sections: [
+                summarySection([
+                    `- governanceDir: ${governanceDir}`,
+                    `- views: ${selectedViews.join(", ")}`,
+                    `- force: ${forceSync ? "true" : "false"}`,
+                ]),
+                evidenceSection([
+                    ...(typeof taskCount === "number" ? [`- tasks.md synced | taskCount=${taskCount}`] : []),
+                    ...(typeof roadmapCount === "number" ? [`- roadmap.md synced | roadmapCount=${roadmapCount}`] : []),
+                ]),
+                guidanceSection([
+                    "Use this tool after batch updates when you need immediate markdown materialization.",
+                    "Routine workflows can rely on lazy sync and usually do not require force=true.",
+                ]),
+                lintSection([]),
+                nextCallSection(`projectContext(projectPath="${toProjectPath(governanceDir)}")`),
+            ],
+        });
+        return asText(markdown);
+    });
     server.registerTool("projectContext", {
         title: "Project Context",
         description: "Get project-level summary before selecting or executing a task",
@@ -535,32 +634,28 @@ export function registerProjectTools(server) {
         const governanceDir = await resolveGovernanceDir(projectPath);
         const normalizedProjectPath = toProjectPath(governanceDir);
         const artifacts = await discoverGovernanceArtifacts(governanceDir);
-        const { tasksPath, tasks, markdown: tasksMarkdown } = await loadTasksDocument(governanceDir);
+        const dbPath = path.join(governanceDir, PROJECT_MARKER);
+        await ensureStore(dbPath);
+        const taskStats = await loadTaskStatusStatsFromStore(dbPath);
+        const { markdownPath: tasksMarkdownPath, tasks } = await loadTasksDocument(governanceDir);
         const roadmapIds = await readRoadmapIds(governanceDir);
-        const lintSuggestions = collectTaskLintSuggestions(tasks, tasksMarkdown);
-        const taskSummary = {
-            total: tasks.length,
-            TODO: tasks.filter((task) => task.status === "TODO").length,
-            IN_PROGRESS: tasks.filter((task) => task.status === "IN_PROGRESS").length,
-            BLOCKED: tasks.filter((task) => task.status === "BLOCKED").length,
-            DONE: tasks.filter((task) => task.status === "DONE").length,
-        };
+        const lintSuggestions = collectTaskLintSuggestions(tasks);
         const markdown = renderToolResponseMarkdown({
             toolName: "projectContext",
             sections: [
                 summarySection([
                     `- projectPath: ${normalizedProjectPath}`,
                     `- governanceDir: ${governanceDir}`,
-                    `- tasksFile: ${tasksPath}`,
+                    `- tasksView: ${tasksMarkdownPath}`,
                     `- roadmapIds: ${roadmapIds.length}`,
                 ]),
                 evidenceSection([
                     "### Task Summary",
-                    `- total: ${taskSummary.total}`,
-                    `- TODO: ${taskSummary.TODO}`,
-                    `- IN_PROGRESS: ${taskSummary.IN_PROGRESS}`,
-                    `- BLOCKED: ${taskSummary.BLOCKED}`,
-                    `- DONE: ${taskSummary.DONE}`,
+                    `- total: ${taskStats.total}`,
+                    `- TODO: ${taskStats.todo}`,
+                    `- IN_PROGRESS: ${taskStats.inProgress}`,
+                    `- BLOCKED: ${taskStats.blocked}`,
+                    `- DONE: ${taskStats.done}`,
                     "",
                     "### Artifacts",
                     renderArtifactsMarkdown(artifacts),

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

@@ -206,10 +206,13 @@ describe("projitive module", () => {
                 path.join(root, ".projitive", "README.md"),
                 path.join(root, ".projitive", "roadmap.md"),
                 path.join(root, ".projitive", "tasks.md"),
-                path.join(root, ".projitive", "hooks", "task_no_actionable.md"),
+                path.join(root, ".projitive", "templates", "README.md"),
+                path.join(root, ".projitive", "templates", "tools", "taskNext.md"),
+                path.join(root, ".projitive", "templates", "tools", "taskUpdate.md"),
                 path.join(root, ".projitive", "designs"),
                 path.join(root, ".projitive", "reports"),
-                path.join(root, ".projitive", "hooks"),
+                path.join(root, ".projitive", "templates"),
+                path.join(root, ".projitive", "templates", "tools"),
             ];
             await Promise.all(expectedPaths.map(async (targetPath) => {
                 await expect(fs.access(targetPath)).resolves.toBeUndefined();
@@ -266,7 +269,7 @@ describe("projitive module", () => {
             const initialized = await initializeProjectStructure(root);
             expect(initialized.directories.some(d => d.path.includes("designs"))).toBe(true);
             expect(initialized.directories.some(d => d.path.includes("reports"))).toBe(true);
-            expect(initialized.directories.some(d => d.path.includes("hooks"))).toBe(true);
+            expect(initialized.directories.some(d => d.path.includes("templates"))).toBe(true);
         });
     });
     describe("utility functions", () => {