@projitive/mcp 1.0.0 → 1.0.1

package/README.md

@@ -2,7 +2,7 @@
 
 Language: English | [简体中文](README_CN.md)
 
-**Current Spec Version: projitive-spec v1.0.0 | MCP Version: 1.0.0**
+**Current Spec Version: projitive-spec v1.0.0 | MCP Version: 1.0.1**
 
 Projitive MCP server (semantic interface edition) helps agents discover projects, select tasks, locate evidence, and execute under governance workflows.
 
@@ -109,6 +109,34 @@ node /absolute/path/to/packages/mcp/output/index.js
 
 ### Discovery Layer
 
+#### `projectInit`
+
+- **Purpose**: manually initialize governance directory structure for a project (default `.projitive`).
+- **Input**: `rootPath?`, `governanceDir?`, `force?`
+- **Output Example (Markdown)**:
+
+```markdown
+# projectInit
+
+## Summary
+- rootPath: /workspace/proj-a
+- governanceDir: /workspace/proj-a/.projitive
+- markerPath: /workspace/proj-a/.projitive/.projitive
+- force: false
+
+## Evidence
+- createdFiles: 4
+- updatedFiles: 0
+- skippedFiles: 0
+
+## Agent Guidance
+- If files were skipped and you want to overwrite templates, rerun with force=true.
+- Continue with projectContext and taskList for execution.
+
+## Next Call
+- projectContext(projectPath="/workspace/proj-a/.projitive")
+```
+
 #### `projectNext`
 
 - **Purpose**: directly list recently actionable projects (ranked by actionable task count and recency).

package/output/index.js

@@ -46,6 +46,7 @@ function renderMethodCatalogMarkdown() {
         "## Methods",
         "| Group | Method | Role |",
         "|---|---|---|",
+        "| Project | projectInit | initialize governance directory structure |",
         "| Project | projectScan | discover governance projects by marker |",
         "| Project | projectNext | rank actionable projects |",
         "| Project | projectLocate | resolve nearest governance root |",

package/output/projitive.js

@@ -6,6 +6,7 @@ import { discoverGovernanceArtifacts } from "./helpers/files/index.js";
 import { catchIt } from "./helpers/catch/index.js";
 import { loadTasks } 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;
@@ -17,6 +18,22 @@ function asText(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;
@@ -134,7 +151,130 @@ 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 = [
+            "# projectInit",
+            "",
+            "## Summary",
+            `- rootPath: ${initialized.rootPath}`,
+            `- governanceDir: ${initialized.governanceDir}`,
+            `- markerPath: ${initialized.markerPath}`,
+            `- force: ${force === true ? "true" : "false"}`,
+            "",
+            "## Evidence",
+            `- 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}`),
+            "",
+            "## Agent Guidance",
+            "- If files were skipped and you want to overwrite templates, rerun with force=true.",
+            "- Continue with projectContext and taskList for execution.",
+            "",
+            "## Next Call",
+            `- projectContext(projectPath=\"${initialized.governanceDir}\")`,
+        ].join("\n");
+        return asText(markdown);
+    });
     server.registerTool("projectScan", {
         title: "Project Scan",
         description: "Scan filesystem and discover project governance roots marked by .projitive",

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@projitive/mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Projitive MCP Server for project and task discovery/update",
   "license": "ISC",
   "author": "",