@projitive/mcp 1.0.0 → 1.0.2

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.2**
 
 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/helpers/artifacts/artifacts.js

@@ -0,0 +1,10 @@
+export function candidateFilesFromArtifacts(artifacts) {
+    return artifacts
+        .filter((item) => item.exists)
+        .flatMap((item) => {
+        if (item.kind === "file") {
+            return [item.path];
+        }
+        return (item.markdownFiles ?? []).map((entry) => entry.path);
+    });
+}

package/output/helpers/artifacts/artifacts.test.js

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { candidateFilesFromArtifacts } from "./artifacts.js";
+describe("candidateFilesFromArtifacts", () => {
+    it("collects existing file artifacts and markdown files from existing directories", () => {
+        const candidates = candidateFilesFromArtifacts([
+            { name: "README.md", kind: "file", path: "/a/README.md", exists: true, lineCount: 3 },
+            { name: "tasks.md", kind: "file", path: "/a/tasks.md", exists: false },
+            {
+                name: "designs",
+                kind: "directory",
+                path: "/a/designs",
+                exists: true,
+                markdownFiles: [{ path: "/a/designs/d1.md", lineCount: 10 }],
+            },
+        ]);
+        expect(candidates).toEqual(["/a/README.md", "/a/designs/d1.md"]);
+    });
+});

package/output/helpers/artifacts/index.js

@@ -0,0 +1 @@
+export * from "./artifacts.js";

package/output/helpers/index.js

@@ -1,3 +1,6 @@
+export * from './artifacts/index.js';
 export * from './catch/index.js';
 export * from './files/index.js';
+export * from './linter/index.js';
 export * from './markdown/index.js';
+export * from './response/index.js';

package/output/helpers/linter/codes.js

@@ -0,0 +1,25 @@
+export const TASK_LINT_CODES = {
+    DUPLICATE_ID: "TASK_DUPLICATE_ID",
+    IN_PROGRESS_OWNER_EMPTY: "TASK_IN_PROGRESS_OWNER_EMPTY",
+    DONE_LINKS_MISSING: "TASK_DONE_LINKS_MISSING",
+    BLOCKED_SUMMARY_EMPTY: "TASK_BLOCKED_SUMMARY_EMPTY",
+    UPDATED_AT_INVALID: "TASK_UPDATED_AT_INVALID",
+    ROADMAP_REFS_EMPTY: "TASK_ROADMAP_REFS_EMPTY",
+    OUTSIDE_MARKER: "TASK_OUTSIDE_MARKER",
+    LINK_TARGET_MISSING: "TASK_LINK_TARGET_MISSING",
+    HOOK_FILE_MISSING: "TASK_HOOK_FILE_MISSING",
+    FILTER_EMPTY: "TASK_FILTER_EMPTY",
+    CONTEXT_HOOK_HEAD_MISSING: "TASK_CONTEXT_HOOK_HEAD_MISSING",
+    CONTEXT_HOOK_FOOTER_MISSING: "TASK_CONTEXT_HOOK_FOOTER_MISSING",
+};
+export const ROADMAP_LINT_CODES = {
+    IDS_EMPTY: "ROADMAP_IDS_EMPTY",
+    TASKS_EMPTY: "ROADMAP_TASKS_EMPTY",
+    TASK_REFS_EMPTY: "ROADMAP_TASK_REFS_EMPTY",
+    UNKNOWN_REFS: "ROADMAP_UNKNOWN_REFS",
+    ZERO_LINKED_TASKS: "ROADMAP_ZERO_LINKED_TASKS",
+    CONTEXT_RELATED_TASKS_EMPTY: "ROADMAP_CONTEXT_RELATED_TASKS_EMPTY",
+};
+export const PROJECT_LINT_CODES = {
+    TASKS_FILE_MISSING: "PROJECT_TASKS_FILE_MISSING",
+};

package/output/helpers/linter/index.js

@@ -0,0 +1,2 @@
+export * from './linter.js';
+export * from './codes.js';

package/output/helpers/linter/linter.js

@@ -0,0 +1,6 @@
+export function renderLintSuggestions(suggestions) {
+    return suggestions.map((item) => {
+        const suffix = item.fixHint ? ` ${item.fixHint}` : "";
+        return `- [${item.code}] ${item.message}${suffix}`;
+    });
+}

package/output/helpers/linter/linter.test.js

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { renderLintSuggestions } from "./linter.js";
+describe("renderLintSuggestions", () => {
+    it("renders lint lines with code and message", () => {
+        const lines = renderLintSuggestions([
+            { code: "TASK_001", message: "Example lint" },
+        ]);
+        expect(lines).toEqual(["- [TASK_001] Example lint"]);
+    });
+    it("appends fixHint when provided", () => {
+        const lines = renderLintSuggestions([
+            { code: "TASK_002", message: "Missing field.", fixHint: "Set owner." },
+        ]);
+        expect(lines).toEqual(["- [TASK_002] Missing field. Set owner."]);
+    });
+});

