@mandujs/core 0.52.0 → 0.53.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

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

@@ -0,0 +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();
+  });
+});

package/src/design/__tests__/lint.test.ts

@@ -0,0 +1,110 @@
+/**
+ * Issue #245 M5 — DESIGN.md lint tests.
+ */
+
+import { describe, it, expect } from "bun:test";
+import { lintDesignSpec } from "../lint";
+import { parseDesignMd } from "../parser";
+
+describe("lintDesignSpec — color-palette", () => {
+  it("warns when parser couldn't extract a value (rule: color-missing-value)", () => {
+    // Parser drops non-hex/rgb values during extraction, so the
+    // resulting token has no `.value` — the linter flags that.
+    const r = lintDesignSpec(parseDesignMd(`# T
+## Color Palette
+- Primary — #FF8C42 — brand
+- Bad — notahex — wrong
+`));
+    expect(
+      r.issues.find((i) => i.rule === "color-missing-value" && i.name === "Bad"),
+    ).toBeDefined();
+  });
+
+  it("warns on missing color value", () => {
+    const r = lintDesignSpec(parseDesignMd(`# T
+## Color Palette
+- Primary — see docs
+`));
+    expect(r.issues.find((i) => i.rule === "color-missing-value")?.severity).toBe("warning");
+  });
+
+  it("warns on slug collision", () => {
+    const r = lintDesignSpec(parseDesignMd(`# T
+## Color Palette
+- Primary — #FF0000
+- primary — #00FF00
+`));
+    expect(r.issues.find((i) => i.rule === "color-slug-collision")).toBeDefined();
+  });
+
+  it("notes duplicate values across distinct names (info)", () => {
+    const r = lintDesignSpec(parseDesignMd(`# T
+## Color Palette
+- Brand — #FF8C42 — main
+- Accent — #FF8C42 — secondary
+`));
+    const dup = r.issues.find((i) => i.rule === "color-duplicate-value");
+    expect(dup?.severity).toBe("info");
+  });
+});
+
+describe("lintDesignSpec — typography / layout / shadows / components", () => {
+  it("warns on a typography token with neither family nor size", () => {
+    const r = lintDesignSpec(parseDesignMd(`# T
+## Typography
+- body: weight: 400
+`));
+    expect(r.issues.find((i) => i.rule === "typography-empty-token")).toBeDefined();
+  });
+
+  it("warns on layout slug collision", () => {
+    const r = lintDesignSpec(parseDesignMd(`# T
+## Layout
+- sm: 0.5rem
+- SM: 0.5rem
+`));
+    expect(r.issues.find((i) => i.rule === "spacing-slug-collision")).toBeDefined();
+  });
+
+  it("warns on shadow slug collision", () => {
+    const r = lintDesignSpec(parseDesignMd(`# T
+## Depth & Elevation
+- card — 0 1px 2px rgba(0,0,0,0.1)
+- Card — 0 2px 4px rgba(0,0,0,0.2)
+`));
+    expect(r.issues.find((i) => i.rule === "shadow-slug-collision")).toBeDefined();
+  });
+
+  it("warns on duplicate component H3 names", () => {
+    const r = lintDesignSpec(parseDesignMd(`# T
+## Components
+
+### Button
+
+### button
+`));
+    expect(r.issues.find((i) => i.rule === "component-duplicate")).toBeDefined();
+  });
+});
+
+describe("lintDesignSpec — clean DESIGN.md", () => {
+  it("returns ok with empty issues for a well-formed spec", () => {
+    const r = lintDesignSpec(parseDesignMd(`# T
+## Color Palette
+- Primary — #FF8C42 — brand
+- Accent — #1A1F36 — text
+
+## Typography
+- body: font-family: Inter, sans-serif; size: 16px
+
+## Layout
+- sm: 0.5rem
+- md: 1rem
+
+## Depth & Elevation
+- card — 0 1px 3px rgba(0,0,0,0.1)
+`));
+    expect(r.issues).toEqual([]);
+    expect(r.ok).toBe(true);
+  });
+});

