irgen 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to the `irgen` project will be documented in this file.
 
+## [0.3.2] - 2026-02-04
+
+### Enhancements
+- **CLI Execution Order**: Refactored the core entry point to ensure TypeScript support (`tsx`) and extensions (`--ext`) are fully loaded before subcommands (`init`, `studio`, `check`) are executed.
+- **Detailed CLI Help**: Added specialized help messages for `init`, `studio`, and `check` commands, providing better guidance on parameters and extension usage.
+- **Resilient Studio Dashboard**: Updated the Studio UI to be more robust when visualizing complex Hybrid applications (Backend + Frontend) and added better error handling for malformed IR.
+
+### Bug Fixes
+- **Studio Data Loading**: Fixed an issue where the Studio dashboard would appear empty when using extension-specific DSLs due to late extension loading.
+
 ## [0.3.1] - 2026-02-03
 
 ### New Features

package/README.md

@@ -92,6 +92,9 @@ npx irgen examples/app.dsl.ts --targets=backend,frontend --outDir=generated/full
 # Static-site (HTML-first)
 npx irgen examples/docs.dsl.ts --targets=static-site --outDir=generated/static-docs
 
+> [!TIP]
+> **Working with multiple DSL files?** Instead of passing multiple files to the CLI, use a **single entry point** and `import` your other DSL files. This ensures your project structure remains clean and prevents CLI ambiguity.
+
 ## Specialized Commands
 
 ### Project Scaffolding

package/dist/cli/check.js

