@kitn.ai/ui 0.25.2 → 0.27.0

package/src/agent-tooling/mcp/tools/theme.ts

@@ -1,17 +1,138 @@
 import { z } from 'zod';
+import themeCss from '../../../../theme.css?raw';
 import type { Tool } from './types';
 
 /**
  * theme — produce a `--kai-*` CSS token override block from a brand color or
- * description. Tokens are sourced exclusively from the real names in theme.css.
+ * description.
  *
- * Real --kai-color-* names (verified against repo-root theme.css):
- *   --kai-color-primary            → brand color
- *   --kai-color-primary-foreground → AA-contrast fg (white or black)
- *   --kai-color-ring               → focus ring (brand color)
- *   --kai-color-accent             → tinted accent surface
- *   --kai-color-accent-foreground  → text on accent surface
+ * WHICH tokens get branded is a curated product call (see BRAND_TOKENS below).
+ * Their NAMES are not: every one is resolved against theme.css, whose text is
+ * inlined above, so a name this tool emits is a name theme.css declares.
+ *
+ * That import is the whole fix and the reason it is an import rather than a
+ * `readFile`. This module ships inside dist/mcp.es.js, an SSR bundle a consumer
+ * runs from bin/mcp.js in their node_modules — a runtime read of a repo-root
+ * path resolves to nothing there, and the src/ and dist/ depths differ anyway.
+ * `?raw` bakes the bytes in at build time from the SAME theme.css that
+ * package.json `files` ships (and `exports` publishes as "./theme.css"), so the
+ * tarball's tool and the tarball's stylesheet cannot disagree by construction,
+ * and there is no runtime I/O at all.
+ *
+ * Before this, the names were five string literals and a docblock claiming they
+ * had been "verified against repo-root theme.css" — nothing read that file, so
+ * renaming a token left the tool emitting the dead name, its test green, and an
+ * agent pasting CSS that themes nothing.
+ */
+
+// ─── token names, read out of theme.css ──────────────────────────────────────
+
+/**
+ * Every `--kai-*` knob theme.css declares. Anchored on `var(` because that is
+ * the only place a knob is really wired up — each kit token is written
+ * `--color-x: var(--kai-color-x, <default>)`. Prose in the file mentions
+ * wildcards like `--kai-color-*`, which a bare `--kai-` scan would pick up as
+ * fictional token names.
+ */
+function declaredKaiTokens(css: string): ReadonlySet<string> {
+  const names = new Set<string>();
+  for (const m of css.matchAll(/var\(\s*(--kai-[a-zA-Z0-9-]+)\s*[,)]/g)) names.add(m[1]);
+  return names;
+}
+
+const DECLARED_TOKENS = declaredKaiTokens(themeCss);
+
+/**
+ * Resolve one `--kai-color-<suffix>` against theme.css, or fail naming it.
+ *
+ * Refusing is deliberate — emitting a token nothing reads is the whole defect
+ * this file exists to prevent — but it happens on the HANDLER path, not at
+ * module load. `server.ts` imports all four tools statically at top level, so a
+ * module-scope throw here took `reference`, `scaffold` and `debug` down with it;
+ * measured against an installed tarball, `initialize` never returned and the
+ * server exited before answering anything. Nothing was bought for that: the
+ * guard in theme.test.ts calls `theme.handler(...)` directly, so it goes red on
+ * exactly the same rename with exactly the same message either way. Handler
+ * scope is pure isolation — `theme` alone reports the error, its three
+ * neighbours keep working.
+ */
+function colorToken(suffix: string): string {
+  const name = `--kai-color-${suffix}`;
+  if (!DECLARED_TOKENS.has(name)) {
+    throw new Error(
+      `[kai mcp: theme] theme.css declares no \`${name}\`. The tool brands that token, ` +
+        `so emitting it would hand the caller CSS that themes nothing. Either the token was ` +
+        `renamed in packages/ui/theme.css (update the BRAND_TOKENS suffix in ` +
+        `src/agent-tooling/mcp/tools/theme.ts to match) or it was removed (drop the entry). ` +
+        `Known --kai-color-* names: ${[...DECLARED_TOKENS].filter((n) => n.startsWith('--kai-color-')).sort().join(', ')}`,
+    );
+  }
+  return name;
+}
+
+interface TokenSet {
+  primary: string;
+  primaryFg: string;
+  ring: string;
+  accent: string;
+  accentFg: string;
+}
+
+interface BrandToken {
+  /** Which computed value from a TokenSet fills this token. */
+  key: keyof TokenSet;
+  /** `--kai-color-<suffix>`, checked against theme.css. */
+  suffix: string;
+  /** One-line explanation, rendered in the "Tokens emitted" list. */
+  purpose: string;
+}
+
+/**
+ * The tokens a brand override needs, in emit order. This LIST is the curated
+ * part — it is a judgement about what rebranding means, not a fact theme.css can
+ * be asked for. It declares far more knobs than this (the error in colorToken
+ * prints the current set); dumping all of them would be a worse answer than
+ * picking the ones that carry a brand. The `suffix` of each is what gets checked.
  */
