@design-ai/cli 4.55.0

package/cli/bin/design-ai.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// design-ai CLI — distribution entry point
+//
+// Commands:
+//   install              Install design-ai into Claude Code (~/.claude)
+//   update [--dry-run]   Update to latest design-ai (re-fetch + reinstall)
+//   uninstall            Remove design-ai from Claude Code
+//   status               Show what's installed
+//   list [domain]        List skills / commands / knowledge (optionally filtered)
+//   search               Search the local design-ai markdown corpus
+//   show                 Print a corpus file or line range
+//   route                Recommend and explain commands, skills, and knowledge for a brief
+//   routes               List available route ids
+//   prompt               Generate a ready-to-use agent prompt from a brief
+//   pack                 Generate a prompt plus bounded context file contents
+//   audit                Run repository quality checks
+//   check                Check generated Markdown artifact quality
+//   doctor               Diagnose source, runtime, and install state
+//   examples             Find worked examples by query or route
+//   learn                Manage local learning preferences for prompt personalization
+//   workspace            Show read-only dogfood readiness: git, repository, learning usage/eval, release scripts
+//                        Add --strict to fail on readiness warnings/failures
+//   site                 Validate Website Improvement Console exports and generate handoff artifacts
+//   version [--json]     Show CLI + plugin versions
+//   help                 Show help
+
+import { runCommand } from "../lib/dispatch.mjs";
+import { red } from "../lib/log.mjs";
+
+const args = process.argv.slice(2);
+const command = args[0] || "help";
+const restArgs = args.slice(1);
+
+try {
+  await runCommand(command, restArgs);
+} catch (err) {
+  console.error(`${red("✗")} ${err.message}`);
+  if (process.env.DEBUG) console.error(err.stack);
+  process.exit(1);
+}

package/cli/commands/audit.mjs

@@ -0,0 +1,111 @@
+// `design-ai audit` — run the repository quality gate from the shipped CLI.
+
+import path from "node:path";
+
+import { run } from "../lib/exec.mjs";
+import { REPOSITORY_AUDIT_SCRIPTS } from "../lib/doctor.mjs";
+import { header, info } from "../lib/log.mjs";
+import { DESIGN_AI_HOME, pathExists } from "../lib/paths.mjs";
+import { unknownOptionMessage } from "../lib/suggest.mjs";
+
+const AUDIT_RUNNER = path.join(DESIGN_AI_HOME, "tools", "audit", "run-all.py");
+const AUDIT_OPTIONS = ["-h", "--help", "--strict", "--quiet", "--json"];
+const AUDIT_USAGE = "Usage: design-ai audit [--strict] [--quiet] [--json]";
+const AUDIT_HELP_LABEL_OVERRIDES = new Map([
+  ["korean-copy-check.py", "Korean copy"],
+  ["example-qa.py", "example QA"],
+]);
+
+export function auditScriptLabel(script) {
+  if (AUDIT_HELP_LABEL_OVERRIDES.has(script)) {
+    return AUDIT_HELP_LABEL_OVERRIDES.get(script);
+  }
+
+  return script
+    .replace(/\.py$/, "")
+    .replace(/-check$/, "")
+    .replace(/^check-/, "")
+    .replaceAll("-", " ");
+}
+
+export function parseAuditArgs(args) {
+  const flags = {
+    help: false,
+    strict: false,
+    quiet: false,
+    json: false,
+  };
+
+  for (const arg of args) {
+    if (arg === "-h" || arg === "--help") {
+      flags.help = true;
+      continue;
+    }
+    if (arg === "--strict") {
+      flags.strict = true;
+      continue;
+    }
+    if (arg === "--quiet") {
+      flags.quiet = true;
+      continue;
+    }
+    if (arg === "--json") {
+      flags.json = true;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(
+        `${unknownOptionMessage("audit", arg, AUDIT_OPTIONS)}\n` +
+          AUDIT_USAGE
+      );
+    }
+    throw new Error(AUDIT_USAGE);
+  }
+
+  return {
+    ...flags,
+    runnerArgs: [
+      ...(flags.strict ? ["--strict"] : []),
+      ...(flags.quiet ? ["--quiet"] : []),
+      ...(flags.json ? ["--json"] : []),
+    ],
+  };
+}
+
+function printHelp() {
+  const auditLabels = REPOSITORY_AUDIT_SCRIPTS.map(auditScriptLabel).join(", ");
+
+  console.log("Usage:  design-ai audit [--strict] [--quiet] [--json]\n");
+  console.log(`Runs the same ${REPOSITORY_AUDIT_SCRIPTS.length} repository audits used by CI:`);
+  console.log(`  ${auditLabels}\n`);
+  console.log("Options:");
+  console.log("  --strict   Exit non-zero when any supported audit fails");
+  console.log("  --quiet    Print only failures and the final summary");
+  console.log("  --json     Emit machine-readable audit results");
+}
+
+export async function runAudit(args) {
+  const parsed = parseAuditArgs(args);
+  if (parsed.help) {
+    printHelp();
+    return;
+  }
+
+  if (!pathExists(AUDIT_RUNNER)) {
+    throw new Error(
+      `Audit runner not found at ${AUDIT_RUNNER}.\n` +
+        "If installed via npm, this is a packaging bug. If running from a clone, ensure DESIGN_AI_HOME points at the repo root."
+    );
+  }
+
+  if (!parsed.json) {
+    header("design-ai audit", "Run repository quality checks");
+    info(`Source: ${DESIGN_AI_HOME}`);
+    info("Runner: tools/audit/run-all.py");
+    console.log();
+  }
+
+  await run("python3", [AUDIT_RUNNER, ...parsed.runnerArgs], {
+    cwd: DESIGN_AI_HOME,
+  });
+}

