@projitive/mcp 1.0.0 → 1.0.2

package/output/projitive.js

@@ -4,19 +4,33 @@ import process from "node:process";
 import { z } from "zod";
 import { discoverGovernanceArtifacts } from "./helpers/files/index.js";
 import { catchIt } from "./helpers/catch/index.js";
-import { loadTasks } from "./tasks.js";
+import { PROJECT_LINT_CODES, renderLintSuggestions } from "./helpers/linter/index.js";
+import { asText, evidenceSection, guidanceSection, lintSection, nextCallSection, renderToolResponseMarkdown, summarySection, } from "./helpers/response/index.js";
+import { collectTaskLintSuggestions, loadTasksDocument } from "./tasks.js";
 export const PROJECT_MARKER = ".projitive";
+const DEFAULT_GOVERNANCE_DIR = ".projitive";
 const ignoreNames = new Set(["node_modules", ".git", ".next", "dist", "build"]);
 const DEFAULT_SCAN_DEPTH = 3;
 const MAX_SCAN_DEPTH = 8;
-function asText(markdown) {
-    return {
-        content: [{ type: "text", text: markdown }],
-    };
-}
 function normalizePath(inputPath) {
     return inputPath ? path.resolve(inputPath) : process.cwd();
 }
+function normalizeGovernanceDirName(input) {
+    const name = input?.trim() || DEFAULT_GOVERNANCE_DIR;
+    if (!name) {
+        throw new Error("governanceDir cannot be empty");
+    }
+    if (path.isAbsolute(name)) {
+        throw new Error("governanceDir must be a relative directory name");
+    }
+    if (name.includes("/") || name.includes("\\")) {
+        throw new Error("governanceDir must not contain path separators");
+    }
+    if (name === "." || name === "..") {
+        throw new Error("governanceDir must be a normal directory name");
+    }
+    return name;
+}
 function parseDepthFromEnv(rawDepth) {
     if (typeof rawDepth !== "string" || rawDepth.trim().length === 0) {
         return undefined;
@@ -54,11 +68,22 @@ 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") {
-        return { tasksPath, exists: false, tasks: [] };
+        return {
+            tasksPath,
+            exists: false,
+            tasks: [],
+            lintSuggestions: renderLintSuggestions([
+                {
+                    code: PROJECT_LINT_CODES.TASKS_FILE_MISSING,
+                    message: "tasks.md is missing.",
+                    fixHint: "Initialize governance tasks structure first.",
+                },
+            ]),
+        };
     }
     const { parseTasksBlock } = await import("./tasks.js");
     const tasks = await parseTasksBlock(markdown);
-    return { tasksPath, exists: true, tasks };
+    return { tasksPath, exists: true, tasks, lintSuggestions: collectTaskLintSuggestions(tasks, markdown) };
 }
 function latestTaskUpdatedAt(tasks) {
     const timestamps = tasks
@@ -134,7 +159,134 @@ export async function discoverProjects(rootPath, maxDepth) {
     await walk(rootPath, 0);
     return Array.from(new Set(results)).sort();
 }
+async function pathExists(targetPath) {
+    const accessResult = await catchIt(fs.access(targetPath));
+    return !accessResult.isError();
+}
+async function writeTextFile(targetPath, content, force) {
+    const exists = await pathExists(targetPath);
+    if (exists && !force) {
+        return { path: targetPath, action: "skipped" };
+    }
+    await fs.writeFile(targetPath, content, "utf-8");
+    return { path: targetPath, action: exists ? "updated" : "created" };
+}
+function defaultReadmeMarkdown(governanceDirName) {
+    return [
+        "# Projitive Governance Workspace",
+        "",
+        `This directory (\`${governanceDirName}/\`) is the governance root for this project.`,
+        "",
+        "## Conventions",
+        "- Keep roadmap/task/design/report files in markdown.",
+        "- 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 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}`,
+        "- links:",
+        "- roadmapRefs: ROADMAP-0001",
+        "- hooks:",
+        "<!-- PROJITIVE:TASKS:END -->",
+    ].join("\n");
+}
+export async function initializeProjectStructure(inputPath, governanceDir, force = false) {
+    const rootPath = normalizePath(inputPath);
+    const governanceDirName = normalizeGovernanceDirName(governanceDir);
+    const rootStat = await catchIt(fs.stat(rootPath));
+    if (rootStat.isError()) {
+        throw new Error(`Path not found: ${rootPath}`);
+    }
+    if (!rootStat.value.isDirectory()) {
+        throw new Error(`rootPath must be a directory: ${rootPath}`);
+    }
+    const governancePath = path.join(rootPath, governanceDirName);
+    const directories = [];
+    const requiredDirectories = [governancePath, path.join(governancePath, "designs"), path.join(governancePath, "reports"), path.join(governancePath, "hooks")];
+    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),
+        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),
+    ]);
+    return {
+        rootPath,
+        governanceDir: governancePath,
+        markerPath,
+        directories,
+        files,
+    };
+}
 export function registerProjectTools(server) {
+    server.registerTool("projectInit", {
+        title: "Project Init",
+        description: "Initialize Projitive governance directory structure manually (default .projitive)",
+        inputSchema: {
+            rootPath: z.string().optional(),
+            governanceDir: z.string().optional(),
+            force: z.boolean().optional(),
+        },
+    }, async ({ rootPath, governanceDir, force }) => {
+        const initialized = await initializeProjectStructure(rootPath, governanceDir, force ?? false);
+        const filesByAction = {
+            created: initialized.files.filter((item) => item.action === "created"),
+            updated: initialized.files.filter((item) => item.action === "updated"),
+            skipped: initialized.files.filter((item) => item.action === "skipped"),
+        };
+        const markdown = renderToolResponseMarkdown({
+            toolName: "projectInit",
+            sections: [
+                summarySection([
+                    `- rootPath: ${initialized.rootPath}`,
+                    `- governanceDir: ${initialized.governanceDir}`,
+                    `- markerPath: ${initialized.markerPath}`,
+                    `- force: ${force === true ? "true" : "false"}`,
+                ]),
+                evidenceSection([
+                    `- createdFiles: ${filesByAction.created.length}`,
+                    `- updatedFiles: ${filesByAction.updated.length}`,
+                    `- skippedFiles: ${filesByAction.skipped.length}`,
+                    "- directories:",
+                    ...initialized.directories.map((item) => `  - ${item.action}: ${item.path}`),
+                    "- files:",
+                    ...initialized.files.map((item) => `  - ${item.action}: ${item.path}`),
+                ]),
+                guidanceSection([
+                    "- If files were skipped and you want to overwrite templates, rerun with force=true.",
+                    "- 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.",
+                ]),
+                nextCallSection(`projectContext(projectPath=\"${initialized.governanceDir}\")`),
+            ],
+        });
+        return asText(markdown);
+    });
     server.registerTool("projectScan", {
         title: "Project Scan",
         description: "Scan filesystem and discover project governance roots marked by .projitive",
@@ -146,27 +298,30 @@ export function registerProjectTools(server) {
         const root = resolveScanRoot(rootPath);
         const depth = resolveScanDepth(maxDepth);
         const projects = await discoverProjects(root, depth);
-        const markdown = [
-            "# projectScan",
-            "",
-            "## Summary",
-            `- rootPath: ${root}`,
-            `- maxDepth: ${depth}`,
-            `- discoveredCount: ${projects.length}`,
-            "",
-            "## Evidence",
-            "- projects:",
-            ...(projects.length > 0 ? projects.map((project, index) => `${index + 1}. ${project}`) : ["- (none)"]),
-            "",
-            "## Agent Guidance",
-            "- Use one discovered project path and call `projectLocate` to lock governance root.",
-            "- Then call `projectContext` to inspect current governance state.",
-            "",
-            "## Next Call",
-            ...(projects.length > 0
-                ? [`- projectLocate(inputPath=\"${projects[0]}\")`]
-                : ["- (none)"]),
-        ].join("\n");
+        const markdown = renderToolResponseMarkdown({
+            toolName: "projectScan",
+            sections: [
+                summarySection([
+                    `- rootPath: ${root}`,
+                    `- maxDepth: ${depth}`,
+                    `- discoveredCount: ${projects.length}`,
+                ]),
+                evidenceSection([
+                    "- projects:",
+                    ...projects.map((project, index) => `${index + 1}. ${project}`),
+                ]),
+                guidanceSection([
+                    "- Use one discovered project path and call `projectLocate` to lock governance root.",
+                    "- Then call `projectContext` to inspect current governance state.",
+                ]),
+                lintSection(projects.length === 0
+                    ? ["- No governance root discovered. Add `.projitive` marker and baseline artifacts before execution."]
+                    : ["- Run `projectContext` on a discovered project to receive module-level lint suggestions."]),
+                nextCallSection(projects[0]
+                    ? `projectLocate(inputPath=\"${projects[0]}\")`
+                    : undefined),
+            ],
+        });
         return asText(markdown);
     });
     server.registerTool("projectNext", {
@@ -192,7 +347,7 @@ export function registerProjectTools(server) {
                 governanceDir,
                 tasksPath: snapshot.tasksPath,
                 tasksExists: snapshot.exists,
-                total: snapshot.tasks.length,
+                lintSuggestions: snapshot.lintSuggestions,
                 inProgress,
                 todo,
                 blocked,
@@ -211,32 +366,31 @@ export function registerProjectTools(server) {
             return b.latestUpdatedAt.localeCompare(a.latestUpdatedAt);
         })
             .slice(0, limit ?? 10);
-        const markdown = [
-            "# projectNext",
-            "",
-            "## Summary",
-            `- rootPath: ${root}`,
-            `- maxDepth: ${depth}`,
-            `- matchedProjects: ${projects.length}`,
-            `- actionableProjects: ${ranked.length}`,
-            `- limit: ${limit ?? 10}`,
-            "",
-            "## Evidence",
-            "- rankedProjects:",
-            ...(ranked.length > 0
-                ? 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)"}`)
-                : ["- (none)"]),
-            "",
-            "## Agent Guidance",
-            "- Pick top 1 project and call `projectContext` with its governanceDir.",
-            "- Then call `taskList` and `taskContext` to continue execution.",
-            "- If `tasksPath` is missing, create tasks.md using project convention before task-level operations.",
-            "",
-            "## Next Call",
-            ...(ranked.length > 0
-                ? [`- projectContext(projectPath=\"${ranked[0].governanceDir}\")`]
-                : ["- (none)"]),
-        ].join("\n");
+        const markdown = renderToolResponseMarkdown({
+            toolName: "projectNext",
+            sections: [
+                summarySection([
+                    `- rootPath: ${root}`,
+                    `- maxDepth: ${depth}`,
+                    `- matchedProjects: ${projects.length}`,
+                    `- actionableProjects: ${ranked.length}`,
+                    `- limit: ${limit ?? 10}`,
+                ]),
+                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)"}`),
+                ]),
+                guidanceSection([
+                    "- Pick top 1 project and call `projectContext` with its governanceDir.",
+                    "- Then call `taskList` and `taskContext` to continue execution.",
+                    "- If `tasksPath` is missing, create tasks.md using project convention before task-level operations.",
+                ]),
+                lintSection(ranked[0]?.lintSuggestions ?? []),
+                nextCallSection(ranked[0]
+                    ? `projectContext(projectPath=\"${ranked[0].governanceDir}\")`
+                    : undefined),
+            ],
+        });
         return asText(markdown);
     });
     server.registerTool("projectLocate", {
@@ -249,20 +403,19 @@ export function registerProjectTools(server) {
         const resolvedFrom = normalizePath(inputPath);
         const governanceDir = await resolveGovernanceDir(resolvedFrom);
         const markerPath = path.join(governanceDir, ".projitive");
-        const markdown = [
-            "# projectLocate",
-            "",
-            "## Summary",
-            `- resolvedFrom: ${resolvedFrom}`,
-            `- governanceDir: ${governanceDir}`,
-            `- markerPath: ${markerPath}`,
-            "",
-            "## Agent Guidance",
-            "- Call `projectContext` with this governanceDir to get task and roadmap summaries.",
-            "",
-            "## Next Call",
-            `- projectContext(projectPath=\"${governanceDir}\")`,
-        ].join("\n");
+        const markdown = renderToolResponseMarkdown({
+            toolName: "projectLocate",
+            sections: [
+                summarySection([
+                    `- resolvedFrom: ${resolvedFrom}`,
+                    `- governanceDir: ${governanceDir}`,
+                    `- markerPath: ${markerPath}`,
+                ]),
+                guidanceSection(["- Call `projectContext` with this governanceDir to get task and roadmap summaries."]),
+                lintSection(["- Run `projectContext` to get governance/module lint suggestions for this project."]),
+                nextCallSection(`projectContext(projectPath=\"${governanceDir}\")`),
+            ],
+        });
         return asText(markdown);
     });
     server.registerTool("projectContext", {
@@ -274,8 +427,9 @@ export function registerProjectTools(server) {
     }, async ({ projectPath }) => {
         const governanceDir = await resolveGovernanceDir(projectPath);
         const artifacts = await discoverGovernanceArtifacts(governanceDir);
-        const { tasksPath, tasks } = await loadTasks(governanceDir);
+        const { tasksPath, tasks, markdown: tasksMarkdown } = 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,
@@ -283,32 +437,33 @@ export function registerProjectTools(server) {
             BLOCKED: tasks.filter((task) => task.status === "BLOCKED").length,
             DONE: tasks.filter((task) => task.status === "DONE").length,
         };
-        const markdown = [
-            "# projectContext",
-            "",
-            "## Summary",
-            `- governanceDir: ${governanceDir}`,
-            `- tasksFile: ${tasksPath}`,
-            `- roadmapIds: ${roadmapIds.length}`,
-            "",
-            "## Evidence",
-            "### Task Summary",
-            `- total: ${taskSummary.total}`,
-            `- TODO: ${taskSummary.TODO}`,
-            `- IN_PROGRESS: ${taskSummary.IN_PROGRESS}`,
-            `- BLOCKED: ${taskSummary.BLOCKED}`,
-            `- DONE: ${taskSummary.DONE}`,
-            "",
-            "### Artifacts",
-            renderArtifactsMarkdown(artifacts),
-            "",
-            "## Agent Guidance",
-            "- Start from `taskList` to choose a target task.",
-            "- Then call `taskContext` with a task ID to retrieve evidence locations and reading order.",
-            "",
-            "## Next Call",
-            `- taskList(projectPath=\"${governanceDir}\")`,
-        ].join("\n");
+        const markdown = renderToolResponseMarkdown({
+            toolName: "projectContext",
+            sections: [
+                summarySection([
+                    `- governanceDir: ${governanceDir}`,
+                    `- tasksFile: ${tasksPath}`,
+                    `- roadmapIds: ${roadmapIds.length}`,
+                ]),
+                evidenceSection([
+                    "### Task Summary",
+                    `- total: ${taskSummary.total}`,
+                    `- TODO: ${taskSummary.TODO}`,
+                    `- IN_PROGRESS: ${taskSummary.IN_PROGRESS}`,
+                    `- BLOCKED: ${taskSummary.BLOCKED}`,
+                    `- DONE: ${taskSummary.DONE}`,
+                    "",
+                    "### Artifacts",
+                    renderArtifactsMarkdown(artifacts),
+                ]),
+                guidanceSection([
+                    "- Start from `taskList` to choose a target task.",
+                    "- Then call `taskContext` with a task ID to retrieve evidence locations and reading order.",
+                ]),
+                lintSection(lintSuggestions),
+                nextCallSection(`taskList(projectPath=\"${governanceDir}\")`),
+            ],
+        });
         return asText(markdown);
     });
 }

package/output/projitive.test.js

@@ -2,7 +2,7 @@ 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";
+import { discoverProjects, hasProjectMarker, initializeProjectStructure, resolveGovernanceDir } from "./projitive.js";
 const tempPaths = [];
 async function createTempDir() {
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), "projitive-mcp-test-"));
@@ -43,4 +43,32 @@ describe("projitive module", () => {
         expect(projects).toContain(p1);
         expect(projects).toContain(p2);
     });
