@mandujs/mcp 0.38.12 → 0.39.0-beta.1

package/src/tx-lock.ts

@@ -1,73 +1,73 @@
-/**
- * Transaction Lock — prevents concurrent project mutations from multiple AI agents.
- *
- * In-process singleton. If no lock exists, destructive tools work as before (backward compatible).
- * When a lock is held, only the holder (matching lockId) may execute destructive operations.
- */
-
-export interface TxLock {
-  lockId: string;
-  sessionId: string;
-  acquiredAt: number;
-  timeoutMs: number;
-}
-
-const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
-
-let activeLock: TxLock | null = null;
-
-function isExpired(lock: TxLock): boolean {
-  return Date.now() - lock.acquiredAt > lock.timeoutMs;
-}
-
-export function acquireLock(
-  sessionId: string,
-  timeoutMs: number = DEFAULT_TIMEOUT_MS,
-): { success: boolean; lockId?: string; error?: string } {
-  if (activeLock) {
-    if (isExpired(activeLock)) {
-      activeLock = null; // auto-release stale lock
-    } else {
-      return {
-        success: false,
-        error: `Lock held by session "${activeLock.sessionId}" since ${new Date(activeLock.acquiredAt).toISOString()}`,
-      };
-    }
-  }
-  const lockId = crypto.randomUUID();
-  activeLock = { lockId, sessionId, acquiredAt: Date.now(), timeoutMs };
-  return { success: true, lockId };
-}
-
-export function releaseLock(lockId: string): boolean {
-  if (!activeLock || activeLock.lockId !== lockId) return false;
-  activeLock = null;
-  return true;
-}
-
-export function checkLock(): {
-  locked: boolean;
-  lockId?: string;
-  sessionId?: string;
-  acquiredAt?: number;
-} {
-  if (activeLock && isExpired(activeLock)) {
-    activeLock = null;
-  }
-  if (!activeLock) return { locked: false };
-  return {
-    locked: true,
-    lockId: activeLock.lockId,
-    sessionId: activeLock.sessionId,
-    acquiredAt: activeLock.acquiredAt,
-  };
-}
-
-export function requireLock(lockId?: string): { allowed: boolean; error?: string } {
-  if (!activeLock || isExpired(activeLock)) return { allowed: true };
-  if (lockId === activeLock.lockId) return { allowed: true };
-  return {
-    allowed: false,
-    error: `Project is locked by session "${activeLock.sessionId}". Provide a matching lockId or wait for expiry.`,
-  };
-}
+/**
+ * Transaction Lock — prevents concurrent project mutations from multiple AI agents.
+ *
+ * In-process singleton. If no lock exists, destructive tools work as before (backward compatible).
+ * When a lock is held, only the holder (matching lockId) may execute destructive operations.
+ */
+
+export interface TxLock {
+  lockId: string;
+  sessionId: string;
+  acquiredAt: number;
+  timeoutMs: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+
+let activeLock: TxLock | null = null;
+
+function isExpired(lock: TxLock): boolean {
+  return Date.now() - lock.acquiredAt > lock.timeoutMs;
+}
+
+export function acquireLock(
+  sessionId: string,
+  timeoutMs: number = DEFAULT_TIMEOUT_MS,
+): { success: boolean; lockId?: string; error?: string } {
+  if (activeLock) {
+    if (isExpired(activeLock)) {
+      activeLock = null; // auto-release stale lock
+    } else {
+      return {
+        success: false,
+        error: `Lock held by session "${activeLock.sessionId}" since ${new Date(activeLock.acquiredAt).toISOString()}`,
+      };
+    }
+  }
+  const lockId = crypto.randomUUID();
+  activeLock = { lockId, sessionId, acquiredAt: Date.now(), timeoutMs };
+  return { success: true, lockId };
+}
+
+export function releaseLock(lockId: string): boolean {
+  if (!activeLock || activeLock.lockId !== lockId) return false;
+  activeLock = null;
+  return true;
+}
+
+export function checkLock(): {
+  locked: boolean;
+  lockId?: string;
+  sessionId?: string;
+  acquiredAt?: number;
+} {
+  if (activeLock && isExpired(activeLock)) {
+    activeLock = null;
+  }
+  if (!activeLock) return { locked: false };
+  return {
+    locked: true,
+    lockId: activeLock.lockId,
+    sessionId: activeLock.sessionId,
+    acquiredAt: activeLock.acquiredAt,
+  };
+}
+
+export function requireLock(lockId?: string): { allowed: boolean; error?: string } {
+  if (!activeLock || isExpired(activeLock)) return { allowed: true };
+  if (lockId === activeLock.lockId) return { allowed: true };
+  return {
+    allowed: false,
+    error: `Project is locked by session "${activeLock.sessionId}". Provide a matching lockId or wait for expiry.`,
+  };
+}

package/src/utils/runtime-control.ts

@@ -1,52 +1,52 @@
-import path from "path";
-
-export interface RuntimeControlRecord {
-  mode: "dev" | "start";
-  port: number;
-  token: string;
-  baseUrl: string;
-  startedAt: string;
-}
-
-const RUNTIME_CONTROL_RELATIVE_PATH = path.join(".mandu", "runtime-control.json");
-
-export async function readRuntimeControl(rootDir: string): Promise<RuntimeControlRecord | null> {
-  try {
-    const file = Bun.file(path.join(rootDir, RUNTIME_CONTROL_RELATIVE_PATH));
-    if (!(await file.exists())) {
-      return null;
-    }
-    return await file.json() as RuntimeControlRecord;
-  } catch {
-    return null;
-  }
-}
-
-export async function requestRuntimeCache(
-  rootDir: string,
-  action: "stats" | "clear",
-  payload: Record<string, unknown> = {}
-): Promise<{ control: RuntimeControlRecord; response: Response; body: unknown } | null> {
-  const control = await readRuntimeControl(rootDir);
-  if (!control) {
-    return null;
-  }
-
-  const response = await fetch(`${control.baseUrl}/_mandu/cache`, {
-    method: action === "stats" ? "GET" : "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "x-mandu-control-token": control.token,
-    },
-    ...(action === "clear" ? { body: JSON.stringify(payload) } : {}),
-  });
-
-  let body: unknown = null;
-  try {
-    body = await response.json();
-  } catch {
-    // ignore invalid JSON
-  }
-
-  return { control, response, body };
-}
+import path from "path";
+
+export interface RuntimeControlRecord {
+  mode: "dev" | "start";
+  port: number;
+  token: string;
+  baseUrl: string;
+  startedAt: string;
+}
+
+const RUNTIME_CONTROL_RELATIVE_PATH = path.join(".mandu", "runtime-control.json");
+
+export async function readRuntimeControl(rootDir: string): Promise<RuntimeControlRecord | null> {
+  try {
+    const file = Bun.file(path.join(rootDir, RUNTIME_CONTROL_RELATIVE_PATH));
+    if (!(await file.exists())) {
+      return null;
+    }
+    return await file.json() as RuntimeControlRecord;
+  } catch {
+    return null;
+  }
+}
+
+export async function requestRuntimeCache(
+  rootDir: string,
+  action: "stats" | "clear",
+  payload: Record<string, unknown> = {}
+): Promise<{ control: RuntimeControlRecord; response: Response; body: unknown } | null> {
+  const control = await readRuntimeControl(rootDir);
+  if (!control) {
+    return null;
+  }
+
+  const response = await fetch(`${control.baseUrl}/_mandu/cache`, {
+    method: action === "stats" ? "GET" : "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-mandu-control-token": control.token,
+    },
+    ...(action === "clear" ? { body: JSON.stringify(payload) } : {}),
+  });
+
+  let body: unknown = null;
+  try {
+    body = await response.json();
+  } catch {
+    // ignore invalid JSON
+  }
+
+  return { control, response, body };
+}

