@mandujs/core 0.52.0 → 0.53.1

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/extract.ts

@@ -1,3 +1,4 @@
+import type * as __ManduNodeFsTypes0 from "node:fs";
 /**
  * DESIGN.md token extractor — scan project source for tokens that
  * should be promoted into DESIGN.md (Issue #245 M4 §3.5 internal loop).
@@ -155,7 +156,7 @@ 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[];
+    let entries: __ManduNodeFsTypes0.Dirent[];
     try {
       entries = await fs.readdir(dir, { withFileTypes: true });
     } catch {

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 };
+}

package/src/design/patch.ts

@@ -23,7 +23,6 @@
  * limitation or fall back to a hand-edit.
  */
 
-import { parseDesignMd } from "./parser";
 
 export type PatchableSection =
   | "color-palette"

package/src/devtools/ai/mcp-connector.ts

@@ -165,26 +165,26 @@ export class MCPConnector {
       try {
         this.ws = new WebSocket(url);
 
-        this.ws.onopen = () => {
-          clearTimeout(timeout);
-          this.setStatus('connected');
-          this.reconnectAttempts = 0;
-          resolve();
-        };
-
-        this.ws.onclose = () => {
-          this.handleDisconnect();
-        };
-
-        this.ws.onerror = (event) => {
-          clearTimeout(timeout);
-          this.handleConnectionError(new Error('WebSocket error'));
-          reject(new Error('WebSocket connection failed'));
-        };
-
-        this.ws.onmessage = (event) => {
-          this.handleMessage(event.data);
-        };
+        this.ws.addEventListener('open', () => {
+          clearTimeout(timeout);
+          this.setStatus('connected');
+          this.reconnectAttempts = 0;
+          resolve();
+        });
+
+        this.ws.addEventListener('close', () => {
+          this.handleDisconnect();
+        });
+
+        this.ws.addEventListener('error', () => {
+          clearTimeout(timeout);
+          this.handleConnectionError(new Error('WebSocket error'));
+          reject(new Error('WebSocket connection failed'));
+        });
+
+        this.ws.addEventListener('message', (event) => {
+          this.handleMessage(event.data);
+        });
       } catch (error) {
         clearTimeout(timeout);
         this.handleConnectionError(
@@ -210,10 +210,10 @@ export class MCPConnector {
     }
 
     // 대기 중인 요청 모두 reject
-    for (const [id, pending] of this.pendingRequests) {
-      clearTimeout(pending.timeout);
-      pending.reject(new Error('Connection closed'));
-    }
+    for (const [, pending] of this.pendingRequests) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error('Connection closed'));
+    }
     this.pendingRequests.clear();
 
     this.setStatus('disconnected');

package/src/devtools/client/components/kitchen-root.tsx

@@ -7,7 +7,7 @@
 
 import React, { useEffect, useState, useCallback, useMemo } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
-import type { NormalizedError, DevToolsConfig, IslandSnapshot, NetworkRequest, DevToolsGuardViolation } from '../../types';
+import type { NormalizedError, DevToolsConfig } from '../../types';
 import { generateCSSVariables, testIds, zIndex } from '../../design-tokens';
 import { getStateManager, type KitchenState } from '../state-manager';
 import { getOrCreateHook } from '../../hook';

package/src/devtools/client/components/panel/errors-panel.tsx

@@ -159,7 +159,7 @@ export interface ErrorsPanelProps {
 export function ErrorsPanel({
   errors,
   onErrorClick,
-  onErrorIgnore,
+  onErrorIgnore: _onErrorIgnore,
   onClearAll,
 }: ErrorsPanelProps): React.ReactElement {
   const formatTime = useCallback((timestamp: number): string => {

package/src/devtools/client/state-manager.ts

@@ -257,7 +257,7 @@ export class KitchenStateManager {
     }
   }
 
-  setIslandHydrated(id: string, time: number): void {
+  setIslandHydrated(id: string, _time: number): void {
     this.updateIsland(id, {
       status: 'hydrated',
       hydrateEndTime: Date.now(),

package/src/devtools/init.ts

@@ -17,10 +17,9 @@ import {
   initializePersistence,
   destroyPersistence,
   getStateManager,
-  getPersistenceManager,
 } from './client';
 import { initializeWorkerManager, destroyWorkerManager } from './worker';
-import { getContextBuilder, resetContextBuilder, getMCPConnector, destroyMCPConnector } from './ai';
+import { getContextBuilder, resetContextBuilder, destroyMCPConnector } from './ai';
 
 // ============================================================================
 // Types
@@ -134,7 +133,7 @@ export function initManduKitchen(config: DevToolsConfig = {}): KitchenInstance {
     });
 
     // 6. v1.1: AI Context Builder 초기화
-    const contextBuilder = getContextBuilder({ config });
+    const _contextBuilder = getContextBuilder({ config });
 
     // 7. UI 마운트
     mountKitchen(config);

package/src/devtools/server/source-context.ts

@@ -424,7 +424,7 @@ export function createViteMiddleware(projectRoot: string) {
       res.setHeader('Cache-Control', 'no-store');
       res.statusCode = result.success ? 200 : 400;
       res.end(JSON.stringify(result));
-    } catch (error) {
+    } catch  {
       res.statusCode = 500;
       res.end(JSON.stringify({
         success: false,