@@ -1,6 +1,22 @@
 import { aggregateDecls } from "../dsl/aggregator.js";
 import { validateSemantics } from "../dsl/validator.js";
 export async function runCheck(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log(`
+irgen check — Semantic validation for irgen DSL files
+
+Usage:
+  irgen check <dsl-file>... [options]
+
+Options:
+  --ext=<path>         Load extensions (for extension-specific validation)
+  --help, -h           Show this help message
+
+Example:
+  npx irgen check app.dsl.ts ui.dsl.ts --ext=irgen-ext-php-shared-hosting
+        `);
+        return;
+    }
     const dslFiles = args.filter(a => a.endsWith(".dsl.ts"));
     if (dslFiles.length === 0) {
         console.error("Usage: irgen check <dsl-file>...");
@@ -8,12 +24,6 @@ export async function runCheck(args) {
     }
     console.log(`Checking semantic integrity for: ${dslFiles.join(", ")}...`);
     try {
-        const extFlags = args.filter(a => a.startsWith("--ext="));
-        const extModules = extFlags.flatMap(f => f.replace("--ext=", "").split(",")).filter(Boolean);
-        if (extModules.length > 0) {
-            const { loadExtensions } = await import("./extensions.js");
-            await loadExtensions(extModules);
-        }
         const decl = await aggregateDecls(dslFiles);
         const messages = validateSemantics(decl);
         if (messages.length === 0) {

package/dist/cli/init.js

@@ -2,11 +2,29 @@ import prompts from "prompts";
 import fs from "node:fs";
 import path from "node:path";
 export async function runInit(args) {
-    const extFlags = args.filter(a => a.startsWith("--ext="));
-    const extModules = extFlags.flatMap(f => f.replace("--ext=", "").split(",")).filter(Boolean);
-    if (extModules.length > 0) {
-        const { loadExtensions } = await import("./extensions.js");
-        await loadExtensions(extModules);
+    if (args.includes("--help") || args.includes("-h")) {
+        const { templateRegistry } = await import("./template-registry.js");
+        const extTemplates = templateRegistry.getTemplates();
+        console.log(`
+irgen init — Scaffold a new irgen project
+
+Usage:
+  irgen init <projectName> [options]
+
+Options:
+  --ext=<path>         Load extensions (provides extra templates)
+  --help, -h           Show this help message
+
+Available Templates:
+  - fullstack          Standard Backend + Frontend (React)
+  - backend            Node.js/Prisma backend only
+  - frontend           React/Vite frontend only
+${extTemplates.map(t => `  - ${t.id.padEnd(18)} ${t.title}`).join("\n")}
+
+Example:
+  npx irgen init my-blog --ext=irgen-ext-php-shared-hosting --template=php-blog
+        `);
+        return;
     }
     const { templateRegistry } = await import("./template-registry.js");
     const extTemplates = templateRegistry.getTemplates();

package/dist/cli/studio.js

@@ -4,6 +4,25 @@ import { aggregateDecls } from "../dsl/aggregator.js";
 import path from "node:path";
 import fs from "node:fs";
 export async function runStudio(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log(`
+irgen studio — Interactive DSL Dashboard
+
+Usage:
+  irgen studio <dsl-file>... [options]
+
+Options:
+  --ext=<path>         Load extensions (to visualize custom mappers/emitters)
+  --help, -h           Show this help message
+
+The Studio provides a real-time visual representation of your system's
+entities, pages, and components as defined in your DSL.
+
+Example:
+  npx irgen studio app.dsl.ts ui.dsl.ts --ext=irgen-ext-php-shared-hosting
+        `);
+        return;
+    }
     const dslFiles = args.filter(a => a.endsWith(".dsl.ts"));
     if (dslFiles.length === 0) {
         console.error("Usage: irgen studio <dsl-file>...");
@@ -40,7 +59,6 @@ export async function runStudio(args) {
         res.json(currentIR);
     });
     // Static UI
-    // For now, let's embed a simple but beautiful HTML
     app.get("/", (req, res) => {
         res.send(getStudioHtml());
     });
@@ -278,14 +296,17 @@ function getStudioHtml() {
             document.getElementById('header-content').innerHTML = '<h2>Project Overview</h2><p>Summary of discovered resources</p>';
             let totalEntities = 0;
             let totalPages = 0;
-            ir.apps.forEach(a => { totalEntities += (a.entities?.length || 0); totalPages += (a.pages?.length || 0); });
+            ir.apps.forEach(a => { 
+                if (a.entities) totalEntities += a.entities.length;
+                if (a.pages) totalPages += a.pages.length;
+            });
 
             const content = document.getElementById('content');
             content.innerHTML = \`
                 <div class="stats-row">
                     <div class="stat-card">
                         <div class="stat-value">\${ir.apps.length}</div>
-                        <div class="stat-label">Applications</div>
+                        <div class="stat-label">Applications / Modules</div>
                     </div>
                     <div class="stat-card">
                         <div class="stat-value">\${totalEntities}</div>
@@ -297,14 +318,22 @@ function getStudioHtml() {
                     </div>
                 </div>
                 <div class="card">
-                    <h3>Metadata</h3>
+                    <h3>Metadata & Configuration</h3>
                     <table class="mono">
-                        \${Object.entries(ir.apps[0]?.meta || {}).map(([k,v]) => \`
+                        \${Object.entries(ir.meta || {}).map(([k,v]) => \`
                             <tr>
-                                <td style="color: var(--accent)">\${k}</td>
-                                <td>\${JSON.stringify(v)}</td>
+                                <td style="color: var(--accent); width: 200px">\${k}</td>
+                                <td><pre style="margin:0; white-space: pre-wrap">\${JSON.stringify(v, null, 2)}</pre></td>
                             </tr>
                         \`).join('')}
+                        \${ir.apps.map(app => 
+                            Object.entries(app.meta || {}).map(([k,v]) => \`
+                                <tr>
+                                    <td style="color: var(--text-dim)">[\${app.name}] \${k}</td>
+                                    <td><pre style="margin:0; white-space: pre-wrap">\${JSON.stringify(v, null, 2)}</pre></td>
+                                </tr>
+                            \`).join('')
+                        ).join('')}
                     </table>
                 </div>
             \`;
@@ -352,7 +381,7 @@ function getStudioHtml() {
                                     <strong>\${comp.name}</strong>
                                     \${comp.entityRef ? '<span class="badge">Bound</span>' : ''}
                                 </div>
-                                \${comp.entityRef ? \`<div class="stat-label">Entity: \${comp.entityRef}</div>\` : ''}
+                                \${comp.entityRef ? \\\`<div class="stat-label">Entity: \\\${comp.entityRef}</div>\\\` : ''}
                             </div>
                         \`).join('')}
                     </div>

package/dist/cli.js

@@ -44,6 +44,17 @@ Examples:
         console.log("irgen 0.1.0");
         process.exit(0);
     }
+    try {
+        const { register } = await import("tsx/esm/api");
+        register();
+    }
+    catch (err) {
+        console.warn("tsx loader unavailable; falling back to manual TS transpile where supported.", err instanceof Error ? err.message : err);
+    }
+    const rawArgs = process.argv.slice(2);
+    const extFlags = rawArgs.filter(a => a.startsWith("--ext="));
+    const extModules = extFlags.flatMap(f => f.replace("--ext=", "").split(",")).filter(Boolean);
+    await loadExtensions(extModules);
     if (process.argv[2] === "check") {
         const { runCheck } = await import("./cli/check.js");
         await runCheck(process.argv.slice(3));
@@ -59,13 +70,6 @@ Examples:
         await runInit(process.argv.slice(3));
         process.exit(0);
     }
-    try {
-        const { register } = await import("tsx/esm/api");
-        register();
-    }
-    catch (err) {
-        console.warn("tsx loader unavailable; falling back to manual TS transpile where supported.", err instanceof Error ? err.message : err);
-    }
     const modeFlag = process.argv.find(a => a.startsWith("--mode=")) ?? "--mode=backend";
     const mode = modeFlag.split("=")[1];
     // Additional flags: --emitters (list emitters), --emitter=<name> (run one emitter)
@@ -73,9 +77,6 @@ Examples:
     const emitterFlag = process.argv.find(a => a.startsWith("--emitter=")) ?? null;
     const emitterName = emitterFlag ? emitterFlag.split("=")[1] : null;
     // parse positional args: first DSL entry and optional outDir
-    const rawArgs = process.argv.slice(2);
-    const extFlags = rawArgs.filter(a => a.startsWith("--ext="));
-    const extModules = extFlags.flatMap(f => f.replace("--ext=", "").split(",")).filter(Boolean);
     const outDirFlag = process.argv.find(a => a.startsWith("--outDir=")) ?? null;
     const entries = rawArgs.filter(a => a.endsWith(".dsl.ts"));
     const entry = entries[0];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "irgen",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "private": false,
   "license": "MIT",
   "description": "a policy-driven, IR-based code generation toolchain for backend, frontend, and beyond.",