package/src/utils/withWarnings.ts

@@ -7,7 +7,7 @@
  * MCP notification이 AI 에이전트에 전달되지 않는 문제를 해결.
  */
 
-import { getWatcher } from "@mandujs/core/watcher";
+import { getWatcher } from "@mandujs/core/compat/watcher/index";
 
 const MUTATION_TOOLS = new Set([
   "mandu_write_slot",

package/src/resources/skills/mandu-agent-workflow/SKILL.md

@@ -1,124 +0,0 @@
----
-name: mandu-agent-workflow
-description: |
-  Canonical Mandu agent workflow. Use first in Mandu projects before direct
-  source edits so Codex, Claude Code, Gemini CLI, and other agents follow the
-  same context -> plan -> apply -> verify -> repair loop.
-license: MIT
-metadata:
-  author: mandu
-  version: "1.0.0"
----
-
-# Mandu Agent Workflow
-
-Mandu is an agent-native fullstack framework. Agents should not begin by
-guessing file structure or calling low-level tools directly. Start with the
-official agent surface, then use domain tools only when the plan identifies a
-specific domain.
-
-## When to Use
-
-Use this skill for every Mandu project task that may inspect, create, modify, or
-verify application code, framework configuration, contracts, slots, islands, or
-deployment artifacts.
-
-## Canonical Workflow
-
-Always follow this loop:
-
-```text
-context -> plan -> apply -> verify -> repair
-```
-
-1. `context`: read the project map.
-2. `plan`: convert the user request into domains, files, risks, and checks.
-3. `apply`: prefer intent-level MCP/domain tools; direct edits must be grounded
-   in the plan.
-4. `verify`: run the single agent-facing verification report.
-5. `repair`: convert failures into next actions, then verify again.
-
-## Preferred MCP Tools
-
-Use these first when MCP is available:
-
-| Step | Tool | Purpose |
-|------|------|---------|
-| context | `mandu.agent.context` | Project map, routes, APIs, slots, contracts, guard, diagnostics. |
-| plan | `mandu.agent.plan` | Deterministic task plan with domains, files, tools, risks. |
-| apply | `mandu.agent.apply` | Ordered action preview from `.mandu/agent-plan.json`. |
-| verify | `mandu.agent.verify` | Unified post-change guard/diagnose/contract report. |
-| repair | `mandu.agent.repair` | Structured next actions from `.mandu/agent-verify.json`. |
-
-If MCP is unavailable, use the CLI equivalents:
-
-```bash
-mandu agent context --json
-mandu agent plan "<task>" --json --write
-mandu agent apply --from .mandu/agent-plan.json --json
-mandu agent verify --changed --json --write
-mandu agent repair --from .mandu/agent-verify.json --json
-```
-
-## Allowed File Edits
-
-Direct file edits are allowed only after `plan` identifies the relevant domain
-and the agent has inspected the local pattern. Prefer MCP/domain generation for:
-
-- pages, layouts, and API routes
-- contracts and OpenAPI-related files
-- slots and fillings
-- islands, partials, and hydration boundaries
-- deploy intent and provider artifacts
-
-Do not use destructive cleanup, cache removal, deploy execution, or broad
-refactors without an explicit plan and verification path.
-
-## Domain Skill Escalation
-
-Read the matching domain skill when `mandu.agent.plan` includes that domain:
-
-| Domain | Skill |
-|--------|-------|
-| route/api | `mandu-fs-routes` |
-| hydration/island/partial | `mandu-hydration` |
-| slot/filling | `mandu-slot` |
-| guard/import boundary | `mandu-guard` |
-| test/e2e/ATE | `mandu-testing` |
-| deploy | `mandu-deployment` |
-| security/auth/session | `mandu-security` |
-| styling/ui/design | `mandu-styling`, `mandu-ui`, `mandu-composition` |
-| performance | `mandu-performance` |
-
-Domain skills are addenda. They must not replace the canonical workflow.
-
-## Verification Command
-
-Every code-changing task should end with:
-
-```bash
-mandu agent verify --changed --json --write
-```
-
-Run additional commands listed in the plan or verify report, usually
-`bun run typecheck` and targeted `bun test` commands.
-
-## Repair Path
-
-When verify fails:
-
-```bash
-mandu agent repair --from .mandu/agent-verify.json --json
-```
-
-Apply only actions that are explicitly safe and scoped. After any repair, run
-`mandu agent verify --changed --json --write` again.
-
-## Common Failures
-
-- Skipping context and editing the wrong route or contract path.
-- Calling low-level Guard, Doctor, Fix, ATE, or deploy tools before a plan.
-- Treating a domain skill as the full workflow.
-- Ending a task after tests without writing or reading the agent verify report.
-- Applying broad file changes when `agent.apply` only produced a dry-run action
-  report.

package/src/resources/skills/mandu-agent-workflow/metadata.json

@@ -1,7 +0,0 @@
-{
-  "version": "1.0.0",
-  "organization": "Mandu Framework",
-  "date": "May 2026",
-  "abstract": "Canonical Mandu agent workflow for Codex, Claude Code, Gemini CLI, and other coding agents. Establishes context -> plan -> apply -> verify -> repair as the default loop and routes domain work through focused Mandu skills and MCP tools.",
-  "tags": ["agent", "workflow", "mcp", "skills", "mandu"]
-}

package/src/resources/skills/mandu-composition/SKILL.md

@@ -1,131 +0,0 @@
----
-name: mandu-composition
-description: |
-  React composition patterns for Mandu applications. Use when designing
-  Island components, managing shared state, or building reusable component
-  APIs. Triggers on compound components, context providers, boolean props,
-  or component architecture tasks.
-license: MIT
-metadata:
-  author: mandu
-  version: "1.0.0"
----
-
-# Mandu Composition
-
-Mandu 애플리케이션을 위한 React 컴포지션 패턴 가이드. Island 컴파운드 컴포넌트, 상태 관리 인터페이스, Provider 패턴, slot-client 분리를 다룹니다. Vercel의 Composition Patterns를 Mandu 컨텍스트로 변환하여 적용합니다.
-
-## Agent Workflow Contract
-
-This skill is a Domain addendum. It must not replace `mandu-agent-workflow`.
-Use it only after `mandu.agent.plan` selects composition, UI, hydration, slot, or component domains.
-
-Canonical workflow step: `plan -> apply -> verify`.
-
-Preferred MCP tools:
-
-| Step | Tools |
-|------|-------|
-| plan | `mandu.agent.plan`, `mandu.design.get`, `mandu.island.list` |
-| apply | `mandu.agent.apply` |
-| verify | `mandu.agent.verify`, `mandu.design.check`, `mandu.slot.validate` |
-| repair | `mandu.agent.repair` |
-
-Allowed file edits:
-
-- Island/client component files named in the plan
-- Provider/state modules scoped to the target feature
-- Slot-client boundaries only when the plan includes slot or hydration domains
-
-Verification command:
-
-```bash
-mandu agent verify --changed --json --write
-```
-
-Common failures:
-
-- Refactoring component APIs without checking island/client boundaries
-- Adding shared state providers broader than the planned feature
-- Mixing slot server logic into client composition files
-
-Repair path:
-
-```bash
-mandu agent repair --from .mandu/agent-verify.json --json
-```
-
-## When to Apply
-
-Reference these guidelines when:
-- Designing Island component architecture
-- Managing shared state between Islands
-- Building reusable component APIs
-- Refactoring components with boolean prop proliferation
-- Working with compound components or context providers
-
-## Rule Categories by Priority
-
-| Priority | Category | Impact | Prefix |
-|----------|----------|--------|--------|
-| 1 | Component Architecture | HIGH | `comp-arch-` |
-| 2 | State Management | HIGH | `comp-state-` |
-| 3 | Island Patterns | MEDIUM | `comp-island-` |
-| 4 | Implementation Patterns | MEDIUM | `comp-pattern-` |
-
-## Quick Reference
-
-### 1. Component Architecture (HIGH)
-
-- `comp-arch-avoid-boolean-props` - Use composition instead of boolean customization
-- `comp-arch-compound-components` - Structure Islands as compound components
-- `comp-arch-explicit-variants` - Create explicit variant components
-
-### 2. State Management (HIGH)
-
-- `comp-state-context-interface` - Define generic state/actions/meta interface
-- `comp-state-lift-state` - Move state into provider for sibling access
-- `comp-state-decouple-impl` - Provider is the only place knowing implementation
-
-### 3. Island Patterns (MEDIUM)
-
-- `comp-island-compound` - Compose Islands with shared context
-- `comp-island-event` - Communicate between Islands with useIslandEvent
-- `comp-island-slot-split` - Separate server logic (slot) from client (Island)
-
-### 4. Implementation Patterns (MEDIUM)
-
-- `comp-pattern-children` - Use children for composition over render props
-- `comp-pattern-provider-boundary` - Understand provider boundary vs visual nesting
-
-## Core Principle
-
-**Lift state, compose internals, make state dependency-injectable.**
-
-```
-┌─────────────────────────────────────────┐
-│  Provider (state + actions + meta)      │
-│  ┌───────────────────────────────────┐  │
-│  │  Composer.Frame                   │  │
-│  │  ┌─────────┐ ┌─────────────────┐  │  │
-│  │  │ Input   │ │ Footer          │  │  │
-│  │  └─────────┘ │ ┌─────┐ ┌─────┐ │  │  │
-│  │              │ │Emoji│ │Send │ │  │  │
-│  │              │ └─────┘ └─────┘ │  │  │
-│  │              └─────────────────┘  │  │
-│  └───────────────────────────────────┘  │
-│  ┌───────────────┐  ← Outside Frame     │
-│  │ Preview       │     but inside       │
-│  └───────────────┘     Provider!        │
-└─────────────────────────────────────────┘
-```
-
-## How to Use
-
-Read individual rule files for detailed explanations:
-
-```
-rules/comp-arch-compound-components.md
-rules/comp-state-context-interface.md
-rules/comp-island-event.md
-```

package/src/resources/skills/mandu-composition/metadata.json

@@ -1,13 +0,0 @@
-{
-  "version": "1.0.0",
-  "organization": "Mandu Framework",
-  "date": "February 2026",
-  "abstract": "Mandu 애플리케이션을 위한 React 컴포지션 패턴 가이드. Island 컴파운드 컴포넌트, state/actions/meta 인터페이스, Provider 패턴, useIslandEvent를 통한 Island 간 통신, slot-client 분리 패턴을 다룹니다. Vercel Composition Patterns 기반으로 Mandu 컨텍스트에 맞게 변환되었습니다.",
-  "references": [
-    "https://react.dev/learn/passing-data-deeply-with-context",
-    "https://react.dev/learn/scaling-up-with-reducer-and-context",
-    "https://www.patterns.dev/react/compound-pattern",
-    "https://kentcdodds.com/blog/compound-components-with-react-hooks"
-  ],
-  "tags": ["composition", "compound", "context", "state", "island", "mandu"]
-}

package/src/resources/skills/mandu-composition/rules/_sections.md

@@ -1,26 +0,0 @@
-# Sections
-
-This file defines all sections, their ordering, impact levels, and descriptions.
-The section ID (in parentheses) is the filename prefix used to group rules.
-
----
-
-## 1. Component Architecture (comp-arch)
-
-**Impact:** HIGH
-**Description:** Boolean props 대신 컴포지션 사용, 컴파운드 컴포넌트 구조화. 코드베이스가 확장됨에 따라 유지보수성에 큰 영향을 미칩니다.
-
-## 2. State Management (comp-state)
-
-**Impact:** HIGH
-**Description:** state/actions/meta 인터페이스 정의, Provider를 통한 의존성 주입. 같은 UI를 다양한 상태 구현과 함께 재사용할 수 있게 합니다.
-
-## 3. Island Patterns (comp-island)
-
-**Impact:** MEDIUM
-**Description:** Mandu Island 특화 패턴. 컴파운드 Island, Island 간 이벤트 통신, slot-client 분리를 다룹니다.
-
-## 4. Implementation Patterns (comp-pattern)
-
-**Impact:** MEDIUM
-**Description:** children 활용, Provider 경계 이해 등 구현 세부 사항. 올바른 패턴 적용으로 유연성을 확보합니다.

package/src/resources/skills/mandu-composition/rules/_template.md

@@ -1,77 +0,0 @@
-# Rule Template
-
-Use this template when creating new rules for mandu-composition.
-
----
-
-```markdown
----
-title: Rule Title Here
-impact: HIGH | MEDIUM | LOW
-impactDescription: 영향 설명 (예: "enables flexible composition")
-tags: composition, tag1, tag2
----
-
-## Rule Title Here
-
-**Impact: {LEVEL} ({impactDescription})**
-
-규칙의 목적과 아키텍처적 영향을 설명합니다.
-
-**Incorrect (문제가 되는 패턴):**
-
-\`\`\`tsx
-// ❌ Boolean props로 기능 추가
-function Composer({
-  showAttachments,
-  showFormatting,
-  showEmojis,
-  isCompact,
-  isReadOnly,
-}: Props) {
-  return (
-    <form>
-      {!isReadOnly && <Input />}
-      {showAttachments && <Attachments />}
-      {showFormatting && <Formatting />}
-      {showEmojis && <Emojis />}
-    </form>
-  );
-}
-```
-
-**Correct (컴포지션 패턴):**
-
-\`\`\`tsx
-// ✅ 컴포지션으로 유연하게 구성
-<Composer.Provider state={state} actions={actions}>
-  <Composer.Frame>
-    <Composer.Input />
-    <Composer.Footer>
-      <Composer.Emojis />
-      <Composer.Submit />
-    </Composer.Footer>
-  </Composer.Frame>
-</Composer.Provider>
-\`\`\`
-
-## Mandu Context
-
-Mandu Island에서 이 패턴을 적용하는 방법을 설명합니다.
-
-Reference: [관련 문서 링크](https://example.com)
-```
-
----
-
-## Naming Convention
-
-- 파일명: `comp-{category}-{rule-name}.md`
-- 예시: `comp-arch-compound-components.md`, `comp-state-context-interface.md`
-
-## Core Principle
-
-**Lift state, compose internals, make state dependency-injectable.**
-
-UI는 조합 가능한 조각들이고, 상태는 Provider가 주입합니다.
-Provider를 바꾸면 UI는 그대로 유지됩니다.