@design-ai/cli 4.55.0

package/cli/lib/log.mjs

@@ -0,0 +1,47 @@
+// Terminal output helpers.
+
+const isTTY = process.stdout.isTTY;
+const noColor = process.env.NO_COLOR || !isTTY;
+
+const codes = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  cyan: "\x1b[36m",
+};
+
+const c = (color) => (s) => noColor ? s : `${codes[color]}${s}${codes.reset}`;
+
+export const bold = c("bold");
+export const dim = c("dim");
+export const red = c("red");
+export const green = c("green");
+export const yellow = c("yellow");
+export const blue = c("blue");
+export const cyan = c("cyan");
+
+export const info = (msg) => console.log(`${blue("ℹ")}  ${msg}`);
+export const success = (msg) => console.log(`${green("✓")}  ${msg}`);
+export const warn = (msg) => console.log(`${yellow("⚠")}  ${msg}`);
+export const error = (msg) => console.error(`${red("✗")}  ${msg}`);
+
+export function header(title, subtitle) {
+  if (noColor) {
+    console.log(`\n  ${title}`);
+    if (subtitle) console.log(`  ${subtitle}`);
+    console.log();
+    return;
+  }
+  const w = 64;
+  const top = `${codes.blue}╔${"═".repeat(w - 2)}╗${codes.reset}`;
+  const bot = `${codes.blue}╚${"═".repeat(w - 2)}╝${codes.reset}`;
+  const pad = (s) => `${codes.blue}║${codes.reset}  ${s.padEnd(w - 5)}${codes.blue}║${codes.reset}`;
+  console.log(`\n${top}`);
+  console.log(pad(bold(title)));
+  if (subtitle) console.log(pad(dim(subtitle)));
+  console.log(`${bot}\n`);
+}

package/cli/lib/mcp-server.mjs

