@mandujs/core 0.51.0 → 0.52.0

package/package.json

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

package/src/design/__tests__/extract-patch-diff.test.ts

@@ -0,0 +1,265 @@
+/**
+ * Issue #245 M4 §3.5 — extract / patch / diff helper tests.
+ *
+ * Cover the three pure surfaces the MCP write-tools layer over:
+ *   - `extractDesignTokens()` — color/font/component proposals
+ *   - `patchDesignMd()` — section-safe add/update/remove
+ *   - `diffDesignSpecs()` — local ↔ upstream per-section diff
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { extractDesignTokens } from "../extract";
+import { patchDesignMd, patchDesignMdBatch } from "../patch";
+import { diffDesignSpecs } from "../diff";
+import { parseDesignMd } from "../parser";
+
+// ─── extract ──────────────────────────────────────────────────────────
+
+async function setupFixture(): Promise<{ root: string; cleanup: () => Promise<void> }> {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "mandu-extract-"));
+  await fs.mkdir(path.join(root, "src"), { recursive: true });
+  await fs.mkdir(path.join(root, "app"), { recursive: true });
+  await fs.writeFile(
+    path.join(root, "src/a.tsx"),
+    `const a = "#FF8C42"; const b = "#FF8C42"; const c = "#FF8C42";
+const elem = <div className="rounded-lg bg-orange-500 px-4 py-2 text-white" />;`,
+  );
+  await fs.writeFile(
+    path.join(root, "src/b.tsx"),
+    `const a = "#FF8C42"; const card = "#FFF8F0";
+const elem = <div className="rounded-lg bg-orange-500 px-4 py-2 text-white" />;`,
+  );
+  await fs.writeFile(
+    path.join(root, "app/c.tsx"),
+    `const x = "rgb(99,91,255)"; const y = "rgb(99,91,255)"; const z = "rgb(99,91,255)";
+const cssIsh = \`font-family: "Inter", sans-serif;\`;
+const elem = <div className="rounded-lg bg-orange-500 px-4 py-2 text-white" />;`,
+  );
+  return { root, cleanup: () => fs.rm(root, { recursive: true, force: true }) };
+}
+
+describe("extractDesignTokens", () => {
+  let fix: { root: string; cleanup: () => Promise<void> };
+  beforeEach(async () => {
+    fix = await setupFixture();
+  });
+  afterEach(async () => {
+    await fix.cleanup();
+  });
+
+  it("flags colors that occur ≥ minOccurrences", async () => {
+    const result = await extractDesignTokens(fix.root);
+    const orange = result.proposals.find((p) => p.key === "#ff8c42");
+    expect(orange).toBeDefined();
+    expect(orange?.section).toBe("color-palette");
+    expect(orange?.occurrences).toBeGreaterThanOrEqual(3);
+    expect(orange?.confidence).toBeGreaterThan(0);
+  });
+
+  it("ignores colors below the threshold", async () => {
+    const result = await extractDesignTokens(fix.root, { minOccurrences: 4 });
+    expect(result.proposals.find((p) => p.key === "#fff8f0")).toBeUndefined();
+  });
+
+  it("flags font-family declarations", async () => {
+    const result = await extractDesignTokens(fix.root, { minOccurrences: 1 });
+    const inter = result.proposals.find(
+      (p) => p.section === "typography" && p.value.includes("Inter"),
+    );
+    expect(inter).toBeDefined();
+  });
+
+  it("flags repeating className combos", async () => {
+    const result = await extractDesignTokens(fix.root, { kinds: ["component"] });
+    const combo = result.proposals.find((p) => p.section === "components");
+    expect(combo).toBeDefined();
+    expect(combo?.occurrences).toBeGreaterThanOrEqual(3);
+  });
+
+  it("drops proposals already represented in the existing DesignSpec", async () => {
+    const existing = parseDesignMd(`# Test
+## Color Palette
+- Primary — #FF8C42 — brand
+`);
+    const result = await extractDesignTokens(fix.root, { existing });
+    expect(result.proposals.find((p) => p.key === "#ff8c42")).toBeUndefined();
+  });
+});
+
+// ─── patch ────────────────────────────────────────────────────────────
+
+const SAMPLE = `# Test
+## Color Palette
+- Primary — #FF8C42 — brand
+- Surface — #FFF8F0 — background
+
+## Typography
+- body: font-family: "Inter", sans-serif
+
+## Layout
+- sm: 0.5rem
+`;
+
+describe("patchDesignMd — color-palette", () => {
+  it("adds a new token in the right section", () => {
+    const r = patchDesignMd(SAMPLE, {
+      section: "color-palette",
+      operation: "add",
+      key: "Accent",
+      value: "#1A1F36",
+      role: "text",
+    });
+    expect(r.applied).toBe(true);
+    expect(r.next).toContain("- Accent — #1A1F36 — text");
+    // Other sections untouched.
+    expect(r.next).toContain("## Typography");
+    expect(r.next).toContain("## Layout");
+  });
+
+  it("refuses to add a duplicate key (slug-insensitive)", () => {
+    const r = patchDesignMd(SAMPLE, {
+      section: "color-palette",
+      operation: "add",
+      key: "primary",
+      value: "#000",
+    });
+    expect(r.applied).toBe(false);
+    expect(r.reason).toContain("already exists");
+  });
+
+  it("updates a matching key", () => {
+    const r = patchDesignMd(SAMPLE, {
+      section: "color-palette",
+      operation: "update",
+      key: "Primary",
+      value: "#FF7733",
+    });
+    expect(r.applied).toBe(true);
+    expect(r.before).toContain("#FF8C42");
+    expect(r.after).toContain("#FF7733");
+    expect(r.next).toContain("#FF7733");
+    expect(r.next).not.toContain("#FF8C42");
+  });
+
+  it("removes a matching key", () => {
+    const r = patchDesignMd(SAMPLE, {
+      section: "color-palette",
+      operation: "remove",
+      key: "Surface",
+    });
+    expect(r.applied).toBe(true);
+    expect(r.before).toContain("Surface");
+    expect(r.next).not.toContain("Surface");
+    // Primary still there.
+    expect(r.next).toContain("Primary");
+  });
+
+  it("returns no-op + reason when section is absent", () => {
+    const r = patchDesignMd("# Empty\n", {
+      section: "color-palette",
+      operation: "add",
+      key: "X",
+      value: "#000",
+    });
+    expect(r.applied).toBe(false);
+    expect(r.reason).toContain("not found");
+    expect(r.next).toBe("# Empty\n");
+  });
+
+  it("requires a value on add/update", () => {
+    const r = patchDesignMd(SAMPLE, {
+      section: "color-palette",
+      operation: "add",
+      key: "Foo",
+    });
+    expect(r.applied).toBe(false);
+    expect(r.reason).toContain("required");
+  });
+});
+
+describe("patchDesignMd — components (H3)", () => {
+  it("adds a new component as an H3 heading", () => {
+    const r = patchDesignMd(
+      `# Test
+## Components
+
+### Button
+A primary action.
+`,
+      { section: "components", operation: "add", key: "Card" },
+    );
+    expect(r.applied).toBe(true);
+    expect(r.next).toContain("### Card");
+  });
+});
+
+describe("patchDesignMdBatch", () => {
+  it("applies operations in order against the cumulative source", () => {
+    const r = patchDesignMdBatch(SAMPLE, [
+      { section: "color-palette", operation: "add", key: "Accent", value: "#000" },
+      { section: "color-palette", operation: "remove", key: "Surface" },
+      { section: "color-palette", operation: "update", key: "Primary", value: "#111" },
+    ]);
+    expect(r.appliedCount).toBe(3);
+    expect(r.next).toContain("#111");
+    expect(r.next).toContain("#000");
+    expect(r.next).not.toContain("Surface");
+  });
+
+  it("partial success — failed ops surface in results, others still apply", () => {
+    const r = patchDesignMdBatch(SAMPLE, [
+      { section: "color-palette", operation: "remove", key: "doesnotexist" },
+      { section: "color-palette", operation: "add", key: "Accent", value: "#000" },
+    ]);
+    expect(r.appliedCount).toBe(1);
+    expect(r.results[0]?.applied).toBe(false);
+    expect(r.results[1]?.applied).toBe(true);
+  });
+});
+
+// ─── diff ─────────────────────────────────────────────────────────────
+
+describe("diffDesignSpecs", () => {
+  it("flags added / removed / changed color tokens", () => {
+    const local = parseDesignMd(`# A
+## Color Palette
+- Primary — #FF8C42 — brand
+- Surface — #FFF8F0 — background
+`);
+    const upstream = parseDesignMd(`# B
+## Color Palette
+- Primary — #FF7733 — brand
+- Accent — #1A1F36 — text
+`);
+    const d = diffDesignSpecs(local, upstream);
+    expect(d.colorPalette.find((e) => e.kind === "changed" && e.name === "Primary")).toBeDefined();
+    expect(d.colorPalette.find((e) => e.kind === "added" && e.name === "Accent")).toBeDefined();
+    expect(d.colorPalette.find((e) => e.kind === "removed" && e.name === "Surface")).toBeDefined();
+    expect(d.totalChanges).toBe(3);
+  });
+
+  it("returns empty diff when specs are identical at the structured level", () => {
+    const a = parseDesignMd(`# T
+## Color Palette
+- Primary — #FF8C42 — brand
+`);
+    const b = parseDesignMd(`# Different prose, same tokens
+## Color Palette
+- Primary — #FF8C42 — brand
+`);
+    const d = diffDesignSpecs(a, b);
+    expect(d.totalChanges).toBe(0);
+  });
+
+  it("surfaces section presence changes", () => {
+    const local = parseDesignMd(`# A\n## Color Palette\n- Primary — #FF8C42 — brand\n`);
+    const upstream = parseDesignMd(
+      `# B\n## Color Palette\n- Primary — #FF8C42 — brand\n## Agent Prompts\n### Brand voice\nTone.\n`,
+    );
+    const d = diffDesignSpecs(local, upstream);
+    expect(d.sectionPresenceChanged).toContain("agent-prompts");
+  });
+});

package/src/design/diff.ts

@@ -0,0 +1,138 @@
+/**
+ * DESIGN.md upstream diff (Issue #245 M4 §3.5 external loop).
+ *
+ * Compare a local DESIGN.md against an upstream source (typically a
+ * brand spec from awesome-design-md). The diff is computed at the
+ * **structured-token level** — added / changed / removed entries per
+ * section — so agents can patch only the sections the user wants to
+ * sync without touching free-form prose.
+ *
+ * The diff is intentionally narrow: it ignores prose changes inside
+ * `rawBody`, comment shifts, and heading wording differences. It
+ * answers one question — "did the upstream catalog gain, change, or
+ * drop a token compared to my local file?".
+ */
+
+import type { ColorToken, DesignSpec, ShadowToken, SpacingToken, TypographyToken } from "./types";
+
+export interface DiffEntryAddedRemoved<T> {
+  kind: "added" | "removed";
+  name: string;
+  token: T;
+}
+
+export interface DiffEntryChanged<T> {
+  kind: "changed";
+  name: string;
+  before: T;
+  after: T;
+}
+
+export type DiffEntry<T> =
+  | DiffEntryAddedRemoved<T>
+  | DiffEntryChanged<T>;
+
+export interface DesignSpecDiff {
+  /** Per-section diff arrays (only structured sections). */
+  colorPalette: DiffEntry<ColorToken>[];
+  typography: DiffEntry<TypographyToken>[];
+  layout: DiffEntry<SpacingToken>[];
+  shadows: DiffEntry<ShadowToken>[];
+  /** Total count of differences across all sections — convenience. */
+  totalChanges: number;
+  /** Sections whose `present` flag flipped between local and upstream. */
+  sectionPresenceChanged: string[];
+}
+
+/**
+ * Compute the diff. Pure — accepts already-parsed specs so callers
+ * own fetching / caching of the upstream source.
+ */
+export function diffDesignSpecs(local: DesignSpec, upstream: DesignSpec): DesignSpecDiff {
+  const colorPalette = diffByName(
+    local.sections["color-palette"].tokens,
+    upstream.sections["color-palette"].tokens,
+    (a, b) => a.value === b.value && a.role === b.role,
+  );
+  const typography = diffByName(
+    local.sections.typography.tokens,
+    upstream.sections.typography.tokens,
+    (a, b) =>
+      a.fontFamily === b.fontFamily &&
+      a.size === b.size &&
+      a.weight === b.weight &&
+      a.lineHeight === b.lineHeight,
+  );
+  const layout = diffByName(
+    local.sections.layout.tokens,
+    upstream.sections.layout.tokens,
+    (a, b) => a.value === b.value,
+  );
+  const shadows = diffByName(
+    local.sections.shadows.tokens,
+    upstream.sections.shadows.tokens,
+    (a, b) => a.value === b.value,
+  );
+
+  const sectionPresenceChanged: string[] = [];
+  for (const id of [
+    "theme",
+    "color-palette",
+    "typography",
+    "components",
+    "layout",
+    "shadows",
+    "dos-donts",
+    "responsive",
+    "agent-prompts",
+  ] as const) {
+    if (local.sections[id].present !== upstream.sections[id].present) {
+      sectionPresenceChanged.push(id);
+    }
+  }
+
+  const totalChanges = colorPalette.length + typography.length + layout.length + shadows.length;
+  return { colorPalette, typography, layout, shadows, totalChanges, sectionPresenceChanged };
+}
+
+interface NamedToken {
+  name: string;
+}
+
+function diffByName<T extends NamedToken>(
+  local: readonly T[],
+  upstream: readonly T[],
+  same: (a: T, b: T) => boolean,
+): DiffEntry<T>[] {
+  const localByKey = new Map<string, T>();
+  for (const t of local) localByKey.set(slug(t.name), t);
+  const upstreamByKey = new Map<string, T>();
+  for (const t of upstream) upstreamByKey.set(slug(t.name), t);
+
+  const entries: DiffEntry<T>[] = [];
+  for (const [key, upstreamToken] of upstreamByKey) {
+    const localToken = localByKey.get(key);
+    if (!localToken) {
+      entries.push({ kind: "added", name: upstreamToken.name, token: upstreamToken });
+      continue;
+    }
+    if (!same(localToken, upstreamToken)) {
+      entries.push({ kind: "changed", name: upstreamToken.name, before: localToken, after: upstreamToken });
+    }
+  }
+  for (const [key, localToken] of localByKey) {
+    if (!upstreamByKey.has(key)) {
+      entries.push({ kind: "removed", name: localToken.name, token: localToken });
+    }
+  }
+  return entries;
+}
+
+function slug(name: string): string {
+  return name
+    .normalize("NFKD")
+    .replace(/[^\w\s-]/g, "")
+    .trim()
+    .replace(/\s+/g, "-")
+    .toLowerCase();
+}