package/output/helpers/response/index.js

@@ -0,0 +1 @@
+export * from "./response.js";

package/output/helpers/response/response.js

@@ -0,0 +1,73 @@
+export function asText(markdown) {
+    return {
+        content: [{ type: "text", text: markdown }],
+    };
+}
+function withFallback(lines) {
+    return lines.length > 0 ? lines : ["- (none)"];
+}
+function shouldKeepRawLine(trimmed) {
+    if (trimmed.length === 0) {
+        return true;
+    }
+    if (trimmed.startsWith("#") || trimmed.startsWith(">") || trimmed.startsWith("```")) {
+        return true;
+    }
+    if (/^[-*+]\s/.test(trimmed)) {
+        return true;
+    }
+    if (/^\d+\.\s/.test(trimmed)) {
+        return true;
+    }
+    return false;
+}
+function normalizeLine(line) {
+    const trimmed = line.trim();
+    if (shouldKeepRawLine(trimmed)) {
+        return line;
+    }
+    return `- ${trimmed}`;
+}
+function normalizeLines(lines) {
+    return lines.map((line) => normalizeLine(line));
+}
+export function section(title, lines) {
+    return { title, lines: normalizeLines(lines) };
+}
+export function summarySection(lines) {
+    return section("Summary", lines);
+}
+export function evidenceSection(lines) {
+    return section("Evidence", lines);
+}
+export function guidanceSection(lines) {
+    return section("Agent Guidance", lines);
+}
+export function lintSection(lines) {
+    return section("Lint Suggestions", lines);
+}
+export function nextCallSection(nextCall) {
+    return section("Next Call", nextCall ? [nextCall] : []);
+}
+export function renderToolResponseMarkdown(payload) {
+    const body = payload.sections.flatMap((section) => [
+        `## ${section.title}`,
+        ...withFallback(section.lines),
+        "",
+    ]);
+    return [
+        `# ${payload.toolName}`,
+        "",
+        ...body,
+    ].join("\n").trimEnd();
+}
+export function renderErrorMarkdown(toolName, cause, nextSteps, retryExample) {
+    return renderToolResponseMarkdown({
+        toolName,
+        sections: [
+            section("Error", [`cause: ${cause}`]),
+            section("Next Step", nextSteps),
+            section("Retry Example", [retryExample ?? "(none)"]),
+        ],
+    });
+}

package/output/helpers/response/response.test.js

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { asText, nextCallSection, renderErrorMarkdown, renderToolResponseMarkdown, summarySection, } from "./response.js";
+describe("response helpers", () => {
+    it("wraps markdown text as MCP text content", () => {
+        const result = asText("# hello");
+        expect(result.content).toEqual([{ type: "text", text: "# hello" }]);
+    });
+    it("renders error markdown sections", () => {
+        const markdown = renderErrorMarkdown("taskContext", "bad id", ["retry"], "taskContext(...)");
+        expect(markdown).toContain("# taskContext");
+        expect(markdown).toContain("## Error");
+        expect(markdown).toContain("- cause: bad id");
+        expect(markdown).toContain("- retry");
+        expect(markdown).toContain("## Retry Example");
+    });
+    it("renders standard tool response sections with fallback", () => {
+        const markdown = renderToolResponseMarkdown({
+            toolName: "taskList",
+            sections: [
+                { title: "Summary", lines: ["- governanceDir: /tmp/.projitive"] },
+                { title: "Evidence", lines: [] },
+            ],
+        });
+        expect(markdown).toContain("# taskList");
+        expect(markdown).toContain("## Summary");
+        expect(markdown).toContain("## Evidence");
+        expect(markdown).toContain("- (none)");
+    });
+    it("auto-prefixes plain lines in section helpers", () => {
+        const markdown = renderToolResponseMarkdown({
+            toolName: "taskList",
+            sections: [
+                summarySection(["governanceDir: /tmp/.projitive"]),
+            ],
+        });
+        expect(markdown).toContain("- governanceDir: /tmp/.projitive");
+    });
+    it("nextCallSection accepts optional call and falls back when missing", () => {
+        const withCall = renderToolResponseMarkdown({
+            toolName: "taskList",
+            sections: [nextCallSection("taskContext(projectPath=\"/tmp\", taskId=\"TASK-0001\")")],
+        });
+        expect(withCall).toContain("- taskContext(projectPath=\"/tmp\", taskId=\"TASK-0001\")");
+        const withoutCall = renderToolResponseMarkdown({
+            toolName: "taskList",
+            sections: [nextCallSection(undefined)],
+        });
+        expect(withoutCall).toContain("- (none)");
+    });
+});

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 |",