@mandujs/core 0.54.9 → 0.54.11

package/src/agent/sync.ts

@@ -1,200 +1,200 @@
-import fs from "fs/promises";
-import path from "path";
-import type {
-  AgentSuggestedCommand,
-  AgentSyncFile,
-  AgentSyncReport,
-  AgentSyncTarget,
-  BuildAgentSyncOptions,
-} from "./types";
-
-const SYNC_ROOT = path.join(".mandu", "agent-sync");
-const TARGETS = ["codex", "claude", "gemini"] as const;
-type ConcreteTarget = (typeof TARGETS)[number];
-
-function toPosix(value: string): string {
-  return value.split(path.sep).join("/");
-}
-
-function isTarget(value: string | undefined): value is AgentSyncTarget {
-  return value === "codex" || value === "claude" || value === "gemini" || value === "all";
-}
-
-function concreteTargets(target: AgentSyncTarget): ConcreteTarget[] {
-  return target === "all" ? [...TARGETS] : [target];
-}
-
-function targetFile(target: ConcreteTarget): string {
-  if (target === "codex") return path.join(SYNC_ROOT, "codex", "AGENTS.md");
-  if (target === "claude") return path.join(SYNC_ROOT, "claude", "CLAUDE.md");
-  return path.join(SYNC_ROOT, "gemini", "GEMINI.md");
-}
-
-function renderInstructions(target: ConcreteTarget): string {
-  const title =
-    target === "codex"
-      ? "Codex"
-      : target === "claude"
-        ? "Claude Code"
-        : "Gemini CLI";
-  return [
-    `# Mandu Agent Workflow for ${title}`,
-    "",
-    "Mandu is an agent-native fullstack framework. Use the official agent surface before direct source edits.",
-    "",
-    "## Canonical Loop",
-    "",
-    "```text",
-    "context -> plan -> apply -> verify -> repair",
-    "```",
-    "",
-    "## Required First Choices",
-    "",
-    "1. Start with `mandu.agent.context` or `mandu agent context --json`.",
-    "2. Create a plan with `mandu.agent.plan` or `mandu agent plan \"<task>\" --json --write`.",
-    "3. Prefer `mandu.agent.apply` and domain MCP tools before direct file edits.",
-    "4. End code-changing work with `mandu.agent.verify` or `mandu agent verify --changed --json --write`.",
-    "5. If verification fails, run `mandu.agent.repair` or `mandu agent repair --from .mandu/agent-verify.json --json`, then verify again.",
-    "",
-    "## MCP Profile",
-    "",
-    "Use the reduced default profile:",
-    "",
-    "```bash",
-    "MANDU_MCP_PROFILE=agent-core",
-    "```",
-    "",
-    "Escalate to `agent-full` only when the plan selects route, API, slot, hydration, contract, guard, testing, or lint domains. Use `internal` only for framework maintenance.",
-    "",
-    "## Domain Skill Escalation",
-    "",
-    "- 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`",
-    "",
-    "Domain skills are addenda. They do not replace the canonical loop.",
-    "",
-  ].join("\n");
-}
-
-function renderClaudeSkill(): string {
-  return [
-    "---",
-    "name: mandu-agent-workflow",
-    "description: Canonical context -> plan -> apply -> verify -> repair workflow for Mandu projects.",
-    "---",
-    "",
-    "# Mandu Agent Workflow",
-    "",
-    "Use this skill first in Mandu projects. Follow `context -> plan -> apply -> verify -> repair`.",
-    "",
-    "Preferred tools: `mandu.agent.context`, `mandu.agent.plan`, `mandu.agent.apply`, `mandu.agent.verify`, `mandu.agent.repair`.",
-    "",
-    "CLI fallback:",
-    "",
-    "```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",
-    "```",
-    "",
-  ].join("\n");
-}
-
-function syncEntries(target: ConcreteTarget): Array<{ target: ConcreteTarget; relPath: string; content: string }> {
-  const entries = [
-    {
-      target,
-      relPath: targetFile(target),
-      content: renderInstructions(target),
-    },
-  ];
-  if (target === "claude") {
-    entries.push({
-      target,
-      relPath: path.join(SYNC_ROOT, "claude", "skills", "mandu-agent-workflow", "SKILL.md"),
-      content: renderClaudeSkill(),
-    });
-  }
-  return entries;
-}
-
-async function writeEntry(
-  rootDir: string,
-  entry: { target: ConcreteTarget; relPath: string; content: string },
-  dryRun: boolean,
-): Promise<AgentSyncFile> {
-  const absPath = path.join(rootDir, entry.relPath);
-  let action: AgentSyncFile["action"] = "created";
-  try {
-    const existing = await fs.readFile(absPath, "utf8");
-    action = existing === entry.content ? "unchanged" : "updated";
-  } catch {
-    action = "created";
-  }
-
-  if (dryRun) {
-    action = "planned";
-  } else if (action !== "unchanged") {
-    await fs.mkdir(path.dirname(absPath), { recursive: true });
-    await fs.writeFile(absPath, entry.content, "utf8");
-  }
-
-  return {
-    target: entry.target,
-    path: toPosix(entry.relPath),
-    action,
-    bytes: Buffer.byteLength(entry.content, "utf8"),
-  };
-}
-
-function nextCommands(): AgentSuggestedCommand[] {
-  return [
-    {
-      command: "mandu agent context --json",
-      reason: "Confirm the generated workflow matches the current project state.",
-      required: true,
-    },
-    {
-      command: "MANDU_MCP_PROFILE=agent-core",
-      reason: "Use the reduced default MCP exposure for coding agents.",
-      required: true,
-    },
-  ];
-}
-
-export async function buildAgentSyncReport(
-  rootDir: string = process.cwd(),
-  options: BuildAgentSyncOptions = {},
-): Promise<AgentSyncReport> {
-  const target = isTarget(options.target) ? options.target : "all";
-  const dryRun = options.dryRun === true;
-  const root = path.resolve(rootDir);
-  const files: AgentSyncFile[] = [];
-
-  for (const concrete of concreteTargets(target)) {
-    for (const entry of syncEntries(concrete)) {
-      files.push(await writeEntry(root, entry, dryRun));
-    }
-  }
-
-  return {
-    schemaVersion: 1,
-    framework: "mandu",
-    generatedAt: new Date().toISOString(),
-    ok: true,
-    target,
-    profile: "agent-core",
-    workflow: ["context", "plan", "apply", "verify", "repair"],
-    files,
-    warnings: dryRun ? ["Dry-run only. No files were written."] : [],
-    nextCommands: nextCommands(),
-  };
-}
+import fs from "fs/promises";
+import path from "path";
+import type {
+  AgentSuggestedCommand,
+  AgentSyncFile,
+  AgentSyncReport,
+  AgentSyncTarget,
+  BuildAgentSyncOptions,
+} from "./types";
+
+const SYNC_ROOT = path.join(".mandu", "agent-sync");
+const TARGETS = ["codex", "claude", "gemini"] as const;
+type ConcreteTarget = (typeof TARGETS)[number];
+
+function toPosix(value: string): string {
+  return value.split(path.sep).join("/");
+}
+
+function isTarget(value: string | undefined): value is AgentSyncTarget {
+  return value === "codex" || value === "claude" || value === "gemini" || value === "all";
+}
+
+function concreteTargets(target: AgentSyncTarget): ConcreteTarget[] {
+  return target === "all" ? [...TARGETS] : [target];
+}
+
+function targetFile(target: ConcreteTarget): string {
+  if (target === "codex") return path.join(SYNC_ROOT, "codex", "AGENTS.md");
+  if (target === "claude") return path.join(SYNC_ROOT, "claude", "CLAUDE.md");
+  return path.join(SYNC_ROOT, "gemini", "GEMINI.md");
+}
+
+function renderInstructions(target: ConcreteTarget): string {
+  const title =
+    target === "codex"
+      ? "Codex"
+      : target === "claude"
+        ? "Claude Code"
+        : "Gemini CLI";
+  return [
+    `# Mandu Agent Workflow for ${title}`,
+    "",
+    "Mandu is an agent-native fullstack framework. Use the official agent surface before direct source edits.",
+    "",
+    "## Canonical Loop",
+    "",
+    "```text",
+    "context -> plan -> apply -> verify -> repair",
+    "```",
+    "",
+    "## Required First Choices",
+    "",
+    "1. Start with `mandu.agent.context` or `mandu agent context --json`.",
+    "2. Create a plan with `mandu.agent.plan` or `mandu agent plan \"<task>\" --json --write`.",
+    "3. Prefer `mandu.agent.apply` and domain MCP tools before direct file edits.",
+    "4. End code-changing work with `mandu.agent.verify` or `mandu agent verify --changed --json --write`.",
+    "5. If verification fails, run `mandu.agent.repair` or `mandu agent repair --from .mandu/agent-verify.json --json`, then verify again.",
+    "",
+    "## MCP Profile",
+    "",
+    "Use the reduced default profile:",
+    "",
+    "```bash",
+    "MANDU_MCP_PROFILE=agent-core",
+    "```",
+    "",
+    "Escalate to `agent-full` only when the plan selects route, API, slot, hydration, contract, guard, testing, or lint domains. Use `internal` only for framework maintenance.",
+    "",
+    "## Domain Skill Escalation",
+    "",
+    "- 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`",
+    "",
+    "Domain skills are addenda. They do not replace the canonical loop.",
+    "",
+  ].join("\n");
+}
+
+function renderClaudeSkill(): string {
+  return [
+    "---",
+    "name: mandu-agent-workflow",
+    "description: Canonical context -> plan -> apply -> verify -> repair workflow for Mandu projects.",
+    "---",
+    "",
+    "# Mandu Agent Workflow",
+    "",
+    "Use this skill first in Mandu projects. Follow `context -> plan -> apply -> verify -> repair`.",
+    "",
+    "Preferred tools: `mandu.agent.context`, `mandu.agent.plan`, `mandu.agent.apply`, `mandu.agent.verify`, `mandu.agent.repair`.",
+    "",
+    "CLI fallback:",
+    "",
+    "```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",
+    "```",
+    "",
+  ].join("\n");
+}
+
+function syncEntries(target: ConcreteTarget): Array<{ target: ConcreteTarget; relPath: string; content: string }> {
+  const entries = [
+    {
+      target,
+      relPath: targetFile(target),
+      content: renderInstructions(target),
+    },
+  ];
+  if (target === "claude") {
+    entries.push({
+      target,
+      relPath: path.join(SYNC_ROOT, "claude", "skills", "mandu-agent-workflow", "SKILL.md"),
+      content: renderClaudeSkill(),
+    });
+  }
+  return entries;
+}
+
+async function writeEntry(
+  rootDir: string,
+  entry: { target: ConcreteTarget; relPath: string; content: string },
+  dryRun: boolean,
+): Promise<AgentSyncFile> {
+  const absPath = path.join(rootDir, entry.relPath);
+  let action: AgentSyncFile["action"] = "created";
+  try {
+    const existing = await fs.readFile(absPath, "utf8");
+    action = existing === entry.content ? "unchanged" : "updated";
+  } catch {
+    action = "created";
+  }
+
+  if (dryRun) {
+    action = "planned";
+  } else if (action !== "unchanged") {
+    await fs.mkdir(path.dirname(absPath), { recursive: true });
+    await fs.writeFile(absPath, entry.content, "utf8");
+  }
+
+  return {
+    target: entry.target,
+    path: toPosix(entry.relPath),
+    action,
+    bytes: Buffer.byteLength(entry.content, "utf8"),
+  };
+}
+
+function nextCommands(): AgentSuggestedCommand[] {
+  return [
+    {
+      command: "mandu agent context --json",
+      reason: "Confirm the generated workflow matches the current project state.",
+      required: true,
+    },
+    {
+      command: "MANDU_MCP_PROFILE=agent-core",
+      reason: "Use the reduced default MCP exposure for coding agents.",
+      required: true,
+    },
+  ];
+}
+
+export async function buildAgentSyncReport(
+  rootDir: string = process.cwd(),
+  options: BuildAgentSyncOptions = {},
+): Promise<AgentSyncReport> {
+  const target = isTarget(options.target) ? options.target : "all";
+  const dryRun = options.dryRun === true;
+  const root = path.resolve(rootDir);
+  const files: AgentSyncFile[] = [];
+
+  for (const concrete of concreteTargets(target)) {
+    for (const entry of syncEntries(concrete)) {
+      files.push(await writeEntry(root, entry, dryRun));
+    }
+  }
+
+  return {
+    schemaVersion: 1,
+    framework: "mandu",
+    generatedAt: new Date().toISOString(),
+    ok: true,
+    target,
+    profile: "agent-core",
+    workflow: ["context", "plan", "apply", "verify", "repair"],
+    files,
+    warnings: dryRun ? ["Dry-run only. No files were written."] : [],
+    nextCommands: nextCommands(),
+  };
+}