package/src/design/agents-link.ts

@@ -0,0 +1,165 @@
+/**
+ * AGENTS.md / CLAUDE.md ↔ DESIGN.md linker (Issue #245 M5).
+ *
+ * Drops a markered `## Design System` section into the project's
+ * agent guide files so coding agents read DESIGN.md and use the
+ * Mandu MCP tools (M4) before touching UI. Idempotent — running it
+ * twice never duplicates the section.
+ *
+ * The linker writes the same payload to whichever of `AGENTS.md` /
+ * `CLAUDE.md` exists. When neither exists in `force: true` mode it
+ * creates `AGENTS.md` (the open standard) seeded with just the
+ * design block — agents that consume `CLAUDE.md` follow the
+ * cross-reference to `AGENTS.md` per Anthropic's convention.
+ *
+ * The injected section:
+ *
+ *   - Names DESIGN.md as the canonical design source.
+ *   - Lists the 8 MCP tools with one-line descriptions.
+ *   - Spells out the §3.5 incremental loop as a 5-step prompt agents
+ *     can follow verbatim.
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+export const DESIGN_LINK_MARKER_START =
+  "<!-- @mandu-design-link:start — managed by `mandu design link` / `init --design`, do not edit -->";
+export const DESIGN_LINK_MARKER_END = "<!-- @mandu-design-link:end -->";
+
+export interface LinkAgentsOptions {
+  /** Project root. */
+  rootDir: string;
+  /** Filenames to update. Defaults to `["AGENTS.md", "CLAUDE.md"]`. */
+  filenames?: readonly string[];
+  /**
+   * When true, create a fresh `AGENTS.md` containing just the design
+   * link block when none of `filenames` exists. Default false — the
+   * linker only updates existing files unless explicitly asked.
+   */
+  createIfMissing?: boolean;
+  /** Override DESIGN.md filename. Defaults to `DESIGN.md`. */
+  designFilename?: string;
+}
+
+export interface LinkAgentsResult {
+  files: Array<{
+    path: string;
+    /** "created" | "inserted" (markered block added) | "updated" (markered block replaced) | "unchanged" */
+    action: "created" | "inserted" | "updated" | "unchanged";
+  }>;
+  /** True when at least one file was written. */
+  changed: boolean;
+}
+
+/** Generate the markered block payload. Pure — used by tests too. */
+export function buildAgentsDesignBlock(designFilename: string = "DESIGN.md"): string {
+  const lines = [
+    DESIGN_LINK_MARKER_START,
+    "",
+    "## Design System",
+    "",
+    `This project uses **${designFilename}** as the single source of truth for visual design (colors, typography, spacing, shadows, components, agent prompts).`,
+    "Mandu's MCP tools expose every part of it without grepping the codebase. Agents MUST read DESIGN.md *before* writing or editing UI.",
+    "",
+    "### Tools (call before / during UI work)",
+    "",
+    "| Phase | Tool | Use it for |",
+    "|---|---|---|",
+    "| Read | `mandu.design.get` | Section-by-section DESIGN.md (or `'all'` for full spec). |",
+    "| Read | `mandu.design.prompt` | §9 Agent Prompts — pre-warm context every session. |",
+    "| Read | `mandu.component.list` | Existing components in `src/client/shared/ui/` + `widgets/`. Don't re-implement. |",
+    "| Check | `mandu.design.check` | Lint a file BEFORE editing — surfaces forbidden inline classes. |",
+    "| Discover | `mandu.design.extract` | Find token candidates the project uses but DESIGN.md doesn't list. |",
+    "| Patch | `mandu.design.propose` | One-call: extract → dry-run patch → user reviews diff. |",
+    "| Patch | `mandu.design.patch` | Section-safe add/update/remove. Defaults to `dry_run: true`. |",
+    "| Sync | `mandu.design.diff_upstream` | Compare against awesome-design-md slugs (e.g. `'stripe'`). |",
+    "",
+    "### 5-step UI workflow",
+    "",
+    "1. **Pre-warm.** Call `mandu.design.prompt` (and `mandu.design.get` for the section you'll touch) so your edit honours existing tokens.",
+    "2. **Inventory.** Call `mandu.component.list` for the matching category. Re-use first; only add when nothing fits.",
+    "3. **Check.** Before editing a file, call `mandu.design.check { file }` to see if the file already violates DESIGN.md §7.",
+    "4. **Edit.** Write the change. Use existing tokens from §2 / components from §1.",
+    "5. **Propose tokens.** If you introduced a new color/font/spacing pattern, call `mandu.design.propose` and ask the user to apply the patch (default `dry_run: true`).",
+    "",
+    "### Hard rules",
+    "",
+    "- Never invent colors / fonts / spacing values without a `mandu.design.propose` round.",
+    "- Never bypass `mandu.design.check` on a file you're about to edit.",
+    "- DESIGN.md is the spec — when in doubt, update DESIGN.md *first*, then write code.",
+    "",
+    DESIGN_LINK_MARKER_END,
+    "",
+  ];
+  return lines.join("\n");
+}
+
+/**
+ * Update agent guide files to reference DESIGN.md and the MCP tools.
+ *
+ * Behaviour per file:
+ *   - Marker present → replace the markered region (idempotent).
+ *   - File exists, no marker → append the block at the end.
+ *   - File missing → skip unless `createIfMissing: true`.
+ */
+export async function linkAgentsToDesignMd(
+  options: LinkAgentsOptions,
+): Promise<LinkAgentsResult> {
+  const filenames = options.filenames ?? ["AGENTS.md", "CLAUDE.md"];
+  const block = buildAgentsDesignBlock(options.designFilename);
+  const files: LinkAgentsResult["files"] = [];
+
+  let anyExists = false;
+  for (const name of filenames) {
+    const full = path.join(options.rootDir, name);
+    let existing: string | null;
+    try {
+      existing = await fs.readFile(full, "utf8");
+      anyExists = true;
+    } catch {
+      existing = null;
+    }
+
+    if (existing === null) {
+      files.push({ path: full, action: "unchanged" });
+      continue;
+    }
+
+    const startIdx = existing.indexOf(DESIGN_LINK_MARKER_START);
+    const endIdx = existing.indexOf(DESIGN_LINK_MARKER_END);
+    let next: string;
+    let action: LinkAgentsResult["files"][number]["action"];
+    if (startIdx >= 0 && endIdx > startIdx) {
+      const before = existing.slice(0, startIdx);
+      const after = existing.slice(endIdx + DESIGN_LINK_MARKER_END.length);
+      const replacement = block.replace(/\n+$/, "");
+      next = `${before}${replacement}${after}`;
+      action = next === existing ? "unchanged" : "updated";
+    } else {
+      const sep = existing.endsWith("\n") ? "" : "\n";
+      next = `${existing}${sep}\n${block}`;
+      action = "inserted";
+    }
+
+    if (action !== "unchanged") {
+      await fs.writeFile(full, next, "utf8");
+    }
+    files.push({ path: full, action });
+  }
+
+  if (!anyExists && options.createIfMissing) {
+    const target = path.join(options.rootDir, filenames[0] ?? "AGENTS.md");
+    const seed = `# Project Agent Guide\n\n${block}`;
+    await fs.writeFile(target, seed, "utf8");
+    // Replace the placeholder "unchanged" entry with the real outcome.
+    const idx = files.findIndex((f) => f.path === target);
+    if (idx >= 0) files[idx] = { path: target, action: "created" };
+    else files.push({ path: target, action: "created" });
+  }
+
+  return {
+    files,
+    changed: files.some((f) => f.action !== "unchanged"),
+  };
+}

