@design-ai/cli 4.55.0

package/cli/commands/list.mjs

@@ -0,0 +1,143 @@
+// `design-ai list [domain]` — list skills / commands / agents from the plugin manifest.
+
+import { readFileSync } from "node:fs";
+import { hasHelpFlag } from "../lib/help-flags.mjs";
+import { header, info, dim } from "../lib/log.mjs";
+import { PLUGIN_MANIFEST, pathExists } from "../lib/paths.mjs";
+import { expectedValueMessage, unknownOptionMessage } from "../lib/suggest.mjs";
+
+export const LIST_KINDS = ["skills", "commands", "agents"];
+const LIST_OPTIONS = ["-h", "--help", "--json"];
+
+function loadManifest() {
+  if (!pathExists(PLUGIN_MANIFEST)) {
+    throw new Error(`Plugin manifest not found at ${PLUGIN_MANIFEST}`);
+  }
+  return JSON.parse(readFileSync(PLUGIN_MANIFEST, "utf8"));
+}
+
+export function parseListArgs(args) {
+  const flags = {
+    help: false,
+    json: false,
+    kind: "",
+  };
+
+  const domains = [];
+  for (const arg of args) {
+    if (arg === "-h" || arg === "--help") {
+      flags.help = true;
+      continue;
+    }
+    if (arg === "--json") {
+      flags.json = true;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(
+        `${unknownOptionMessage("list", arg, LIST_OPTIONS)}\n` +
+          "Usage: design-ai list [skills|commands|agents] [--json]",
+      );
+    }
+    domains.push(arg);
+  }
+
+  if (domains.length > 1) {
+    throw new Error("Usage: design-ai list [skills|commands|agents] [--json]");
+  }
+
+  const filter = domains[0]?.toLowerCase() || "";
+  const target = filter && LIST_KINDS.find(k => k.startsWith(filter));
+
+  if (filter && !target) {
+    throw new Error(
+      `Unknown domain: ${filter}\n` +
+        expectedValueMessage("domain", filter, LIST_KINDS),
+    );
+  }
+
+  flags.kind = target || "";
+  return flags;
+}
+
+function catalogItem(item) {
+  return {
+    name: item.name,
+    path: item.path,
+    description: item.description,
+  };
+}
+
+export function buildListCatalog(manifest, kind = "") {
+  const kinds = kind ? [kind] : LIST_KINDS;
+  return {
+    name: manifest.name,
+    version: manifest.version,
+    kind: kind || null,
+    sections: kinds.map((sectionKind) => {
+      const items = (manifest[sectionKind] || []).map(catalogItem);
+      return {
+        kind: sectionKind,
+        count: items.length,
+        items,
+      };
+    }),
+  };
+}
+
+export function formatListJson(catalog) {
+  return JSON.stringify(catalog, null, 2);
+}
+
+function printList(kind, items) {
+  console.log(`\n${kind} (${items.length})`);
+  console.log("─".repeat(40));
+  for (const item of items) {
+    console.log(`  ${item.name}`);
+    if (item.description) {
+      // Truncate to fit terminal nicely
+      const desc = item.description.length > 90
+        ? item.description.slice(0, 87) + "..."
+        : item.description;
+      console.log(`    ${dim(desc)}`);
+    }
+  }
+}
+
+function printHelp() {
+  console.log("Usage:  design-ai list [skills|commands|agents] [--json]\n");
+  console.log("Lists catalog entries from the plugin manifest.");
+  console.log("Omit the kind to print all catalog sections.\n");
+  console.log("Arguments:");
+  console.log("  skills     List installed skill playbooks");
+  console.log("  commands   List slash command templates");
+  console.log("  agents     List bundled agent personas");
+  console.log("\nOptions:");
+  console.log("  --json     Emit machine-readable catalog entries");
+}
+
+export async function runList(args) {
+  if (hasHelpFlag(args)) {
+    printHelp();
+    return;
+  }
+
+  const parsed = parseListArgs(args);
+  const manifest = loadManifest();
+  if (parsed.json) {
+    console.log(formatListJson(buildListCatalog(manifest, parsed.kind)));
+    return;
+  }
+
+  header("design-ai catalog");
+  info(`Plugin: ${manifest.name} v${manifest.version}`);
+  console.log();
+
+  if (parsed.kind) {
+    printList(parsed.kind, manifest[parsed.kind] || []);
+  } else {
+    for (const k of LIST_KINDS) {
+      printList(k, manifest[k] || []);
+    }
+  }
+}

package/cli/commands/mcp.mjs