@@ -0,0 +1,426 @@
+// Minimal stdio MCP server for exposing design-ai CLI workflows to Claude/Codex.
+
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+import { DESIGN_AI_HOME, PACKAGE_ROOT } from "./paths.mjs";
+
+const PROTOCOL_VERSION = "2025-11-25";
+const MAX_TOOL_OUTPUT_BYTES = 220_000;
+const DESIGN_AI_BIN = path.join(PACKAGE_ROOT, "cli", "bin", "design-ai.mjs");
+
+function optionalString(description = "") {
+  return { type: "string", description };
+}
+
+function optionalBoolean(description = "") {
+  return { type: "boolean", description };
+}
+
+function optionalInteger({ description = "", minimum = 1, maximum = 100 } = {}) {
+  return { type: "integer", minimum, maximum, description };
+}
+
+export const MCP_TOOLS = [
+  {
+    name: "design_ai_route",
+    title: "Route a design task",
+    description: "Recommend the best design-ai route, command, skills, and knowledge files for a task brief. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        brief: { type: "string", minLength: 1, description: "Task brief to route." },
+        limit: optionalInteger({ description: "Maximum route recommendations, 1-10.", minimum: 1, maximum: 10 }),
+        explain: optionalBoolean("Include route scoring and reference coverage details."),
+      },
+      required: ["brief"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "design_ai_prompt",
+    title: "Generate an agent prompt",
+    description: "Generate a ready-to-use design-ai agent prompt from a brief. Read-only unless withLearning is true, which records local usage metadata.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        brief: { type: "string", minLength: 1, description: "Task brief." },
+        routeId: optionalString("Optional forced route id, such as component-spec or website-improvement."),
+        withLearning: optionalBoolean("Include local learning preferences and record local usage metadata."),
+        learningCategory: optionalString("Optional learning category when withLearning is true."),
+        learningLimit: optionalInteger({ description: "Maximum learning entries, 1-100.", minimum: 1, maximum: 100 }),
+        json: optionalBoolean("Return machine-readable prompt plan JSON instead of Markdown."),
+      },
+      required: ["brief"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "design_ai_pack",
+    title: "Generate prompt plus bounded context",
+    description: "Generate a prompt pack with relevant design-ai context files. Read-only unless withLearning is true, which records local usage metadata.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        brief: { type: "string", minLength: 1, description: "Task brief." },
+        routeId: optionalString("Optional forced route id."),
+        maxBytes: optionalInteger({ description: "Maximum context bytes to include.", minimum: 1000, maximum: 1_000_000 }),
+        withLearning: optionalBoolean("Include local learning preferences and record local usage metadata."),
+        learningCategory: optionalString("Optional learning category when withLearning is true."),
+        learningLimit: optionalInteger({ description: "Maximum learning entries, 1-100.", minimum: 1, maximum: 100 }),
+        json: optionalBoolean("Return machine-readable pack JSON instead of Markdown."),
+      },
+      required: ["brief"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "design_ai_search",
+    title: "Search design-ai corpus",
+    description: "Search knowledge, examples, skills, docs, agents, or commands. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", minLength: 2, description: "Search query." },
+        dir: optionalString("Optional corpus directory: knowledge, examples, skills, docs, agents, commands."),
+        limit: optionalInteger({ description: "Maximum hits, 1-500.", minimum: 1, maximum: 500 }),
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "design_ai_show",
+    title: "Show corpus file",
+    description: "Read a design-ai corpus file or line range. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: { type: "string", minLength: 1, description: "Path or path:line target, such as knowledge/PRINCIPLES.md:1." },
+        lines: optionalString("Optional line range N:M."),
+        context: optionalInteger({ description: "Context lines around target.", minimum: 0, maximum: 100 }),
+      },
+      required: ["target"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "design_ai_examples",
+    title: "Find worked examples",
+    description: "Find worked design-ai examples by query or route id. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: optionalString("Optional example search query."),
+        routeId: optionalString("Optional route id, such as component-spec."),
+        limit: optionalInteger({ description: "Maximum examples.", minimum: 1, maximum: 50 }),
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "design_ai_check",
+    title: "Check Markdown artifact quality",
+    description: "Check generated Markdown for grounding, accessibility, responsive notes, unresolved markers, and route-specific requirements. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        artifact: { type: "string", minLength: 1, description: "Markdown artifact content to check." },
+        routeId: optionalString("Optional route-specific checks."),
+        strict: optionalBoolean("Treat warnings as failures."),
+        issuesOnly: optionalBoolean("Show only warnings/failures in human output."),
+        json: optionalBoolean("Return machine-readable JSON. Defaults to true."),
+      },
+      required: ["artifact"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "design_ai_site_mcp_check",
+    title: "Check Website Improvement MCP readiness",
+    description: "Validate Website Improvement workspace MCP readiness without external MCP calls or target-repo mutation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceJson: { type: "string", minLength: 2, description: "Website Improvement workspace JSON." },
+        probes: optionalBoolean("Include read-only local probes."),
+        strict: optionalBoolean("Exit non-zero on warning/failure readiness."),
+        json: optionalBoolean("Return machine-readable JSON. Defaults to true."),
+      },
+      required: ["workspaceJson"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "design_ai_site_mcp_plan",
+    title: "Generate Website Improvement MCP action plan",
+    description: "Generate a Website Improvement MCP action plan without external MCP calls or target-repo mutation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceJson: { type: "string", minLength: 2, description: "Website Improvement workspace JSON." },
+        probes: optionalBoolean("Include read-only local probes."),
+        strict: optionalBoolean("Exit non-zero on warning/failure readiness."),
+        json: optionalBoolean("Return machine-readable JSON instead of Markdown."),
+      },
+      required: ["workspaceJson"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "design_ai_version",
+    title: "Show design-ai version",
+    description: "Return design-ai CLI and corpus version metadata. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+];
+
+function readPackageVersion() {
+  try {
+    return JSON.parse(readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8")).version || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+function assertString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${name} must be a non-empty string`);
+  }
+  return value;
+}
+
+function maybePush(args, flag, value) {
+  if (value !== undefined && value !== null && value !== "") args.push(flag, String(value));
+}
+
+function maybeBool(args, flag, value) {
+  if (value === true) args.push(flag);
+}
+
+function truncateText(text) {
+  const bytes = Buffer.byteLength(text, "utf8");
+  if (bytes <= MAX_TOOL_OUTPUT_BYTES) return text;
+  const truncated = Buffer.from(text, "utf8").subarray(0, MAX_TOOL_OUTPUT_BYTES).toString("utf8");
+  return `${truncated}\n\n[design-ai MCP output truncated at ${MAX_TOOL_OUTPUT_BYTES} bytes from ${bytes} bytes]`;
+}
+
+export function buildCliInvocation(toolName, input = {}) {
+  const args = [];
+  let stdin = "";
+
+  if (toolName === "design_ai_route") {
+    args.push("route", assertString(input.brief, "brief"), "--json");
+    maybePush(args, "--limit", input.limit);
+    maybeBool(args, "--explain", input.explain);
+    return { args, stdin };
+  }
+
+  if (toolName === "design_ai_prompt") {
+    args.push("prompt", assertString(input.brief, "brief"));
+    maybePush(args, "--route", input.routeId);
+    maybeBool(args, "--with-learning", input.withLearning);
+    maybePush(args, "--learning-category", input.learningCategory);
+    maybePush(args, "--learning-limit", input.learningLimit);
+    maybeBool(args, "--json", input.json);
+    return { args, stdin };
+  }
+
+  if (toolName === "design_ai_pack") {
+    args.push("pack", assertString(input.brief, "brief"));
+    maybePush(args, "--route", input.routeId);
+    maybePush(args, "--max-bytes", input.maxBytes);
+    maybeBool(args, "--with-learning", input.withLearning);
+    maybePush(args, "--learning-category", input.learningCategory);
+    maybePush(args, "--learning-limit", input.learningLimit);
+    maybeBool(args, "--json", input.json);
+    return { args, stdin };
+  }
+
+  if (toolName === "design_ai_search") {
+    args.push("search", assertString(input.query, "query"), "--json");
+    maybePush(args, "--dir", input.dir);
+    maybePush(args, "--limit", input.limit);
+    return { args, stdin };
+  }
+
+  if (toolName === "design_ai_show") {
+    args.push("show", assertString(input.target, "target"), "--json");
+    maybePush(args, "--lines", input.lines);
+    maybePush(args, "--context", input.context);
+    return { args, stdin };
+  }
+
+  if (toolName === "design_ai_examples") {
+    args.push("examples", "--json");
+    if (input.query) args.splice(1, 0, String(input.query));
+    maybePush(args, "--route", input.routeId);
+    maybePush(args, "--limit", input.limit);
+    return { args, stdin };
+  }
+
+  if (toolName === "design_ai_check") {
+    args.push("check", "--stdin");
+    stdin = assertString(input.artifact, "artifact");
+    maybePush(args, "--route", input.routeId);
+    maybeBool(args, "--strict", input.strict);
+    maybeBool(args, "--issues-only", input.issuesOnly);
+    if (input.json !== false) args.push("--json");
+    return { args, stdin };
+  }
+
+  if (toolName === "design_ai_site_mcp_check") {
+    args.push("site", "--stdin", "--mcp-check");
+    stdin = assertString(input.workspaceJson, "workspaceJson");
+    maybeBool(args, "--probes", input.probes);
+    maybeBool(args, "--strict", input.strict);
+    if (input.json !== false) args.push("--json");
+    return { args, stdin };
+  }
+
+  if (toolName === "design_ai_site_mcp_plan") {
+    args.push("site", "--stdin", "--mcp-plan");
+    stdin = assertString(input.workspaceJson, "workspaceJson");
+    maybeBool(args, "--probes", input.probes);
+    maybeBool(args, "--strict", input.strict);
+    maybeBool(args, "--json", input.json);
+    return { args, stdin };
+  }
+
+  if (toolName === "design_ai_version") {
+    args.push("version", "--json");
+    return { args, stdin };
+  }
+
+  throw new Error(`Unknown MCP tool: ${toolName}`);
+}
+
+export function runDesignAiCli(args, { stdin = "" } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [DESIGN_AI_BIN, ...args], {
+      cwd: DESIGN_AI_HOME,
+      env: process.env,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", (error) => {
+      resolve({ code: 1, stdout, stderr: `${stderr}${error.message}` });
+    });
+    child.on("close", (code) => {
+      resolve({ code: code ?? 1, stdout, stderr });
+    });
+    child.stdin.end(stdin);
+  });
+}
+
+export async function callMcpTool(name, input = {}, runCli = runDesignAiCli) {
+  const invocation = buildCliInvocation(name, input || {});
+  const result = await runCli(invocation.args, { stdin: invocation.stdin });
+  const text = [
+    result.stdout.trimEnd(),
+    result.stderr.trim() ? `\n[stderr]\n${result.stderr.trimEnd()}` : "",
+  ].filter(Boolean).join("\n");
+
+  return {
+    content: [{ type: "text", text: truncateText(text || "(no output)") }],
+    isError: result.code !== 0,
+  };
+}
+
+function successResponse(id, result) {
+  return { jsonrpc: "2.0", id, result };
+}
+
+function errorResponse(id, code, message) {
+  return { jsonrpc: "2.0", id: id ?? null, error: { code, message } };
+}
+
+export async function handleMcpRequest(message, { runCli = runDesignAiCli } = {}) {
+  const { id, method, params = {} } = message || {};
+
+  if (!method) return errorResponse(id, -32600, "Invalid MCP request: missing method");
+
+  if (method === "initialize") {
+    return successResponse(id, {
+      protocolVersion: params.protocolVersion || PROTOCOL_VERSION,
+      capabilities: {
+        tools: { listChanged: false },
+      },
+      serverInfo: {
+        name: "design-ai",
+        version: readPackageVersion(),
+      },
+      instructions: "Use design-ai MCP tools for local, deterministic design expertise: route briefs, generate prompts/packs, search/show the design corpus, check Markdown artifacts, and validate Website Improvement MCP readiness. Prefer read-only tools unless the user explicitly asks to record local learning usage.",
+    });
+  }
+
+  if (method === "notifications/initialized") return null;
+  if (method === "ping") return successResponse(id, {});
+
+  if (method === "tools/list") {
+    return successResponse(id, { tools: MCP_TOOLS });
+  }
+
+  if (method === "tools/call") {
+    const name = params.name;
+    const tool = MCP_TOOLS.find((item) => item.name === name);
+    if (!tool) return errorResponse(id, -32602, `Unknown tool: ${name}`);
+    try {
+      const result = await callMcpTool(name, params.arguments || {}, runCli);
+      return successResponse(id, result);
+    } catch (error) {
+      return successResponse(id, {
+        content: [{ type: "text", text: error.message || String(error) }],
+        isError: true,
+      });
+    }
+  }
+
+  if (method === "resources/list") return successResponse(id, { resources: [] });
+  if (method === "prompts/list") return successResponse(id, { prompts: [] });
+
+  return errorResponse(id, -32601, `Method not found: ${method}`);
+}
+
+export function startMcpStdioServer({ input = process.stdin, output = process.stdout, error = process.stderr } = {}) {
+  const rl = createInterface({ input, crlfDelay: Infinity });
+
+  rl.on("line", async (line) => {
+    if (!line.trim()) return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch (parseError) {
+      output.write(`${JSON.stringify(errorResponse(null, -32700, `Parse error: ${parseError.message}`))}\n`);
+      return;
+    }
+
+    try {
+      const response = await handleMcpRequest(message);
+      if (response && message.id !== undefined) {
+        output.write(`${JSON.stringify(response)}\n`);
+      }
+    } catch (requestError) {
+      const id = message && message.id !== undefined ? message.id : null;
+      output.write(`${JSON.stringify(errorResponse(id, -32603, requestError.message || String(requestError)))}\n`);
+    }
+  });
+
+  rl.on("error", (streamError) => {
+    error.write(`design-ai MCP stdin error: ${streamError.message}\n`);
+  });
+}

