npm - larats - Versions diffs - 1.0.1 → 1.1.0 - Mend

larats 1.0.1 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/dist/index.js CHANGED Viewed

@@ -2,7 +2,10 @@
 // src/index.ts
 import fs3 from "fs";
-import path3 from "path";
+import path4 from "path";
+import os2 from "os";
+import { exec } from "child_process";
+import { parseArgs } from "util";
 import * as p from "@clack/prompts";
 import pc from "picocolors";
@@ -12,7 +15,7 @@ import path from "path";
 function readJsonSafe(filePath) {
   try {
     if (!fs.existsSync(filePath)) return null;
-    const content = fs.readFileSync(filePath, "utf-8");
+    const content = fs.readFileSync(filePath, "utf-8").replace(/^\uFEFF/, "");
     return JSON.parse(content);
   } catch {
     return null;
@@ -39,11 +42,13 @@ async function detectProjectType(targetDir = process.cwd()) {
     const hasInertia = "inertiajs/inertia-laravel" in allDeps;
     const hasSanctum = "laravel/sanctum" in allDeps;
     const rawVersion = allDeps["laravel/framework"] || "";
-    const cleanVersion = rawVersion.replace(/[\^~><=]/g, "").trim();
+    const versionMatch = rawVersion.match(/\d+(?:\.\d+)*/);
+    const cleanVersion = versionMatch ? versionMatch[0] : "";
     const appModulesDir = path.join(resolvedDir, "app", "Modules");
     const rootModulesDir = path.join(resolvedDir, "modules");
-    const isModular = fs.existsSync(appModulesDir) || fs.existsSync(rootModulesDir);
-    const modulesDir = fs.existsSync(appModulesDir) ? "app/Modules" : fs.existsSync(rootModulesDir) ? "modules" : void 0;
+    const rootModulesCapDir = path.join(resolvedDir, "Modules");
+    const isModular = fs.existsSync(appModulesDir) || fs.existsSync(rootModulesDir) || fs.existsSync(rootModulesCapDir);
+    const modulesDir = fs.existsSync(appModulesDir) ? "app/Modules" : fs.existsSync(rootModulesDir) ? "modules" : fs.existsSync(rootModulesCapDir) ? "Modules" : void 0;
     const extras = [];
     if (hasFilament) extras.push("Filament");
     if (hasLivewire) extras.push("Livewire");
@@ -66,7 +71,7 @@ async function detectProjectType(targetDir = process.cwd()) {
       summary
     };
   }
-  if (hasTsConfig && hasPackageJson) {
+  if (hasPackageJson) {
     const pkg = readJsonSafe(packageJsonPath);
     const allDeps = {
       ...pkg?.dependencies || {},
@@ -88,13 +93,15 @@ async function detectProjectType(targetDir = process.cwd()) {
     const hasSrc = fs.existsSync(path.join(resolvedDir, "src"));
     const srcDir = hasSrc ? "src" : ".";
     const isModular = fs.existsSync(path.join(resolvedDir, srcDir, "modules")) || fs.existsSync(path.join(resolvedDir, "modules"));
-    const extras = [framework !== "node-vanilla" ? framework : "TypeScript"];
+    const isTypeScript = hasTsConfig || "typescript" in allDeps;
+    const stackLabel = isTypeScript ? "TypeScript" : "JavaScript / Node.js";
+    const extras = [framework !== "node-vanilla" ? framework : stackLabel];
     if (hasPrisma) extras.push("Prisma");
     if (hasTypeORM) extras.push("TypeORM");
     if (hasDrizzle) extras.push("Drizzle");
     if (isMonorepo) extras.push("Monorepo");
     if (isModular) extras.push("Modular");
-    const summary = `TypeScript (${extras.join(", ")})`;
+    const summary = isTypeScript ? `TypeScript (${extras.join(", ")})` : `JavaScript / Node.js (${extras.join(", ")})`;
     return {
       type: "typescript",
       name: pkg?.name || dirName,
@@ -106,7 +113,8 @@ async function detectProjectType(targetDir = process.cwd()) {
         hasDrizzle,
         isMonorepo,
         isModular,
-        srcDir
+        srcDir,
+        isTypeScript
       },
       summary
     };
@@ -125,6 +133,8 @@ async function detectProjectType(targetDir = process.cwd()) {
 }
 // src/scanner.ts
+import path2 from "path";
+import os from "os";
 import fg from "fast-glob";
 var SAFE_IGNORE_LIST = [
   // Dependencies & package management
@@ -136,32 +146,42 @@ var SAFE_IGNORE_LIST = [
   "**/.git/**",
   "**/.svn/**",
   "**/.hg/**",
-  // Storage, cache & build outputs
+  // Storage, cache & build outputs (scoped to root to preserve src/build/)
   "**/storage/**",
   "**/dist/**",
-  "**/build/**",
-  "**/out/**",
+  "build/**",
+  "out/**",
   "**/.next/**",
   "**/.nuxt/**",
   "**/.turbo/**",
   "**/.cache/**",
   "**/coverage/**",
   "**/.temp/**",
-  "**/tmp/**",
+  "tmp/**",
   // IDEs & OS files
   "**/.idea/**",
   "**/.vscode/**",
   "**/.DS_Store",
   "**/Thumbs.db",
-  // Secrets & environment configurations
+  // Secrets, private keys & cloud credentials
   "**/.env*",
   "**/*.pem",
   "**/*.key",
   "**/*.pfx",
+  "**/*.p12",
+  "**/*.jks",
+  "**/*.keystore",
   "**/*.cert",
   "**/*.crt",
   "**/*.secret",
-  "**/*.id_rsa",
+  "**/secrets/**",
+  "**/.aws/**",
+  "**/.ssh/**",
+  "**/credentials*.json",
+  "**/*service-account*.json",
+  "**/id_rsa*",
+  "**/id_ed25519*",
+  "**/id_ecdsa*",
   "**/*.pub",
   // Logs & Lock files
   "**/*.log",
@@ -171,6 +191,9 @@ var SAFE_IGNORE_LIST = [
   "**/pnpm-lock.yaml",
   "**/composer.lock"
 ];
+function localeIndependentCompare(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
 function buildCleanDirectoryTree(files, maxDepth = 3) {
   const root = { name: "", isDir: true, children: /* @__PURE__ */ new Map() };
   for (const file of files) {
@@ -194,7 +217,7 @@ function buildCleanDirectoryTree(files, maxDepth = 3) {
     if (currentDepth > maxDepth) return;
     const entries = Array.from(node.children.values()).sort((a, b) => {
       if (a.isDir !== b.isDir) return a.isDir ? -1 : 1;
-      return a.name.localeCompare(b.name);
+      return localeIndependentCompare(a.name, b.name);
     });
     if (currentDepth === maxDepth && entries.length > 0) {
       lines.push(`${prefix}\u2514\u2500\u2500 ... (${entries.length} items hidden)`);
@@ -219,7 +242,7 @@ function buildCleanDirectoryTree(files, maxDepth = 3) {
   }
   const topLevel = Array.from(root.children.values()).sort((a, b) => {
     if (a.isDir !== b.isDir) return a.isDir ? -1 : 1;
-    return a.name.localeCompare(b.name);
+    return localeIndependentCompare(a.name, b.name);
   });
   topLevel.forEach((child, index) => {
     const isLast = index === topLevel.length - 1;
@@ -236,52 +259,76 @@ function buildCleanDirectoryTree(files, maxDepth = 3) {
 async function scanProject(projectInfo) {
   const startTime = Date.now();
   const root = projectInfo.rootPath;
+  const resolvedRoot = path2.resolve(root);
+  const parsedRoot = path2.parse(resolvedRoot);
+  if (parsedRoot.root === resolvedRoot || typeof os.homedir === "function" && resolvedRoot === os.homedir()) {
+    throw new Error(`Refusing to scan system drive or home directory root directly: "${resolvedRoot}".`);
+  }
   const allFiles = await fg("**/*", {
     cwd: root,
     ignore: SAFE_IGNORE_LIST,
     dot: false,
-    onlyFiles: true
+    onlyFiles: true,
+    followSymbolicLinks: false,
+    suppressErrors: true
   });
-  const normalizedFiles = allFiles.map((f) => f.replace(/\\/g, "/"));
+  const MAX_FILES_CAP = 1e4;
+  let normalizedFiles = allFiles.map((f) => f.replace(/\\/g, "/"));
+  if (normalizedFiles.length > MAX_FILES_CAP) {
+    console.warn(`[WARN] Large codebase detected (${normalizedFiles.length} files). Capping scan analysis to first ${MAX_FILES_CAP} files.`);
+    normalizedFiles = normalizedFiles.slice(0, MAX_FILES_CAP);
+  }
   const components = {};
   const modulesSet = /* @__PURE__ */ new Set();
   if (projectInfo.type === "laravel") {
-    const models = normalizedFiles.filter((f) => /^app\/(Models\/.*|.*Model)\.php$/i.test(f));
+    const models = normalizedFiles.filter(
+      (f) => /^(?:app|modules|Modules)\/(?:.*\/)?Models\/.*\.php$/i.test(f)
+    );
     components["Models"] = {
       name: "Eloquent Models",
       count: models.length,
       files: models,
       description: "Database entity mappings and business logic models"
     };
-    const controllers = normalizedFiles.filter((f) => /^app\/Http\/Controllers\/.*\.php$/i.test(f));
+    const controllers = normalizedFiles.filter(
+      (f) => /^(?:app|modules|Modules)\/(?:.*\/)?Controllers\/.*\.php$/i.test(f)
+    );
     components["Controllers"] = {
       name: "HTTP Controllers",
       count: controllers.length,
       files: controllers,
       description: "Request handling and response orchestration"
     };
-    const services = normalizedFiles.filter((f) => /^app\/(Services|Domain\/.*\/Services)\/.*\.php$/i.test(f));
+    const services = normalizedFiles.filter(
+      (f) => /^(?:app|modules|Modules)\/(?:.*\/)?Services\/.*\.php$/i.test(f)
+    );
     components["Services"] = {
       name: "Service Classes",
       count: services.length,
       files: services,
       description: "Encapsulated business logic and external integrations"
     };
-    const actions = normalizedFiles.filter((f) => /^app\/(Actions|Domain\/.*\/Actions)\/.*\.php$/i.test(f));
+    const actions = normalizedFiles.filter(
+      (f) => /^(?:app|modules|Modules)\/(?:.*\/)?Actions\/.*\.php$/i.test(f)
+    );
     components["Actions"] = {
       name: "Action Classes",
       count: actions.length,
       files: actions,
       description: "Single-responsibility invokable operations"
     };
-    const requests = normalizedFiles.filter((f) => /^app\/Http\/Requests\/.*\.php$/i.test(f));
+    const requests = normalizedFiles.filter(
+      (f) => /^(?:app|modules|Modules)\/(?:.*\/)?(?:Http\/)?Requests\/.*\.php$/i.test(f)
+    );
     components["Form Requests"] = {
       name: "Form Requests",
       count: requests.length,
       files: requests,
       description: "Input validation and authorization rules"
     };
-    const filament = normalizedFiles.filter((f) => /^app\/Filament\/.*\.php$/i.test(f));
+    const filament = normalizedFiles.filter(
+      (f) => /^(?:app|modules|Modules)\/(?:.*\/)?Filament\/.*\.php$/i.test(f)
+    );
     if (filament.length > 0 || projectInfo.laravel?.hasFilament) {
       components["Filament Resources"] = {
         name: "Filament Admin Resources",
@@ -290,55 +337,74 @@ async function scanProject(projectInfo) {
         description: "Admin panel CRUD pages, widgets, and schemas"
       };
     }
-    const routes = normalizedFiles.filter((f) => /^routes\/.*\.php$/i.test(f));
+    const routes = normalizedFiles.filter(
+      (f) => /^(?:routes\/.*\.php|(?:app\/Modules|modules|Modules)\/.*\/routes?.*\.php)$/i.test(f)
+    );
     components["Routes"] = {
       name: "Routing Definitions",
       count: routes.length,
       files: routes,
       description: "Web, API, and console endpoint routes"
     };
-    const migrations = normalizedFiles.filter((f) => /^database\/migrations\/.*\.php$/i.test(f));
+    const migrations = normalizedFiles.filter(
+      (f) => /(?:^database\/migrations\/.*\.php$|\/migrations\/.*\.php$)/i.test(f)
+    );
     components["Migrations"] = {
       name: "Database Migrations",
       count: migrations.length,
       files: migrations,
       description: "Schema version control and table definitions"
     };
-    const moduleFiles = normalizedFiles.filter((f) => /^app\/Modules\/([^/]+)/i.test(f) || /^modules\/([^/]+)/i.test(f));
-    for (const mf of moduleFiles) {
-      const match = mf.match(/^(?:app\/Modules|modules)\/([^/]+)/i);
-      if (match && match[1]) modulesSet.add(match[1]);
+    const modDirPattern = projectInfo.laravel?.modulesDir ? `(?:${projectInfo.laravel.modulesDir}|app/Modules|modules|Modules)` : "(?:app/Modules|modules|Modules)";
+    const modRegex = new RegExp(`^${modDirPattern}/([^/]+)/`, "i");
+    for (const f of normalizedFiles) {
+      const match = f.match(modRegex);
+      if (match && match[1]) {
+        modulesSet.add(match[1]);
+      }
     }
   } else if (projectInfo.type === "typescript") {
-    const controllers = normalizedFiles.filter((f) => /(?:^src\/.*(?:\.|\/)controller\.(?:ts|js)$)/i.test(f));
+    const srcDir = projectInfo.typescript?.srcDir ?? "src";
+    const tsPrefix = `(?:${srcDir}|(?:apps|packages)/[^/]+/(?:${srcDir}|src))`;
+    const controllers = normalizedFiles.filter(
+      (f) => !f.endsWith(".d.ts") && new RegExp(`^${tsPrefix}/(?:.*/)?(?:controllers/.*\\.(?:ts|js|mts|cts)|.*[./]controller\\.(?:ts|js|mts|cts))$`, "i").test(f)
+    );
     components["Controllers"] = {
       name: "Controllers",
       count: controllers.length,
       files: controllers,
       description: "HTTP request handlers and response dispatchers"
     };
-    const services = normalizedFiles.filter((f) => /(?:^src\/.*(?:\.|\/)service\.(?:ts|js)$)/i.test(f));
+    const services = normalizedFiles.filter(
+      (f) => !f.endsWith(".d.ts") && new RegExp(`^${tsPrefix}/(?:.*/)?(?:services/.*\\.(?:ts|js|mts|cts)|.*[./]service\\.(?:ts|js|mts|cts))$`, "i").test(f)
+    );
     components["Services"] = {
       name: "Services",
       count: services.length,
       files: services,
       description: "Core domain logic and application workflows"
     };
-    const repositories = normalizedFiles.filter((f) => /(?:^src\/.*(?:\.|\/)repository\.(?:ts|js)$)/i.test(f));
+    const repositories = normalizedFiles.filter(
+      (f) => !f.endsWith(".d.ts") && new RegExp(`^${tsPrefix}/(?:.*/)?(?:repositories/.*\\.(?:ts|js|mts|cts)|.*[./]repository\\.(?:ts|js|mts|cts))$`, "i").test(f)
+    );
     components["Repositories"] = {
       name: "Repositories",
       count: repositories.length,
       files: repositories,
       description: "Data access abstraction and database queries"
     };
-    const routes = normalizedFiles.filter((f) => /(?:^src\/.*(?:\.|\/)routes?\.(?:ts|js)$)/i.test(f));
+    const routes = normalizedFiles.filter(
+      (f) => !f.endsWith(".d.ts") && new RegExp(`^${tsPrefix}/(?:.*/)?(?:routes/.*\\.(?:ts|js|mts|cts)|.*[./]routes?\\.(?:ts|js|mts|cts))$`, "i").test(f)
+    );
     components["Routes"] = {
       name: "Routes",
       count: routes.length,
       files: routes,
       description: "API endpoint mappings and router handlers"
     };
-    const dtos = normalizedFiles.filter((f) => /(?:^src\/.*(?:\.|\/)(?:dto|schema)\.(?:ts|js)$)/i.test(f));
+    const dtos = normalizedFiles.filter(
+      (f) => !f.endsWith(".d.ts") && new RegExp(`^${tsPrefix}/(?:.*/)?(?:(?:dtos|schemas)/.*\\.(?:ts|js|mts|cts)|.*[./](?:dto|schema)\\.(?:ts|js|mts|cts))$`, "i").test(f)
+    );
     components["DTOs & Schemas"] = {
       name: "DTOs & Schemas",
       count: dtos.length,
@@ -346,7 +412,7 @@ async function scanProject(projectInfo) {
       description: "Data transfer objects and request validation schemas"
     };
     const models = normalizedFiles.filter(
-      (f) => /(?:^src\/.*(?:\.|\/)(?:model|entity)\.(?:ts|js)$|^prisma\/schema\.prisma$)/i.test(f)
+      (f) => !f.endsWith(".d.ts") && (new RegExp(`^${tsPrefix}/(?:.*/)?(?:(?:models|entities)/.*\\.(?:ts|js|mts|cts)|.*[./](?:model|entity)\\.(?:ts|js|mts|cts))$`, "i").test(f) || /(?:^|\/)prisma\/schema\.prisma$/i.test(f))
     );
     components["Models & Entities"] = {
       name: "Models & Entities",
@@ -354,7 +420,9 @@ async function scanProject(projectInfo) {
       files: models,
       description: "Database schema definitions and entity declarations"
     };
-    const componentsFiles = normalizedFiles.filter((f) => /^src\/(?:components|ui)\/.*\.(?:tsx|jsx|vue|ts|js)$/i.test(f));
+    const componentsFiles = normalizedFiles.filter(
+      (f) => new RegExp(`^${tsPrefix}/(?:components|ui)/.*\\.(?:tsx|jsx|vue|svelte|ts|js)$`, "i").test(f)
+    );
     if (componentsFiles.length > 0) {
       components["UI Components"] = {
         name: "UI Components",
@@ -363,14 +431,39 @@ async function scanProject(projectInfo) {
         description: "Reusable user interface views and components"
       };
     }
-    const moduleFiles = normalizedFiles.filter((f) => /^src\/modules\/([^/]+)/i.test(f));
-    for (const mf of moduleFiles) {
-      const match = mf.match(/^src\/modules\/([^/]+)/i);
-      if (match && match[1]) modulesSet.add(match[1]);
+    const moduleRegex = new RegExp(`^(?:${tsPrefix}/modules|modules)/([^/]+)/`, "i");
+    for (const mf of normalizedFiles) {
+      const match = mf.match(moduleRegex);
+      if (match && match[1]) {
+        modulesSet.add(match[1]);
+      }
+    }
+    const totalWebLayers = Object.values(components).reduce((acc, c) => acc + c.count, 0);
+    if (totalWebLayers === 0) {
+      const srcFiles = normalizedFiles.filter(
+        (f) => new RegExp(`^${tsPrefix}/`, "i").test(f)
+      );
+      const testFiles = normalizedFiles.filter(
+        (f) => /(?:^|[._-])(?:test|spec)\.[a-z]+$|(?:^|\/)__tests__\//i.test(f)
+      );
+      components["Source Files"] = {
+        name: "Source Files",
+        count: srcFiles.length,
+        files: srcFiles,
+        description: "Main application source code"
+      };
+      components["Test Files"] = {
+        name: "Test Files",
+        count: testFiles.length,
+        files: testFiles,
+        description: "Automated test suites and specifications"
+      };
     }
   } else {
     const srcFiles = normalizedFiles.filter((f) => /^src\//i.test(f));
-    const testFiles = normalizedFiles.filter((f) => /(?:test|spec)\.[a-z]+$/i.test(f));
+    const testFiles = normalizedFiles.filter(
+      (f) => /(?:^|[._-])(?:test|spec)\.[a-z]+$|(?:^|\/)__tests__\//i.test(f)
+    );
     components["Source Files"] = {
       name: "Source Files",
       count: srcFiles.length,
@@ -390,20 +483,66 @@ async function scanProject(projectInfo) {
     projectInfo,
     totalFilesScanned: normalizedFiles.length,
     components,
-    modules: Array.from(modulesSet).sort(),
+    modules: Array.from(modulesSet).sort(localeIndependentCompare),
     directoryTree,
     scanDurationMs
   };
 }
 // src/generator/markdown.ts
+function mdCell(str) {
+  if (!str) return "-";
+  const cleaned = str.replace(/\|/g, "\\|").replace(/[\r\n]+/g, " ").trim();
+  return cleaned || "-";
+}
+function fence(body, lang = "") {
+  const matches = body.match(/`+/g);
+  let maxBackticks = 2;
+  if (matches) {
+    for (const match of matches) {
+      if (match.length > maxBackticks) maxBackticks = match.length;
+    }
+  }
+  const f = "`".repeat(maxBackticks + 1);
+  return `${f}${lang ? lang : ""}
+${body}
+${f}`;
+}
+function mermaidLabel(str, maxLen = 40) {
+  if (!str) return "";
+  let cleaned = str.replace(/"/g, "'").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/`/g, "'").replace(/[\[\]\(\)\{\}]/g, "").replace(/[\r\n]+/g, " ").trim();
+  if (cleaned.length > maxLen) {
+    cleaned = cleaned.slice(0, maxLen - 3) + "...";
+  }
+  return cleaned;
+}
+function renderModulesSubgraph(modules) {
+  if (modules.length === 0) return "";
+  let output = `
+    subgraph ModulesLayer ["\u{1F4E6} Detected Modules (${modules.length})"]
+`;
+  modules.slice(0, 6).forEach((mod, idx) => {
+    output += `        Mod_${idx}["${mermaidLabel(mod)} Module"]:::service
+`;
+  });
+  if (modules.length > 6) {
+    output += `        Mod_More["...and ${modules.length - 6} more modules"]:::service
+`;
+  }
+  output += `    end
+`;
+  return output;
+}
 function generateMermaidDiagram(scanResult) {
   const { projectInfo, components, modules } = scanResult;
   if (projectInfo.type === "laravel") {
     const hasFilament = projectInfo.laravel?.hasFilament || (components["Filament Resources"]?.count ?? 0) > 0;
     const hasActions = (components["Actions"]?.count ?? 0) > 0;
     const hasServices = (components["Services"]?.count ?? 0) > 0;
-    let diagram = `flowchart TD
+    const hasRequests = (components["Form Requests"]?.count ?? 0) > 0;
+    const hasModels = (components["Models"]?.count ?? 0) > 0;
+    const hasMigrations = (components["Migrations"]?.count ?? 0) > 0;
+    let diagram2 = `flowchart TD
     %% Styling Definitions
     classDef client fill:#E0F2FE,stroke:#0284C7,stroke-width:2px,color:#0369A1;
     classDef routing fill:#FEF3C7,stroke:#D97706,stroke-width:2px,color:#B45309;
@@ -412,92 +551,155 @@ function generateMermaidDiagram(scanResult) {
     classDef data fill:#FEE2E2,stroke:#DC2626,stroke-width:2px,color:#B91C1C;
     classDef db fill:#F1F5F9,stroke:#475569,stroke-width:2px,color:#334155;
-    subgraph Layer1 ["1. Client & Entrypoints"]
+    subgraph EntryLayer ["1. Client & Entrypoints"]
         Client["Client / Browser / API Consumer"]:::client
-        Routes["HTTP Routes<br/>(routes/web.php, routes/api.php)"]:::routing
+        Routes["HTTP Routes"]:::routing
     end
-    subgraph Layer2 ["2. Request Pipeline & Security"]
+`;
+    if (hasRequests) {
+      diagram2 += `
+    subgraph RequestLayer ["2. Request Pipeline & Validation"]
         Middleware["Middleware Pipeline<br/>(Auth, CSRF, Rate Limiting)"]:::routing
         FormRequests["Form Requests<br/>(Validation & Authorization)"]:::routing
     end
-    subgraph Layer3 ["3. Controllers & Presentation"]
-        Controllers["HTTP Controllers<br/>(app/Http/Controllers)"]:::controller
+`;
+    }
+    diagram2 += `
+    subgraph HttpLayer ["3. Controllers & Presentation"]
+        Controllers["HTTP Controllers"]:::controller
 `;
     if (hasFilament) {
-      diagram += `        Filament["Filament Admin Panel<br/>(app/Filament/Resources)"]:::controller
+      diagram2 += `        Filament["Filament Admin Resources"]:::controller
 `;
     }
-    diagram += `    end
-    subgraph Layer4 ["4. Domain & Business Logic"]
+    diagram2 += `    end
 `;
-    if (hasServices || !hasActions) {
-      diagram += `        Services["Service Layer<br/>(app/Services)"]:::service
+    if (hasServices || hasActions) {
+      diagram2 += `
+    subgraph DomainLayer ["4. Domain & Business Logic"]
+`;
+      if (hasServices) {
+        diagram2 += `        Services["Service Classes"]:::service
+`;
+      }
+      if (hasActions) {
+        diagram2 += `        Actions["Action Classes"]:::service
+`;
+      }
+      diagram2 += `    end
 `;
     }
-    if (hasActions) {
-      diagram += `        Actions["Action Classes<br/>(app/Actions)"]:::service
+    diagram2 += `
+    subgraph DataLayer ["5. Data Persistence & Storage"]
+`;
+    if (hasModels) {
+      diagram2 += `        Models["Eloquent Models"]:::data
 `;
     }
-    diagram += `    end
-    subgraph Layer5 ["5. Data Persistence & Storage"]
-        Models["Eloquent Models<br/>(app/Models)"]:::data
-        Database[("Database<br/>(MySQL / Postgres / SQLite)")]:::db
-        Migrations["Database Migrations<br/>(database/migrations)"]:::data
-    end
+    diagram2 += `        Database[("Database<br/>(MySQL / Postgres / SQLite)")]:::db
+`;
+    if (hasMigrations) {
+      diagram2 += `        Migrations["Database Migrations"]:::data
+`;
+    }
+    diagram2 += `    end
-    Client --> Routes
-    Routes --> Middleware
-    Middleware --> FormRequests
-    FormRequests --> Controllers
 `;
+    diagram2 += `    Client --> Routes
+`;
+    if (hasRequests) {
+      diagram2 += `    Routes --> Middleware
+`;
+      diagram2 += `    Middleware --> FormRequests
+`;
+      diagram2 += `    FormRequests --> Controllers
+`;
+    } else {
+      diagram2 += `    Routes --> Controllers
+`;
+    }
     if (hasServices && hasActions) {
-      diagram += `    Controllers --> Services
-    Controllers --> Actions
-    Services --> Models
-    Actions --> Models
+      diagram2 += `    Controllers --> Services
+`;
+      diagram2 += `    Controllers --> Actions
 `;
+      if (hasModels) {
+        diagram2 += `    Services --> Models
+`;
+        diagram2 += `    Actions --> Models
+`;
+      } else {
+        diagram2 += `    Services --> Database
+`;
+        diagram2 += `    Actions --> Database
+`;
+      }
+    } else if (hasServices) {
+      diagram2 += `    Controllers --> Services
+`;
+      if (hasModels) {
+        diagram2 += `    Services --> Models
+`;
+      } else {
+        diagram2 += `    Services --> Database
+`;
+      }
     } else if (hasActions) {
-      diagram += `    Controllers --> Actions
-    Actions --> Models
+      diagram2 += `    Controllers --> Actions
+`;
+      if (hasModels) {
+        diagram2 += `    Actions --> Models
+`;
+      } else {
+        diagram2 += `    Actions --> Database
 `;
+      }
     } else {
-      diagram += `    Controllers --> Services
-    Services --> Models
+      if (hasModels) {
+        diagram2 += `    Controllers --> Models
+`;
+      } else {
+        diagram2 += `    Controllers --> Database
 `;
+      }
     }
     if (hasFilament) {
-      diagram += `    Client --> Filament
+      if (hasModels) {
+        diagram2 += `    Client --> Filament
     Filament --> Models
 `;
-    }
-    diagram += `    Models --> Database
-    Migrations -.-> Database
-`;
-    if (modules.length > 0) {
-      diagram += `
-    subgraph ModulesLayer ["\u{1F4E6} Detected Modules (${modules.length})"]
-`;
-      modules.slice(0, 6).forEach((mod, idx) => {
-        diagram += `        Mod_${idx}["${mod} Module"]:::service
-`;
-      });
-      if (modules.length > 6) {
-        diagram += `        Mod_More["...and ${modules.length - 6} more modules"]:::service
+      } else {
+        diagram2 += `    Client --> Filament
+    Filament --> Database
 `;
       }
-      diagram += `    end
+    }
+    if (hasModels) {
+      diagram2 += `    Models --> Database
 `;
     }
-    return diagram;
+    if (hasMigrations) {
+      diagram2 += `    Migrations -.-> Database
+`;
+    }
+    if (modules.length > 0) {
+      diagram2 += renderModulesSubgraph(modules);
+    }
+    return diagram2;
   }
   if (projectInfo.type === "typescript") {
-    const fw = projectInfo.typescript?.framework || "Express";
-    const orm = projectInfo.typescript?.hasPrisma ? "Prisma" : projectInfo.typescript?.hasTypeORM ? "TypeORM" : "ORM";
-    let diagram = `flowchart TD
+    const rawFw = projectInfo.typescript?.framework || "express";
+    const fwDisplay = rawFw !== "unknown" && rawFw !== "node-vanilla" ? `${rawFw.charAt(0).toUpperCase() + rawFw.slice(1)} Router` : "API Endpoints & Handlers";
+    const orm = projectInfo.typescript?.hasPrisma ? "Prisma" : projectInfo.typescript?.hasTypeORM ? "TypeORM" : projectInfo.typescript?.hasDrizzle ? "Drizzle" : null;
+    const hasControllers = (components["Controllers"]?.count ?? 0) > 0;
+    const hasServices = (components["Services"]?.count ?? 0) > 0;
+    const hasRepositories = (components["Repositories"]?.count ?? 0) > 0;
+    const hasDtos = (components["DTOs & Schemas"]?.count ?? 0) > 0;
+    const hasUi = (components["UI Components"]?.count ?? 0) > 0;
+    const hasModels = (components["Models & Entities"]?.count ?? 0) > 0;
+    const hasAnyLayer = hasControllers || hasServices || hasRepositories || hasDtos || hasUi || hasModels;
+    if (hasAnyLayer) {
+      let diagram2 = `flowchart TD
     %% Styling Definitions
     classDef client fill:#E0F2FE,stroke:#0284C7,stroke-width:2px,color:#0369A1;
     classDef routing fill:#FEF3C7,stroke:#D97706,stroke-width:2px,color:#B45309;
@@ -506,77 +708,146 @@ function generateMermaidDiagram(scanResult) {
     classDef data fill:#FEE2E2,stroke:#DC2626,stroke-width:2px,color:#B91C1C;
     classDef db fill:#F1F5F9,stroke:#475569,stroke-width:2px,color:#334155;
-    subgraph Layer1 ["1. Client & API Gateway"]
+    subgraph EntryLayer ["1. Client & API Gateway"]
         Client["Frontend / API Client"]:::client
-        Router["Router & Endpoints<br/>(${fw} Routes)"]:::routing
+        Router["Router & Endpoints<br/>(${fwDisplay})"]:::routing
     end
-    subgraph Layer2 ["2. Validation & Guards"]
-        Middleware["Auth & Error Middleware"]:::routing
+`;
+      if (hasUi) {
+        diagram2 += `
+    subgraph UiLayer ["Frontend Presentation"]
+        UiComponents["UI Components<br/>(src/components)"]:::controller
+    end
+`;
+      }
+      if (hasDtos) {
+        diagram2 += `
+    subgraph ValidationLayer ["2. Validation & Schemas"]
         DTOs["DTOs & Schemas<br/>(Input Validation)"]:::routing
     end
-    subgraph Layer3 ["3. Controllers"]
+`;
+      }
+      if (hasControllers) {
+        diagram2 += `
+    subgraph ControllerLayer ["3. Controllers"]
         Controllers["Controllers<br/>(Request Handling)"]:::controller
     end
-    subgraph Layer4 ["4. Application Services"]
+`;
+      }
+      if (hasServices) {
+        diagram2 += `
+    subgraph ServiceLayer ["4. Application Services"]
         Services["Domain Services<br/>(Business Logic)"]:::service
     end
+`;
+      }
+      diagram2 += `
+    subgraph PersistenceLayer ["5. Data Layer & Storage"]
+`;
+      if (hasRepositories) {
+        diagram2 += `        Repositories["Repositories / Data Access<br/>(${orm || "Data Layer"})"]:::data
+`;
+      } else if (hasModels) {
+        diagram2 += `        Entities["Models & Entities<br/>(${orm || "ORM"})"]:::data
+`;
+      }
+      diagram2 += `        Database[("Database / Storage")]:::db
+`;
+      diagram2 += `    end
-    subgraph Layer5 ["5. Data Layer & Storage"]
-        Repositories["Repositories / ${orm}<br/>(Data Access Layer)"]:::data
-        Database[("Database<br/>(SQL / NoSQL)")]:::db
-    end
-    Client --> Router
-    Router --> Middleware
-    Middleware --> DTOs
-    DTOs --> Controllers
-    Controllers --> Services
-    Services --> Repositories
-    Repositories --> Database
 `;
-    if (modules.length > 0) {
-      diagram += `
-    subgraph ModulesLayer ["\u{1F4E6} Detected Feature Modules (${modules.length})"]
+      diagram2 += `    Client --> Router
 `;
-      modules.slice(0, 6).forEach((mod, idx) => {
-        diagram += `        Mod_${idx}["${mod} Module"]:::service
+      if (hasUi) {
+        diagram2 += `    Client --> UiComponents
 `;
-      });
-      if (modules.length > 6) {
-        diagram += `        Mod_More["...and ${modules.length - 6} more modules"]:::service
+        diagram2 += `    UiComponents --> Router
+`;
+      }
+      let previousNode = "Router";
+      if (hasDtos) {
+        diagram2 += `    ${previousNode} --> DTOs
+`;
+        previousNode = "DTOs";
+      }
+      if (hasControllers) {
+        diagram2 += `    ${previousNode} --> Controllers
+`;
+        previousNode = "Controllers";
+      }
+      if (hasServices) {
+        diagram2 += `    ${previousNode} --> Services
 `;
+        previousNode = "Services";
       }
-      diagram += `    end
+      if (hasRepositories) {
+        diagram2 += `    ${previousNode} --> Repositories
 `;
+        diagram2 += `    Repositories --> Database
+`;
+      } else if (hasModels) {
+        diagram2 += `    ${previousNode} --> Entities
+`;
+        diagram2 += `    Entities --> Database
+`;
+      } else {
+        diagram2 += `    ${previousNode} --> Database
+`;
+      }
+      if (modules.length > 0) {
+        diagram2 += renderModulesSubgraph(modules);
+      }
+      return diagram2;
     }
-    return diagram;
   }
-  return `flowchart TD
+  const hasEntry = (components["Source Files"]?.files || []).some(
+    (f) => /(?:^|\/)(?:index|cli|main|bin)\.[a-z]+$/i.test(f)
+  );
+  const hasSource = (components["Source Files"]?.count ?? 0) > 0;
+  const hasTests = (components["Test Files"]?.count ?? 0) > 0;
+  let diagram = `flowchart TD
     classDef client fill:#E0F2FE,stroke:#0284C7,stroke-width:2px,color:#0369A1;
     classDef core fill:#DCFCE7,stroke:#16A34A,stroke-width:2px,color:#15803D;
     classDef test fill:#FEF3C7,stroke:#D97706,stroke-width:2px,color:#B45309;
-    subgraph App ["Application Architecture"]
-        Entry["Entrypoint / CLI"]:::client
-        Source["Source Core Logic (src/)"]:::core
-        Tests["Test Suites"]:::test
-    end
+    subgraph App ["CLI & Application Architecture"]
+`;
+  if (hasEntry) {
+    diagram += `        Entry["Entrypoint CLI (bin/)"]:::client
+`;
+  }
+  if (hasSource) {
+    diagram += `        Source["Core Modules & Generators (src/)"]:::core
+`;
+  }
+  if (hasTests) {
+    diagram += `        Tests["Automated Test Suites (tests/)"]:::test
+`;
+  }
+  if (!hasEntry && !hasSource && !hasTests) {
+    diagram += `        Source["Source Files"]:::core
+`;
+  }
+  diagram += `    end
-    Entry --> Source
-    Tests -.-> Source
 `;
+  if (hasEntry && hasSource) {
+    diagram += `    Entry --> Source
+`;
+  }
+  if (hasTests && hasSource) {
+    diagram += `    Tests -.-> Source
+`;
+  }
+  return diagram;
 }
 function generateArchitectureMarkdown(scanResult) {
-  const { projectInfo, totalFilesScanned, components, modules, directoryTree, scanDurationMs } = scanResult;
-  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace("T", " ").substring(0, 19) + " UTC";
+  const { projectInfo, totalFilesScanned, components, modules, directoryTree } = scanResult;
   const mermaid = generateMermaidDiagram(scanResult);
-  const componentRows = Object.entries(components).map(([key, comp]) => {
+  const componentRows = Object.entries(components).map(([, comp]) => {
     const sampleFiles = comp.files.slice(0, 3).map((f) => `\`${f}\``).join(", ");
     const moreSuffix = comp.files.length > 3 ? ` *(+${comp.files.length - 3} more)*` : "";
-    return `| **${comp.name}** | \`${comp.count}\` | ${comp.description} | ${sampleFiles || "-"} ${moreSuffix} |`;
+    return `| **${mdCell(comp.name)}** | \`${comp.count}\` | ${mdCell(comp.description)} | ${sampleFiles ? mdCell(sampleFiles + moreSuffix) : "-"} |`;
   }).join("\n");
   let modulesSection = "";
   if (modules.length > 0) {
@@ -588,10 +859,19 @@ This project organizes features into modular domains:
 ${modules.map((m) => `- **\`${m}\`**`).join("\n")}
 `;
   }
+  const sampleIgnores = SAFE_IGNORE_LIST.slice(0, 8).map((p2) => `\`${p2}\``).join(", ");
+  const securityNotice = `## \u{1F512} Security & Privacy Notice
+This architectural map was produced with strict privacy guarantees:
+- **Zero Network Transmission:** Executed locally without telemetry, tracking, or outbound communication.
+- **Safe Exclusion Filter:** Automatically ignores sensitive files and secret patterns (${sampleIgnores}, etc.) including \`node_modules\`, \`vendor\`, \`.env*\`, private keys, secrets, credentials, cloud configs, and cache folders.
+- **Manifest & Structure Only:** Safely reads standard manifest dependencies (\`package.json\` / \`composer.json\`) to determine framework types, and relative file paths to categorize components. Never reads private configurations or file contents.
+*Generated with \u2764\uFE0F by LaraTS CLI.*`;
   return `# \u{1F3DB}\uFE0F Architecture Overview: ${projectInfo.name}
-> Auto-generated by **[LaraTS CLI](https://github.com/SidiqFatuh187/Larats)** on \`${timestamp}\`.
-> **100% Local & Safe:** Generated entirely in offline mode via local filesystem metadata analysis. Zero data transmitted.
+> Auto-generated by **[LaraTS CLI](https://github.com/SidiqFatuh187/Larats)**.
+> **100% Local & Safe:** Generated entirely in offline mode via local filesystem manifest & structure analysis. Zero data transmitted.
 ---
@@ -603,7 +883,6 @@ ${modules.map((m) => `- **\`${m}\`**`).join("\n")}
 | **Project Type** | **${projectInfo.type.toUpperCase()}** |
 | **Detected Stack** | \`${projectInfo.summary}\` |
 | **Scanned Files** | \`${totalFilesScanned}\` files indexed (safe ignore filter applied) |
-| **Scan Duration** | \`${scanDurationMs} ms\` |
 ---
@@ -619,9 +898,7 @@ ${modulesSection}
 Visual representation of the project layers and request lifecycle rendered with [Mermaid.js](https://mermaid.js.org/):
-\`\`\`mermaid
-${mermaid}
-\`\`\`
+${fence(mermaid, "mermaid")}
 ---
@@ -629,49 +906,256 @@ ${mermaid}
 Clean, high-level directory tree showing key folders (ignoring build artifacts, vendor files, and sensitive keys):
-\`\`\`text
-${directoryTree || "(Empty directory structure)"}
-\`\`\`
+${fence(directoryTree || "(Empty directory structure)", "text")}
 ---
-## \u{1F512} Security & Privacy Notice
-This architectural map was produced with strict privacy rules:
-- **Zero Network Transmission:** Executed locally without telemetry or outbound communication.
-- **Safe Exclusion Filter:** Ignored \`node_modules\`, \`vendor\`, \`.env*\`, key files, credentials, and cache folders.
-- **Metadata Only:** Scanned file names and relative paths only; no secrets or private business contents were extracted.
-*Generated with \u2764\uFE0F by LaraTS CLI.*
+${securityNotice}
 `;
 }
+function renderTerminalFlow(scanResult) {
+  const { projectInfo, components } = scanResult;
+  const steps = [];
+  if (projectInfo.type === "laravel") {
+    steps.push("Client");
+    const routes = components["Routes"]?.count ?? 0;
+    if (routes > 0) steps.push(`Routes [${routes}]`);
+    const requests = components["Form Requests"]?.count ?? 0;
+    if (requests > 0) steps.push(`Requests [${requests}]`);
+    const controllers = components["Controllers"]?.count ?? 0;
+    if (controllers > 0) steps.push(`Controllers [${controllers}]`);
+    const services = (components["Services"]?.count ?? 0) + (components["Actions"]?.count ?? 0);
+    if (services > 0) steps.push(`Services [${services}]`);
+    const models = components["Models"]?.count ?? 0;
+    if (models > 0) steps.push(`Models [${models}]`);
+    steps.push("Database");
+  } else if (projectInfo.type === "typescript") {
+    const hasAnyLayer = ["Controllers", "Services", "Repositories", "Routes", "DTOs & Schemas", "Models & Entities", "UI Components"].some((k) => (components[k]?.count ?? 0) > 0);
+    if (hasAnyLayer) {
+      steps.push("Client");
+      const ui = components["UI Components"]?.count ?? 0;
+      if (ui > 0) steps.push(`UI [${ui}]`);
+      const routes = components["Routes"]?.count ?? 0;
+      if (routes > 0) steps.push(`Router [${routes}]`);
+      const dtos = components["DTOs & Schemas"]?.count ?? 0;
+      if (dtos > 0) steps.push(`DTOs [${dtos}]`);
+      const controllers = components["Controllers"]?.count ?? 0;
+      if (controllers > 0) steps.push(`Controllers [${controllers}]`);
+      const services = components["Services"]?.count ?? 0;
+      if (services > 0) steps.push(`Services [${services}]`);
+      const data = (components["Repositories"]?.count ?? 0) + (components["Models & Entities"]?.count ?? 0);
+      if (data > 0) steps.push(`Data Layer [${data}]`);
+      steps.push("Database");
+    } else {
+      const src = components["Source Files"]?.count ?? 0;
+      const tests = components["Test Files"]?.count ?? 0;
+      steps.push("CLI / Entrypoint");
+      if (src > 0) steps.push(`Source Modules [${src}]`);
+      if (tests > 0) steps.push(`Test Suites [${tests}]`);
+    }
+  } else {
+    const src = components["Source Files"]?.count ?? 0;
+    const tests = components["Test Files"]?.count ?? 0;
+    steps.push("Project Root");
+    if (src > 0) steps.push(`Source [${src}]`);
+    if (tests > 0) steps.push(`Tests [${tests}]`);
+  }
+  return steps.join(" \u2500\u2500> ");
+}
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function generateArchitectureHtml(scanResult) {
+  const { projectInfo, totalFilesScanned, components, modules, directoryTree } = scanResult;
+  const mermaid = generateMermaidDiagram(scanResult);
+  const componentRowsHtml = Object.entries(components).map(([, comp]) => {
+    const samples = comp.files.slice(0, 3).map((f) => `<code>${escapeHtml(f)}</code>`).join(", ");
+    const more = comp.files.length > 3 ? ` <span class="muted">(+${comp.files.length - 3} more)</span>` : "";
+    return `<tr>
+        <td><strong>${escapeHtml(comp.name)}</strong></td>
+        <td><span class="badge">${comp.count}</span></td>
+        <td>${escapeHtml(comp.description)}</td>
+        <td>${samples ? samples + more : "-"}</td>
+      </tr>`;
+  }).join("\n");
+  const modulesHtml = modules.length > 0 ? `<div class="card">
+        <h2>\u{1F4E6} Detected Modules & Domains (${modules.length})</h2>
+        <div class="modules-grid">
+          ${modules.map((m) => `<div class="module-item"><code>${escapeHtml(m)}</code></div>`).join("\n")}
+        </div>
+      </div>` : "";
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>LaraTS Architecture: ${escapeHtml(projectInfo.name)}</title>
+  <style>
+    :root {
+      --bg: #0f172a;
+      --card-bg: #1e293b;
+      --text: #f8fafc;
+      --muted: #94a3b8;
+      --border: #334155;
+      --primary: #38bdf8;
+      --accent: #818cf8;
+    }
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      background: var(--bg);
+      color: var(--text);
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+      line-height: 1.5;
+      padding: 2rem 1rem;
+    }
+    .container { max-width: 1080px; margin: 0 auto; }
+    header { margin-bottom: 2rem; border-bottom: 1px solid var(--border); padding-bottom: 1.5rem; }
+    .header-top { display: flex; align-items: center; justify-content: space-between; flex-wrap: wrap; gap: 1rem; }
+    h1 { font-size: 1.8rem; font-weight: 700; color: #fff; }
+    .pill { background: #0284c7; color: #fff; padding: 0.25rem 0.75rem; border-radius: 9999px; font-size: 0.85rem; font-weight: 600; }
+    .subtitle { color: var(--muted); margin-top: 0.5rem; font-size: 0.95rem; }
+    .card { background: var(--card-bg); border: 1px solid var(--border); border-radius: 8px; padding: 1.5rem; margin-bottom: 2rem; }
+    h2 { font-size: 1.25rem; font-weight: 600; margin-bottom: 1rem; color: #e2e8f0; }
+    table { width: 100%; border-collapse: collapse; margin-top: 0.5rem; font-size: 0.9rem; }
+    th, td { text-align: left; padding: 0.75rem 1rem; border-bottom: 1px solid var(--border); }
+    th { color: var(--muted); font-size: 0.8rem; text-transform: uppercase; letter-spacing: 0.05em; }
+    .badge { background: #334155; padding: 0.2rem 0.6rem; border-radius: 4px; font-weight: 600; font-size: 0.85rem; }
+    code { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; background: #090d16; padding: 0.15rem 0.4rem; border-radius: 4px; font-size: 0.85rem; color: #38bdf8; }
+    pre { background: #090d16; padding: 1rem; border-radius: 6px; overflow-x: auto; font-size: 0.85rem; border: 1px solid var(--border); line-height: 1.4; }
+    .mermaid-box { display: flex; justify-content: center; background: #090d16; border-radius: 8px; padding: 2rem 1rem; overflow-x: auto; border: 1px solid var(--border); }
+    .modules-grid { display: flex; flex-wrap: wrap; gap: 0.5rem; }
+    .module-item { background: #090d16; border: 1px solid var(--border); border-radius: 6px; padding: 0.5rem 1rem; }
+    .muted { color: var(--muted); font-size: 0.85rem; }
+    footer { text-align: center; color: var(--muted); font-size: 0.85rem; margin-top: 3rem; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <header>
+      <div class="header-top">
+        <div>
+          <h1>\u{1F3DB}\uFE0F Architecture Overview: ${escapeHtml(projectInfo.name)}</h1>
+          <p class="subtitle">Stack: <strong>${escapeHtml(projectInfo.summary)}</strong> &bull; Total Files: <strong>${totalFilesScanned}</strong></p>
+        </div>
+        <span class="pill">LaraTS Architecture Map</span>
+      </div>
+    </header>
+    <div class="card">
+      <h2>\u{1F5FA}\uFE0F Interactive Architecture Flowchart</h2>
+      <div class="mermaid-box">
+        <pre class="mermaid">${mermaid}</pre>
+      </div>
+    </div>
+    <div class="card">
+      <h2>\u{1F4CA} Architectural Component Statistics</h2>
+      <table>
+        <thead>
+          <tr>
+            <th>Component Layer</th>
+            <th>Files</th>
+            <th>Description</th>
+            <th>Sample Files</th>
+          </tr>
+        </thead>
+        <tbody>
+          ${componentRowsHtml || '<tr><td colspan="4">No architectural components detected</td></tr>'}
+        </tbody>
+      </table>
+    </div>
+    ${modulesHtml}
+    <div class="card">
+      <h2>\u{1F332} Directory Structure Tree</h2>
+      <pre><code>${escapeHtml(directoryTree || "(Empty directory)")}</code></pre>
+    </div>
+    <footer>
+      Generated locally &amp; offline with \u2764\uFE0F by <strong>LaraTS CLI</strong>
+    </footer>
+  </div>
+  <script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
+  <script>
+    if (typeof mermaid !== 'undefined') {
+      mermaid.initialize({
+        startOnLoad: true,
+        theme: 'dark',
+        flowchart: { curve: 'basis' }
+      });
+    }
+  </script>
+</body>
+</html>`;
+}
 // src/generator/scaffolder.ts
 import fs2 from "fs";
-import path2 from "path";
+import path3 from "path";
 // src/templates/laravel.ts
+function pluralize(word) {
+  const lower = word.toLowerCase();
+  if (lower.endsWith("s") && !lower.endsWith("ss")) {
+    return word;
+  }
+  if (/[bcdfghjklmnpqrstvwxyz]y$/i.test(word)) {
+    return word.slice(0, -1) + (word.endsWith("Y") ? "IES" : "ies");
+  }
+  if (/(?:s|x|z|ch|sh)$/i.test(word)) {
+    return word + (word === word.toUpperCase() ? "ES" : "es");
+  }
+  return word + (word === word.toUpperCase() ? "S" : "s");
+}
 function getNaming(input) {
   const words = input.trim().replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[^a-zA-Z0-9]/g, " ").split(/\s+/).filter(Boolean);
   if (words.length === 0) {
-    words.push("SampleModule");
+    words.push("sample", "module");
   }
   const pascal = words.map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join("");
   const camel = pascal.charAt(0).toLowerCase() + pascal.slice(1);
   const snake = words.map((w) => w.toLowerCase()).join("_");
   const kebab = words.map((w) => w.toLowerCase()).join("-");
-  const pluralSuffix = snake.endsWith("s") || snake.endsWith("ch") || snake.endsWith("sh") ? "es" : "s";
-  const pluralSnake = snake + pluralSuffix;
-  const pluralPascal = pascal + pluralSuffix;
+  const pluralWords = [...words];
+  const lastIdx = pluralWords.length - 1;
+  pluralWords[lastIdx] = pluralize(pluralWords[lastIdx]);
+  const pluralSnake = pluralWords.map((w) => w.toLowerCase()).join("_");
+  const pluralPascal = pluralWords.map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join("");
   return { pascal, camel, kebab, snake, pluralSnake, pluralPascal };
 }
-function laravelModelTemplate(names, namespace = "App\\Models") {
+function laravelModelTemplate(names, namespace = "App\\Models", laravelVersion) {
+  const major = laravelVersion ? parseInt(laravelVersion.split(".")[0], 10) : 11;
+  const isLaravel10OrOlder = major > 0 && major < 11;
+  const castsBlock = isLaravel10OrOlder ? `    /**
+     * The attributes that should be cast.
+     *
+     * @var array<string, string>
+     */
+    protected $casts = [
+        'metadata' => 'array',
+        'created_at' => 'datetime',
+        'updated_at' => 'datetime',
+    ];` : `    /**
+     * Get the attributes that should be cast.
+     *
+     * @return array<string, string>
+     */
+    protected function casts(): array
+    {
+        return [
+            'metadata' => 'array',
+            'created_at' => 'datetime',
+            'updated_at' => 'datetime',
+        ];
+    }`;
   return `<?php
 namespace ${namespace};
-use IlluminateDatabaseEloquentFactoriesHasFactory;
-use IlluminateDatabaseEloquentModel;
+use Illuminate\\Database\\Eloquent\\Factories\\HasFactory;
+use Illuminate\\Database\\Eloquent\\Model;
 class ${names.pascal} extends Model
 {
@@ -695,19 +1179,7 @@ class ${names.pascal} extends Model
         'metadata',
     ];
-    /**
-     * Get the attributes that should be cast.
-     *
-     * @return array<string, string>
-     */
-    protected function casts(): array
-    {
-        return [
-            'metadata' => 'array',
-            'created_at' => 'datetime',
-            'updated_at' => 'datetime',
-        ];
-    }
+${castsBlock}
 }
 `;
 }
@@ -716,15 +1188,16 @@ function laravelControllerTemplate(names, options = {}) {
   const modelNamespace = options.modelNamespace || "App\\Models";
   const serviceNamespace = options.serviceNamespace || "App\\Services";
   const requestNamespace = options.requestNamespace || "App\\Http\\Requests";
+  const baseControllerImport = namespace !== "App\\Http\\Controllers" ? "use App\\Http\\Controllers\\Controller;\n" : "";
   return `<?php
 namespace ${namespace};
-use ${modelNamespace}\\${names.pascal};
+${baseControllerImport}use ${modelNamespace}\\${names.pascal};
 use ${serviceNamespace}\\${names.pascal}Service;
 use ${requestNamespace}\\${names.pascal}Request;
-use IlluminateHttpJsonResponse;
-use IlluminateHttpRequest;
+use Illuminate\\Http\\JsonResponse;
+use Illuminate\\Http\\Request;
 class ${names.pascal}Controller extends Controller
 {
@@ -809,7 +1282,7 @@ function laravelServiceTemplate(names, options = {}) {
 namespace ${namespace};
 use ${modelNamespace}\\${names.pascal};
-use IlluminateDatabaseEloquentCollection;
+use Illuminate\\Database\\Eloquent\\Collection;
 class ${names.pascal}Service
 {
@@ -888,7 +1361,7 @@ function laravelRequestTemplate(names, namespace = "App\\Http\\Requests") {
 namespace ${namespace};
-use IlluminateFoundationHttpFormRequest;
+use Illuminate\\Foundation\\Http\\FormRequest;
 class ${names.pascal}Request extends FormRequest
 {
@@ -931,9 +1404,9 @@ class ${names.pascal}Request extends FormRequest
 function laravelMigrationTemplate(names) {
   return `<?php
-use IlluminateDatabaseMigrationsMigration;
-use IlluminateDatabaseSchemaBlueprint;
-use IlluminateSupportFacadesSchema;
+use Illuminate\\Database\\Migrations\\Migration;
+use Illuminate\\Database\\Schema\\Blueprint;
+use Illuminate\\Support\\Facades\\Schema;
 return new class extends Migration
 {
@@ -997,7 +1470,11 @@ export class ${names.pascal}Controller {
         return;
       }
       res.status(200).json({ status: 'success', data: item });
-    } catch (error) {
+    } catch (error: any) {
+      if (error?.name === 'NotFoundError') {
+        res.status(404).json({ status: 'fail', message: error.message });
+        return;
+      }
       next(error);
     }
   };
@@ -1024,7 +1501,11 @@ export class ${names.pascal}Controller {
       const payload: Update${names.pascal}Dto = req.body;
       const updated = await this.${names.camel}Service.update(id, payload);
       res.status(200).json({ status: 'success', data: updated });
-    } catch (error) {
+    } catch (error: any) {
+      if (error?.name === 'NotFoundError') {
+        res.status(404).json({ status: 'fail', message: error.message });
+        return;
+      }
       next(error);
     }
   };
@@ -1035,9 +1516,17 @@ export class ${names.pascal}Controller {
   delete = async (req: Request, res: Response, next: NextFunction): Promise<void> => {
     try {
       const { id } = req.params;
-      await this.${names.camel}Service.delete(id);
+      const deleted = await this.${names.camel}Service.delete(id);
+      if (!deleted) {
+        res.status(404).json({ status: 'fail', message: '${names.pascal} not found' });
+        return;
+      }
       res.status(200).json({ status: 'success', message: '${names.pascal} deleted successfully' });
-    } catch (error) {
+    } catch (error: any) {
+      if (error?.name === 'NotFoundError') {
+        res.status(404).json({ status: 'fail', message: error.message });
+        return;
+      }
       next(error);
     }
   };
@@ -1077,7 +1566,8 @@ export class ${names.pascal}Service {
 }
 function tsRepositoryTemplate(names, isModular = true) {
   const dtoImport = isModular ? `./${names.kebab}.dto.js` : `../dtos/${names.kebab}.dto.js`;
-  return `import type { ${names.pascal}Entity, Create${names.pascal}Dto, Update${names.pascal}Dto } from '${dtoImport}';
+  return `import { randomUUID } from 'node:crypto';
+import { NotFoundError, type ${names.pascal}Entity, type Create${names.pascal}Dto, type Update${names.pascal}Dto } from '${dtoImport}';
 export interface I${names.pascal}Repository {
   findAll(query?: Record<string, any>): Promise<${names.pascal}Entity[]>;
@@ -1100,7 +1590,7 @@ export class ${names.pascal}Repository implements I${names.pascal}Repository {
   }
   async create(data: Create${names.pascal}Dto): Promise<${names.pascal}Entity> {
-    const id = (Math.random() * 100000).toFixed(0);
+    const id = randomUUID();
     const newRecord: ${names.pascal}Entity = {
       id,
       ...data,
@@ -1115,7 +1605,7 @@ export class ${names.pascal}Repository implements I${names.pascal}Repository {
   async update(id: string, data: Update${names.pascal}Dto): Promise<${names.pascal}Entity> {
     const existing = await this.findById(id);
     if (!existing) {
-      throw new Error(\`${names.pascal} with id \${id} not found\`);
+      throw new NotFoundError(\`${names.pascal} with id \${id} not found\`);
     }
     const updated: ${names.pascal}Entity = {
       ...existing,
@@ -1154,7 +1644,14 @@ export default router;
 `;
 }
 function tsDtoTemplate(names) {
-  return `export interface ${names.pascal}Entity {
+  return `export class NotFoundError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'NotFoundError';
+  }
+}
+export interface ${names.pascal}Entity {
   id: string;
   name: string;
   status: 'draft' | 'active' | 'archived';
@@ -1181,6 +1678,39 @@ export interface Update${names.pascal}Dto {
 }
 // src/generator/scaffolder.ts
+var RESERVED_NAMES = /* @__PURE__ */ new Set([
+  "model",
+  "controller",
+  "service",
+  "action",
+  "request",
+  "migration",
+  "repository",
+  "route",
+  "dto",
+  "object",
+  "class",
+  "interface",
+  "module",
+  "app",
+  "base"
+]);
+function validateModuleName(name) {
+  if (!name || !name.trim()) {
+    return "Module name cannot be empty.";
+  }
+  const trimmed = name.trim();
+  if (!/^[a-zA-Z]/.test(trimmed)) {
+    return "Module name must start with an alphabetical letter.";
+  }
+  if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(trimmed)) {
+    return "Module name may only contain alphanumeric characters, hyphens, and underscores.";
+  }
+  if (RESERVED_NAMES.has(trimmed.toLowerCase())) {
+    return `"${trimmed}" is a reserved framework name and cannot be used as a module name.`;
+  }
+  return null;
+}
 function getMigrationTimestamp() {
   const now = /* @__PURE__ */ new Date();
   const YYYY = now.getFullYear();
@@ -1195,16 +1725,46 @@ async function scaffoldModule(projectInfo, options) {
   const root = projectInfo.rootPath;
   const names = getNaming(options.moduleName);
   const filesToGenerate = [];
+  const results = [];
+  let createdCount = 0;
+  let skippedCount = 0;
+  let errorCount = 0;
   const isModular = options.isModular ?? (projectInfo.type === "laravel" ? Boolean(projectInfo.laravel?.isModular) : projectInfo.type === "typescript" ? Boolean(projectInfo.typescript?.isModular) : true);
   if (projectInfo.type === "laravel") {
     const selected = new Set(options.components);
+    const addMigrationIfRequested = () => {
+      const migrationsDir = path3.join(root, "database", "migrations");
+      let existingMigration = null;
+      if (fs2.existsSync(migrationsDir)) {
+        const files = fs2.readdirSync(migrationsDir);
+        const match = files.find((f) => f.endsWith(`_create_${names.pluralSnake}_table.php`));
+        if (match) {
+          existingMigration = match;
+        }
+      }
+      if (existingMigration && !options.forceOverwrite) {
+        results.push({
+          filePath: path3.join(migrationsDir, existingMigration),
+          relativeFilePath: `database/migrations/${existingMigration}`,
+          status: "skipped",
+          reason: "Migration for table already exists (overwrite protected)"
+        });
+        skippedCount++;
+      } else {
+        const timestamp = existingMigration ? existingMigration.split("_create_")[0] : getMigrationTimestamp();
+        filesToGenerate.push({
+          relativePath: `database/migrations/${timestamp}_create_${names.pluralSnake}_table.php`,
+          content: laravelMigrationTemplate(names)
+        });
+      }
+    };
     if (isModular) {
       const baseDir = `app/Modules/${names.pascal}`;
       const baseNamespace = `App\\Modules\\${names.pascal}`;
       if (selected.has("model")) {
         filesToGenerate.push({
           relativePath: `${baseDir}/Models/${names.pascal}.php`,
-          content: laravelModelTemplate(names, `${baseNamespace}\\Models`)
+          content: laravelModelTemplate(names, `${baseNamespace}\\Models`, projectInfo.laravel?.version)
         });
       }
       if (selected.has("controller")) {
@@ -1243,17 +1803,13 @@ async function scaffoldModule(projectInfo, options) {
         });
       }
       if (selected.has("migration")) {
-        const timestamp = getMigrationTimestamp();
-        filesToGenerate.push({
-          relativePath: `database/migrations/${timestamp}_create_${names.pluralSnake}_table.php`,
-          content: laravelMigrationTemplate(names)
-        });
+        addMigrationIfRequested();
       }
     } else {
       if (selected.has("model")) {
         filesToGenerate.push({
           relativePath: `app/Models/${names.pascal}.php`,
-          content: laravelModelTemplate(names, "App\\Models")
+          content: laravelModelTemplate(names, "App\\Models", projectInfo.laravel?.version)
         });
       }
       if (selected.has("controller")) {
@@ -1281,11 +1837,7 @@ async function scaffoldModule(projectInfo, options) {
         });
       }
       if (selected.has("migration")) {
-        const timestamp = getMigrationTimestamp();
-        filesToGenerate.push({
-          relativePath: `database/migrations/${timestamp}_create_${names.pluralSnake}_table.php`,
-          content: laravelMigrationTemplate(names)
-        });
+        addMigrationIfRequested();
       }
     }
   } else {
@@ -1330,11 +1882,15 @@ async function scaffoldModule(projectInfo, options) {
         if (selected.has("repository")) exports.push(`export * from './${names.kebab}.repository.js';`);
         if (selected.has("route")) exports.push(`export * from './${names.kebab}.routes.js';`);
         if (selected.has("dto")) exports.push(`export * from './${names.kebab}.dto.js';`);
-        filesToGenerate.push({
-          relativePath: `${moduleFolder}/index.ts`,
-          content: `${exports.join("\n")}
-`
-        });
+        if (exports.length > 0) {
+          filesToGenerate.push({
+            relativePath: `${moduleFolder}/index.ts`,
+            content: `${exports.join("\n")}
+`,
+            isBarrel: true,
+            barrelExports: exports
+          });
+        }
       }
     } else {
       if (selected.has("controller")) {
@@ -1369,20 +1925,17 @@ async function scaffoldModule(projectInfo, options) {
       }
     }
   }
-  const results = [];
-  let createdCount = 0;
-  let skippedCount = 0;
-  let errorCount = 0;
   for (const item of filesToGenerate) {
-    const fullPath = path2.resolve(root, item.relativePath);
-    if (fs2.existsSync(fullPath) && !options.forceOverwrite) {
+    const fullPath = path3.resolve(root, item.relativePath);
+    const rel = path3.relative(root, fullPath);
+    if (rel.startsWith("..") || path3.isAbsolute(rel)) {
       results.push({
         filePath: fullPath,
         relativeFilePath: item.relativePath,
-        status: "skipped",
-        reason: "File already exists (overwrite protected)"
+        status: "error",
+        reason: "Path traversal attempt detected outside project root"
       });
-      skippedCount++;
+      errorCount++;
       continue;
     }
     if (options.dryRun) {
@@ -1395,12 +1948,52 @@ async function scaffoldModule(projectInfo, options) {
       createdCount++;
       continue;
     }
+    if (item.isBarrel && item.barrelExports && fs2.existsSync(fullPath)) {
+      try {
+        const existingContent = fs2.readFileSync(fullPath, "utf-8");
+        const missingExports = item.barrelExports.filter(
+          (line) => !existingContent.includes(line)
+        );
+        if (missingExports.length > 0) {
+          const newContent = existingContent.endsWith("\n") ? existingContent + missingExports.join("\n") + "\n" : existingContent + "\n" + missingExports.join("\n") + "\n";
+          fs2.writeFileSync(fullPath, newContent, "utf-8");
+          results.push({
+            filePath: fullPath,
+            relativeFilePath: item.relativePath,
+            status: "created",
+            reason: "Appended exports to existing barrel index"
+          });
+          createdCount++;
+        } else {
+          results.push({
+            filePath: fullPath,
+            relativeFilePath: item.relativePath,
+            status: "skipped",
+            reason: "File already exists and contains all module exports"
+          });
+          skippedCount++;
+        }
+        continue;
+      } catch (err) {
+        results.push({
+          filePath: fullPath,
+          relativeFilePath: item.relativePath,
+          status: "error",
+          reason: err.message || String(err)
+        });
+        errorCount++;
+        continue;
+      }
+    }
     try {
-      const parentDir = path2.dirname(fullPath);
+      const parentDir = path3.dirname(fullPath);
       if (!fs2.existsSync(parentDir)) {
         fs2.mkdirSync(parentDir, { recursive: true });
       }
-      fs2.writeFileSync(fullPath, item.content, "utf-8");
+      fs2.writeFileSync(fullPath, item.content, {
+        flag: options.forceOverwrite ? "w" : "wx",
+        encoding: "utf-8"
+      });
       results.push({
         filePath: fullPath,
         relativeFilePath: item.relativePath,
@@ -1408,13 +2001,23 @@ async function scaffoldModule(projectInfo, options) {
       });
       createdCount++;
     } catch (err) {
-      results.push({
-        filePath: fullPath,
-        relativeFilePath: item.relativePath,
-        status: "error",
-        reason: err.message || String(err)
-      });
-      errorCount++;
+      if (err.code === "EEXIST") {
+        results.push({
+          filePath: fullPath,
+          relativeFilePath: item.relativePath,
+          status: "skipped",
+          reason: "File already exists (overwrite protected)"
+        });
+        skippedCount++;
+      } else {
+        results.push({
+          filePath: fullPath,
+          relativeFilePath: item.relativePath,
+          status: "error",
+          reason: err.message || String(err)
+        });
+        errorCount++;
+      }
     }
   }
   return {
@@ -1423,12 +2026,13 @@ async function scaffoldModule(projectInfo, options) {
     files: results,
     createdCount,
     skippedCount,
-    errorCount
+    errorCount,
+    dryRun: Boolean(options.dryRun)
   };
 }
 // src/index.ts
-var VERSION = "1.0.1";
+var VERSION = true ? "1.1.0" : "1.1.0";
 function showHelp() {
   console.log(`
 ${pc.bold(pc.cyan("LaraTS CLI"))} ${pc.gray(`v${VERSION}`)}
@@ -1440,19 +2044,22 @@ ${pc.bold("USAGE:")}
 ${pc.bold("COMMANDS:")}
   ${pc.green("scan")}                 Scan repository & generate ARCHITECTURE.md
+  ${pc.green("view")}, ${pc.green("preview")}          Open interactive architecture diagram in local browser
   ${pc.green("scaffold")}, ${pc.green("make")} [name] Scaffold a new module or feature with clean boilerplate
   ${pc.green("info")}                 Show detected project type & architectural flavor
   ${pc.green("help")}                 Display this help message
 ${pc.bold("OPTIONS:")}
-  ${pc.yellow("-o, --output")} <file>    Output markdown path for scan (default: ARCHITECTURE.md)
+  ${pc.yellow("-o, --output")} <file>    Output path for scan (default: ARCHITECTURE.md)
+  ${pc.yellow("--view")}                 Open local browser viewer immediately after scanning
+  ${pc.yellow("-t, --tree")}             Print directory tree in terminal
+  ${pc.yellow("--html")}                 Also export standalone ARCHITECTURE.html
   ${pc.yellow("-m, --modular")}          Enforce modular directory structure
   ${pc.yellow("-s, --standard")}         Enforce standard/layered directory structure
   ${pc.yellow("--dry-run")}              Simulate generation without writing files
   ${pc.yellow("-f, --force")}            Overwrite files if they already exist
   ${pc.yellow("-v, --version")}          Display CLI version
   ${pc.yellow("-h, --help")}             Display this help message
 ${pc.bold("EXAMPLES:")}
   ${pc.cyan("$")} larats
   ${pc.cyan("$")} larats scan
@@ -1465,41 +2072,165 @@ function handleCancel() {
   p.cancel(pc.yellow("Operation cancelled. See you next time! \u{1F44B}"));
   process.exit(0);
 }
-async function runScan(projectInfo, outputPath = "ARCHITECTURE.md") {
+function checkAndPromptStar() {
+  try {
+    const configDir = path4.join(os2.homedir(), ".larats");
+    const statsFile = path4.join(configDir, "stats.json");
+    if (!fs3.existsSync(configDir)) {
+      fs3.mkdirSync(configDir, { recursive: true });
+    }
+    let stats = {};
+    if (fs3.existsSync(statsFile)) {
+      stats = JSON.parse(fs3.readFileSync(statsFile, "utf-8"));
+    }
+    const runs = (stats.runs || 0) + 1;
+    stats.runs = runs;
+    fs3.writeFileSync(statsFile, JSON.stringify(stats, null, 2), "utf-8");
+    if (runs === 2 || runs === 3) {
+      console.log(
+        `
+${pc.yellow("\u2B50 Enjoying LaraTS?")} If you find this CLI useful, please consider giving it a star on GitHub:
+   ${pc.bold(pc.cyan("\u{1F449} https://github.com/SidiqFatuh187/larats-cli"))}
+`
+      );
+    }
+  } catch {
+  }
+}
+function openViewer(destination) {
+  const startCmd = process.platform === "win32" ? `start "" "${destination}"` : process.platform === "darwin" ? `open "${destination}"` : `xdg-open "${destination}"`;
+  try {
+    exec(startCmd, (err) => {
+      if (err) {
+        p.log.warn(`Could not open browser automatically. Please open ${pc.cyan(destination)} manually.`);
+      }
+    });
+  } catch {
+    p.log.warn(`Could not open browser automatically. Please open ${pc.cyan(destination)} manually.`);
+  }
+}
+async function runScan(projectInfo, outputPath = "ARCHITECTURE.md", options = {}) {
   const spinner2 = p.spinner();
   spinner2.start("Scanning codebase structure & components (strict ignore list active)...");
   try {
+    const destination = path4.resolve(projectInfo.rootPath, outputPath);
+    const rel = path4.relative(projectInfo.rootPath, destination);
+    if (rel.startsWith("..") || path4.isAbsolute(rel)) {
+      spinner2.stop(pc.red("Scan failed"));
+      p.log.error(`Refusing to write output: "${outputPath}" resolves outside project root directory.`);
+      process.exitCode = 1;
+      return;
+    }
+    if (fs3.existsSync(destination) && !options.force) {
+      const existingContent = fs3.readFileSync(destination, "utf-8");
+      const isLaraTsFile = existingContent.includes("Auto-generated by **[LaraTS CLI]") || existingContent.includes("Auto-generated by **[ArchMind CLI]") || existingContent.includes("LaraTS CLI") || existingContent.includes("<!-- larats-generated -->");
+      if (!isLaraTsFile) {
+        spinner2.stop(pc.red("Scan refused"));
+        p.log.error(
+          `Destination file "${outputPath}" already exists and does not appear to be generated by LaraTS.
+To protect user files from accidental overwrites, use --force to overwrite.`
+        );
+        process.exitCode = 1;
+        return;
+      }
+    }
     const scanResult = await scanProject(projectInfo);
+    const nonZeroLayers = Object.values(scanResult.components).filter((c) => c.count > 0).length;
+    const totalComponents = Object.values(scanResult.components).reduce((sum, c) => sum + c.count, 0);
+    const terminalFlow = renderTerminalFlow(scanResult);
+    if (options.dryRun) {
+      spinner2.stop(pc.green(`Scan completed in ${scanResult.scanDurationMs}ms (dry run)`));
+      p.note(
+        `${pc.bold("Architecture Flow:")}
+  ${pc.cyan(terminalFlow)}
+${pc.bold("Scanned Files:")} ${scanResult.totalFilesScanned}
+${pc.bold("Total Components:")} ${totalComponents} across ${nonZeroLayers} active architectural layers
+${pc.bold("Modules Detected:")} ${scanResult.modules.length > 0 ? scanResult.modules.join(", ") : "None (monolithic structure)"}
+${pc.bold("Simulated Output:")} Would write ARCHITECTURE.md to ${pc.cyan(outputPath)} (dry run: no files written)`,
+        pc.green("Architecture Map (Dry Run) \u{1F5FA}\uFE0F")
+      );
+      if (options.tree) {
+        console.log(`
+${pc.bold("Directory Tree:")}
+${scanResult.directoryTree}
+`);
+      }
+      p.outro(pc.cyan("Dry run completed: no files written."));
+      return;
+    }
     spinner2.stop(pc.green(`Scan completed in ${scanResult.scanDurationMs}ms`));
     const markdown = generateArchitectureMarkdown(scanResult);
-    const destination = path3.resolve(projectInfo.rootPath, outputPath);
-    const parentDir = path3.dirname(destination);
+    const parentDir = path4.dirname(destination);
     if (!fs3.existsSync(parentDir)) {
       fs3.mkdirSync(parentDir, { recursive: true });
     }
     fs3.writeFileSync(destination, markdown, "utf-8");
+    const shouldWriteHtml = options.html || options.view;
+    if (shouldWriteHtml) {
+      const htmlDestination = destination.replace(/\.md$/i, "") + ".html";
+      fs3.writeFileSync(htmlDestination, generateArchitectureHtml(scanResult), "utf-8");
+      p.log.success(`HTML architecture saved to ${pc.cyan(path4.relative(projectInfo.rootPath, htmlDestination) || htmlDestination)}`);
+      if (options.view) {
+        openViewer(htmlDestination);
+        p.log.info(pc.green("\u{1F310} Opened interactive architecture diagram in your browser!"));
+      }
+    }
+    if (options.tree) {
+      console.log(`
+${pc.bold("Directory Tree:")}
+${scanResult.directoryTree}
+`);
+    }
     p.note(
-      `${pc.bold("Scanned Files:")} ${scanResult.totalFilesScanned}
-${pc.bold("Components Identified:")} ${Object.keys(scanResult.components).length}
+      `${pc.bold("Architecture Flow:")}
+  ${pc.cyan(terminalFlow)}
+${pc.bold("Scanned Files:")} ${scanResult.totalFilesScanned}
+${pc.bold("Total Components:")} ${totalComponents} across ${nonZeroLayers} active architectural layers
 ${pc.bold("Modules Detected:")} ${scanResult.modules.length > 0 ? scanResult.modules.join(", ") : "None (monolithic structure)"}
-${pc.bold("Documentation:")} Saved to ${pc.cyan(path3.relative(projectInfo.rootPath, destination) || outputPath)}`,
+${pc.bold("Documentation:")} Saved to ${pc.cyan(path4.relative(projectInfo.rootPath, destination) || outputPath)}
+${pc.bold("\u{1F4A1} How to view diagram:")}
+  \u2022 On GitHub: Push ${outputPath} (Mermaid renders automatically)
+  \u2022 In VS Code: Press ${pc.yellow("Ctrl+Shift+V")} for Markdown Preview
+  \u2022 In Browser: Run ${pc.cyan("npx larats view")} for instant local web preview`,
       pc.green("Architecture Map Generated! \u{1F5FA}\uFE0F")
     );
-    p.outro(pc.cyan(`Open ${outputPath} to view your project structure & Mermaid diagram!`));
+    p.outro(pc.cyan(`Done! Open ${outputPath} or run "npx larats view" to inspect architecture!`));
   } catch (err) {
     spinner2.stop(pc.red("Scan failed"));
     p.log.error(err.message || String(err));
+    process.exitCode = 1;
   }
 }
 async function runScaffold(projectInfo, moduleNameArg, cliOptions = {}) {
+  if (projectInfo.type === "unknown") {
+    p.log.warn(pc.yellow("Warning: Project type is unknown (neither Laravel nor TypeScript detected). Scaffolding standard TypeScript/Express components."));
+  } else if (projectInfo.type === "typescript" && projectInfo.typescript?.framework && !["express", "node-vanilla", "unknown"].includes(projectInfo.typescript.framework)) {
+    p.log.warn(
+      pc.yellow(`Warning: Project detected as "${projectInfo.typescript.framework}". LaraTS generates standard Express-compatible TypeScript boilerplate.`)
+    );
+  }
   let moduleName = moduleNameArg;
-  if (!moduleName) {
+  if (moduleName) {
+    const errorMsg = validateModuleName(moduleName);
+    if (errorMsg) {
+      p.log.error(pc.red(`Invalid module name: ${errorMsg}`));
+      process.exitCode = 1;
+      return;
+    }
+  } else {
+    if (!process.stdin.isTTY) {
+      p.log.error(pc.red("Error: Module name is required in non-interactive (non-TTY) mode. Example: `larats scaffold Payment`"));
+      process.exitCode = 1;
+      return;
+    }
     const input = await p.text({
       message: "What is the name of the new module or feature?",
       placeholder: "e.g. Payment, Order, UserProfile",
       validate(val) {
-        if (!val || !val.trim()) return "Module name cannot be empty.";
-        if (!/^[a-zA-Z0-9_-]+$/.test(val.trim())) return "Use only alphanumeric characters, dashes, or underscores.";
+        return validateModuleName(val) || void 0;
       }
     });
     if (p.isCancel(input)) handleCancel();
@@ -1507,42 +2238,68 @@ async function runScaffold(projectInfo, moduleNameArg, cliOptions = {}) {
   }
   let selectedComponents = [];
   if (projectInfo.type === "laravel") {
-    const componentsPrompt = await p.multiselect({
-      message: `Select components to scaffold for ${pc.cyan(moduleName)}:`,
-      options: [
-        { value: "model", label: "Eloquent Model", hint: "Includes table name, fillables, and casts" },
-        { value: "controller", label: "Resourceful Controller", hint: "Includes standard CRUD methods & DI service" },
-        { value: "service", label: "Service Class", hint: "Encapsulated business logic operations" },
-        { value: "action", label: "Single Action Class", hint: "Invokable single-responsibility class" },
-        { value: "request", label: "Form Request", hint: "Request validation rules & authorization" },
-        { value: "migration", label: "Database Migration", hint: "Schema definition with timestamps" }
-      ],
-      initialValues: ["model", "controller", "service", "request", "migration"],
-      required: true
-    });
-    if (p.isCancel(componentsPrompt)) handleCancel();
-    selectedComponents = componentsPrompt;
+    if (!process.stdin.isTTY) {
+      selectedComponents = ["model", "controller", "service", "request", "migration"];
+    } else {
+      const componentsPrompt = await p.multiselect({
+        message: `Select components to scaffold for ${pc.cyan(moduleName)}:`,
+        options: [
+          { value: "model", label: "Eloquent Model", hint: "Includes table name, fillables, and casts" },
+          { value: "controller", label: "Resourceful Controller", hint: "Includes standard CRUD methods & DI service" },
+          { value: "service", label: "Service Class", hint: "Encapsulated business logic operations" },
+          { value: "action", label: "Single Action Class", hint: "Invokable single-responsibility class" },
+          { value: "request", label: "Form Request", hint: "Request validation rules & authorization" },
+          { value: "migration", label: "Database Migration", hint: "Schema definition with timestamps" }
+        ],
+        initialValues: ["model", "controller", "service", "request", "migration"],
+        required: true
+      });
+      if (p.isCancel(componentsPrompt)) handleCancel();
+      selectedComponents = componentsPrompt;
+    }
+    if (selectedComponents.includes("controller") && !selectedComponents.includes("service")) {
+      p.log.warn(pc.yellow('Notice: Controller requires Service class. Auto-adding "service" to scaffolded components.'));
+      selectedComponents.push("service");
+    }
   } else {
-    const componentsPrompt = await p.multiselect({
-      message: `Select components to scaffold for ${pc.cyan(moduleName)}:`,
-      options: [
-        { value: "controller", label: "Controller", hint: "Express request handlers & response orchestration" },
-        { value: "service", label: "Service", hint: "Application logic & repository coordination" },
-        { value: "repository", label: "Repository", hint: "Data persistence abstraction & queries" },
-        { value: "route", label: "Router & Routes", hint: "Express router mapping endpoints to controller" },
-        { value: "dto", label: "DTOs & Interfaces", hint: "Typed interfaces for entities and payloads" }
-      ],
-      initialValues: ["controller", "service", "repository", "route", "dto"],
-      required: true
-    });
-    if (p.isCancel(componentsPrompt)) handleCancel();
-    selectedComponents = componentsPrompt;
+    if (!process.stdin.isTTY) {
+      selectedComponents = ["controller", "service", "repository", "route", "dto"];
+    } else {
+      const componentsPrompt = await p.multiselect({
+        message: `Select components to scaffold for ${pc.cyan(moduleName)}:`,
+        options: [
+          { value: "controller", label: "Controller", hint: "Express request handlers & response orchestration" },
+          { value: "service", label: "Service", hint: "Application logic & repository coordination" },
+          { value: "repository", label: "Repository", hint: "Data persistence abstraction & queries" },
+          { value: "route", label: "Router & Routes", hint: "Express router mapping endpoints to controller" },
+          { value: "dto", label: "DTOs & Interfaces", hint: "Typed interfaces for entities and payloads" }
+        ],
+        initialValues: ["controller", "service", "repository", "route", "dto"],
+        required: true
+      });
+      if (p.isCancel(componentsPrompt)) handleCancel();
+      selectedComponents = componentsPrompt;
+    }
+    if (selectedComponents.includes("route") && !selectedComponents.includes("controller")) {
+      p.log.warn(pc.yellow('Notice: Route requires Controller. Auto-adding "controller" to scaffolded components.'));
+      selectedComponents.push("controller");
+    }
+    if (selectedComponents.includes("controller") && !selectedComponents.includes("service")) {
+      p.log.warn(pc.yellow('Notice: Controller requires Service. Auto-adding "service" to scaffolded components.'));
+      selectedComponents.push("service");
+    }
+    if (selectedComponents.includes("service") && !selectedComponents.includes("repository")) {
+      p.log.warn(pc.yellow('Notice: Service requires Repository. Auto-adding "repository" to scaffolded components.'));
+      selectedComponents.push("repository");
+    }
   }
   let isModular = true;
   if (cliOptions.modular) {
     isModular = true;
   } else if (cliOptions.standard) {
     isModular = false;
+  } else if (!process.stdin.isTTY) {
+    isModular = projectInfo.type === "laravel" ? Boolean(projectInfo.laravel?.isModular) : projectInfo.type === "typescript" ? Boolean(projectInfo.typescript?.isModular) : true;
   } else {
     const defaultModular = projectInfo.type === "laravel" ? Boolean(projectInfo.laravel?.isModular) : projectInfo.type === "typescript" ? Boolean(projectInfo.typescript?.isModular) : true;
     const structurePrompt = await p.select({
@@ -1585,8 +2342,14 @@ async function runScaffold(projectInfo, moduleNameArg, cliOptions = {}) {
     forceOverwrite: cliOptions.force
   });
   spinner2.stop("Generation finished!");
+  if (result.errorCount > 0) {
+    process.exitCode = 1;
+  }
   const fileLines = result.files.map((f) => {
     if (f.status === "created") {
+      if (cliOptions.dryRun) {
+        return `  ${pc.blue("\u2139")} ${f.relativeFilePath} ${pc.gray("(would create)")}`;
+      }
       return `  ${pc.green("\u2714")} ${f.relativeFilePath} ${pc.gray("(created)")}`;
     } else if (f.status === "skipped") {
       return `  ${pc.yellow("\u26A0")} ${f.relativeFilePath} ${pc.yellow(`(skipped - ${f.reason})`)}`;
@@ -1594,6 +2357,16 @@ async function runScaffold(projectInfo, moduleNameArg, cliOptions = {}) {
       return `  ${pc.red("\u2716")} ${f.relativeFilePath} ${pc.red(`(error - ${f.reason})`)}`;
     }
   });
+  if (cliOptions.dryRun) {
+    p.note(
+      fileLines.join("\n") + `
+${pc.bold("Dry run summary:")} ${pc.cyan(`${result.createdCount} would be created`)}, ${pc.yellow(`${result.skippedCount} skipped`)}, ${pc.red(`${result.errorCount} errors`)}`,
+      pc.cyan(`Dry run: Scaffolding ${moduleName}`)
+    );
+    p.outro(pc.cyan("Dry run: no files written."));
+    return;
+  }
   p.note(
     fileLines.join("\n") + `
@@ -1603,6 +2376,25 @@ ${pc.bold("Summary:")} ${pc.green(`${result.createdCount} created`)}, ${pc.yello
   if (result.skippedCount > 0 && !cliOptions.force) {
     p.log.warn(pc.yellow("Anti-Overwrite Protection prevented modifying existing files. Use --force to overwrite if intended."));
   }
+  const names = getNaming(moduleName);
+  if (result.createdCount > 0) {
+    if (projectInfo.type === "laravel") {
+      p.note(
+        `1. Run database migration:
+   ${pc.cyan("php artisan migrate")}
+2. Register routes in routes/api.php or routes/web.php:
+   ${pc.cyan(`Route::apiResource('${names.kebab}', \\${isModular ? `App\\Modules\\${names.pascal}\\Controllers\\` : "App\\Http\\Controllers\\"}${names.pascal}Controller::class);`)}`,
+        "\u{1F680} Next Steps"
+      );
+    } else {
+      p.note(
+        `1. Mount routes into Express app:
+   ${pc.cyan(`import { ${names.camel}Routes } from './${isModular ? `modules/${names.kebab}` : `routes/${names.kebab}.routes.js`}';
+   app.use('/api/${names.kebab}', ${names.camel}Routes);`)}`,
+        "\u{1F680} Next Steps"
+      );
+    }
+  }
   p.outro(pc.green(`\u2728 Successfully scaffolded ${moduleName} module!`));
 }
 function showProjectInfo(projectInfo) {
@@ -1626,34 +2418,99 @@ ${pc.bold("Modular Src:")} ${projectInfo.typescript.isModular ? pc.green("Yes")
   p.note(details, pc.cyan("Detected Project Architecture"));
 }
 async function main() {
-  const args = process.argv.slice(2);
-  if (args.includes("--help") || args.includes("-h") || args[0] === "help") {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: process.argv.slice(2),
+      options: {
+        output: { type: "string", short: "o" },
+        modular: { type: "boolean", short: "m" },
+        standard: { type: "boolean", short: "s" },
+        force: { type: "boolean", short: "f" },
+        "dry-run": { type: "boolean" },
+        view: { type: "boolean" },
+        tree: { type: "boolean", short: "t" },
+        html: { type: "boolean" },
+        version: { type: "boolean", short: "v" },
+        help: { type: "boolean", short: "h" }
+      },
+      allowPositionals: true,
+      strict: true
+    });
+  } catch (err) {
+    console.error(pc.red(`Error: ${err.message}`));
     showHelp();
+    process.exitCode = 1;
     return;
   }
-  if (args.includes("--version") || args.includes("-v")) {
+  if (parsed.values.help || parsed.positionals[0] === "help") {
+    showHelp();
+    return;
+  }
+  if (parsed.values.version || parsed.positionals[0] === "version") {
     console.log(`larats v${VERSION}`);
     return;
   }
-  let outputPath = "ARCHITECTURE.md";
-  const outputIdx = args.findIndex((a) => a === "--output" || a === "-o");
-  if (outputIdx !== -1 && args[outputIdx + 1]) {
-    outputPath = args[outputIdx + 1];
+  const command = parsed.positionals[0];
+  const VALID_COMMANDS = {
+    scan: true,
+    view: true,
+    preview: true,
+    scaffold: true,
+    make: true,
+    info: true,
+    help: true
+  };
+  if (command && !VALID_COMMANDS[command]) {
+    console.error(pc.red(`Error: Unknown command "${command}".`));
+    showHelp();
+    process.exitCode = 1;
+    return;
   }
-  const isModularFlag = args.includes("--modular") || args.includes("-m");
-  const isStandardFlag = args.includes("--standard") || args.includes("-s");
-  const isForceFlag = args.includes("--force") || args.includes("-f");
-  const isDryRunFlag = args.includes("--dry-run");
-  const command = args[0] && !args[0].startsWith("-") ? args[0] : null;
+  const outputPath = parsed.values.output || "ARCHITECTURE.md";
+  const isModularFlag = parsed.values.modular;
+  const isStandardFlag = parsed.values.standard;
+  const isForceFlag = parsed.values.force;
+  const isDryRunFlag = parsed.values["dry-run"];
+  const isViewFlag = parsed.values.view;
+  const isTreeFlag = parsed.values.tree;
+  const isHtmlFlag = parsed.values.html;
   const projectInfo = await detectProjectType(process.cwd());
   if (command === "scan") {
     p.intro(`${pc.bgCyan(pc.black(" LaraTS "))} ${pc.gray(`v${VERSION}`)} - Scanning Architecture`);
     p.log.info(`Detected: ${pc.green(projectInfo.summary)}`);
-    await runScan(projectInfo, outputPath);
+    await runScan(projectInfo, outputPath, {
+      force: isForceFlag,
+      dryRun: isDryRunFlag,
+      view: isViewFlag,
+      tree: isTreeFlag,
+      html: isHtmlFlag
+    });
+    checkAndPromptStar();
+    return;
+  }
+  if (command === "view" || command === "preview") {
+    p.intro(`${pc.bgCyan(pc.black(" LaraTS "))} ${pc.gray(`v${VERSION}`)} - Architecture Viewer`);
+    p.log.info(`Target: ${pc.green(projectInfo.summary)}`);
+    const spinner2 = p.spinner();
+    spinner2.start("Scanning repository & generating architecture map...");
+    const scanResult = await scanProject(projectInfo);
+    spinner2.stop(pc.green(`Scanned ${scanResult.totalFilesScanned} files in ${scanResult.scanDurationMs}ms`));
+    const htmlDestination = path4.resolve(projectInfo.rootPath, "ARCHITECTURE.html");
+    fs3.writeFileSync(htmlDestination, generateArchitectureHtml(scanResult), "utf-8");
+    openViewer(htmlDestination);
+    p.note(
+      `${pc.bold("File:")} ${pc.cyan("ARCHITECTURE.html")}
+Interactive Mermaid.js flowchart & component breakdown loaded in your browser.
+Double-click ${pc.cyan("ARCHITECTURE.html")} anytime to view offline!`,
+      pc.green("Opened in Browser! \u{1F310}")
+    );
+    p.outro(pc.cyan("Done!"));
+    checkAndPromptStar();
     return;
   }
   if (command === "scaffold" || command === "make") {
-    const moduleName = args[1] && !args[1].startsWith("-") ? args[1] : void 0;
+    const moduleName = parsed.positionals[1];
     p.intro(`${pc.bgCyan(pc.black(" LaraTS "))} ${pc.gray(`v${VERSION}`)} - Module Scaffolder`);
     p.log.info(`Target Project: ${pc.green(projectInfo.summary)}`);
     await runScaffold(projectInfo, moduleName, {
@@ -1662,12 +2519,18 @@ async function main() {
       force: isForceFlag,
       dryRun: isDryRunFlag
     });
+    checkAndPromptStar();
     return;
   }
   if (command === "info") {
     p.intro(`${pc.bgCyan(pc.black(" LaraTS "))} ${pc.gray(`v${VERSION}`)}`);
     showProjectInfo(projectInfo);
     p.outro(pc.cyan("Done."));
+    checkAndPromptStar();
+    return;
+  }
+  if (!process.stdin.isTTY) {
+    showHelp();
     return;
   }
   p.intro(`${pc.bgCyan(pc.black(" LaraTS "))} ${pc.bold("Smart Architecture Visualizer & Scaffolder")} ${pc.gray(`v${VERSION}`)}`);
@@ -1681,6 +2544,11 @@ async function main() {
         label: "\u{1F50D} Scan Architecture & Generate ARCHITECTURE.md",
         hint: "Creates component stats, directory tree & Mermaid flowchart"
       },
+      {
+        value: "view",
+        label: "\u{1F310} Open Interactive Architecture Viewer in Browser",
+        hint: "Spawns local browser tab with Mermaid flowchart & stats"
+      },
       {
         value: "scaffold",
         label: "\u{1F3D7}\uFE0F  Scaffold New Feature / Module",
@@ -1701,7 +2569,22 @@ async function main() {
     handleCancel();
   }
   if (action === "scan") {
-    await runScan(projectInfo, outputPath);
+    await runScan(projectInfo, outputPath, {
+      force: isForceFlag,
+      dryRun: isDryRunFlag,
+      view: isViewFlag,
+      tree: isTreeFlag,
+      html: isHtmlFlag
+    });
+  } else if (action === "view") {
+    const spinner2 = p.spinner();
+    spinner2.start("Scanning repository & generating architecture map...");
+    const scanResult = await scanProject(projectInfo);
+    spinner2.stop(pc.green(`Scanned in ${scanResult.scanDurationMs}ms`));
+    const htmlDestination = path4.resolve(projectInfo.rootPath, "ARCHITECTURE.html");
+    fs3.writeFileSync(htmlDestination, generateArchitectureHtml(scanResult), "utf-8");
+    openViewer(htmlDestination);
+    p.outro(pc.green("\u{1F310} Opened interactive architecture diagram in your browser!"));
   } else if (action === "scaffold") {
     await runScaffold(projectInfo, void 0, {
       modular: isModularFlag,
@@ -1713,9 +2596,13 @@ async function main() {
     showProjectInfo(projectInfo);
     p.outro(pc.cyan("Done!"));
   }
+  checkAndPromptStar();
 }
 main().catch((err) => {
   p.log.error(pc.red(`Fatal error: ${err.message || String(err)}`));
   process.exit(1);
 });
+export {
+  checkAndPromptStar
+};
 //# sourceMappingURL=index.js.map