@@ -0,0 +1,27 @@
+// `design-ai mcp` — start the design-ai stdio MCP server.
+
+import { startMcpStdioServer } from "../lib/mcp-server.mjs";
+
+function printHelp() {
+  console.log("Usage:  design-ai mcp\n");
+  console.log("Starts the design-ai stdio MCP server for Claude Code, Codex, and other MCP clients.");
+  console.log("The server writes only JSON-RPC messages to stdout; diagnostics go to stderr.");
+  console.log("\nExamples:");
+  console.log("  Claude Code:");
+  console.log("  claude mcp add --transport stdio design-ai -- design-ai mcp");
+  console.log("  Codex:");
+  console.log("  codex mcp add design-ai -- design-ai mcp");
+  console.log("  Local clone:");
+  console.log("  node cli/bin/design-ai-mcp.mjs");
+}
+
+export async function runMcp(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    printHelp();
+    return;
+  }
+  if (args.length > 0) {
+    throw new Error("Usage: design-ai mcp");
+  }
+  startMcpStdioServer();
+}

package/cli/commands/pack.mjs

@@ -0,0 +1,211 @@
+// `design-ai pack` — generate a prompt plus bounded context file contents.
+
+import { DESIGN_AI_HOME, SYMLINK_PREFIX } from "../lib/paths.mjs";
+import { header, info, success } from "../lib/log.mjs";
+import { resolveBriefInput } from "../lib/brief.mjs";
+import { recordLearningUsage } from "../lib/learn.mjs";
+import {
+  buildPackEvalTemplate,
+  buildPromptPack,
+  formatPackJson,
+  packEvalReport,
+  parsePackArgs,
+} from "../lib/pack.mjs";
+import { writeOutputFile } from "../lib/output.mjs";
+
+function printHelp() {
+  console.log("Usage:  design-ai pack <brief> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--max-bytes N] [--json] [--out file] [--force]");
+  console.log("        design-ai pack --from-file brief.md [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--max-bytes N] [--json] [--out file] [--force]");
+  console.log("        design-ai pack --eval-template [--json] [--out file] [--force]");
+  console.log("        design-ai pack --eval --from-file pack-eval.json [--strict] [--json] [--out file] [--force]");
+  console.log("        cat pack-eval.json | design-ai pack --eval --stdin [--strict] [--json]");
+  console.log("        cat brief.md | design-ai pack --stdin [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--max-bytes N] [--json]\n");
+  console.log("Generates a ready-to-use prompt plus bounded context file contents, summary, and warnings.");
+  console.log("Pack eval is read-only and checks generated prompt-pack context contracts.\n");
+  console.log("Options:");
+  console.log("  --from-file file  Read the task brief, or pack eval JSON with --eval, from a file");
+  console.log("  --stdin           Read the task brief, or pack eval JSON with --eval, from standard input");
+  console.log("  --route id        Force a route id from `design-ai route --json`");
+  console.log("  --with-learning   Include brief-relevant local learning preferences and record local usage metadata");
+  console.log("  --learning-category kind  Include only one learning category; requires --with-learning");
+  console.log("  --learning-limit N        Limit included learning entries, 1-100; requires --with-learning");
+  console.log("  --max-bytes N     Maximum context bytes to include, 1000-1000000. Default: 120000");
+  console.log("  --eval-template   Generate a runnable pack eval checkpoint JSON template");
+  console.log("  --eval            Run deterministic prompt-pack checkpoint cases");
+  console.log("  --strict          With --eval, exit non-zero on warning or failure");
+  console.log("  --json            Emit machine-readable bundle");
+  console.log("  --out file        Write output to a file instead of stdout");
+  console.log("  --force           Overwrite an existing --out file");
+  console.log("");
+  console.log("Environment:");
+  console.log("  DESIGN_AI_LEARNING_FILE=/path/learning.json        Override the profile used by --with-learning");
+  console.log("  DESIGN_AI_LEARNING_USAGE_FILE=/path/usage.json     Override the local usage sidecar path");
+  console.log("");
+  console.log("Examples:");
+  console.log("  design-ai pack \"audit checkout UX\" --with-learning --learning-category korean --learning-limit 5");
+  console.log("  design-ai pack --from-file product-brief.md --route design-review --out prompt-pack.md");
+  console.log("  design-ai pack \"spec a Button component API\" --max-bytes 80000");
+  console.log("  design-ai pack --eval-template --json > pack-eval.json");
+  console.log("  design-ai pack --eval --from-file pack-eval.json --strict --json");
+}
+
+function printPackEvalTemplate(template) {
+  header("design-ai pack", "Pack eval checkpoint template");
+  info(`Source: ${DESIGN_AI_HOME}`);
+  info(`Corpus version: ${template.sourcePackVersion}`);
+  info(`Cases: ${template.cases.length}`);
+  console.log();
+  console.log("Write the JSON below to a file, edit cases if needed, then run:");
+  console.log("design-ai pack --eval --from-file pack-eval.json --strict");
+  console.log();
+  console.log(formatPackJson(template));
+}
+
+function printPackEvalReport(report) {
+  header("design-ai pack", "Pack eval report");
+  info(`Source: ${report.source}`);
+  info(`Corpus version: ${report.version}`);
+  info(`Status: ${report.status}`);
+  info(`Cases: ${report.summary.total} (${report.summary.pass} pass, ${report.summary.warn} warn, ${report.summary.fail} fail)`);
+  console.log();
+
+  for (const result of report.cases) {
+    console.log(`${result.status.toUpperCase()} ${result.id}`);
+    console.log(`   expected: ${result.expectedRouteId}`);
+    console.log(`   route:    ${result.routeId || "none"}`);
+    console.log(`   context:  ${result.contextStatus}, ${result.includedFiles}/${result.totalFiles} files included`);
+    console.log(`   missing:  ${result.missingRequiredFiles.length} planned files, ${result.missingIncludedFiles.length} included files`);
+    console.log(`   result:   ${result.message}`);
+    console.log();
+  }
+}
+
+export async function runPack(args) {
+  const parsed = parsePackArgs(args);
+  if (parsed.help) {
+    printHelp();
+    return;
+  }
+
+  if (parsed.evalTemplate) {
+    const template = buildPackEvalTemplate({ sourceRoot: DESIGN_AI_HOME });
+    const content = `${formatPackJson(template)}\n`;
+    if (parsed.outPath) {
+      const written = writeOutputFile({
+        outPath: parsed.outPath,
+        content,
+        force: parsed.force,
+      });
+      success(`Wrote ${written}`);
+      return;
+    }
+    if (parsed.json) {
+      console.log(content.trimEnd());
+      return;
+    }
+    printPackEvalTemplate(template);
+    return;
+  }
+
+  if (parsed.eval) {
+    const evalText = resolveBriefInput(parsed);
+    const report = packEvalReport({
+      evalText,
+      source: parsed.fromFile || "stdin",
+      sourceRoot: DESIGN_AI_HOME,
+      prefix: SYMLINK_PREFIX,
+      maxBytes: parsed.maxBytes,
+    });
+    const content = `${formatPackJson(report)}\n`;
+    if (parsed.outPath) {
+      const written = writeOutputFile({
+        outPath: parsed.outPath,
+        content,
+        force: parsed.force,
+      });
+      success(`Wrote ${written}`);
+    } else if (parsed.json) {
+      console.log(content.trimEnd());
+    } else {
+      printPackEvalReport(report);
+    }
+    if (parsed.strict && report.status !== "pass") {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  let brief = "";
+  try {
+    brief = resolveBriefInput(parsed);
+  } catch (err) {
+    if (err.message === "Brief is empty") {
+      printHelp();
+    } else {
+      throw err;
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!brief) {
+    printHelp();
+    process.exitCode = 1;
+    return;
+  }
+
+  const pack = buildPromptPack({
+    brief,
+    sourceRoot: DESIGN_AI_HOME,
+    prefix: SYMLINK_PREFIX,
+    maxBytes: parsed.maxBytes,
+    routeId: parsed.routeId,
+    withLearning: parsed.withLearning,
+    learningCategory: parsed.learningCategory,
+    learningLimit: parsed.learningLimit,
+  });
+  const learningUsage = parsed.withLearning
+    ? recordLearningUsage({
+      command: "pack",
+      routeId: pack.plan.route.id,
+      learningContext: pack.plan.learningContext,
+    })
+    : null;
+  const outputPack = learningUsage
+    ? {
+      ...pack,
+      learningUsage,
+      plan: {
+        ...pack.plan,
+        learningUsage,
+      },
+    }
+    : pack;
+
+  const content = parsed.json ? `${formatPackJson(outputPack)}\n` : `${outputPack.markdown}\n`;
+
+  if (parsed.outPath) {
+    const written = writeOutputFile({
+      outPath: parsed.outPath,
+      content,
+      force: parsed.force,
+    });
+    success(`Wrote ${written}`);
+    return;
+  }
+
+  if (parsed.json) {
+    console.log(content.trimEnd());
+    return;
+  }
+
+  header("design-ai pack", brief);
+  info(`Source: ${DESIGN_AI_HOME}`);
+  info(`Corpus version: ${outputPack.version}`);
+  info(`Context: ${outputPack.summary.status}, ${outputPack.usedBytes}/${outputPack.maxBytes} bytes, ${outputPack.warnings.length} warnings`);
+  if (learningUsage?.recorded) {
+    info(`Learning usage: recorded ${learningUsage.event.id}`);
+  }
+  console.log();
+  console.log(outputPack.markdown);
+}

package/cli/commands/prompt.mjs

@@ -0,0 +1,199 @@
+// `design-ai prompt` — generate a ready-to-use agent prompt from a task brief.
+
+import { DESIGN_AI_HOME, SYMLINK_PREFIX } from "../lib/paths.mjs";
+import { header, info, success } from "../lib/log.mjs";
+import { resolveBriefInput } from "../lib/brief.mjs";
+import { recordLearningUsage } from "../lib/learn.mjs";
+import {
+  buildPromptEvalTemplate,
+  buildPromptPlan,
+  formatPromptJson,
+  parsePromptArgs,
+  promptEvalReport,
+} from "../lib/prompt.mjs";
+import { writeOutputFile } from "../lib/output.mjs";
+
+function printHelp() {
+  console.log("Usage:  design-ai prompt <brief> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--json] [--out file] [--force]");
+  console.log("        design-ai prompt --from-file brief.md [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--json] [--out file] [--force]");
+  console.log("        design-ai prompt --eval-template [--json] [--out file] [--force]");
+  console.log("        design-ai prompt --eval --from-file prompt-eval.json [--strict] [--json] [--out file] [--force]");
+  console.log("        cat prompt-eval.json | design-ai prompt --eval --stdin [--strict] [--json]");
+  console.log("        cat brief.md | design-ai prompt --stdin [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--json]\n");
+  console.log("Builds a ready-to-use prompt from route recommendations and required design-ai files.");
+  console.log("Prompt eval is read-only and checks generated prompt-plan contracts.\n");
+  console.log("Options:");
+  console.log("  --from-file file  Read the task brief, or prompt eval JSON with --eval, from a file");
+  console.log("  --stdin           Read the task brief, or prompt eval JSON with --eval, from standard input");
+  console.log("  --route id        Force a route id from `design-ai route --json`");
+  console.log("  --with-learning   Include brief-relevant local learning preferences and record local usage metadata");
+  console.log("  --learning-category kind  Include only one learning category; requires --with-learning");
+  console.log("  --learning-limit N        Limit included learning entries, 1-100; requires --with-learning");
+  console.log("  --eval-template   Generate a runnable prompt eval checkpoint JSON template");
+  console.log("  --eval            Run deterministic prompt-plan checkpoint cases");
+  console.log("  --strict          With --eval, exit non-zero on warning or failure");
+  console.log("  --json            Emit machine-readable prompt plan");
+  console.log("  --out file        Write output to a file instead of stdout");
+  console.log("  --force           Overwrite an existing --out file");
+  console.log("");
+  console.log("Environment:");
+  console.log("  DESIGN_AI_LEARNING_FILE=/path/learning.json        Override the profile used by --with-learning");
+  console.log("  DESIGN_AI_LEARNING_USAGE_FILE=/path/usage.json     Override the local usage sidecar path");
+  console.log("");
+  console.log("Examples:");
+  console.log("  design-ai prompt \"audit a Figma signup flow for Korean fintech\"");
+  console.log("  design-ai prompt \"audit checkout UX\" --with-learning --learning-category korean --learning-limit 5");
+  console.log("  design-ai prompt --from-file product-brief.md --route design-review --out prompt.md");
+  console.log("  design-ai prompt \"spec a Button component API\" --json --out button-prompt.json");
+  console.log("  design-ai prompt --eval-template --json > prompt-eval.json");
+  console.log("  design-ai prompt --eval --from-file prompt-eval.json --strict --json");
+}
+
+function printPromptEvalTemplate(template) {
+  header("design-ai prompt", "Prompt eval checkpoint template");
+  info(`Source: ${DESIGN_AI_HOME}`);
+  info(`Corpus version: ${template.sourcePromptVersion}`);
+  info(`Cases: ${template.cases.length}`);
+  console.log();
+  console.log("Write the JSON below to a file, edit cases if needed, then run:");
+  console.log("design-ai prompt --eval --from-file prompt-eval.json --strict");
+  console.log();
+  console.log(formatPromptJson(template));
+}
+
+function printPromptEvalReport(report) {
+  header("design-ai prompt", "Prompt eval report");
+  info(`Source: ${report.source}`);
+  info(`Corpus version: ${report.version}`);
+  info(`Status: ${report.status}`);
+  info(`Cases: ${report.summary.total} (${report.summary.pass} pass, ${report.summary.warn} warn, ${report.summary.fail} fail)`);
+  console.log();
+
+  for (const result of report.cases) {
+    console.log(`${result.status.toUpperCase()} ${result.id}`);
+    console.log(`   expected: ${result.expectedRouteId}`);
+    console.log(`   route:    ${result.routeId || "none"}`);
+    console.log(`   files:    ${result.filesToReadCount} planned, ${result.missingRequiredFiles.length} required missing`);
+    console.log(`   checks:   ${result.missingChecklist.length} checklist missing, ${result.missingPromptFragments.length} prompt fragments missing`);
+    console.log(`   result:   ${result.message}`);
+    console.log();
+  }
+}
+
+export async function runPrompt(args) {
+  const parsed = parsePromptArgs(args);
+  if (parsed.help) {
+    printHelp();
+    return;
+  }
+
+  if (parsed.evalTemplate) {
+    const template = buildPromptEvalTemplate({ sourceRoot: DESIGN_AI_HOME });
+    const content = parsed.json ? `${formatPromptJson(template)}\n` : `${formatPromptJson(template)}\n`;
+    if (parsed.outPath) {
+      const written = writeOutputFile({
+        outPath: parsed.outPath,
+        content,
+        force: parsed.force,
+      });
+      success(`Wrote ${written}`);
+      return;
+    }
+    if (parsed.json) {
+      console.log(content.trimEnd());
+      return;
+    }
+    printPromptEvalTemplate(template);
+    return;
+  }
+
+  if (parsed.eval) {
+    const evalText = resolveBriefInput(parsed);
+    const report = promptEvalReport({
+      evalText,
+      source: parsed.fromFile || "stdin",
+      sourceRoot: DESIGN_AI_HOME,
+      prefix: SYMLINK_PREFIX,
+    });
+    const content = parsed.json ? `${formatPromptJson(report)}\n` : "";
+    if (parsed.outPath) {
+      const written = writeOutputFile({
+        outPath: parsed.outPath,
+        content: parsed.json ? content : `${formatPromptJson(report)}\n`,
+        force: parsed.force,
+      });
+      success(`Wrote ${written}`);
+    } else if (parsed.json) {
+      console.log(content.trimEnd());
+    } else {
+      printPromptEvalReport(report);
+    }
+    if (parsed.strict && report.status !== "pass") {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  let brief = "";
+  try {
+    brief = resolveBriefInput(parsed);
+  } catch (err) {
+    if (err.message === "Brief is empty") {
+      printHelp();
+    } else {
+      throw err;
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!brief) {
+    printHelp();
+    process.exitCode = 1;
+    return;
+  }
+
+  const plan = buildPromptPlan({
+    brief,
+    sourceRoot: DESIGN_AI_HOME,
+    prefix: SYMLINK_PREFIX,
+    routeId: parsed.routeId,
+    withLearning: parsed.withLearning,
+    learningCategory: parsed.learningCategory,
+    learningLimit: parsed.learningLimit,
+  });
+  const learningUsage = parsed.withLearning
+    ? recordLearningUsage({
+      command: "prompt",
+      routeId: plan.route.id,
+      learningContext: plan.learningContext,
+    })
+    : null;
+  const outputPlan = learningUsage ? { ...plan, learningUsage } : plan;
+
+  const content = parsed.json ? `${formatPromptJson(outputPlan)}\n` : `${outputPlan.prompt}\n`;
+
+  if (parsed.outPath) {
+    const written = writeOutputFile({
+      outPath: parsed.outPath,
+      content,
+      force: parsed.force,
+    });
+    success(`Wrote ${written}`);
+    return;
+  }
+
+  if (parsed.json) {
+    console.log(content.trimEnd());
+    return;
+  }
+
+  header("design-ai prompt", brief);
+  info(`Source: ${DESIGN_AI_HOME}`);
+  info(`Corpus version: ${outputPlan.version}`);
+  if (learningUsage?.recorded) {
+    info(`Learning usage: recorded ${learningUsage.event.id}`);
+  }
+  console.log();
+  console.log(outputPlan.prompt);
+}