package/src/design/extract.ts

@@ -0,0 +1,284 @@
+/**
+ * DESIGN.md token extractor — scan project source for tokens that
+ * should be promoted into DESIGN.md (Issue #245 M4 §3.5 internal loop).
+ *
+ * Scope:
+ *   - **color**: `#rgb`, `#rrggbb`, `#rrggbbaa`, `rgb(...)`, `rgba(...)`,
+ *     `hsl(...)`, `oklch(...)` literals in TS/TSX/JSX/CSS/MDX sources.
+ *   - **font-family**: `font-family: "X", sans-serif` declarations and
+ *     Tailwind v4-style `--font-<slug>: ...;` tokens that don't yet
+ *     appear in DESIGN.md typography.
+ *   - **component**: identifier-style className combos that recur 3+
+ *     times across files, suggesting a missing extraction.
+ *
+ * The extractor is **proposal-only**: it never edits anything.
+ * Callers (CLI / MCP `mandu.design.extract`) decide whether to flow
+ * the proposals into DESIGN.md via `patchDesignMd`. Confidence is a
+ * coarse 0..1 score driven by occurrence count; agents can filter on
+ * it before showing the user.
+ *
+ * Performance: the walker bounds itself to the conventional source
+ * roots and skips dotfile dirs / node_modules. Large monorepos can
+ * narrow further with the `scope` option.
+ */
+
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import type { DesignSpec } from "./types";
+
+// ─── Public surface ───────────────────────────────────────────────────
+
+export type ExtractKind = "color" | "typography" | "spacing" | "component";
+
+export interface ExtractProposal {
+  kind: ExtractKind;
+  /** DESIGN.md section the proposal would land in. */
+  section: "color-palette" | "typography" | "layout" | "components";
+  /** Stable key to compare against existing tokens (slug or literal). */
+  key: string;
+  /** Suggested DESIGN.md value (`#FF8C42`, `Inter sans-serif`, …). */
+  value: string;
+  /** Total occurrences across the scanned tree. */
+  occurrences: number;
+  /** Up to 5 distinct file paths the literal/pattern was found in. */
+  files: string[];
+  /** Coarse 0..1 confidence — higher = more occurrences. */
+  confidence: number;
+  /** Optional human note ("seen in ButtonPrimary, ButtonGhost"). */
+  note?: string;
+}
+
+export interface ExtractOptions {
+  /** Glob-rooted scopes (relative). Defaults to `["src", "app"]`. */
+  scope?: readonly string[];
+  /** Filter the kinds emitted. Defaults to all four. */
+  kinds?: readonly ExtractKind[];
+  /** Minimum occurrence threshold for color/font/component. Default 3. */
+  minOccurrences?: number;
+  /**
+   * When provided, proposals already represented by an existing
+   * DesignSpec token are dropped (so agents only see "new" candidates).
+   */
+  existing?: DesignSpec;
+}
+
+export interface ExtractResult {
+  proposals: ExtractProposal[];
+  /** Total source files scanned. */
+  scannedFiles: number;
+}
+
+/**
+ * Walk the project and collect proposals. Pure async — no caching, no
+ * side effects beyond reads.
+ */
+export async function extractDesignTokens(
+  rootDir: string,
+  options: ExtractOptions = {},
+): Promise<ExtractResult> {
+  const scope = options.scope ?? ["src", "app"];
+  const kinds = new Set<ExtractKind>(options.kinds ?? ["color", "typography", "spacing", "component"]);
+  const minOccurrences = options.minOccurrences ?? 3;
+
+  const colorOccurrences = new Map<string, { files: Set<string>; count: number }>();
+  const fontFamilyOccurrences = new Map<string, { files: Set<string>; count: number }>();
+  const classnameComboOccurrences = new Map<string, { files: Set<string>; count: number }>();
+
+  let scannedFiles = 0;
+  for (const dir of scope) {
+    const root = path.join(rootDir, dir);
+    const files = await collectFiles(root);
+    scannedFiles += files.length;
+    for (const file of files) {
+      let content: string;
+      try {
+        content = await fs.readFile(file, "utf8");
+      } catch {
+        continue;
+      }
+      const rel = path.relative(rootDir, file).replace(/\\/g, "/");
+      if (kinds.has("color")) collectColors(content, rel, colorOccurrences);
+      if (kinds.has("typography")) collectFontFamilies(content, rel, fontFamilyOccurrences);
+      if (kinds.has("component")) collectClassNameCombos(content, rel, classnameComboOccurrences);
+    }
+  }
+
+  const proposals: ExtractProposal[] = [];
+  if (kinds.has("color")) {
+    proposals.push(
+      ...buildProposals({
+        section: "color-palette",
+        kind: "color",
+        keyer: (literal) => literal,
+        valuer: (literal) => literal,
+        seed: colorOccurrences,
+        minOccurrences,
+        existingKeys: collectExistingColorValues(options.existing),
+      }),
+    );
+  }
+  if (kinds.has("typography")) {
+    proposals.push(
+      ...buildProposals({
+        section: "typography",
+        kind: "typography",
+        keyer: (literal) => literal,
+        valuer: (literal) => literal,
+        seed: fontFamilyOccurrences,
+        minOccurrences,
+        existingKeys: collectExistingFontFamilies(options.existing),
+      }),
+    );
+  }
+  if (kinds.has("component")) {
+    proposals.push(
+      ...buildProposals({
+        section: "components",
+        kind: "component",
+        keyer: (literal) => literal,
+        valuer: (literal) => literal,
+        seed: classnameComboOccurrences,
+        minOccurrences,
+        existingKeys: new Set(),
+      }),
+    );
+  }
+
+  proposals.sort((a, b) => b.occurrences - a.occurrences);
+  return { proposals, scannedFiles };
+}
+
+// ─── Walker ───────────────────────────────────────────────────────────
+
+const SOURCE_RX = /\.(?:tsx?|jsx?|mdx?|css)$/;
+
+async function collectFiles(root: string): Promise<string[]> {
+  const out: string[] = [];
+  async function walk(dir: string): Promise<void> {
+    let entries: import("node:fs").Dirent[];
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+        await walk(full);
+      } else if (entry.isFile() && SOURCE_RX.test(entry.name)) {
+        out.push(full);
+      }
+    }
+  }
+  await walk(root);
+  return out;
+}
+
+// ─── Collectors ───────────────────────────────────────────────────────
+
+const COLOR_RX = /#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b|(?:rgba?|hsla?|oklch|hwb|lab|lch)\([^)]+\)/g;
+
+function collectColors(
+  content: string,
+  rel: string,
+  bucket: Map<string, { files: Set<string>; count: number }>,
+): void {
+  let m: RegExpExecArray | null;
+  while ((m = COLOR_RX.exec(content)) !== null) {
+    const literal = m[0]!.toLowerCase();
+    const entry = bucket.get(literal) ?? { files: new Set(), count: 0 };
+    entry.files.add(rel);
+    entry.count++;
+    bucket.set(literal, entry);
+  }
+}
+
+const FONT_FAMILY_RX = /font-family\s*:\s*([^;\n}]+)/gi;
+
+function collectFontFamilies(
+  content: string,
+  rel: string,
+  bucket: Map<string, { files: Set<string>; count: number }>,
+): void {
+  let m: RegExpExecArray | null;
+  while ((m = FONT_FAMILY_RX.exec(content)) !== null) {
+    const value = m[1]!.trim().replace(/[`'"]/g, "");
+    if (!value || value.length > 200) continue;
+    const entry = bucket.get(value) ?? { files: new Set(), count: 0 };
+    entry.files.add(rel);
+    entry.count++;
+    bucket.set(value, entry);
+  }
+}
+
+const CLASSNAME_RX = /className\s*=\s*["']([^"']{16,200})["']/g;
+
+function collectClassNameCombos(
+  content: string,
+  rel: string,
+  bucket: Map<string, { files: Set<string>; count: number }>,
+): void {
+  let m: RegExpExecArray | null;
+  while ((m = CLASSNAME_RX.exec(content)) !== null) {
+    const literal = m[1]!.trim().split(/\s+/).sort().join(" ");
+    if (!literal) continue;
+    // Skip combos that are mostly variant prefixes — they're rarely
+    // good extraction candidates.
+    const tokenCount = literal.split(/\s+/).length;
+    if (tokenCount < 3) continue;
+    const entry = bucket.get(literal) ?? { files: new Set(), count: 0 };
+    entry.files.add(rel);
+    entry.count++;
+    bucket.set(literal, entry);
+  }
+}
+
+// ─── Proposal builder ────────────────────────────────────────────────
+
+interface BuildProposalsArgs {
+  section: ExtractProposal["section"];
+  kind: ExtractKind;
+  keyer: (literal: string) => string;
+  valuer: (literal: string) => string;
+  seed: Map<string, { files: Set<string>; count: number }>;
+  minOccurrences: number;
+  existingKeys: Set<string>;
+}
+
+function buildProposals(args: BuildProposalsArgs): ExtractProposal[] {
+  const out: ExtractProposal[] = [];
+  for (const [literal, info] of args.seed) {
+    if (info.count < args.minOccurrences) continue;
+    const key = args.keyer(literal).toLowerCase();
+    if (args.existingKeys.has(key)) continue;
+    out.push({
+      kind: args.kind,
+      section: args.section,
+      key: literal,
+      value: args.valuer(literal),
+      occurrences: info.count,
+      files: [...info.files].slice(0, 5),
+      confidence: Math.min(1, info.count / 10),
+    });
+  }
+  return out;
+}
+
+function collectExistingColorValues(spec: DesignSpec | undefined): Set<string> {
+  const out = new Set<string>();
+  if (!spec) return out;
+  for (const t of spec.sections["color-palette"].tokens) {
+    if (t.value) out.add(t.value.toLowerCase());
+  }
+  return out;
+}
+
+function collectExistingFontFamilies(spec: DesignSpec | undefined): Set<string> {
+  const out = new Set<string>();
+  if (!spec) return out;
+  for (const t of spec.sections.typography.tokens) {
+    if (t.fontFamily) out.add(t.fontFamily.toLowerCase());
+  }
+  return out;
+}

package/src/design/index.ts

@@ -34,6 +34,29 @@ export {
   type ThemeMergeResult,
 } from "./tailwind-theme";
 
+export {
+  extractDesignTokens,
+  type ExtractKind,
+  type ExtractOptions,
+  type ExtractProposal,
+  type ExtractResult,
+} from "./extract";
+
+export {
+  patchDesignMd,
+  patchDesignMdBatch,
+  type PatchableSection,
+  type PatchOperation,
+  type PatchResult,
+  type PatchBatchResult,
+} from "./patch";
+
+export {
+  diffDesignSpecs,
+  type DesignSpecDiff,
+  type DiffEntry,
+} from "./diff";
+
 export type {
   AgentPrompt,
   AgentPromptsSection,

package/src/design/patch.ts

@@ -0,0 +1,242 @@
+/**
+ * Section-safe DESIGN.md patcher (Issue #245 M4 §3.5).
+ *
+ * The patcher rewrites only the *body* of a target H2 section, leaving:
+ *   - the H1 title and other H2 sections untouched (verbatim)
+ *   - the target heading line itself untouched
+ *   - any free-form prose between the heading and the first structured
+ *     row preserved
+ *
+ * Operations are scoped to one `(section, key)` pair at a time so an
+ * agent can stream multiple patches without re-loading the file. The
+ * `dryRun` flag returns the would-be next source without writing it,
+ * so MCP tools can show the user a diff before committing.
+ *
+ * Token row rules per section:
+ *   - color-palette / shadows / layout / typography: bullet rows of
+ *     the form `- <Name> — <value>` (extra columns preserved verbatim
+ *     for `update`).
+ *   - components: H3 sub-headings with optional bullet body.
+ *
+ * Unsupported sections return `{ applied: false, reason: ... }` —
+ * they're free-form by design. Callers decide whether to surface the
+ * limitation or fall back to a hand-edit.
+ */
+
+import { parseDesignMd } from "./parser";
+
+export type PatchableSection =
+  | "color-palette"
+  | "typography"
+  | "layout"
+  | "shadows"
+  | "components";
+
+export interface PatchOperation {
+  section: PatchableSection;
+  /** "add" creates the row; "update" replaces an existing matching row;
+   *  "remove" deletes a matching row. */
+  operation: "add" | "update" | "remove";
+  /** Token name. Match is case-insensitive on the slug. */
+  key: string;
+  /** Required for `add` / `update`. Free-form value (`#FF8C42`,
+   *  `Inter, sans-serif`, `0 1px 3px rgba(...)`). */
+  value?: string;
+  /** Optional functional role / usage hint (color/shadow). */
+  role?: string;
+}
+
+export interface PatchResult {
+  applied: boolean;
+  /** Reason the operation was a no-op or rejected. */
+  reason?: string;
+  /** Source after applying — same as input when not applied. */
+  next: string;
+  /** Old row (for `update` / `remove`). Undefined for clean adds. */
+  before?: string;
+  /** New row (for `add` / `update`). Undefined for `remove`. */
+  after?: string;
+}
+
+const HEADING_BY_SECTION: Record<PatchableSection, RegExp> = {
+  "color-palette": /^##\s+.*?(color|palette).*$/im,
+  typography: /^##\s+.*?(typograph|typeface|font|type scale).*$/im,
+  layout: /^##\s+.*?(layout|spacing|grid).*$/im,
+  shadows: /^##\s+.*?(shadow|elevation|depth).*$/im,
+  components: /^##\s+.*?(component|button|card|input).*$/im,
+};
+
+/**
+ * Apply a single patch. Pure — does not touch the filesystem.
+ *
+ * The result's `applied` flag tells the caller whether the source
+ * actually changed (e.g. `remove` of a non-existent key returns
+ * `applied: false` with `reason`).
+ */
+export function patchDesignMd(source: string, op: PatchOperation): PatchResult {
+  const headingRx = HEADING_BY_SECTION[op.section];
+  const headingMatch = headingRx.exec(source);
+  if (!headingMatch) {
+    return {
+      applied: false,
+      reason: `Section "${op.section}" not found in DESIGN.md`,
+      next: source,
+    };
+  }
+
+  const sectionStart = headingMatch.index + headingMatch[0].length;
+  const nextHeadingIdx = source.indexOf("\n## ", sectionStart);
+  const sectionEnd = nextHeadingIdx >= 0 ? nextHeadingIdx : source.length;
+  const sectionBody = source.slice(sectionStart, sectionEnd);
+
+  const updated = applyToBody(sectionBody, op);
+  if (!updated.applied) {
+    return { ...updated, next: source };
+  }
+
+  const next = source.slice(0, sectionStart) + updated.body + source.slice(sectionEnd);
+  return {
+    applied: true,
+    next,
+    before: updated.before,
+    after: updated.after,
+  };
+}
+
+interface BodyApplyResult {
+  applied: boolean;
+  reason?: string;
+  body: string;
+  before?: string;
+  after?: string;
+}
+
+function applyToBody(body: string, op: PatchOperation): BodyApplyResult {
+  const lines = body.split(/\r?\n/);
+  const targetSlug = slug(op.key);
+
+  const matchIdx = lines.findIndex((line) => {
+    const row = parseTokenRow(line, op.section);
+    return row !== null && slug(row.name) === targetSlug;
+  });
+
+  if (op.operation === "remove") {
+    if (matchIdx < 0) {
+      return { applied: false, reason: `No row with name "${op.key}"`, body };
+    }
+    const before = lines[matchIdx]!;
+    lines.splice(matchIdx, 1);
+    return { applied: true, body: lines.join("\n"), before };
+  }
+
+  if (op.operation === "update") {
+    if (matchIdx < 0) {
+      return { applied: false, reason: `No row with name "${op.key}"`, body };
+    }
+    if (op.value === undefined) {
+      return { applied: false, reason: "`value` is required for update", body };
+    }
+    const before = lines[matchIdx]!;
+    const after = renderRow(op);
+    lines[matchIdx] = after;
+    return { applied: true, body: lines.join("\n"), before, after };
+  }
+
+  // add — value is required for token rows, optional for component H3
+  if (op.section !== "components" && op.value === undefined) {
+    return { applied: false, reason: "`value` is required for add", body };
+  }
+  if (matchIdx >= 0) {
+    return {
+      applied: false,
+      reason: `Row "${op.key}" already exists — use update or remove first`,
+      body,
+    };
+  }
+
+  const after = renderRow(op);
+  // Find the last existing token row to anchor the insertion. When
+  // none exist, insert at the bottom of the section before any
+  // trailing whitespace.
+  let insertAt = lines.length;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (parseTokenRow(lines[i]!, op.section) !== null) {
+      insertAt = i + 1;
+      break;
+    }
+  }
+  lines.splice(insertAt, 0, after);
+  // Ensure the section body keeps its trailing blank line before the
+  // next H2 (or EOF) so subsequent patches don't crowd headers.
+  let next = lines.join("\n");
+  if (!next.endsWith("\n")) next = `${next}\n`;
+  return { applied: true, body: next, after };
+}
+
+interface ParsedTokenRow {
+  name: string;
+  rest: string;
+}
+
+function parseTokenRow(line: string, section: PatchableSection): ParsedTokenRow | null {
+  if (section === "components") {
+    const h3 = /^###\s+(.+?)\s*$/.exec(line);
+    if (h3) return { name: h3[1]!, rest: "" };
+    return null;
+  }
+  const stripped = line.trim().replace(/^[-*+]\s*/, "");
+  if (!stripped || /^[#|]/.test(stripped)) return null;
+  const m = /^([^—:|]+?)\s*[—:–|]\s*(.+)$/.exec(stripped);
+  if (!m) return null;
+  return { name: m[1]!.replace(/[`*_]/g, "").trim(), rest: m[2]!.trim() };
+}
+
+function renderRow(op: PatchOperation): string {
+  if (op.section === "components") {
+    return `### ${op.key}`;
+  }
+  const value = op.value ?? "";
+  const role = op.role ? ` — ${op.role}` : "";
+  return `- ${op.key} — ${value}${role}`;
+}
+
+function slug(name: string): string {
+  return name
+    .normalize("NFKD")
+    .replace(/[^\w\s-]/g, "")
+    .trim()
+    .replace(/\s+/g, "-")
+    .toLowerCase();
+}
+
+// ─── Multi-op sugar ───────────────────────────────────────────────────
+
+export interface PatchBatchResult {
+  next: string;
+  results: PatchResult[];
+  appliedCount: number;
+}
+
+/**
+ * Apply a list of operations in order. Each operation runs against
+ * the cumulative source — later ops see earlier ones. Failures are
+ * surfaced per-entry but never abort the batch (so a partial success
+ * is observable).
+ */
+export function patchDesignMdBatch(
+  source: string,
+  ops: readonly PatchOperation[],
+): PatchBatchResult {
+  let current = source;
+  const results: PatchResult[] = [];
+  let appliedCount = 0;
+  for (const op of ops) {
+    const r = patchDesignMd(current, op);
+    results.push(r);
+    if (r.applied) {
+      appliedCount++;
+      current = r.next;
+    }
+  }
+  return { next: current, results, appliedCount };
+}