+const BRAND_TOKENS: readonly BrandToken[] = [
+  { key: 'primary', suffix: 'primary', purpose: 'primary brand color' },
+  {
+    key: 'primaryFg',
+    suffix: 'primary-foreground',
+    purpose: 'AA-contrast foreground on primary (auto-selected black/white)',
+  },
+  { key: 'ring', suffix: 'ring', purpose: 'keyboard focus ring' },
+  { key: 'accent', suffix: 'accent', purpose: 'tinted accent surface' },
+  { key: 'accentFg', suffix: 'accent-foreground', purpose: 'text on accent surface' },
+];
+
+interface EmittedTokens {
+  readonly tokens: readonly { key: keyof TokenSet; name: string; purpose: string }[];
+  /** Value-column offset, derived so the block stays aligned when a name changes length. */
+  readonly valueColumn: number;
+}
+
+let memo: EmittedTokens | undefined;
+
+/**
+ * BRAND_TOKENS with each name resolved against theme.css, memoized.
+ *
+ * Called from the handler, so the resolution failure lands on the one tool that
+ * cannot do its job (see colorToken). Only a SUCCESSFUL resolution is cached —
+ * a failing one re-throws per call, which is what keeps the error the same on
+ * the second request as on the first.
+ */
+function emittedTokens(): EmittedTokens {
+  if (!memo) {
+    const tokens = BRAND_TOKENS.map((t) => ({
+      key: t.key,
+      name: colorToken(t.suffix),
+      purpose: t.purpose,
+    }));
+    memo = { tokens, valueColumn: Math.max(...tokens.map((t) => t.name.length + 1)) + 2 };
+  }
+  return memo;
+}
 
 // ─── hex color utilities (no deps) ──────────────────────────────────────────
 
