@mandujs/core 0.54.32 → 0.55.0-beta.1

package/src/deploy/plan.ts

@@ -1,178 +1,178 @@
-/**
- * Plan a deploy — compute the next `DeployIntentCache` from a
- * manifest and the previous cache.
- *
- * Issue #250 — Phase 1.
- *
- * The plan step is pure: it takes the manifest + previous cache +
- * inferer and returns the new cache + a diff. No filesystem writes
- * here; that's the CLI's job. Keeping this pure makes the diff easy
- * to render in tests and lets future surfaces (kitchen UI, MCP tool)
- * reuse the same plan logic.
- *
- * Override hierarchy (highest wins):
- *
- *   1. **Explicit** — entry where `source === "explicit"` in the
- *      previous cache. Never overwritten by inference. Re-keyed by
- *      `sourceHash` only so users can hand-edit the file and have
- *      their edits stick.
- *   2. **Cached, source unchanged** — same `sourceHash` ⇒ reuse the
- *      stored intent. This is the cost cap on brain calls.
- *   3. **Inferred** — call the inferer. Default is heuristic; brain
- *      can swap in via the `infer` parameter.
- */
-
-import type { RoutesManifest } from "../spec/schema";
-import {
-  emptyDeployIntentCache,
-  type DeployIntentCache,
-  type DeployIntentCacheEntry,
-} from "./cache";
-import { buildDeployInferenceContext, type DeployInferenceContext } from "./inference/context";
-import {
-  inferDeployIntentHeuristic,
-  type InferenceResult,
-} from "./inference/heuristic";
-
-/**
- * Per-route diff entry surfaced to the CLI / tests.
- *
- *   - `added`     — no prior entry, new intent inferred.
- *   - `unchanged` — same source hash; entry kept verbatim.
- *   - `changed`   — source hash differs OR explicit override updated;
- *                   the `previous` field carries the old entry for
- *                   diff rendering.
- *   - `removed`   — route exists in cache but not in manifest. Pruned.
- *   - `pinned`    — explicit entry; inference skipped.
- */
-export type PlanDiffEntryKind =
-  | "added"
-  | "unchanged"
-  | "changed"
-  | "removed"
-  | "pinned";
-
-export interface PlanDiffEntry {
-  routeId: string;
-  pattern: string;
-  kind: PlanDiffEntryKind;
-  next?: DeployIntentCacheEntry;
-  previous?: DeployIntentCacheEntry;
-}
-
-export interface PlanResult {
-  cache: DeployIntentCache;
-  diff: PlanDiffEntry[];
-}
-
-export interface PlanDeployOptions {
-  rootDir: string;
-  manifest: RoutesManifest;
-  previous?: DeployIntentCache;
-  /**
-   * Override the inferer. Defaults to the offline heuristic. The
-   * brain inferer (M4) plugs in here without changing the plan flow.
-   */
-  infer?: (ctx: DeployInferenceContext) => Promise<InferenceResult> | InferenceResult;
-  /** Identifier written into `cache.brainModel`. Defaults to `"heuristic"`. */
-  brainModel?: string;
-  /** ISO timestamp override — primarily for test determinism. */
-  now?: () => string;
-  /** Force re-inference even when the source hash matches. */
-  reinfer?: boolean;
-}
-
-export async function planDeploy(opts: PlanDeployOptions): Promise<PlanResult> {
-  const previous = opts.previous ?? emptyDeployIntentCache();
-  const infer =
-    opts.infer ?? ((ctx: DeployInferenceContext) => inferDeployIntentHeuristic(ctx));
-  const now = opts.now ?? (() => new Date().toISOString());
-  const brainModel = opts.brainModel ?? "heuristic";
-  const reinfer = opts.reinfer === true;
-
-  const nextIntents: Record<string, DeployIntentCacheEntry> = {};
-  const diff: PlanDiffEntry[] = [];
-
-  for (const route of opts.manifest.routes) {
-    const ctx = await buildDeployInferenceContext(opts.rootDir, route);
-    const prevEntry = previous.intents[route.id];
-
-    // 1. Explicit override — never re-infer; only refresh sourceHash.
-    if (prevEntry && prevEntry.source === "explicit") {
-      const refreshed: DeployIntentCacheEntry = {
-        ...prevEntry,
-        sourceHash: ctx.sourceHash,
-      };
-      nextIntents[route.id] = refreshed;
-      diff.push({
-        routeId: route.id,
-        pattern: route.pattern,
-        kind: "pinned",
-        next: refreshed,
-        previous: prevEntry,
-      });
-      continue;
-    }
-
-    // 2. Cached, source unchanged.
-    if (
-      !reinfer &&
-      prevEntry &&
-      prevEntry.sourceHash === ctx.sourceHash
-    ) {
-      nextIntents[route.id] = prevEntry;
-      diff.push({
-        routeId: route.id,
-        pattern: route.pattern,
-        kind: "unchanged",
-        next: prevEntry,
-        previous: prevEntry,
-      });
-      continue;
-    }
-
-    // 3. Infer.
-    const result = await infer(ctx);
-    const entry: DeployIntentCacheEntry = {
-      intent: result.intent,
-      source: "inferred",
-      rationale: result.rationale,
-      sourceHash: ctx.sourceHash,
-      inferredAt: now(),
-    };
-    nextIntents[route.id] = entry;
-    diff.push({
-      routeId: route.id,
-      pattern: route.pattern,
-      kind: prevEntry ? "changed" : "added",
-      next: entry,
-      previous: prevEntry,
-    });
-  }
-
-  // 4. Detect removed entries (cache had them, manifest doesn't).
-  const manifestIds = new Set(opts.manifest.routes.map((r) => r.id));
-  for (const [routeId, entry] of Object.entries(previous.intents)) {
-    if (manifestIds.has(routeId)) continue;
-    diff.push({
-      routeId,
-      pattern: "(removed from manifest)",
-      kind: "removed",
-      previous: entry,
-    });
-  }
-
-  const cache: DeployIntentCache = {
-    version: 1,
-    generatedAt: now(),
-    brainModel,
-    intents: nextIntents,
-  };
-
-  return { cache, diff };
-}
-
-/** True if the diff contains any non-`unchanged` entry. */
-export function planHasChanges(diff: readonly PlanDiffEntry[]): boolean {
-  return diff.some((d) => d.kind !== "unchanged" && d.kind !== "pinned");
-}
+/**
+ * Plan a deploy — compute the next `DeployIntentCache` from a
+ * manifest and the previous cache.
+ *
+ * Issue #250 — Phase 1.
+ *
+ * The plan step is pure: it takes the manifest + previous cache +
+ * inferer and returns the new cache + a diff. No filesystem writes
+ * here; that's the CLI's job. Keeping this pure makes the diff easy
+ * to render in tests and lets future surfaces (kitchen UI, MCP tool)
+ * reuse the same plan logic.
+ *
+ * Override hierarchy (highest wins):
+ *
+ *   1. **Explicit** — entry where `source === "explicit"` in the
+ *      previous cache. Never overwritten by inference. Re-keyed by
+ *      `sourceHash` only so users can hand-edit the file and have
+ *      their edits stick.
+ *   2. **Cached, source unchanged** — same `sourceHash` ⇒ reuse the
+ *      stored intent. This is the cost cap on brain calls.
+ *   3. **Inferred** — call the inferer. Default is heuristic; brain
+ *      can swap in via the `infer` parameter.
+ */
+
+import type { RoutesManifest } from "../spec/schema";
+import {
+  emptyDeployIntentCache,
+  type DeployIntentCache,
+  type DeployIntentCacheEntry,
+} from "./cache";
+import { buildDeployInferenceContext, type DeployInferenceContext } from "./inference/context";
+import {
+  inferDeployIntentHeuristic,
+  type InferenceResult,
+} from "./inference/heuristic";
+
+/**
+ * Per-route diff entry surfaced to the CLI / tests.
+ *
+ *   - `added`     — no prior entry, new intent inferred.
+ *   - `unchanged` — same source hash; entry kept verbatim.
+ *   - `changed`   — source hash differs OR explicit override updated;
+ *                   the `previous` field carries the old entry for
+ *                   diff rendering.
+ *   - `removed`   — route exists in cache but not in manifest. Pruned.
+ *   - `pinned`    — explicit entry; inference skipped.
+ */
+export type PlanDiffEntryKind =
+  | "added"
+  | "unchanged"
+  | "changed"
+  | "removed"
+  | "pinned";
+
+export interface PlanDiffEntry {
+  routeId: string;
+  pattern: string;
+  kind: PlanDiffEntryKind;
+  next?: DeployIntentCacheEntry;
+  previous?: DeployIntentCacheEntry;
+}
+
+export interface PlanResult {
+  cache: DeployIntentCache;
+  diff: PlanDiffEntry[];
+}
+
+export interface PlanDeployOptions {
+  rootDir: string;
+  manifest: RoutesManifest;
+  previous?: DeployIntentCache;
+  /**
+   * Override the inferer. Defaults to the offline heuristic. The
+   * brain inferer (M4) plugs in here without changing the plan flow.
+   */
+  infer?: (ctx: DeployInferenceContext) => Promise<InferenceResult> | InferenceResult;
+  /** Identifier written into `cache.brainModel`. Defaults to `"heuristic"`. */
+  brainModel?: string;
+  /** ISO timestamp override — primarily for test determinism. */
+  now?: () => string;
+  /** Force re-inference even when the source hash matches. */
+  reinfer?: boolean;
+}
+
+export async function planDeploy(opts: PlanDeployOptions): Promise<PlanResult> {
+  const previous = opts.previous ?? emptyDeployIntentCache();
+  const infer =
+    opts.infer ?? ((ctx: DeployInferenceContext) => inferDeployIntentHeuristic(ctx));
+  const now = opts.now ?? (() => new Date().toISOString());
+  const brainModel = opts.brainModel ?? "heuristic";
+  const reinfer = opts.reinfer === true;
+
+  const nextIntents: Record<string, DeployIntentCacheEntry> = {};
+  const diff: PlanDiffEntry[] = [];
+
+  for (const route of opts.manifest.routes) {
+    const ctx = await buildDeployInferenceContext(opts.rootDir, route);
+    const prevEntry = previous.intents[route.id];
+
+    // 1. Explicit override — never re-infer; only refresh sourceHash.
+    if (prevEntry && prevEntry.source === "explicit") {
+      const refreshed: DeployIntentCacheEntry = {
+        ...prevEntry,
+        sourceHash: ctx.sourceHash,
+      };
+      nextIntents[route.id] = refreshed;
+      diff.push({
+        routeId: route.id,
+        pattern: route.pattern,
+        kind: "pinned",
+        next: refreshed,
+        previous: prevEntry,
+      });
+      continue;
+    }
+
+    // 2. Cached, source unchanged.
+    if (
+      !reinfer &&
+      prevEntry &&
+      prevEntry.sourceHash === ctx.sourceHash
+    ) {
+      nextIntents[route.id] = prevEntry;
+      diff.push({
+        routeId: route.id,
+        pattern: route.pattern,
+        kind: "unchanged",
+        next: prevEntry,
+        previous: prevEntry,
+      });
+      continue;
+    }
+
+    // 3. Infer.
+    const result = await infer(ctx);
+    const entry: DeployIntentCacheEntry = {
+      intent: result.intent,
+      source: "inferred",
+      rationale: result.rationale,
+      sourceHash: ctx.sourceHash,
+      inferredAt: now(),
+    };
+    nextIntents[route.id] = entry;
+    diff.push({
+      routeId: route.id,
+      pattern: route.pattern,
+      kind: prevEntry ? "changed" : "added",
+      next: entry,
+      previous: prevEntry,
+    });
+  }
+
+  // 4. Detect removed entries (cache had them, manifest doesn't).
+  const manifestIds = new Set(opts.manifest.routes.map((r) => r.id));
+  for (const [routeId, entry] of Object.entries(previous.intents)) {
+    if (manifestIds.has(routeId)) continue;
+    diff.push({
+      routeId,
+      pattern: "(removed from manifest)",
+      kind: "removed",
+      previous: entry,
+    });
+  }
+
+  const cache: DeployIntentCache = {
+    version: 1,
+    generatedAt: now(),
+    brainModel,
+    intents: nextIntents,
+  };
+
+  return { cache, diff };
+}
+
+/** True if the diff contains any non-`unchanged` entry. */
+export function planHasChanges(diff: readonly PlanDiffEntry[]): boolean {
+  return diff.some((d) => d.kind !== "unchanged" && d.kind !== "pinned");
+}