package/cli/lib/output.mjs

@@ -0,0 +1,101 @@
+// Output file helpers for CLI commands that can write artifacts.
+
+import {
+  existsSync,
+  mkdirSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+
+function exists(p) {
+  try {
+    return existsSync(p);
+  } catch {
+    return false;
+  }
+}
+
+export function parseOutputFlags(args, out) {
+  const arg = args[out.index];
+  if (arg === "--out" || arg === "--output") {
+    const next = args[out.index + 1];
+    if (!next || next.startsWith("--")) throw new Error(`${arg} expects a file path`);
+    out.outPath = next;
+    out.index += 1;
+    return true;
+  }
+  if (arg === "--force") {
+    out.force = true;
+    return true;
+  }
+  return false;
+}
+
+export function writeOutputFile({ outPath, content, force = false, cwd = process.cwd() }) {
+  if (!outPath) throw new Error("Missing output path");
+
+  const absolute = path.resolve(cwd, outPath);
+  if (exists(absolute)) {
+    if (statSync(absolute).isDirectory()) {
+      throw new Error(`Output path is a directory: ${absolute}`);
+    }
+    if (!force) {
+      throw new Error(`Output file already exists: ${absolute}. Use --force to overwrite.`);
+    }
+  }
+
+  mkdirSync(path.dirname(absolute), { recursive: true });
+  writeFileSync(absolute, content, "utf8");
+  return absolute;
+}
+
+function assertSafeRelativePath(relPath) {
+  const normalized = path.normalize(String(relPath || ""));
+  if (!normalized || normalized === ".") {
+    throw new Error("Output bundle file path is empty");
+  }
+  if (path.isAbsolute(normalized) || normalized.startsWith("..") || normalized.includes(`${path.sep}..${path.sep}`)) {
+    throw new Error(`Output bundle file path must stay inside the output directory: ${relPath}`);
+  }
+  return normalized;
+}
+
+export function writeOutputFiles({ outPath, files, force = false, cwd = process.cwd() }) {
+  if (!outPath) throw new Error("Missing output directory");
+  if (!Array.isArray(files) || files.length === 0) throw new Error("No output files provided");
+
+  const absolute = path.resolve(cwd, outPath);
+  if (exists(absolute) && !statSync(absolute).isDirectory()) {
+    throw new Error(`Output path is not a directory: ${absolute}`);
+  }
+
+  const planned = files.map((file) => {
+    const relativePath = assertSafeRelativePath(file.path);
+    const target = path.join(absolute, relativePath);
+    if (exists(target)) {
+      if (statSync(target).isDirectory()) {
+        throw new Error(`Output bundle file path is a directory: ${target}`);
+      }
+      if (!force) {
+        throw new Error(`Output bundle file already exists: ${target}. Use --force to overwrite.`);
+      }
+    }
+    return {
+      relativePath,
+      target,
+      content: String(file.content ?? ""),
+    };
+  });
+
+  mkdirSync(absolute, { recursive: true });
+  for (const file of planned) {
+    mkdirSync(path.dirname(file.target), { recursive: true });
+    writeFileSync(file.target, file.content, "utf8");
+  }
+
+  return {
+    directory: absolute,
+    files: planned.map((file) => file.target),
+  };
+}