@mandujs/core 0.53.3 → 0.54.0

package/src/design/agents-link.ts

@@ -1,165 +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"),
-  };
-}
+/**
+ * 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/diff.ts

@@ -1,138 +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();
-}
+/**
+ * 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();
+}