package/src/design/index.ts

@@ -57,6 +57,22 @@ export {
   type DiffEntry,
 } from "./diff";
 
+export {
+  buildAgentsDesignBlock,
+  linkAgentsToDesignMd,
+  DESIGN_LINK_MARKER_START,
+  DESIGN_LINK_MARKER_END,
+  type LinkAgentsOptions,
+  type LinkAgentsResult,
+} from "./agents-link";
+
+export {
+  lintDesignSpec,
+  type LintIssue,
+  type LintResult,
+  type LintSeverity,
+} from "./lint";
+
 export type {
   AgentPrompt,
   AgentPromptsSection,

package/src/design/lint.ts

@@ -0,0 +1,209 @@
+/**
+ * DESIGN.md self-consistency lint (Issue #245 M5).
+ *
+ * Different from `validateDesignSpec` (M1), which reports section
+ * presence / shape. The linter checks the *content* for issues that
+ * compile fine but waste reader time:
+ *
+ *   - color-palette: hex values that aren't 3/6/8 digits, duplicate
+ *     hex values across distinct names, slug collisions across names
+ *   - typography: tokens missing both `fontFamily` and `size`,
+ *     duplicate display-name slugs
+ *   - layout / shadows: tokens with no value, duplicate slugs
+ *   - components: duplicate H3 names
+ *   - dos-donts: rules under §7 with no `do` / `don't` mode marker
+ *
+ * The linter is conservative — every rule is opt-out via severity
+ * filtering at the call site. The tool returns `{ ok, issues[] }`
+ * so CLIs can produce exit codes and MCP tools can stream the issue
+ * list.
+ */
+
+import { slugifyTokenName } from "./tailwind-theme";
+import type { DesignSpec } from "./types";
+
+export type LintSeverity = "error" | "warning" | "info";
+
+export interface LintIssue {
+  rule: string;
+  section:
+    | "color-palette"
+    | "typography"
+    | "layout"
+    | "shadows"
+    | "components"
+    | "dos-donts"
+    | "agent-prompts"
+    | "responsive";
+  severity: LintSeverity;
+  message: string;
+  /** Token / row name when the issue is per-row. */
+  name?: string;
+}
+
+export interface LintResult {
+  ok: boolean;
+  issues: LintIssue[];
+}
+
+const HEX_RX = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+const COLOR_FN_RX = /^(rgba?|hsla?|oklch|hwb|lab|lch)\(/i;
+
+export function lintDesignSpec(spec: DesignSpec): LintResult {
+  const issues: LintIssue[] = [];
+
+  // ─── color-palette ────────────────────────────────────────────────
+  const seenColorSlug = new Map<string, string>();
+  const seenColorValue = new Map<string, string>();
+  for (const token of spec.sections["color-palette"].tokens) {
+    if (!token.value) {
+      issues.push({
+        rule: "color-missing-value",
+        section: "color-palette",
+        severity: "warning",
+        message: `Color "${token.name}" has no parseable value — Tailwind sync will skip it.`,
+        name: token.name,
+      });
+      continue;
+    }
+    if (!HEX_RX.test(token.value) && !COLOR_FN_RX.test(token.value)) {
+      issues.push({
+        rule: "color-malformed-value",
+        section: "color-palette",
+        severity: "error",
+        message: `Color "${token.name}" value "${token.value}" is not a recognised hex/rgb/hsl/oklch literal.`,
+        name: token.name,
+      });
+    }
+    const sl = slugifyTokenName(token.name);
+    const prevByName = seenColorSlug.get(sl);
+    if (prevByName) {
+      issues.push({
+        rule: "color-slug-collision",
+        section: "color-palette",
+        severity: "warning",
+        message: `Color "${token.name}" slugifies to the same id as "${prevByName}" — Tailwind sync keeps only the first.`,
+        name: token.name,
+      });
+    } else {
+      seenColorSlug.set(sl, token.name);
+    }
+    const prevByValue = seenColorValue.get(token.value.toLowerCase());
+    if (prevByValue && prevByValue !== token.name) {
+      issues.push({
+        rule: "color-duplicate-value",
+        section: "color-palette",
+        severity: "info",
+        message: `Color "${token.name}" shares value ${token.value} with "${prevByValue}" — consider a single canonical name.`,
+        name: token.name,
+      });
+    } else {
+      seenColorValue.set(token.value.toLowerCase(), token.name);
+    }
+  }
+
+  // ─── typography ──────────────────────────────────────────────────
+  const seenTypoSlug = new Map<string, string>();
+  for (const token of spec.sections.typography.tokens) {
+    if (!token.fontFamily && !token.size) {
+      issues.push({
+        rule: "typography-empty-token",
+        section: "typography",
+        severity: "warning",
+        message: `Typography token "${token.name}" has neither fontFamily nor size — nothing to sync.`,
+        name: token.name,
+      });
+    }
+    const sl = slugifyTokenName(token.name);
+    const prev = seenTypoSlug.get(sl);
+    if (prev) {
+      issues.push({
+        rule: "typography-slug-collision",
+        section: "typography",
+        severity: "warning",
+        message: `Typography "${token.name}" collides with "${prev}" on slug "${sl}".`,
+        name: token.name,
+      });
+    } else {
+      seenTypoSlug.set(sl, token.name);
+    }
+  }
+
+  // ─── layout (spacing) ────────────────────────────────────────────
+  const seenLayoutSlug = new Map<string, string>();
+  for (const token of spec.sections.layout.tokens) {
+    if (!token.value) {
+      issues.push({
+        rule: "spacing-missing-value",
+        section: "layout",
+        severity: "warning",
+        message: `Spacing "${token.name}" has no value.`,
+        name: token.name,
+      });
+      continue;
+    }
+    const sl = slugifyTokenName(token.name);
+    const prev = seenLayoutSlug.get(sl);
+    if (prev) {
+      issues.push({
+        rule: "spacing-slug-collision",
+        section: "layout",
+        severity: "warning",
+        message: `Spacing "${token.name}" collides with "${prev}" on slug "${sl}".`,
+        name: token.name,
+      });
+    } else {
+      seenLayoutSlug.set(sl, token.name);
+    }
+  }
+
+  // ─── shadows ─────────────────────────────────────────────────────
+  const seenShadowSlug = new Map<string, string>();
+  for (const token of spec.sections.shadows.tokens) {
+    if (!token.value) {
+      issues.push({
+        rule: "shadow-missing-value",
+        section: "shadows",
+        severity: "warning",
+        message: `Shadow "${token.name}" has no value.`,
+        name: token.name,
+      });
+      continue;
+    }
+    const sl = slugifyTokenName(token.name);
+    const prev = seenShadowSlug.get(sl);
+    if (prev) {
+      issues.push({
+        rule: "shadow-slug-collision",
+        section: "shadows",
+        severity: "warning",
+        message: `Shadow "${token.name}" collides with "${prev}" on slug "${sl}".`,
+        name: token.name,
+      });
+    } else {
+      seenShadowSlug.set(sl, token.name);
+    }
+  }
+
+  // ─── components ──────────────────────────────────────────────────
+  const seenComponentSlug = new Map<string, string>();
+  for (const token of spec.sections.components.tokens) {
+    const sl = slugifyTokenName(token.name);
+    const prev = seenComponentSlug.get(sl);
+    if (prev) {
+      issues.push({
+        rule: "component-duplicate",
+        section: "components",
+        severity: "warning",
+        message: `Component "${token.name}" appears twice (also as "${prev}").`,
+        name: token.name,
+      });
+    } else {
+      seenComponentSlug.set(sl, token.name);
+    }
+  }
+
+  // The most critical level of severity wins for the `ok` flag.
+  const ok = !issues.some((i) => i.severity === "error");
+  return { ok, issues };
+}