@clarity-tools/cli 0.1.1 → 0.1.2

package/README.md

@@ -4,6 +4,16 @@ Generate beautiful, hand-drawn style architecture diagrams from your Infrastruct
 
 [![npm version](https://img.shields.io/npm/v/@clarity-tools/cli.svg)](https://www.npmjs.com/package/@clarity-tools/cli)
 
+## Examples
+
+### Temporal
+
+![Temporal architecture](https://raw.githubusercontent.com/BrennerSpear/clarity/main/docs/images/temporal.png)
+
+### Mastodon
+
+![Mastodon architecture](https://raw.githubusercontent.com/BrennerSpear/clarity/main/docs/images/mastodon.png)
+
 ## Features
 
 - **Auto-detection**: Finds docker-compose.yml, compose.yml, and Helm charts
@@ -50,6 +60,7 @@ iac-diagrams [path] [options]
 - `-o, --output <dir>` - Output directory (default: `./docs/diagrams`)
 - `--no-llm` - Disable LLM enhancement
 - `--no-png` - Skip PNG rendering (output .excalidraw only)
+- `--artifacts` - Save parsed/enhanced/elk JSON artifacts alongside outputs
 - `-v, --verbose` - Show detailed output
 
 **Examples:**
@@ -108,6 +119,16 @@ docs/diagrams/
 └── docker-compose.png         # Rendered PNG image
 ```
 
+With `--artifacts`, additional JSON files are saved:
+
+```
+docs/diagrams/
+├── docker-compose.parsed.json      # Parsed InfraGraph
+├── docker-compose.enhanced.json    # Enhanced InfraGraph (LLM if enabled)
+├── docker-compose.elk-input.json   # ELK input graph
+└── docker-compose.elk-output.json  # ELK output graph (with positions)
+```
+
 The `.excalidraw` file can be opened at [excalidraw.com](https://excalidraw.com) for editing.
 
 ## Supported Formats
@@ -153,6 +174,12 @@ iac-diagrams config show
 
 The key should start with `sk-or-`.
 
+## Appendix: Diagram Conventions
+
+- Shapes: rectangles for application services, ellipses for databases/caches, diamonds for message queues
+- Colors: blue=database, red=cache, green=storage, yellow=queue
+- Layering: UI -> API -> worker -> data -> infrastructure
+
 ## License
 
 MIT

package/dist/index.js

@@ -1596,9 +1596,37 @@ function infraGraphToElk(graph, options = {}) {
 }
 
 // ../core/src/elk/layout.ts
+import { createRequire } from "module";
 import ELK from "elkjs";
+var require2 = createRequire(import.meta.url);
+var loadWorkerModule = () => {
+  const globalSelf = globalThis;
+  const hadSelf = Object.prototype.hasOwnProperty.call(globalSelf, "self");
+  const originalSelf = globalSelf.self;
+  try {
+    globalSelf.self = void 0;
+    return require2("elkjs/lib/elk-worker.js");
+  } finally {
+    if (hadSelf) {
+      globalSelf.self = originalSelf;
+    } else {
+      delete globalSelf.self;
+    }
+  }
+};
+var resolveWorkerConstructor = () => {
+  const workerModule = loadWorkerModule();
+  const maybeWorker = workerModule.Worker ?? workerModule.default ?? workerModule;
+  if (typeof maybeWorker === "function") {
+    return maybeWorker;
+  }
+  throw new Error("ELK worker module not available");
+};
 async function runLayout(graph) {
-  const elk = new ELK();
+  const WorkerCtor = resolveWorkerConstructor();
+  const elk = new ELK({
+    workerFactory: (url) => new WorkerCtor(url)
+  });
   const result = await elk.layout(graph);
   return {
     graph: result,
@@ -2507,6 +2535,7 @@ async function generate(inputPath, options = {}) {
   const verbose = options.verbose ?? false;
   const skipPng = options.png === false;
   const skipLlm = options.llm === false;
+  const saveArtifacts = options.artifacts ?? false;
   if (!skipPng) {
     const browserCheck = await checkBrowserAvailability();
     if (!browserCheck.available) {
@@ -2556,12 +2585,21 @@ async function generate(inputPath, options = {}) {
   for (const file of detected) {
     console.log(`
 Generating diagram for: ${file.name}`);
+    const baseName = file.name.replace(/\.(yml|yaml)$/i, "");
+    const writeArtifact = async (suffix, data) => {
+      if (!saveArtifacts) return;
+      const artifactPath = join6(outputDir, `${baseName}.${suffix}.json`);
+      await writeFile2(artifactPath, JSON.stringify(data, null, 2));
+      console.log(`  \x1B[32m\u2713\x1B[0m Saved: ${artifactPath}`);
+    };
     if (verbose) console.log("  Step 1: Parsing...");
-    let graph = await parseIaC(file, verbose);
+    const parsedGraph = await parseIaC(file, verbose);
+    let graph = parsedGraph;
     if (verbose) {
       console.log(`    Found ${graph.nodes.length} services`);
       console.log(`    Found ${graph.edges.length} dependencies`);
     }
+    await writeArtifact("parsed", parsedGraph);
     if (llmEnabled && apiKey) {
       if (verbose) console.log("  Step 2: Enhancing with LLM...");
       try {
@@ -2574,12 +2612,14 @@ Generating diagram for: ${file.name}`);
     } else if (verbose) {
       console.log("  Step 2: Skipping LLM enhancement");
     }
+    await writeArtifact("enhanced", graph);
     if (verbose) console.log("  Step 3: Computing layout...");
     const elkConversion = infraGraphToElk(graph);
     const elkLayoutResult = await runLayout(elkConversion.graph);
+    await writeArtifact("elk-input", elkConversion.graph);
+    await writeArtifact("elk-output", elkLayoutResult.graph);
     if (verbose) console.log("  Step 4: Generating Excalidraw...");
     const excalidraw = renderWithElkLayout(graph, elkLayoutResult.graph);
-    const baseName = file.name.replace(/\.(yml|yaml)$/i, "");
     const excalidrawPath = join6(outputDir, `${baseName}.excalidraw`);
     await writeFile2(excalidrawPath, JSON.stringify(excalidraw, null, 2));
     console.log(`  \x1B[32m\u2713\x1B[0m Saved: ${excalidrawPath}`);
@@ -2601,7 +2641,10 @@ var program = new Command2().name("iac-diagrams").description(
   "[path]",
   "File or directory to process (default: current directory)",
   "."
-).option("-o, --output <dir>", "Output directory", "./docs/diagrams").option("--no-llm", "Disable LLM enhancement").option("--no-png", "Skip PNG rendering (output .excalidraw only)").option("-v, --verbose", "Show detailed output").action(
+).option("-o, --output <dir>", "Output directory", "./docs/diagrams").option("--no-llm", "Disable LLM enhancement").option("--no-png", "Skip PNG rendering (output .excalidraw only)").option(
+  "--artifacts",
+  "Save parsed/enhanced/elk JSON artifacts alongside outputs"
+).option("-v, --verbose", "Show detailed output").action(
   async (path, options) => {
     await generate(path, options);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@clarity-tools/cli",
-	"version": "0.1.1",
+	"version": "0.1.2",
 	"description": "Generate architecture diagrams from Infrastructure-as-Code files (Docker Compose, Helm charts)",
 	"type": "module",
 	"bin": {