@mandujs/core 0.54.2 → 0.54.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.54.2",
+  "version": "0.54.4",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",
@@ -8,6 +8,7 @@
   "exports": {
     ".": "./src/index.ts",
     "./a11y": "./src/a11y/index.ts",
+    "./agent": "./src/agent/index.ts",
     "./auth": "./src/auth/index.ts",
     "./auth/login": "./src/auth/login.ts",
     "./auth/password": "./src/auth/password.ts",
@@ -110,9 +111,11 @@
     "./components/Image": "./src/components/Image.tsx"
   },
   "files": [
-    "src/**/*"
+    "src/**/*",
+    "scripts/postinstall-lock.ts"
   ],
   "scripts": {
+    "postinstall": "bun ./scripts/postinstall-lock.ts",
     "test": "bun test tests/streaming-ssr && bun test tests/hydration tests/typing src",
     "test:hydration": "bun test tests/hydration",
     "test:streaming": "bun test tests/streaming-ssr",

package/scripts/postinstall-lock.ts

@@ -0,0 +1,153 @@
+/**
+ * Refresh an existing Guard lock after package-manager updates.
+ *
+ * Lifecycle scripts run from inside the installed package, so projectRoot
+ * defaults to INIT_CWD when Bun provides it. This helper is intentionally
+ * best-effort: installs must not fail because a project has a stale, invalid,
+ * or temporarily unreadable Mandu config.
+ */
+
+import path from "node:path";
+import {
+  validateConfig,
+  type ValidatedManduConfig,
+} from "../src/config/validate.js";
+import { CONFIG_FILES } from "../src/config/mandu.js";
+import {
+  generateLockfile,
+  readLockfile,
+  readMcpConfig,
+  writeLockfile,
+  LOCKFILE_PATH,
+} from "../src/lockfile/index.js";
+
+export type PostinstallLockAction =
+  | "updated"
+  | "skipped-disabled"
+  | "skipped-no-project-config"
+  | "skipped-no-lockfile"
+  | "skipped-invalid-lockfile"
+  | "skipped-invalid-config"
+  | "skipped-invalid-mcp-config"
+  | "skipped-write-failed";
+
+export interface PostinstallLockResult {
+  action: PostinstallLockAction;
+  projectRoot: string;
+  hash?: string;
+  error?: string;
+}
+
+export interface PostinstallLockOptions {
+  projectRoot?: string;
+  env?: NodeJS.ProcessEnv;
+  verbose?: boolean;
+  log?: (message: string) => void;
+  warn?: (message: string) => void;
+}
+
+export async function refreshGuardLockAfterInstall(
+  options: PostinstallLockOptions = {},
+): Promise<PostinstallLockResult> {
+  const env = options.env ?? process.env;
+  const projectRoot = path.resolve(
+    options.projectRoot ?? env.INIT_CWD ?? process.cwd(),
+  );
+  const verbose = options.verbose ?? env.MANDU_POSTINSTALL_VERBOSE === "1";
+  const log = options.log ?? console.log;
+  const warn = options.warn ?? console.warn;
+
+  const report = (result: PostinstallLockResult): PostinstallLockResult => {
+    if (verbose) {
+      if (result.action === "updated") {
+        log(`[Mandu] refreshed ${LOCKFILE_PATH} (${result.hash})`);
+      } else if (result.error) {
+        warn(`[Mandu] ${result.action}: ${result.error}`);
+      } else {
+        log(`[Mandu] ${result.action}`);
+      }
+    }
+    return result;
+  };
+
+  if (env.MANDU_POSTINSTALL_LOCK === "0") {
+    return report({ action: "skipped-disabled", projectRoot });
+  }
+
+  if (!(await hasProjectConfig(projectRoot))) {
+    return report({ action: "skipped-no-project-config", projectRoot });
+  }
+
+  let existingLockfile: Awaited<ReturnType<typeof readLockfile>>;
+  try {
+    existingLockfile = await readLockfile(projectRoot);
+  } catch (error) {
+    return report({
+      action: "skipped-invalid-lockfile",
+      projectRoot,
+      error: stringifyError(error),
+    });
+  }
+
+  if (!existingLockfile) {
+    return report({ action: "skipped-no-lockfile", projectRoot });
+  }
+
+  const validation = await validateConfig(projectRoot);
+  if (!validation.valid || !validation.config) {
+    return report({
+      action: "skipped-invalid-config",
+      projectRoot,
+      error:
+        validation.errors?.map((entry) => entry.message).join("; ") ??
+        "Mandu config validation failed",
+    });
+  }
+
+  let mcpConfig: Record<string, unknown> | null;
+  try {
+    mcpConfig = await readMcpConfig(projectRoot);
+  } catch (error) {
+    return report({
+      action: "skipped-invalid-mcp-config",
+      projectRoot,
+      error: stringifyError(error),
+    });
+  }
+
+  try {
+    const lockfile = generateLockfile(
+      validation.config as ValidatedManduConfig,
+      {
+        includeSnapshot: existingLockfile.snapshot !== undefined,
+        includeMcpServerHashes: true,
+      },
+      mcpConfig,
+    );
+    await writeLockfile(projectRoot, lockfile);
+    return report({ action: "updated", projectRoot, hash: lockfile.configHash });
+  } catch (error) {
+    return report({
+      action: "skipped-write-failed",
+      projectRoot,
+      error: stringifyError(error),
+    });
+  }
+}
+
+async function hasProjectConfig(projectRoot: string): Promise<boolean> {
+  for (const fileName of CONFIG_FILES) {
+    if (await Bun.file(path.join(projectRoot, fileName)).exists()) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function stringifyError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+if (import.meta.main) {
+  await refreshGuardLockAfterInstall();
+}

package/src/agent/__tests__/context.test.ts

@@ -0,0 +1,237 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import fs from "fs/promises";
+import os from "os";
+import path from "path";
+import {
+  agentManifestPath,
+  buildAgentContext,
+  readAgentManifest,
+  writeAgentManifest,
+} from "../context";
+import {
+  agentPlanPath,
+  buildAgentApplyReport,
+  buildAgentPlan,
+  writeAgentApplyReport,
+  writeAgentPlan,
+} from "../plan";
+import {
+  agentRepairReportPath,
+  buildAgentRepairReport,
+  writeAgentRepairReport,
+} from "../repair";
+import { buildAgentSyncReport } from "../sync";
+import {
+  agentVerifyReportPath,
+  buildAgentVerifyReport,
+  writeAgentVerifyReport,
+} from "../verify";
+
+async function writeFile(root: string, rel: string, content: string): Promise<void> {
+  const abs = path.join(root, rel);
+  await fs.mkdir(path.dirname(abs), { recursive: true });
+  await fs.writeFile(abs, content, "utf8");
+}
+
+describe("agent context", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), "mandu-agent-context-"));
+    await writeFile(root, "package.json", JSON.stringify({
+      name: "agent-app",
+      version: "1.2.3",
+      packageManager: "bun@1.3.14",
+    }));
+    await writeFile(root, ".mandu/routes.manifest.json", JSON.stringify({
+      version: 1,
+      routes: [
+        {
+          id: "home",
+          pattern: "/",
+          kind: "page",
+          module: "app/page.tsx",
+          componentModule: "app/page.tsx",
+          layoutChain: [],
+        },
+        {
+          id: "api-ping",
+          pattern: "/api/ping",
+          kind: "api",
+          module: "app/api/ping/route.ts",
+          methods: ["GET"],
+          contractModule: "spec/contracts/ping.contract.ts",
+        },
+      ],
+    }));
+    await writeFile(root, "app/dashboard/counter.partial.tsx", "export default function Counter() { return null; }");
+    await writeFile(root, "app/dashboard/chart.island.tsx", "export default function Chart() { return null; }");
+    await writeFile(root, "spec/slots/dashboard.slot.ts", "export default {};");
+    await writeFile(root, "spec/contracts/ping.contract.ts", "export default {};");
+    await writeFile(root, ".env.example", "DATABASE_URL=\n");
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("builds a single agent-facing project map", async () => {
+    const context = await buildAgentContext(root, {
+      includeDiagnose: false,
+      includeGit: false,
+    });
+
+    expect(context.framework).toBe("mandu");
+    expect(context.project.name).toBe("agent-app");
+    expect(context.project.packageManager).toBe("bun@1.3.14");
+    expect(context.routeSource).toBe("manifest");
+    expect(context.routes).toHaveLength(2);
+    expect(context.pages.map((r) => r.id)).toEqual(["home"]);
+    expect(context.apis.map((r) => r.id)).toEqual(["api-ping"]);
+    expect(context.apis[0]?.hasContractModule).toBe(true);
+    expect(context.partials.map((p) => p.path)).toEqual(["app/dashboard/counter.partial.tsx"]);
+    expect(context.islands.map((p) => p.path)).toEqual(["app/dashboard/chart.island.tsx"]);
+    expect(context.slots.map((p) => p.path)).toEqual(["spec/slots/dashboard.slot.ts"]);
+    expect(context.contracts.map((p) => p.path)).toEqual(["spec/contracts/ping.contract.ts"]);
+    expect(context.env[0]).toMatchObject({ path: ".env.example", kind: "template", redacted: true });
+    expect(context.commands.context).toBe("mandu agent context --json");
+    expect(context.agentWorkflow.canonical).toEqual(["context", "plan", "apply", "verify", "repair"]);
+  });
+
+  it("writes and reads .mandu/agent-manifest.json", async () => {
+    const context = await buildAgentContext(root, {
+      includeDiagnose: false,
+      includeGit: false,
+    });
+    const result = await writeAgentManifest(root, context);
+
+    expect(result.path).toBe(agentManifestPath(root));
+    const manifest = await readAgentManifest(root);
+    expect(manifest?.schemaVersion).toBe(1);
+    expect(manifest?.project.name).toBe("agent-app");
+    expect(manifest?.agentWorkflow.canonical).toEqual(["context", "plan", "apply", "verify", "repair"]);
+  });
+
+  it("builds a deterministic agent plan from intent", () => {
+    const plan = buildAgentPlan({
+      intent: "add dashboard page with API contract and partial island",
+    });
+
+    expect(plan.framework).toBe("mandu");
+    expect(plan.intent).toBe("add dashboard page with API contract and partial island");
+    expect(plan.domains).toContain("route");
+    expect(plan.domains).toContain("api");
+    expect(plan.domains).toContain("contract");
+    expect(plan.domains).toContain("hydration");
+    expect(plan.filesToCreate).toContain("app/dashboard/page.tsx");
+    expect(plan.filesToCreate).toContain("app/api/<name>/route.ts");
+    expect(plan.mcpTools).toContain("mandu.agent.verify");
+    expect(plan.mcpTools).toContain("mandu.contract.validate");
+    expect(plan.verification.map((cmd) => cmd.command)).toContain("bun run typecheck");
+  });
+
+  it("writes a plan and previews apply actions without mutating files", async () => {
+    const plan = buildAgentPlan({
+      intent: "add dashboard page with API contract and partial island",
+    });
+    const written = await writeAgentPlan(root, plan);
+    expect(written.path).toBe(agentPlanPath(root));
+
+    const report = await buildAgentApplyReport(root);
+    expect(report.ok).toBe(true);
+    expect(report.dryRun).toBe(true);
+    expect(report.intent).toBe(plan.intent);
+    expect(report.actions.some((action) => action.kind === "mcp_tool")).toBe(true);
+    expect(report.actions.some((action) => action.kind === "manual_edit")).toBe(true);
+    expect(report.actions.every((action) => action.applied === false)).toBe(true);
+
+    const result = await writeAgentApplyReport(root, report);
+    expect(result.path).toBe(path.join(root, ".mandu", "agent-apply.json"));
+    expect(JSON.parse(await fs.readFile(result.path, "utf8")).intent).toBe(plan.intent);
+  });
+
+  it("syncs agent workflow artifacts for Codex, Claude, and Gemini", async () => {
+    const report = await buildAgentSyncReport(root, { target: "all" });
+
+    expect(report.ok).toBe(true);
+    expect(report.profile).toBe("agent-core");
+    expect(report.workflow).toEqual(["context", "plan", "apply", "verify", "repair"]);
+    expect(report.files.map((file) => file.path)).toContain(".mandu/agent-sync/codex/AGENTS.md");
+    expect(report.files.map((file) => file.path)).toContain(".mandu/agent-sync/claude/CLAUDE.md");
+    expect(report.files.map((file) => file.path)).toContain(".mandu/agent-sync/gemini/GEMINI.md");
+    const codex = await fs.readFile(path.join(root, ".mandu", "agent-sync", "codex", "AGENTS.md"), "utf8");
+    expect(codex).toContain("context -> plan -> apply -> verify -> repair");
+    expect(codex).toContain("MANDU_MCP_PROFILE=agent-core");
+  });
+
+  it("builds and writes the agent verify report", async () => {
+    const report = await buildAgentVerifyReport(root, {
+      includeDiagnose: false,
+      includeGit: false,
+      includeGuard: false,
+      includeContract: false,
+    });
+
+    expect(report.framework).toBe("mandu");
+    expect(report.ok).toBe(true);
+    expect(report.checks.map((check) => check.id)).toEqual(["manifest"]);
+    expect(report.suggestedCommands.map((cmd) => cmd.command)).toContain("bun run typecheck");
+    expect(report.nextRepairInput).toBe(".mandu/agent-verify.json");
+
+    const result = await writeAgentVerifyReport(root, report);
+    expect(result.path).toBe(agentVerifyReportPath(root));
+    const parsed = JSON.parse(await fs.readFile(result.path, "utf8"));
+    expect(parsed.project.name).toBe("agent-app");
+  });
+
+  it("turns a verify report into repair actions", async () => {
+    await writeAgentVerifyReport(root, {
+      schemaVersion: 1,
+      framework: "mandu",
+      generatedAt: new Date().toISOString(),
+      project: {
+        name: "agent-app",
+        version: "1.2.3",
+        root,
+        packageManager: "bun",
+        configFile: null,
+      },
+      changedFiles: [],
+      gitAvailable: false,
+      notes: [],
+      ok: false,
+      checks: [],
+      diagnostics: [
+        {
+          code: "MANDU_VERIFY_MANIFEST_UNAVAILABLE",
+          severity: "warning",
+          title: "Routes manifest unavailable",
+          cause: "missing",
+          suggestedFix: {
+            type: "run_command",
+            command: "mandu build",
+            description: "Build the project.",
+          },
+          repairable: true,
+          source: "test",
+        },
+      ],
+      suggestedCommands: [],
+      nextRepairInput: ".mandu/agent-verify.json",
+    });
+
+    const report = await buildAgentRepairReport(root);
+    expect(report.status).toBe("ready");
+    expect(report.actions).toHaveLength(1);
+    expect(report.actions[0]).toMatchObject({
+      diagnosticCode: "MANDU_VERIFY_MANIFEST_UNAVAILABLE",
+      kind: "run_command",
+      command: "mandu build",
+      safeToApply: false,
+    });
+
+    const result = await writeAgentRepairReport(root, report);
+    expect(result.path).toBe(agentRepairReportPath(root));
+    expect(JSON.parse(await fs.readFile(result.path, "utf8")).status).toBe("ready");
+  });
+});