+    it("initializes governance structure under default .projitive directory", async () => {
+        const root = await createTempDir();
+        const initialized = await initializeProjectStructure(root);
+        expect(initialized.governanceDir).toBe(path.join(root, ".projitive"));
+        const expectedPaths = [
+            path.join(root, ".projitive", ".projitive"),
+            path.join(root, ".projitive", "README.md"),
+            path.join(root, ".projitive", "roadmap.md"),
+            path.join(root, ".projitive", "tasks.md"),
+            path.join(root, ".projitive", "designs"),
+            path.join(root, ".projitive", "reports"),
+            path.join(root, ".projitive", "hooks"),
+        ];
+        await Promise.all(expectedPaths.map(async (targetPath) => {
+            await expect(fs.access(targetPath)).resolves.toBeUndefined();
+        }));
+    });
+    it("overwrites template files when force is enabled", async () => {
+        const root = await createTempDir();
+        const governanceDir = path.join(root, ".projitive");
+        const readmePath = path.join(governanceDir, "README.md");
+        await initializeProjectStructure(root);
+        await fs.writeFile(readmePath, "custom-content", "utf-8");
+        const initialized = await initializeProjectStructure(root, ".projitive", true);
+        const readmeContent = await fs.readFile(readmePath, "utf-8");
+        expect(readmeContent).toContain("Projitive Governance Workspace");
+        expect(initialized.files.find((item) => item.path === readmePath)?.action).toBe("updated");
+    });
 });

package/output/rendering-input-guard.test.js

@@ -0,0 +1,20 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+const MODULE_FILES = [
+    "tasks.ts",
+    "roadmap.ts",
+    "projitive.ts",
+];
+const INVALID_LITERAL_PATTERN = /["'`]\s*-\s+(#{1,6}\s|>\s*|```)/g;
+describe("rendering input guard", () => {
+    it("does not contain accidental bullet-prefixed markdown literals in module outputs", async () => {
+        const sourceDir = path.resolve(import.meta.dirname);
+        for (const file of MODULE_FILES) {
+            const filePath = path.join(sourceDir, file);
+            const content = await fs.readFile(filePath, "utf-8");
+            const matches = content.match(INVALID_LITERAL_PATTERN) ?? [];
+            expect(matches, `invalid literals in ${filePath}`).toHaveLength(0);
+        }
+    });
+});