@mandujs/core 0.54.11 → 0.54.13

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/agent/types.ts

@@ -159,12 +159,20 @@ export interface AgentSuggestedCommand {
   required: boolean;
 }
 
+export interface AgentChangedFileReason {
+  file: string;
+  reasons: string[];
+  recommendedChecks: string[];
+  internalApi: boolean;
+}
+
 export interface AgentVerifyReport {
   schemaVersion: 1;
   framework: "mandu";
   generatedAt: string;
   project: AgentProjectSummary;
   changedFiles: string[];
+  changedFileReasons: AgentChangedFileReason[];
   gitAvailable: boolean;
   notes: string[];
   ok: boolean;

package/src/agent/verify.ts

@@ -8,6 +8,7 @@ import {
   buildAgentContext,
 } from "./context";
 import type {
+  AgentChangedFileReason,
   AgentDiagnostic,
   AgentDiagnosticSeverity,
   AgentSuggestedCommand,
@@ -208,7 +209,11 @@ function matchesChanged(
   return candidates.some((file) => changed.has(file));
 }
 
-function commandSuggestions(changedFiles: string[], diagnostics: AgentDiagnostic[]): AgentSuggestedCommand[] {
+function commandSuggestions(
+  changedFiles: string[],
+  diagnostics: AgentDiagnostic[],
+  changedFileReasons: AgentChangedFileReason[] = [],
+): AgentSuggestedCommand[] {
   const files = changedFiles.map(normalizePath).filter((value): value is string => Boolean(value));
   const out: AgentSuggestedCommand[] = [];
   const add = (command: string, reason: string, required: boolean) => {
@@ -243,6 +248,9 @@ function commandSuggestions(changedFiles: string[], diagnostics: AgentDiagnostic
   if (files.some((file) => file.includes("package.json") || file === "bun.lock")) {
     add("bun run check:publish", "Package metadata or lockfile changed.", true);
   }
+  if (changedFileReasons.some((entry) => entry.internalApi)) {
+    add("bun run check:public-api && bun run check:target-boundaries", "Internal framework boundaries changed.", true);
+  }
   if (diagnostics.some((d) => d.severity === "error" || d.severity === "fatal")) {
     add("mandu agent repair --from .mandu/agent-verify.json", "Verification produced repairable diagnostics.", false);
   }
@@ -250,6 +258,89 @@ function commandSuggestions(changedFiles: string[], diagnostics: AgentDiagnostic
   return out;
 }
 
+function isInternalApiEdit(file: string): boolean {
+  return [
+    "packages/core/src/runtime/",
+    "packages/core/src/bundler/",
+    "packages/core/src/server/",
+    "packages/core/src/guard/",
+    "packages/core/src/spec/",
+    "packages/core/src/router/",
+    "packages/core/src/internal/",
+  ].some((prefix) => file.startsWith(prefix));
+}
+
+function changedFileReason(file: string): AgentChangedFileReason {
+  const normalized = normalizePath(file) ?? file;
+  const reasons: string[] = [];
+  const recommendedChecks: string[] = [];
+
+  if (/\.(ts|tsx|js|jsx)$/.test(normalized)) {
+    reasons.push("Source code changed.");
+    recommendedChecks.push("bun run typecheck");
+  }
+  if (/\.test\.(ts|tsx|js|jsx)$/.test(normalized)) {
+    reasons.push("Test code changed.");
+    recommendedChecks.push(`bun test ${normalized}`);
+  }
+  if (normalized.startsWith("packages/cli/")) {
+    reasons.push("CLI behavior or documentation changed.");
+    recommendedChecks.push("bun test packages/cli/src");
+  }
+  if (normalized.startsWith("packages/mcp/")) {
+    reasons.push("MCP tool surface changed.");
+    recommendedChecks.push("bun test packages/mcp/tests");
+  }
+  if (normalized.startsWith("docs/") || normalized.endsWith("README.md") || normalized.endsWith("README.ko.md")) {
+    reasons.push("User-facing documentation changed.");
+    recommendedChecks.push("bun run check:docs-drift");
+  }
+  if (normalized === "package.json" || normalized === "bun.lock" || normalized.endsWith("/package.json")) {
+    reasons.push("Package metadata or dependency graph changed.");
+    recommendedChecks.push("bun run check:publish");
+  }
+
+  const internalApi = isInternalApiEdit(normalized);
+  if (internalApi) {
+    reasons.push("Framework internal API changed.");
+    recommendedChecks.push("bun run check:public-api && bun run check:target-boundaries");
+  }
+
+  return {
+    file: normalized,
+    reasons: reasons.length > 0 ? reasons : ["Changed file requires standard verification."],
+    recommendedChecks: [...new Set(recommendedChecks)],
+    internalApi,
+  };
+}
+
+function buildChangedFileReasons(changedFiles: string[]): AgentChangedFileReason[] {
+  return changedFiles
+    .map(normalizePath)
+    .filter((file): file is string => Boolean(file))
+    .map(changedFileReason);
+}
+
+function internalApiDiagnostics(changedFileReasons: AgentChangedFileReason[]): AgentDiagnostic[] {
+  return changedFileReasons
+    .filter((entry) => entry.internalApi)
+    .map((entry) => ({
+      code: "MANDU_VERIFY_INTERNAL_API_EDIT",
+      severity: "warning" as const,
+      title: "Internal framework API changed",
+      file: entry.file,
+      cause: "This file is part of Mandu's internal runtime/bundler/guard surface and can affect public behavior indirectly.",
+      suggestedFix: {
+        type: "run_command" as const,
+        command: "bun run check:public-api && bun run check:target-boundaries",
+        description: "Verify public API classification and target-safe import boundaries.",
+      },
+      docs: "docs/architect/public-api-boundary.md",
+      repairable: false,
+      source: "agent.verify",
+    }));
+}
+
 function check(
   id: string,
   label: string,
@@ -284,6 +375,7 @@ export async function buildAgentVerifyReport(
   const root = path.resolve(rootDir);
   const changed = await collectChangedFiles(root, options);
   const changedSet = new Set(changed.files.map(normalizePath).filter((value): value is string => Boolean(value)));
+  const changedFileReasons = buildChangedFileReasons(changed.files);
   const context = await buildAgentContext(root, {
     includeDiagnose: false,
     includeGit: false,
@@ -291,6 +383,11 @@ export async function buildAgentVerifyReport(
   const notes = [...changed.notes];
   const checks: AgentVerifyCheck[] = [];
   const diagnostics: AgentDiagnostic[] = [];
+  const internalDiagnostics = internalApiDiagnostics(changedFileReasons);
+  diagnostics.push(...internalDiagnostics);
+  checks.push(check("internal-api", "Internal API boundary", internalDiagnostics, {
+    changedFiles: changedFileReasons.filter((entry) => entry.internalApi).length,
+  }));
 
   if (options.includeDiagnose !== false) {
     try {
@@ -384,12 +481,13 @@ export async function buildAgentVerifyReport(
     generatedAt: new Date().toISOString(),
     project: context.project,
     changedFiles: changed.files,
+    changedFileReasons,
     gitAvailable: changed.gitAvailable,
     notes,
     ok,
     checks,
     diagnostics,
-    suggestedCommands: commandSuggestions(changed.files, diagnostics),
+    suggestedCommands: commandSuggestions(changed.files, diagnostics, changedFileReasons),
     nextRepairInput: AGENT_VERIFY_RELATIVE_PATH,
   };
 }

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

@@ -80,10 +80,11 @@ const manifest: RoutesManifest = mode === "server-page-client-module"
         },
       ],
     }
-  : mode === "server-page-route-client-import"
-    ? {
-        version: 1,
-        routes: [
+  : mode === "server-page-route-client-import"
+    || mode === "server-page-route-named-client-import"
+    ? {
+        version: 1,
+        routes: [
           {
             id: "login",
             kind: "page",