package/src/design/__tests__/agents-link.test.ts

@@ -1,109 +1,109 @@
-/**
- * Issue #245 M5 — AGENTS.md / CLAUDE.md linker tests.
- */
-
-import { afterEach, beforeEach, describe, expect, it } from "bun:test";
-import { promises as fs } from "node:fs";
-import path from "node:path";
-import os from "node:os";
-import {
-  buildAgentsDesignBlock,
-  DESIGN_LINK_MARKER_END,
-  DESIGN_LINK_MARKER_START,
-  linkAgentsToDesignMd,
-} from "../agents-link";
-
-describe("buildAgentsDesignBlock", () => {
-  it("contains markers, the canonical heading, and all 8 MCP tools", () => {
-    const block = buildAgentsDesignBlock();
-    expect(block).toContain(DESIGN_LINK_MARKER_START);
-    expect(block).toContain(DESIGN_LINK_MARKER_END);
-    expect(block).toContain("## Design System");
-    for (const tool of [
-      "mandu.design.get",
-      "mandu.design.prompt",
-      "mandu.component.list",
-      "mandu.design.check",
-      "mandu.design.extract",
-      "mandu.design.propose",
-      "mandu.design.patch",
-      "mandu.design.diff_upstream",
-    ]) {
-      expect(block).toContain(tool);
-    }
-  });
-
-  it("respects custom DESIGN.md filename", () => {
-    expect(buildAgentsDesignBlock("Stripe-DESIGN.md")).toContain("Stripe-DESIGN.md");
-  });
-});
-
-describe("linkAgentsToDesignMd", () => {
-  let TEST_DIR: string;
-  beforeEach(async () => {
-    TEST_DIR = await fs.mkdtemp(path.join(os.tmpdir(), "mandu-design-link-"));
-  });
-  afterEach(async () => {
-    await fs.rm(TEST_DIR, { recursive: true, force: true });
-  });
-
-  it("inserts the block at end of an existing AGENTS.md", async () => {
-    await fs.writeFile(path.join(TEST_DIR, "AGENTS.md"), "# Existing\n\nSome notes.\n");
-    const result = await linkAgentsToDesignMd({ rootDir: TEST_DIR });
-    expect(result.changed).toBe(true);
-    expect(result.files.find((f) => f.path.endsWith("AGENTS.md"))?.action).toBe("inserted");
-    const after = await fs.readFile(path.join(TEST_DIR, "AGENTS.md"), "utf8");
-    expect(after).toContain("# Existing");
-    expect(after).toContain("Some notes.");
-    expect(after).toContain("## Design System");
-  });
-
-  it("is idempotent — running twice produces no diff on the second run", async () => {
-    await fs.writeFile(path.join(TEST_DIR, "AGENTS.md"), "# X\n");
-    await linkAgentsToDesignMd({ rootDir: TEST_DIR });
-    const after1 = await fs.readFile(path.join(TEST_DIR, "AGENTS.md"), "utf8");
-    const second = await linkAgentsToDesignMd({ rootDir: TEST_DIR });
-    const after2 = await fs.readFile(path.join(TEST_DIR, "AGENTS.md"), "utf8");
-    expect(after1).toBe(after2);
-    expect(second.files.find((f) => f.path.endsWith("AGENTS.md"))?.action).toBe("unchanged");
-  });
-
-  it("replaces an existing markered block when the body changed", async () => {
-    await fs.writeFile(
-      path.join(TEST_DIR, "AGENTS.md"),
-      `# X\n\n${DESIGN_LINK_MARKER_START}\n\n## Old block\n\n${DESIGN_LINK_MARKER_END}\n`,
-    );
-    await linkAgentsToDesignMd({ rootDir: TEST_DIR });
-    const after = await fs.readFile(path.join(TEST_DIR, "AGENTS.md"), "utf8");
-    expect(after).not.toContain("## Old block");
-    expect(after).toContain("## Design System");
-  });
-
-  it("touches CLAUDE.md too when both exist", async () => {
-    await fs.writeFile(path.join(TEST_DIR, "AGENTS.md"), "# A\n");
-    await fs.writeFile(path.join(TEST_DIR, "CLAUDE.md"), "# C\n");
-    const result = await linkAgentsToDesignMd({ rootDir: TEST_DIR });
-    expect(result.files.filter((f) => f.action === "inserted")).toHaveLength(2);
-    expect(await fs.readFile(path.join(TEST_DIR, "CLAUDE.md"), "utf8")).toContain(
-      "## Design System",
-    );
-  });
-
-  it("creates AGENTS.md when neither file exists and createIfMissing is true", async () => {
-    const result = await linkAgentsToDesignMd({
-      rootDir: TEST_DIR,
-      createIfMissing: true,
-    });
-    expect(result.changed).toBe(true);
-    expect(result.files.find((f) => f.action === "created")).toBeDefined();
-    expect(await fs.readFile(path.join(TEST_DIR, "AGENTS.md"), "utf8")).toContain(
-      "## Design System",
-    );
-  });
-
-  it("is a no-op when neither file exists and createIfMissing is false", async () => {
-    const result = await linkAgentsToDesignMd({ rootDir: TEST_DIR });
-    expect(result.changed).toBe(false);
-    await expect(fs.access(path.join(TEST_DIR, "AGENTS.md"))).rejects.toThrow();
-  });
-});
+/**
+ * Issue #245 M5 — AGENTS.md / CLAUDE.md linker tests.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import {
+  buildAgentsDesignBlock,
+  DESIGN_LINK_MARKER_END,
+  DESIGN_LINK_MARKER_START,
+  linkAgentsToDesignMd,
+} from "../agents-link";
+
+describe("buildAgentsDesignBlock", () => {
+  it("contains markers, the canonical heading, and all 8 MCP tools", () => {
+    const block = buildAgentsDesignBlock();
+    expect(block).toContain(DESIGN_LINK_MARKER_START);
+    expect(block).toContain(DESIGN_LINK_MARKER_END);
+    expect(block).toContain("## Design System");
+    for (const tool of [
+      "mandu.design.get",
+      "mandu.design.prompt",
+      "mandu.component.list",
+      "mandu.design.check",
+      "mandu.design.extract",
+      "mandu.design.propose",
+      "mandu.design.patch",
+      "mandu.design.diff_upstream",
+    ]) {
+      expect(block).toContain(tool);
+    }
+  });
+
+  it("respects custom DESIGN.md filename", () => {
+    expect(buildAgentsDesignBlock("Stripe-DESIGN.md")).toContain("Stripe-DESIGN.md");
+  });
+});
+
+describe("linkAgentsToDesignMd", () => {
+  let TEST_DIR: string;
+  beforeEach(async () => {
+    TEST_DIR = await fs.mkdtemp(path.join(os.tmpdir(), "mandu-design-link-"));
+  });
+  afterEach(async () => {
+    await fs.rm(TEST_DIR, { recursive: true, force: true });
+  });
+
+  it("inserts the block at end of an existing AGENTS.md", async () => {
+    await fs.writeFile(path.join(TEST_DIR, "AGENTS.md"), "# Existing\n\nSome notes.\n");
+    const result = await linkAgentsToDesignMd({ rootDir: TEST_DIR });
+    expect(result.changed).toBe(true);
+    expect(result.files.find((f) => f.path.endsWith("AGENTS.md"))?.action).toBe("inserted");
+    const after = await fs.readFile(path.join(TEST_DIR, "AGENTS.md"), "utf8");
+    expect(after).toContain("# Existing");
+    expect(after).toContain("Some notes.");
+    expect(after).toContain("## Design System");
+  });
+
+  it("is idempotent — running twice produces no diff on the second run", async () => {
+    await fs.writeFile(path.join(TEST_DIR, "AGENTS.md"), "# X\n");
+    await linkAgentsToDesignMd({ rootDir: TEST_DIR });
+    const after1 = await fs.readFile(path.join(TEST_DIR, "AGENTS.md"), "utf8");
+    const second = await linkAgentsToDesignMd({ rootDir: TEST_DIR });
+    const after2 = await fs.readFile(path.join(TEST_DIR, "AGENTS.md"), "utf8");
+    expect(after1).toBe(after2);
+    expect(second.files.find((f) => f.path.endsWith("AGENTS.md"))?.action).toBe("unchanged");
+  });
+
+  it("replaces an existing markered block when the body changed", async () => {
+    await fs.writeFile(
+      path.join(TEST_DIR, "AGENTS.md"),
+      `# X\n\n${DESIGN_LINK_MARKER_START}\n\n## Old block\n\n${DESIGN_LINK_MARKER_END}\n`,
+    );
+    await linkAgentsToDesignMd({ rootDir: TEST_DIR });
+    const after = await fs.readFile(path.join(TEST_DIR, "AGENTS.md"), "utf8");
+    expect(after).not.toContain("## Old block");
+    expect(after).toContain("## Design System");
+  });
+
+  it("touches CLAUDE.md too when both exist", async () => {
+    await fs.writeFile(path.join(TEST_DIR, "AGENTS.md"), "# A\n");
+    await fs.writeFile(path.join(TEST_DIR, "CLAUDE.md"), "# C\n");
+    const result = await linkAgentsToDesignMd({ rootDir: TEST_DIR });
+    expect(result.files.filter((f) => f.action === "inserted")).toHaveLength(2);
+    expect(await fs.readFile(path.join(TEST_DIR, "CLAUDE.md"), "utf8")).toContain(
+      "## Design System",
+    );
+  });
+
+  it("creates AGENTS.md when neither file exists and createIfMissing is true", async () => {
+    const result = await linkAgentsToDesignMd({
+      rootDir: TEST_DIR,
+      createIfMissing: true,
+    });
+    expect(result.changed).toBe(true);
+    expect(result.files.find((f) => f.action === "created")).toBeDefined();
+    expect(await fs.readFile(path.join(TEST_DIR, "AGENTS.md"), "utf8")).toContain(
+      "## Design System",
+    );
+  });
+
+  it("is a no-op when neither file exists and createIfMissing is false", async () => {
+    const result = await linkAgentsToDesignMd({ rootDir: TEST_DIR });
+    expect(result.changed).toBe(false);
+    await expect(fs.access(path.join(TEST_DIR, "AGENTS.md"))).rejects.toThrow();
+  });
+});