@mandujs/mcp 0.38.11 → 0.39.0-beta.1

package/src/resources/generated-skills/mandu-contract/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: mandu-contract
+description: Define and preserve typed Mandu API contracts.
+license: MPL-2.0
+---
+
+# Mandu Contracts
+
+Use after planning selects an API or contract change.
+
+- Keep request, response, method, and status schemas machine-readable.
+- Co-locate or link the contract using the surrounding project convention.
+- Change handler and contract together; do not weaken validation to silence a
+  mismatch.
+- Generated clients and OpenAPI artifacts are outputs, not direct-edit inputs.
+- Preserve existing consumer behavior unless the plan explicitly authorizes a
+  breaking change.
+
+Prefer `mandu.agent.apply` for a typed contract operation. Run targeted tests
+and finish with `mandu.agent.verify --changed --json --write`.

package/src/resources/generated-skills/mandu-fs-routes/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: mandu-fs-routes
+description: Author Mandu pages and APIs through the app directory convention.
+license: MPL-2.0
+---
+
+# Mandu FS Routes
+
+Use after `mandu.agent.plan` selects the route or API domain.
+
+- `app/page.tsx` maps to `/`.
+- `app/<segment>/page.tsx` maps to a page route.
+- `app/api/<segment>/route.ts` maps to an API route.
+- `[id]`, `[...slug]`, and `[[...slug]]` define dynamic segments.
+- Layouts use `layout.tsx`; never edit generated route manifests directly.
+
+Inspect the nearest existing route before writing. Prefer
+`mandu.agent.apply`; otherwise keep direct edits inside the planned `app/**`
+scope. Verify with `mandu.agent.verify --changed --json --write`.

package/src/resources/generated-skills/mandu-guard/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: mandu-guard
+description: Resolve Mandu architecture violations without weakening policy.
+license: MPL-2.0
+---
+
+# Mandu Guard
+
+Use when planning or verification reports an import, layer, location, or
+generated-artifact violation.
+
+- Fix the dependency direction or file ownership that caused the diagnostic.
+- Do not disable a rule or broaden an allowlist unless policy change is the
+  explicit task.
+- Read generated data through the runtime registry; never import or edit
+  `.mandu/generated` artifacts directly.
+- Keep fixes inside the plan scope and preserve user changes.
+
+Start with `mandu.agent.verify`, use `mandu.agent.repair` for structured next
+actions, and verify again after the repair.

package/src/resources/generated-skills/mandu-hydration/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: mandu-hydration
+description: Keep Mandu server rendering and client islands deterministic.
+license: MPL-2.0
+---
+
+# Mandu Hydration
+
+Use for islands, partials, client boundaries, or hydration diagnostics.
+
+- Server pages remain server-owned; move interactive state into an island.
+- Use explicit client-boundary metadata and serializable props.
+- Never import a generated client artifact directly.
+- Keep HTML, manifest, and client asset URLs pinned to one build generation.
+- Treat missing client assets or hydration samples as failures when the route
+  declares hydration.
+
+Run the targeted hydration tests requested by the plan, then
+`mandu.agent.verify --changed --json --write`.

package/src/resources/generated-skills/mandu-testing/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: mandu-testing
+description: Select and run evidence-bearing Bun tests for Mandu changes.
+license: MPL-2.0
+---
+
+# Mandu Testing
+
+Use after planning identifies the changed behavior or verification recommends
+a test.
+
+- Prefer the smallest test that executes the changed contract, then expand to
+  the affected package and Golden Path.
+- Use `bun test`; do not substitute npm or pnpm runners.
+- Test failure paths, scope preservation, and generated-output invariants.
+- Do not treat a dry run, fixture string, or missing measurement as successful
+  runtime evidence.
+- ATE and browser-healing experiments are Labs and not part of stable testing.
+
+Finish with `mandu.agent.verify --changed --json --write`.

package/src/resources/handlers.ts

@@ -1,8 +1,8 @@
 import type { Resource } from "@modelcontextprotocol/sdk/types.js";
 import { loadManifest } from "@mandujs/core";