package/cli/commands/check.mjs

@@ -0,0 +1,226 @@
+// `design-ai check` — verify generated design artifacts against core output rules.
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+import {
+  buildCheckLearningCapture,
+  checkAllExampleArtifacts,
+  checkArtifactContent,
+  checkExampleArtifacts,
+  formatCheckJson,
+  parseCheckArgs,
+} from "../lib/check.mjs";
+import { dim, error, header, info, red, success, warn } from "../lib/log.mjs";
+import { DESIGN_AI_HOME } from "../lib/paths.mjs";
+
+function printHelp() {
+  console.log("Usage:  design-ai check <artifact.md> [--strict] [--json] [--route id] [--learn [--yes] [--learning-file path]]");
+  console.log("        cat artifact.md | design-ai check --stdin [--strict] [--route id] [--learn [--yes] [--learning-file path]]");
+  console.log("        design-ai check --examples --route id [--limit N] [--issues-only] [--strict] [--json]");
+  console.log("        design-ai check --examples --all-routes [--limit N] [--issues-only] [--strict] [--json]\n");
+  console.log("Checks generated design-ai Markdown artifacts for grounding, accessibility, responsive, unresolved-marker, and route-specific requirements.\n");
+  console.log("Options:");
+  console.log("  --stdin     Read artifact Markdown from standard input");
+  console.log("  --examples  Check worked examples for the selected route");
+  console.log("  --all-routes  Check worked examples for every route");
+  console.log("  --route id  Add route-specific checks such as component-spec, palette-from-brand, or slide-deck");
+  console.log("  --limit N   Number of route examples to check, 1-25. Default: 3");
+  console.log("  --issues-only  In human output, show only warnings and failures");
+  console.log("  --strict    Treat warnings as a failing exit code");
+  console.log("  --learn     Capture warning/failure checks as local learning entries");
+  console.log("  --yes       Apply --learn entries instead of previewing them");
+  console.log("  --learning-file path  Override the learning profile used by --learn");
+  console.log("  --json      Emit machine-readable check results");
+}
+
+function mark(level) {
+  if (level === "pass") return "✓";
+  if (level === "warn") return "!";
+  return "✗";
+}
+
+function printResult(item) {
+  const line = `${mark(item.level)} ${item.title}: ${item.message}`;
+  if (item.level === "pass") {
+    success(line.slice(2));
+  } else if (item.level === "warn") {
+    warn(line.slice(2));
+  } else {
+    error(line.slice(2));
+  }
+  if (item.evidence) {
+    console.log(`   ${dim(item.evidence)}`);
+  }
+}
+
+function printExampleResult(item) {
+  const { example, report } = item;
+  const title = `${example.relPath}: ${report.status} (${report.failures} fail, ${report.warnings} warn)`;
+  if (report.status === "pass") {
+    success(title);
+  } else if (report.status === "warn") {
+    warn(title);
+  } else {
+    error(title);
+  }
+
+  const notable = report.results.filter((resultItem) => resultItem.level !== "pass").slice(0, 3);
+  for (const resultItem of notable) {
+    console.log(`   ${dim(`${resultItem.id}: ${resultItem.evidence || resultItem.message}`)}`);
+  }
+}
+
+function printRouteExampleSummary(routeReport, { issuesOnly = false } = {}) {
+  if (issuesOnly && routeReport.status === "pass") return;
+
+  const line = `${routeReport.routeId}: ${routeReport.status} (${routeReport.failed} fail, ${routeReport.warned} warn, ${routeReport.passed} pass)`;
+  if (routeReport.status === "pass") {
+    success(line);
+  } else if (routeReport.status === "warn") {
+    warn(line);
+  } else {
+    console.log(`${red("✗")}  ${line}`);
+  }
+
+  const notable = routeReport.examples
+    .filter((item) => item.report.status !== "pass")
+    .slice(0, 1);
+  for (const item of notable) {
+    console.log(`   ${dim(`${item.example.relPath}: ${item.report.status}`)}`);
+    const firstIssue = item.report.results.find((resultItem) => resultItem.level !== "pass");
+    if (firstIssue) {
+      console.log(`   ${dim(`${firstIssue.id}: ${firstIssue.evidence || firstIssue.message}`)}`);
+    }
+  }
+}
+
+function printLearningCapture(capture) {
+  console.log();
+  console.log(capture.applied ? "Learning capture applied" : "Learning capture preview");
+  info(`File: ${capture.file}`);
+  info(`Source: ${capture.source}`);
+  info(`Candidates: ${capture.candidateCount}`);
+  info(`Added: ${capture.addedCount}`);
+  info(`Skipped: ${capture.skippedCount}`);
+  console.log();
+
+  if (capture.candidateCount === 0) {
+    console.log("No warning or failure check results to capture.");
+    return;
+  }
+
+  if (capture.entries.length > 0) {
+    console.log(capture.applied ? "Saved entries:" : "Would save:");
+    for (const entry of capture.entries) {
+      console.log(`- [${entry.category}] ${entry.text}`);
+    }
+  }
+
+  if (capture.skipped.length > 0) {
+    if (capture.entries.length > 0) console.log();
+    console.log("Skipped:");
+    for (const entry of capture.skipped) {
+      console.log(`- [${entry.category}] ${entry.textPreview} (${entry.reason})`);
+    }
+  }
+
+  if (capture.dryRun) {
+    console.log();
+    console.log("No changes made. Add --yes to save these learning entries.");
+  }
+}
+
+export async function runCheck(args) {
+  const parsed = parseCheckArgs(args);
+  if (parsed.help) {
+    printHelp();
+    return;
+  }
+
+  if (parsed.examples) {
+    const report = parsed.allRoutes
+      ? checkAllExampleArtifacts({
+        designAiPath: DESIGN_AI_HOME,
+        limit: parsed.limit,
+      })
+      : checkExampleArtifacts({
+        designAiPath: DESIGN_AI_HOME,
+        routeId: parsed.routeId,
+        limit: parsed.limit,
+      });
+
+    if (parsed.json) {
+      console.log(formatCheckJson(report));
+    } else if (parsed.allRoutes) {
+      header("design-ai check examples", "all routes");
+      info(`Source: ${DESIGN_AI_HOME}`);
+      info(`Status: ${report.status}`);
+      info(`Routes: ${report.totalRoutes} (${report.failedRoutes} fail, ${report.warnedRoutes} warn, ${report.passedRoutes} pass)`);
+      info(`Examples: ${report.totalExamples} (${report.failedExamples} fail, ${report.warnedExamples} warn, ${report.passedExamples} pass)`);
+      console.log();
+      for (const routeReport of report.routes) {
+        printRouteExampleSummary(routeReport, { issuesOnly: parsed.issuesOnly });
+      }
+    } else {
+      header("design-ai check examples", parsed.routeId);
+      info(`Source: ${DESIGN_AI_HOME}`);
+      info(`Query: ${report.query}`);
+      info(`Status: ${report.status}`);
+      info(`Examples: ${report.total} (${report.failed} fail, ${report.warned} warn, ${report.passed} pass)`);
+      if (report.message) info(report.message);
+      console.log();
+      const examplesToPrint = parsed.issuesOnly
+        ? report.examples.filter((item) => item.report.status !== "pass")
+        : report.examples;
+      for (const item of examplesToPrint) {
+        printExampleResult(item);
+      }
+    }
+
+    if (report.status === "fail" || (parsed.strict && report.status !== "pass")) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (!parsed.target && !parsed.stdin) {
+    printHelp();
+    process.exitCode = 1;
+    return;
+  }
+
+  const filePath = parsed.stdin ? "stdin" : path.resolve(process.cwd(), parsed.target);
+  const content = parsed.stdin ? readFileSync(0, "utf8") : readFileSync(filePath, "utf8");
+  const report = checkArtifactContent({ content, filePath, routeId: parsed.routeId });
+  const learningCapture = parsed.learn
+    ? buildCheckLearningCapture(report, {
+      filePath: parsed.learningFilePath ? path.resolve(process.cwd(), parsed.learningFilePath) : "",
+      dryRun: !parsed.yes,
+    })
+    : null;
+  const outputReport = learningCapture ? { ...report, learningCapture } : report;
+
+  if (parsed.json) {
+    console.log(formatCheckJson(outputReport));
+  } else {
+    header("design-ai check", parsed.stdin ? "stdin" : parsed.target);
+    if (parsed.routeId) info(`Route: ${parsed.routeId}`);
+    info(`Status: ${report.status}`);
+    info(`Score: ${report.score} (${report.failures} fail, ${report.warnings} warn)`);
+    console.log();
+    const resultsToPrint = parsed.issuesOnly
+      ? report.results.filter((item) => item.level !== "pass")
+      : report.results;
+    for (const item of resultsToPrint) {
+      printResult(item);
+    }
+    if (learningCapture) {
+      printLearningCapture(learningCapture);
+    }
+  }
+
+  if (report.status === "fail" || (parsed.strict && report.status !== "pass")) {
+    process.exitCode = 1;
+  }
+}

package/cli/commands/doctor.mjs

@@ -0,0 +1,141 @@
+// `design-ai doctor` — diagnose source, runtime, and Claude Code install state.
+
+import { collectDoctorReport, formatDoctorJson, STATUS } from "../lib/doctor.mjs";
+import { header, info, success, warn, error, dim } from "../lib/log.mjs";
+import { run } from "../lib/exec.mjs";
+import {
+  DESIGN_AI_HOME,
+  CLAUDE_HOME,
+  SYMLINK_PREFIX,
+  INSTALL_SCRIPT,
+} from "../lib/paths.mjs";
+import { unknownOptionMessage } from "../lib/suggest.mjs";
+
+const DOCTOR_OPTIONS = ["-h", "--help", "--strict", "--json", "--fix"];
+const ALLOWED_ARGS = new Set(["--strict", "--json", "--fix"]);
+
+function normalizeArgs(args) {
+  const flags = {
+    strict: false,
+    json: false,
+    fix: false,
+    help: false,
+  };
+
+  for (const arg of args) {
+    if (arg === "-h" || arg === "--help") {
+      flags.help = true;
+      continue;
+    }
+    if (!ALLOWED_ARGS.has(arg)) {
+      throw new Error(
+        `${unknownOptionMessage("doctor", arg, DOCTOR_OPTIONS)}\n` +
+          "Usage: design-ai doctor [--strict] [--json] [--fix]",
+      );
+    }
+    if (arg === "--strict") flags.strict = true;
+    if (arg === "--json") flags.json = true;
+    if (arg === "--fix") flags.fix = true;
+  }
+
+  return flags;
+}
+
+function printHelp() {
+  console.log("Usage:  design-ai doctor [--strict] [--json] [--fix]\n");
+  console.log("Checks source layout, versions, runtimes, audit tooling, and Claude Code symlinks.\n");
+  console.log("Options:");
+  console.log("  --strict   Exit non-zero when warnings are present");
+  console.log("  --json     Emit machine-readable diagnostics");
+  console.log("  --fix      Re-run install.sh when diagnostics show only fixable warnings");
+}
+
+function printCheck(check) {
+  const line = `${check.label}: ${check.detail}`;
+  if (check.status === STATUS.PASS) {
+    success(line);
+  } else if (check.status === STATUS.WARN) {
+    warn(line);
+  } else {
+    error(line);
+  }
+
+  if (check.action) {
+    console.log(`   ${dim(check.action)}`);
+  }
+}
+
+async function applyFix() {
+  await run("bash", [INSTALL_SCRIPT, "install"], {
+    cwd: DESIGN_AI_HOME,
+    silent: true,
+    env: {
+      DESIGN_AI_PREFIX: SYMLINK_PREFIX,
+      CLAUDE_HOME,
+    },
+  });
+}
+
+function printReport(report) {
+  header("design-ai doctor", "Diagnose install and runtime health");
+  info(`Source: ${report.context.sourceRoot}`);
+  info(`Target: ${report.context.claudeHome}`);
+  info(`Prefix: ${report.context.prefix}`);
+  console.log();
+
+  for (const check of report.checks) {
+    printCheck(check);
+  }
+
+  console.log();
+  info(
+    `Summary: ${report.summary.pass} pass, ${report.summary.warn} warning(s), ${report.summary.fail} failure(s)`,
+  );
+}
+
+export async function runDoctor(args) {
+  const flags = normalizeArgs(args);
+  if (flags.help) {
+    printHelp();
+    return;
+  }
+
+  const before = collectDoctorReport();
+  let report = before;
+  let fix = {
+    attempted: false,
+    applied: false,
+    reason: "",
+  };
+
+  if (flags.fix) {
+    fix.attempted = true;
+    if (before.summary.fail > 0) {
+      fix.reason = "Skipped because diagnostics contain failure(s) that require manual review.";
+    } else if (before.summary.warn === 0) {
+      fix.reason = "Skipped because no fixable warnings were found.";
+    } else {
+      await applyFix();
+      fix.applied = true;
+      fix.reason = "Ran install.sh to refresh Claude Code symlinks.";
+      report = collectDoctorReport();
+    }
+  }
+
+  if (flags.json) {
+    console.log(formatDoctorJson({ ...report, fix }));
+  } else {
+    printReport(report);
+    if (flags.fix) {
+      if (fix.applied) {
+        success(`Fix applied: ${fix.reason}`);
+      } else {
+        warn(`Fix not applied: ${fix.reason}`);
+      }
+    }
+  }
+
+  if (report.summary.fail > 0 || (flags.strict && report.summary.warn > 0)) {
+    process.exitCode = 1;
+  }
+}

package/cli/commands/examples.mjs

@@ -0,0 +1,58 @@
+// `design-ai examples` — discover worked examples for a route or query.
+
+import { DESIGN_AI_HOME } from "../lib/paths.mjs";
+import { dim, header, info, warn } from "../lib/log.mjs";
+import { formatExamplesJson, listExamples, parseExamplesArgs } from "../lib/examples.mjs";
+
+function printHelp() {
+  console.log("Usage:  design-ai examples [query] [--route id] [--limit N] [--json]\n");
+  console.log("Finds worked outputs in examples/ so users can compare against known-good design-ai artifacts.\n");
+  console.log("Options:");
+  console.log("  --route id  Bias example search to a route id from `design-ai routes`");
+  console.log("  --limit N   Maximum examples to return, 1-100. Default: 12");
+  console.log("  --json      Emit machine-readable results");
+}
+
+function printExamples(examples) {
+  for (let i = 0; i < examples.length; i += 1) {
+    const example = examples[i];
+    console.log(`${i + 1}. ${example.title} ${dim(`(${example.category}, score ${example.score})`)}`);
+    console.log(`   ${example.relPath}`);
+    if (example.preview) {
+      console.log(`   ${dim(example.preview)}`);
+    }
+  }
+}
+
+export async function runExamples(args) {
+  const parsed = parseExamplesArgs(args);
+  if (parsed.help) {
+    printHelp();
+    return;
+  }
+
+  const payload = listExamples({
+    designAiPath: DESIGN_AI_HOME,
+    query: parsed.query,
+    routeId: parsed.routeId,
+    limit: parsed.limit,
+  });
+
+  if (parsed.json) {
+    console.log(formatExamplesJson(payload));
+    return;
+  }
+
+  header("design-ai examples", parsed.routeId || parsed.query || "all");
+  info(`Source: ${DESIGN_AI_HOME}`);
+  info(`Effective query: ${payload.effectiveQuery || "(none)"}`);
+  info(`Examples: ${payload.examples.length}`);
+  console.log();
+
+  if (payload.examples.length === 0) {
+    warn("No examples found.");
+    return;
+  }
+
+  printExamples(payload.examples);
+}