@markdy/cli 1.2.0 → 1.3.0

package/dist/index.js

@@ -13,10 +13,21 @@ import {
   repairMarkdyCode,
   getIntelliCodeCompletions,
   predictNextLineSuggestion,
-  getArchitectureSuggestions
+  getArchitectureSuggestions,
+  recommendArchitecturePattern,
+  synthesizeCustomRecipe,
+  getArchitectureRecipe,
+  listArchitectureRecipes,
+  verifyDiagramQuality,
+  analyzeC4Model,
+  filterC4Hierarchy,
+  generateC4Storyboard,
+  exportC4LevelViews,
+  detectArchitectureDrift,
+  autoHealArchitectureDrift
 } from "@markdy/core";
 import { createRequire } from "module";
-import { basename, dirname, extname, join, resolve, sep } from "path";
+import { basename, dirname, extname, join, relative, resolve, sep } from "path";
 import { fileURLToPath, pathToFileURL } from "url";
 import { createServer } from "http";
 import { readdir, readFile, stat, writeFile } from "fs/promises";
@@ -69,6 +80,18 @@ async function runCli(argv, io = defaultIo(), runtime = defaultRuntime()) {
       return aiCommand(parsed, io, runtime);
     case "suggest":
       return suggestCommand(parsed, io);
+    case "guide":
+      return guideCommand(parsed, io);
+    case "recipe":
+      return recipeCommand(parsed, io);
+    case "verify":
+    case "doctor":
+      return verifyCommand(parsed, io);
+    case "drift":
+    case "sync":
+      return driftCommand(parsed, io);
+    case "c4":
+      return c4Command(parsed, io);
     case "check":
       return checkCommand(parsed, io);
     case "check-all":
@@ -275,6 +298,113 @@ async function explainCommand(parsed, io) {
   }
   return { exitCode: 0 };
 }