-import { getTransactionStatus } from "@mandujs/core/change";
-import type { GeneratedMap } from "@mandujs/core/generator";
-import { getWatcher } from "@mandujs/core/watcher";
+import { getTransactionStatus } from "@mandujs/core/compat/change/index";
+import type { GeneratedMap } from "@mandujs/core/compat/generator/index";
+import { getWatcher } from "@mandujs/core/compat/watcher/index";
 import { getProjectPaths, readJsonFile } from "../utils/project.js";
 import {
   getGuide,

package/src/resources/skills/guides.ts

@@ -377,21 +377,21 @@ Island Hydration은 페이지의 일부분만 클라이언트에서 인터랙티
 | \`idle\` | 브라우저 유휴 시 | 비중요 기능 |
 | \`interaction\` | 사용자 상호작용 시 | 클릭해야 활성화 |
 
-## Inline client region 만들기
-
-### 1. 클라이언트 컴포넌트 작성
-
-\`\`\`tsx
-// app/counter/client.tsx
-
-"use client";
-
-import { useState } from "react";
-
-export function Counter({ initial = 0 }: { initial?: number }) {
-  const [count, setCount] = useState(initial);
-
-  return (
+## Inline client region 만들기
+
+### 1. 클라이언트 컴포넌트 작성
+
+\`\`\`tsx
+// app/counter/client.tsx
+
+"use client";
+
+import { useState } from "react";
+
+export function Counter({ initial = 0 }: { initial?: number }) {
+  const [count, setCount] = useState(initial);
+
+  return (
     <div>
       <p>Count: {count}</p>
       <button onClick={() => setCount(c => c - 1)}>-</button>
@@ -399,43 +399,43 @@ export function Counter({ initial = 0 }: { initial?: number }) {
     </div>
   );
 }
-\`\`\`
-
-### 2. 서버 페이지에서 partial로 사용
-
-\`\`\`tsx
-// app/counter/page.tsx
-
-import { partial } from "@mandujs/core/client";
-import { Counter } from "./client";
-
-const CounterPartial = partial({
-  component: Counter,
-  priority: "visible",
-});
-
-export default function CounterPage() {
-  return (
+\`\`\`
+
+### 2. 서버 페이지에서 partial로 사용
+
+\`\`\`tsx
+// app/counter/page.tsx
+
+import { partial } from "@mandujs/core/client";
+import { Counter } from "./client";
+
+const CounterPartial = partial({
+  component: Counter,
+  priority: "visible",
+});
+
+export default function CounterPage() {
+  return (
     <div>
       <h1>Counter Demo</h1>
       <p>이 텍스트는 정적 HTML입니다.</p>
-
-      {/* 이 부분만 hydration됩니다 */}
-      <CounterPartial.Render initial={10} />
-    </div>
-  );
-}
-\`\`\`
-
-## Mandu.island() API
-
-고급 page-level Island 패턴을 위한 API입니다. \`Mandu.island()\`는 단일
-정의 객체만 받습니다. \`island("visible", Component)\` 형태는 지원하지
-않으며, 서버 페이지 안에 inline으로 렌더링할 영역은 \`partial()\`을
-사용하세요.
-
-\`\`\`typescript
-// spec/slots/todos.client.ts
+
+      {/* 이 부분만 hydration됩니다 */}
+      <CounterPartial.Render initial={10} />
+    </div>
+  );
+}
+\`\`\`
+
+## Mandu.island() API
+
+고급 page-level Island 패턴을 위한 API입니다. \`Mandu.island()\`는 단일
+정의 객체만 받습니다. \`island("visible", Component)\` 형태는 지원하지
+않으며, 서버 페이지 안에 inline으로 렌더링할 영역은 \`partial()\`을
+사용하세요.
+
+\`\`\`typescript
+// spec/slots/todos.client.ts
 
 import { Mandu } from "@mandujs/core/client";
 import { useState, useCallback } from "react";

package/src/resources/skills/index.ts

@@ -1,12 +1,12 @@
-export { GUIDES, getGuide, listGuides, type GuideId } from "./guides.js";
-export { RECIPES, getRecipe, listRecipes, type RecipeId } from "./recipes.js";
-
-// Agent Skills pattern
-export {
-  listSkills,
-  getSkill,
-  listSkillRules,
-  getSkillRule,
-  type SkillMeta,
-  type RuleMeta,
-} from "./loader.js";
+export { GUIDES, getGuide, listGuides, type GuideId } from "./guides.js";
+export { RECIPES, getRecipe, listRecipes, type RecipeId } from "./recipes.js";
+
+// Agent Skills pattern
+export {
+  listSkills,
+  getSkill,
+  listSkillRules,
+  getSkillRule,
+  type SkillMeta,
+  type RuleMeta,
+} from "./loader.js";

package/src/resources/skills/loader.ts

@@ -5,7 +5,8 @@
 
 import { readdir, readFile } from "fs/promises";
 import { join, dirname } from "path";
-import { fileURLToPath } from "url";
+import { fileURLToPath } from "url";
+import { OFFICIAL_SKILLS, OFFICIAL_SKILL_IDS } from "../generated-skills/catalog.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -26,21 +27,7 @@ export interface RuleMeta {
   tags: string[];
 }
 
-// Available skills
-const SKILL_IDS = [
-  "mandu-agent-workflow",
-  "mandu-slot",
-  "mandu-fs-routes",
-  "mandu-hydration",
-  "mandu-guard",
-  "mandu-performance",
-  "mandu-composition",
-  "mandu-security",
-  "mandu-testing",
-  "mandu-deployment",
-  "mandu-styling",
-  "mandu-ui",
-];
+const SKILL_IDS: readonly string[] = OFFICIAL_SKILL_IDS;
 
 /**
  * Parse YAML frontmatter from markdown content
@@ -94,22 +81,8 @@ export function listSkills(): SkillMeta[] {
   });
 }
 
-function getSkillDescription(id: string): string {
-  const descriptions: Record<string, string> = {
-    "mandu-agent-workflow": "Canonical context -> plan -> apply -> verify -> repair workflow for Mandu agents",
-    "mandu-slot": "Business logic with Mandu.filling() API",
-    "mandu-fs-routes": "File-system based routing patterns",
-    "mandu-hydration": "Island hydration and client components",
-    "mandu-guard": "Architecture enforcement and layer dependencies",
-    "mandu-performance": "Performance optimization patterns for Mandu apps",
-    "mandu-composition": "React composition patterns for Islands and state",
-    "mandu-security": "Security best practices for authentication and protection",
-    "mandu-testing": "Testing patterns with Bun test and Playwright",
-    "mandu-deployment": "Production deployment with Render, Supabase, Docker, and CI/CD",
-    "mandu-styling": "CSS framework integration with Tailwind, Panda CSS, and theming",
-    "mandu-ui": "UI component library integration with shadcn/ui and accessibility",
-  };
-  return descriptions[id] || "";
+function getSkillDescription(id: string): string {
+  return OFFICIAL_SKILLS.find((skill) => skill.id === id)?.description ?? "";
 }
 
 /**
@@ -120,7 +93,7 @@ export async function getSkill(skillId: string): Promise<{ meta: SkillMeta; cont
     return null;
   }
 
-  const skillPath = join(__dirname, skillId, "SKILL.md");
+  const skillPath = join(__dirname, "..", "generated-skills", skillId, "SKILL.md");
 
   try {
     const content = await readFile(skillPath, "utf-8");
@@ -149,7 +122,7 @@ export async function listSkillRules(skillId: string): Promise<RuleMeta[]> {
     return [];
   }
 
-  const rulesPath = join(__dirname, skillId, "rules");
+  const rulesPath = join(__dirname, "..", "generated-skills", skillId, "rules");
 
   try {
     const files = await readdir(rulesPath);
@@ -194,7 +167,7 @@ export async function getSkillRule(
     return null;
   }
 
-  const rulePath = join(__dirname, skillId, "rules", `${ruleId}.md`);
+  const rulePath = join(__dirname, "..", "generated-skills", skillId, "rules", `${ruleId}.md`);
 
   try {
     const content = await readFile(rulePath, "utf-8");

package/src/resources/skills/recipes.ts

@@ -469,30 +469,30 @@ export default function Counter({ initial = 0, step = 1 }: CounterProps) {
 }
 \`\`\`
 
-## Step 2: 서버 페이지에서 partial로 사용
-
-\`\`\`tsx
-// app/counter/page.tsx
-
-import { partial } from "@mandujs/core/client";
-import Counter from "./client";
-
-const CounterPartial = partial({
-  component: Counter,
-  priority: "visible",
-});
-
-export default function CounterPage() {
-  return (
+## Step 2: 서버 페이지에서 partial로 사용
+
+\`\`\`tsx
+// app/counter/page.tsx
+
+import { partial } from "@mandujs/core/client";
+import Counter from "./client";
+
+const CounterPartial = partial({
+  component: Counter,
+  priority: "visible",
+});
+
+export default function CounterPage() {
+  return (
     <div style={{ padding: "20px" }}>
       <h1>Counter Demo</h1>
       <p>아래 카운터는 클라이언트에서 hydration됩니다.</p>
-
-      {/* Inline client region */}
-      <CounterPartial.Render initial={10} step={5} />
-
-      <p style={{ marginTop: "20px", color: "#666" }}>
-        이 텍스트는 정적 HTML입니다.
+
+      {/* Inline client region */}
+      <CounterPartial.Render initial={10} step={5} />
+
+      <p style={{ marginTop: "20px", color: "#666" }}>
+        이 텍스트는 정적 HTML입니다.
       </p>
     </div>
   );
@@ -624,13 +624,13 @@ export default function UserList() {
 
 ## Mandu.island() API (고급)
 
-서버 데이터와 클라이언트 상태를 분리하는 page-level Island가 필요하면
-\`Mandu.island({ setup, render })\`를 사용합니다. \`island("visible",
-Component)\`는 지원하지 않습니다. 서버 페이지 안에 inline으로 렌더링할
-영역은 \`partial()\`을 사용하세요.
-
-\`\`\`typescript
-// spec/slots/todos.client.ts
+서버 데이터와 클라이언트 상태를 분리하는 page-level Island가 필요하면
+\`Mandu.island({ setup, render })\`를 사용합니다. \`island("visible",
+Component)\`는 지원하지 않습니다. 서버 페이지 안에 inline으로 렌더링할
+영역은 \`partial()\`을 사용하세요.
+
+\`\`\`typescript
+// spec/slots/todos.client.ts
 
 import { Mandu } from "@mandujs/core/client";
 import { useState } from "react";

package/src/server.ts

@@ -22,7 +22,7 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 
 import { loadManduConfig, type ManduConfig } from "@mandujs/core";
-import { startWatcher } from "@mandujs/core/watcher";
+import { startWatcher } from "@mandujs/core/compat/watcher/index";
 
 // DNA-001: 플러그인 기반 도구 레지스트리
 import { mcpToolRegistry } from "./registry/mcp-tool-registry.js";