package/src/brain/doctor/analyzer.ts

@@ -206,13 +206,13 @@ export function generateTemplatePatches(
             "Do NOT import or re-export the island in page.tsx — island() returns " +
             "a config object, not a React component. Use data-island attributes instead.",
           type: "modify",
-          content:
-            `// Example: app/my-feature.island.tsx\n` +
-            `import { wrapComponent } from "@mandujs/core/client";\n\n` +
-            `export default wrapComponent(MyComponent);\n\n` +
-            `// In page.tsx, reference via: <div data-island="my-feature">...</div>`,
-          confidence: 0.9,
-        });
+          content:
+            `// Example: app/my-feature.island.tsx\n` +
+            `import { wrapComponent } from "@mandujs/core/client";\n\n` +
+            `export default wrapComponent(MyComponent);\n\n` +
+            `// In page.tsx, reference via: <div data-island="my-feature">...</div>`,
+          confidence: 0.9,
+        });
         break;
 
       default:

package/src/bundler/__tests__/build-runner.ts

@@ -54,68 +54,87 @@
 import { buildClientBundles } from "../build";
 import type { RoutesManifest } from "../../spec/schema";
 
-const rootDir = process.argv[2];
-if (!rootDir) {
-  console.error("usage: build-runner.ts <rootDir>");
-  process.exit(2);
-}
-const mode = process.argv[3] ?? "default";
-
-const manifest: RoutesManifest = mode === "server-page-client-module"
-  ? {
-      version: 1,
-      routes: [
-        {
-          id: "index",
-          kind: "page",
-          pattern: "/",
-          module: "app/page.tsx",
-          componentModule: "app/page.tsx",
-          clientModule: "app/page.tsx",
-          hydration: {
-            strategy: "island",
-            priority: "visible",
-            preload: false,
-          },
-        },
-      ],
-    }
-  : mode === "hydration-no-client-module"
-    ? {
-        version: 1,
-        routes: [
-          {
-            id: "login",
-            kind: "page",
-            pattern: "/login",
-            module: "app/login/page.tsx",
-            componentModule: "app/login/page.tsx",
-            hydration: {
-              strategy: "full",
-              priority: "immediate",
-              preload: false,
-            },
-          },
-        ],
-      }
-    : {
-        version: 1,
-        routes: [
-          {
-            id: "demo",
-            kind: "page",
-            pattern: "/",
-            module: "app/page.tsx",
-            componentModule: "app/page.tsx",
-            clientModule: "app/demo.client.tsx",
-            hydration: {
-              strategy: "island",
-              priority: "visible",
-              preload: false,
-            },
-          },
-        ],
-      };
+const rootDir = process.argv[2];
+if (!rootDir) {
+  console.error("usage: build-runner.ts <rootDir>");
+  process.exit(2);
+}
+const mode = process.argv[3] ?? "default";
+
+const manifest: RoutesManifest = mode === "server-page-client-module"
+  ? {
+      version: 1,
+      routes: [
+        {
+          id: "index",
+          kind: "page",
+          pattern: "/",
+          module: "app/page.tsx",
+          componentModule: "app/page.tsx",
+          clientModule: "app/page.tsx",
+          hydration: {
+            strategy: "island",
+            priority: "visible",
+            preload: false,
+          },
+        },
+      ],
+    }
+  : mode === "server-page-route-client-import"
+    ? {
+        version: 1,
+        routes: [
+          {
+            id: "login",
+            kind: "page",
+            pattern: "/login",
+            module: "app/login/page.tsx",
+            componentModule: "app/login/page.tsx",
+            clientModule: "app/login/page.tsx",
+            hydration: {
+              strategy: "island",
+              priority: "visible",
+              preload: false,
+            },
+          },
+        ],
+      }
+  : mode === "hydration-no-client-module"
+    ? {
+        version: 1,
+        routes: [
+          {
+            id: "login",
+            kind: "page",
+            pattern: "/login",
+            module: "app/login/page.tsx",
+            componentModule: "app/login/page.tsx",
+            hydration: {
+              strategy: "full",
+              priority: "immediate",
+              preload: false,
+            },
+          },
+        ],
+      }
+    : {
+        version: 1,
+        routes: [
+          {
+            id: "demo",
+            kind: "page",
+            pattern: "/",
+            module: "app/page.tsx",
+            componentModule: "app/page.tsx",
+            clientModule: "app/demo.client.tsx",
+            hydration: {
+              strategy: "island",
+              priority: "visible",
+              preload: false,
+            },
+          },
+        ],
+      };
 
 try {
   const result = await buildClientBundles(manifest, rootDir, {