@@ -185,14 +306,6 @@ function resolveBrand(
 
 // ─── CSS block builders ───────────────────────────────────────────────────────
 
-interface TokenSet {
-  primary: string;
-  primaryFg: string;
-  ring: string;
-  accent: string;
-  accentFg: string;
-}
-
 function buildTokenSet(r: number, g: number, b: number): TokenSet {
   const primary = toHex(r, g, b);
   const primaryFg = foreground(r, g, b);
@@ -228,14 +341,12 @@ function buildDarkTokenSet(r: number, g: number, b: number): TokenSet {
   };
 }
 
-function cssBlock(selector: string, tokens: TokenSet): string {
+function cssBlock(selector: string, values: TokenSet, emitted: EmittedTokens): string {
   return [
     `${selector} {`,
-    `  --kai-color-primary:             ${tokens.primary};`,
-    `  --kai-color-primary-foreground:  ${tokens.primaryFg};`,
-    `  --kai-color-ring:                ${tokens.ring};`,
-    `  --kai-color-accent:              ${tokens.accent};`,
-    `  --kai-color-accent-foreground:   ${tokens.accentFg};`,
+    ...emitted.tokens.map(
+      (t) => `  ${`${t.name}:`.padEnd(emitted.valueColumn)}${values[t.key]};`,
+    ),
     `}`,
   ].join('\n');
 }
@@ -274,6 +385,10 @@ export const theme: Tool = {
       mode = 'light',
     } = args as { brand?: string; description?: string; mode?: 'light' | 'dark' | 'both' };
 
+    // Resolve the token names against theme.css FIRST, so a name it no longer
+    // declares fails this call and nothing else (see emittedTokens/colorToken).
+    const emitted = emittedTokens();
+
     const { hex, r, g, b, note } = resolveBrand(brand, description);
 
     const lightTokens = buildTokenSet(r, g, b);
@@ -282,10 +397,10 @@ export const theme: Tool = {
     // Which blocks to emit
     const blocks: string[] = [];
     if (mode === 'light' || mode === 'both') {
-      blocks.push(cssBlock(':root', lightTokens));
+      blocks.push(cssBlock(':root', lightTokens, emitted));
     }
     if (mode === 'dark' || mode === 'both') {
-      blocks.push(cssBlock('.dark', darkTokens));
+      blocks.push(cssBlock('.dark', darkTokens, emitted));
     }
 
     const cssOutput = blocks.join('\n\n');
@@ -293,6 +408,11 @@ export const theme: Tool = {
     const noteLabel = note.startsWith('Could not parse') ? 'Note' : 'Assumption';
     const noteSection = note ? `\n> **${noteLabel}:** ${note}\n` : '';
 
+    // Same list, same source, so the prose can't describe a different set of
+    // tokens than the CSS block above it.
+    const tokenList = emitted.tokens.map((t) => `- \`${t.name}\` — ${t.purpose}`).join('\n');
+    const firstToken = emitted.tokens[0].name;
+
     const text = `\
 ## AI/UI theme override — \`${hex}\`
 ${noteSection}
@@ -304,14 +424,10 @@ ${cssOutput}
 
 ### How it works
 
-The \`--kai-color-*\` tokens pierce the Shadow DOM via CSS custom-property inheritance. Every \`kai-*\` element reads them through a \`var(--kai-color-primary, <default>)\` fallback chain defined in \`theme.css\`. Setting them on \`:root\` (or a wrapper element) is enough to rebrand everything globally.
+The \`--kai-color-*\` tokens pierce the Shadow DOM via CSS custom-property inheritance. Every \`kai-*\` element reads them through a \`var(${firstToken}, <default>)\` fallback chain defined in \`theme.css\`. Setting them on \`:root\` (or a wrapper element) is enough to rebrand everything globally.
 
-**Tokens emitted** (verified names from \`theme.css\`):
-- \`--kai-color-primary\` — primary brand color
-- \`--kai-color-primary-foreground\` — AA-contrast foreground on primary (auto-selected black/white)
-- \`--kai-color-ring\` — keyboard focus ring
-- \`--kai-color-accent\` — tinted accent surface
-- \`--kai-color-accent-foreground\` — text on accent surface
+**Tokens emitted** (names read from \`theme.css\`):
+${tokenList}
 
 ### Apply to a subtree only
 

package/src/agent-tooling/mcp/validate-args.ts

@@ -0,0 +1,141 @@
+import { z } from 'zod';
+
+/**
+ * The ONE argument-validation path for every AI/UI MCP tool. server.ts calls
+ * this at dispatch, before any handler runs.
+ *
+ * Why it exists: every tool advertises `additionalProperties: false` and a
+ * `required` list over the protocol, and dispatch used to enforce neither —
+ * `request.params.arguments` went straight to the handler. The observed cost
+ * (ladder spec candidate A, twice reproduced): `component_reference` called
+ * with `{ element: "kai-chat" }` instead of `{ name: "kai-chat" }` silently
+ * returned the full element index with `isError` unset — an answer to a
+ * question nobody asked, indistinguishable from success. Decide loudly.
+ *
+ * Scope: unknown keys and missing required keys — the two failures the declared
+ * schema promises to reject and the handler cannot see (an unknown key is
+ * invisible to a handler that only reads the keys it knows). Value TYPES stay
+ * with the handlers, which already own them with better context (e.g. the
+ * provider guard in reference.ts, the registry checks in scaffold.ts).
+ *
+ * Everything here is DERIVED from the tool's zod schema — key list, requiredness
+ * (does the key's schema accept `undefined`?), type words — never restated, so a
+ * schema change moves the error text on its own.
+ */
+
+/** Levenshtein distance, for near-miss key suggestions ("framwork" → "framework"). */
+function editDistance(a: string, b: string): number {
+  const prev = new Array<number>(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    let diag = prev[0];
+    prev[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const tmp = prev[j];
+      prev[j] = Math.min(
+        prev[j] + 1,
+        prev[j - 1] + 1,
+        diag + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+      diag = tmp;
+    }
+  }
+  return prev[b.length];
+}
+
+/** A short type word for one property, read off the tool's advertised JSON Schema. */
+function typeWord(prop: Record<string, unknown> | undefined): string {
+  if (!prop) return 'value';
+  if (Array.isArray(prop.enum)) return prop.enum.map((v) => JSON.stringify(v)).join(' | ');
+  if (prop.type === 'array') {
+    const items = prop.items as Record<string, unknown> | undefined;
+    return `array of ${typeof items?.type === 'string' ? items.type : 'values'}`;
+  }
+  return typeof prop.type === 'string' ? prop.type : 'value';
+}
+
+/**
+ * Which schema key an unknown key most likely meant.
+ *
+ * 1. Spelling: edit distance ≤ 2 to a schema key ("framwork" → "framework").
+ * 2. Value shape: if exactly one NOT-yet-supplied schema key accepts the value
+ *    the caller passed, that's the one ("element": "kai-chat" → "name", because
+ *    `name` takes a string and `provider`'s enum rejects it). Two candidates
+ *    means guessing, so no suggestion — the expected-arguments block below the
+ *    message still teaches.
+ */
+function suggestKey(
+  unknownKey: string,
+  value: unknown,
+  shape: z.ZodRawShape,
+  supplied: readonly string[],
+): string | undefined {
+  const keys = Object.keys(shape);
+  let best: string | undefined;
+  let bestDistance = 3; // accept ≤ 2
+  for (const key of keys) {
+    const d = editDistance(unknownKey.toLowerCase(), key.toLowerCase());
+    if (d < bestDistance) {
+      bestDistance = d;
+      best = key;
+    }
+  }
+  if (best !== undefined) return best;
+
+  const byValue = keys.filter(
+    (key) => !supplied.includes(key) && z.safeParse(shape[key] as z.ZodType, value).success,
+  );
+  return byValue.length === 1 ? byValue[0] : undefined;
+}
+
+/**
+ * Validate `args` against a tool's declared zod object schema. Returns the full
+ * teaching error text on failure, or `undefined` when the arguments conform.
+ */
+export function validateToolArgs(
+  toolName: string,
+  schema: z.ZodObject<z.ZodRawShape>,
+  args: Record<string, unknown>,
+): string | undefined {
+  const shape = schema.shape;
+  const keys = Object.keys(shape);
+  const supplied = Object.keys(args);
+
+  const problems: string[] = [];
+
+  for (const key of supplied) {
+    if (keys.includes(key)) continue;
+    const suggestion = suggestKey(key, args[key], shape, supplied);
+    problems.push(
+      `unknown argument ${JSON.stringify(key)}` +
+        (suggestion ? ` — did you mean ${JSON.stringify(suggestion)}?` : ''),
+    );
+  }
+
+  for (const key of keys) {
+    // Required = the key's own schema refuses `undefined`. Derived, not listed.
+    if (!(key in args) && !z.safeParse(shape[key] as z.ZodType, undefined).success) {
+      problems.push(`missing required argument ${JSON.stringify(key)}`);
+    }
+  }
+
+  if (problems.length === 0) return undefined;
+
+  // The expected-arguments block, from the same JSON Schema the tool advertises.
+  const json = z.toJSONSchema(schema) as {
+    properties?: Record<string, Record<string, unknown>>;
+    required?: string[];
+  };
+  const required = new Set(json.required ?? []);
+  const argLines = keys.map((key) => {
+    const kind = required.has(key) ? 'required' : 'optional';
+    return `  ${key} (${kind}) — ${typeWord(json.properties?.[key])}`;
+  });
+
+  return (
+    `${toolName}: ${problems.join('; ')}.\n\n` +
+    `Nothing was returned for this call — answering anyway could look like a reply ` +
+    `to the question you meant to ask.\n\n` +
+    `Expected arguments for ${toolName}:\n${argLines.join('\n')}`
+  );
+}