+async function guideCommand(parsed, io) {
+  const query = parsed.positionals.join(" ").trim();
+  const jsonMode = hasFlag(parsed, "json");
+  const synthesizeMode = hasFlag(parsed, "synthesize");
+  if (!query) {
+    const recipes = listArchitectureRecipes();
+    if (jsonMode) {
+      io.stdout(JSON.stringify(recipes, null, 2));
+    } else {
+      io.stdout("Markdy Architecture Recipe Catalog:\n");
+      for (const r of recipes) {
+        io.stdout(`  \u2022 [${r.id}] ${r.name} (${r.category}) - ${r.description}`);
+      }
+      io.stdout('\nRun `markdy guide "<query>"` or `markdy recipe <id>` to view full blueprint code.');
+    }
+    return { exitCode: 0 };
+  }
+  if (synthesizeMode) {
+    const synthesized = synthesizeCustomRecipe(query);
+    if (jsonMode) {
+      io.stdout(JSON.stringify(synthesized, null, 2));
+    } else {
+      io.stdout(`
+\u26A1 Dynamic Architecture Synthesis for: "${query}"`);
+      io.stdout(`Pattern: ${synthesized.inferredPattern}`);
+      io.stdout(`Components: ${synthesized.detectedComponents.map((c) => `${c.id} (${c.kind})`).join(", ")}`);
+      io.stdout(`Rationale: ${synthesized.rationale}
+`);
+      io.stdout("Synthesized MarkdyScript:\n");
+      io.stdout(synthesized.markdyScript);
+    }
+    return { exitCode: 0 };
+  }
+  const recommendations = recommendArchitecturePattern(query);
+  if (jsonMode) {
+    io.stdout(JSON.stringify(recommendations, null, 2));
+    return { exitCode: 0 };
+  }
+  const top = recommendations[0];
+  io.stdout(`
+\u2728 Recommended Architecture Pattern: ${top.recipe.name} (${top.recipe.id})`);
+  io.stdout(`Category: ${top.recipe.category} | Layout: ${top.recipe.recommendedLayout}`);
+  io.stdout(`Rationale: ${top.rationale}
+`);
+  io.stdout("Highlights:");
+  for (const hl of top.recipe.highlights) {
+    io.stdout(`  - ${hl}`);
+  }
+  io.stdout("\nCanonical Markdy Blueprint:\n");
+  io.stdout(top.recipe.code);
+  return { exitCode: 0 };
+}
+async function recipeCommand(parsed, io) {
+  const recipeId = parsed.positionals[0];
+  const jsonMode = hasFlag(parsed, "json");
+  if (!recipeId) {
+    return guideCommand(parsed, io);
+  }
+  const recipe = getArchitectureRecipe(recipeId);
+  if (!recipe) {
+    io.stderr(`markdy recipe: no recipe found for '${recipeId}'. Run 'markdy guide' to list available recipes.`);
+    return { exitCode: 1 };
+  }
+  if (jsonMode) {
+    io.stdout(JSON.stringify(recipe, null, 2));
+  } else {
+    io.stdout(recipe.code);
+  }
+  return { exitCode: 0 };
+}
+async function verifyCommand(parsed, io) {
+  const file = parsed.positionals[0];
+  if (!file) {
+    io.stderr("markdy verify: expected a .markdy input file");
+    return { exitCode: 1 };
+  }
+  const qualityFlag = getStringFlag(parsed, "quality")?.toLowerCase();
+  const strict = hasFlag(parsed, "strict") || qualityFlag === "strict" || qualityFlag === "showcase";
+  const profile = strict ? "showcase" : "standard";
+  const jsonMode = hasFlag(parsed, "json");
+  const scene = await loadSceneFromFile(file);
+  const report = verifyDiagramQuality(scene.ast, { profile });
+  if (jsonMode) {
+    io.stdout(JSON.stringify(report, null, 2));
+    return { exitCode: report.passed ? 0 : 1 };
+  }
+  io.stdout("\n\u{1F50D} Markdy 9-Point Quality Gate & Viewport Verification");
+  io.stdout(`File: ${scene.filePath}`);
+  io.stdout(`Profile: ${report.qualityProfile.toUpperCase()} | SHA-256 Receipt: ${report.sha256Receipt}`);
+  io.stdout(`Status: ${report.passed ? "\u2705 PASSED" : "\u274C FAILED"} (Errors: ${report.errorCount}, Warnings: ${report.warningCount})
+`);
+  io.stdout("Checks:");
+  for (const check of report.checks) {
+    const symbol = check.status === "pass" ? "\u2713" : check.status === "warn" ? "\u26A0" : "\u2717";
+    io.stdout(`  ${symbol} [${check.id}] ${check.name}: ${check.message}`);
+  }
+  io.stdout("\nViewport Compliance:");
+  for (const [vp, compliant] of Object.entries(report.viewportCompliance)) {
+    io.stdout(`  \u2022 ${vp}: ${compliant ? "\u2713 PASS" : "\u2717 OVERFLOW"}`);
+  }
+  io.stdout("\nMetrics:");
+  io.stdout(`  Nodes: ${report.metrics.nodeCount} | Edges: ${report.metrics.edgeCount} | Story Beats: ${report.metrics.beatCount}`);
+  io.stdout(`  Estimated Dimensions: ${report.metrics.estimatedWidth}\xD7${report.metrics.estimatedHeight} (Aspect Ratio: ${report.metrics.aspectRatio})`);
+  io.stdout(`  Code Provenance Anchors: ${report.metrics.provenanceAnchorCount} | Vector Symbols: ${report.metrics.symbolCount}
+`);
+  return { exitCode: report.passed ? 0 : 1 };
+}
 async function newCommand(parsed, io) {
   const target = parsed.positionals[0] ?? "scene.markdy";
   const force = hasFlag(parsed, "force");
@@ -310,6 +440,10 @@ async function importCommand(parsed, io) {
   let markdyCode;
   if (formatFlag === "mermaid" || ext === ".mmd" || ext === ".mermaid") {
     markdyCode = compat.transpileMermaidToMarkdy(content, title).code;
+  } else if (formatFlag === "d2" || ext === ".d2") {
+    markdyCode = compat.transpileD2ToMarkdy(content).markdyScript;
+  } else if (formatFlag === "plantuml" || formatFlag === "puml" || ext === ".puml" || ext === ".plantuml" || content.includes("@startuml")) {
+    markdyCode = compat.transpilePlantUmlToMarkdy(content).markdyScript;
   } else if (formatFlag === "compose" || (ext === ".yml" || ext === ".yaml") && (inputFile.includes("compose") || content.includes("services:"))) {
     markdyCode = compat.transpileDockerComposeToMarkdy(content, title);
   } else if (formatFlag === "k8s" || content.includes("apiVersion:") && content.includes("kind:")) {
@@ -355,6 +489,105 @@ async function diffCommand(parsed, io) {
   io.stdout(diffResult.summaryMarkdown);
   return { exitCode: 0 };
 }
+async function collectRepoFiles(dir, baseDir = dir) {
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  const files = [];
+  for (const entry of entries) {
+    if (entry.name.startsWith(".") || entry.name === "node_modules" || entry.name === "dist" || entry.name === "build") {
+      continue;
+    }
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await collectRepoFiles(full, baseDir));
+    } else if (entry.isFile()) {
+      files.push(relative(baseDir, full).replace(/\\/g, "/"));
+    }
+  }
+  return files;
+}
+async function driftCommand(parsed, io) {
+  const file = parsed.positionals[0];
+  if (!file) {
+    io.stderr("markdy drift: expected a .markdy input file (e.g. markdy drift system.markdy)");
+    return { exitCode: 1 };
+  }
+  const scene = await loadSceneFromFile(file).catch((err) => {
+    io.stderr(`markdy drift: ${describeError(err)}`);
+    return null;
+  });
+  if (!scene) return { exitCode: 1 };
+  const repoRoot = resolve(getStringFlag(parsed, "repo") || process.cwd());
+  const repoFiles = await collectRepoFiles(repoRoot);
+  const report = detectArchitectureDrift(scene.ast, repoFiles);
+  const fixMode = hasFlag(parsed, "fix");
+  if (fixMode) {
+    const healed = autoHealArchitectureDrift(scene.ast, report, repoFiles);
+    await writeFile(scene.filePath, healed.healedMarkdyScript, "utf8");
+    if (hasFlag(parsed, "json")) {
+      io.stdout(JSON.stringify({ report, healed }, null, 2));
+    } else {
+      io.stdout(report.summaryMarkdown);
+      io.stdout(`
+\u2705 Auto-healed ${healed.healedAnchorCount} broken anchor(s) and incorporated ${healed.addedServiceCount} orphan service(s) into ${file}`);
+      for (const m of healed.healedMappings) {
+        io.stdout(`  \u2022 ${m.nodeId}: \`${m.oldPath}\` \u2192 \`${m.newPath}\``);
+      }
+    }
+    return { exitCode: 0 };
+  }
+  if (hasFlag(parsed, "json")) {
+    io.stdout(JSON.stringify(report, null, 2));
+    return { exitCode: report.isSynchronized ? 0 : 1 };
+  }
+  io.stdout(report.summaryMarkdown);
+  if (report.healingMarkdySnippet) {
+    io.stdout("\n\u2728 Suggested MarkdyScript Additions (Pass `--fix` to auto-apply):\n```markdy\n" + report.healingMarkdySnippet + "\n```\n");
+  }
+  return { exitCode: report.isSynchronized ? 0 : 1 };
+}
+async function c4Command(parsed, io) {
+  const file = parsed.positionals[0];
+  if (!file) {
+    io.stderr("markdy c4: expected a .markdy input file (e.g. markdy c4 system.markdy)");
+    return { exitCode: 1 };
+  }
+  const scene = await loadSceneFromFile(file).catch((err) => {
+    io.stderr(`markdy c4: ${describeError(err)}`);
+    return null;
+  });
+  if (!scene) return { exitCode: 1 };
+  if (hasFlag(parsed, "storyboard")) {
+    const storyboard = generateC4Storyboard(scene.ast);
+    io.stdout(storyboard);
+    return { exitCode: 0 };
+  }
+  if (hasFlag(parsed, "export-views")) {
+    const views = exportC4LevelViews(scene.ast);
+    const targetDir = getStringFlag(parsed, "out") || dirname(resolve(file));
+    const base = basename(file, extname(file));
+    for (const [lvl, exportData] of Object.entries(views)) {
+      const outPath = join(targetDir, `${base}-L${exportData.levelNumber}-${lvl}.markdy`);
+      await writeFile(outPath, exportData.markdyScript, "utf8");
+      io.stdout(`  \u2713 Exported C4 L${exportData.levelNumber} [${lvl.toUpperCase()}]: ${outPath} (${exportData.nodeCount} nodes, ${exportData.edgeCount} flows)`);
+    }
+    io.stdout(`
+\u{1F4E6} Successfully exported 4 C4 level blueprints to ${targetDir}`);
+    return { exitCode: 0 };
+  }
+  const levelFlag = getStringFlag(parsed, "level");
+  if (levelFlag) {
+    const { visibleNodeIds } = filterC4Hierarchy(scene.ast, levelFlag);
+    io.stdout(`C4 Level [${levelFlag.toUpperCase()}]: ${visibleNodeIds.length} nodes visible (${visibleNodeIds.join(", ")})`);
+    return { exitCode: 0 };
+  }
+  const report = analyzeC4Model(scene.ast);
+  if (hasFlag(parsed, "json")) {
+    io.stdout(JSON.stringify(report, null, 2));
+    return { exitCode: 0 };
+  }
+  io.stdout(report.summaryMarkdown);
+  return { exitCode: 0 };
+}
 async function shareCommand(parsed, io) {
   const file = parsed.positionals[0];
   if (!file) {
@@ -1255,8 +1488,13 @@ function helpText() {
     "  markdy lint <file-or-dir> [--strict] [--arch-rules]",
     "  markdy fmt <file-or-dir> [--write | --check]",
     "  markdy render <file.markdy> [--out file.html] [--port 4242] [--no-open]",
+    "  markdy verify <file.markdy> [--quality standard|strict|showcase] [--json]",
+    "  markdy guide [scenario-query] [--synthesize] [--json]",
+    "  markdy recipe <recipe-id> [--json]",
+    "  markdy c4 <file.markdy> [--level context|container|component|code] [--storyboard] [--export-views] [--out <dir>] [--json]",
+    "  markdy drift <file.markdy> [--repo <dir>] [--fix] [--json]",
     "  markdy explain <file.markdy> [--json]",
-    "  markdy import <file> [--from compose|k8s|terraform|mermaid] [--out scene.markdy]",
+    "  markdy import <file> [--from compose|k8s|terraform|mermaid|d2|plantuml] [--out scene.markdy]",
     "  markdy diff <before.markdy> <after.markdy> [--evolution]",
     "  markdy share <file.markdy>",
     "  markdy suggest <file.markdy> [--line <n>] [--col <n>] [--json]",
@@ -1322,7 +1560,7 @@ function parseArgv(argv) {
   return { command, positionals, flags };
 }
 function expectsValue(flag) {
-  return flag === "out" || flag === "port" || flag === "config" || flag === "dist" || flag === "from" || flag === "line" || flag === "col";
+  return flag === "out" || flag === "port" || flag === "config" || flag === "dist" || flag === "from" || flag === "line" || flag === "col" || flag === "quality" || flag === "level" || flag === "repo" || flag === "theme" || flag === "format";
 }
 function hasFlag(parsed, name) {
   return parsed.flags.get(name) === true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markdy/cli",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "First-party CLI for diagram-native MarkdyScript diagrams: lint, format, explain, render, and preview.",
   "license": "MIT",
   "type": "module",
@@ -43,10 +43,10 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@markdy/compat": "1.2.0",
-    "@markdy/renderer-dom": "1.2.0",
-    "@markdy/core": "1.2.0",
-    "@markdy/stdlib-systems": "1.2.0"
+    "@markdy/compat": "1.3.0",
+    "@markdy/stdlib-systems": "1.3.0",
+    "@markdy/core": "1.3.0",
+    "@markdy/renderer-dom": "1.3.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.5",