larats 1.1.0 → 1.1.1

package/README.md

@@ -18,8 +18,8 @@ When codebases grow large, developers often struggle to understand the architect
 
 1. 🔍 **Architecture Scanner & Visualizer (`scan`)**: Instantly scans your repository, categorizes layers (Models, Controllers, Services, Actions, Filament Resources, Routes, etc.), and generates a clean `ARCHITECTURE.md` with an interactive **Mermaid.js flowchart** and directory tree.
 2. 🏗️ **Contextual Module Scaffolder (`scaffold` / `make`)**: Quickly generates cohesive feature modules with clean, production-ready boilerplate code tailored to your exact stack (Laravel or TypeScript).
-3. 🔒 **100% Local & Secure**: No data ever leaves your computer. Sensitive files (`.env`, private keys, vendor folders) are strictly excluded.
-
+3. 🤖 **AI Architecture Context Packager (`ai`)**: Exports a token-efficient system prompt teaching Cursor AI, Claude, Copilot, or ChatGPT your exact layered boundaries (`--copy`, `--cursor`, `--claude`).
+4. 🔒 **100% Local & Secure**: No data ever leaves your computer. Sensitive files (`.env`, private keys, vendor folders) are strictly excluded.
 ---
 
 ## 🚀 Quick Start
@@ -36,6 +36,9 @@ npx larats scan
 # Open interactive Mermaid diagram in your browser
 npx larats view
 
+# Export architecture context rules for AI (Cursor, Claude, Copilot)
+npx larats ai --copy
+
 # Or scaffold a new module directly
 npx larats scaffold Payment
 ```
@@ -118,6 +121,13 @@ Create new features in seconds with consistent boilerplate:
 ### 3. 🛡️ Anti-Overwrite Protection
 LaraTS will **NEVER** silently overwrite your existing code. If a target file already exists, LaraTS skips it and alerts you. You can only overwrite files by explicitly providing `--force`.
 
+
+### 4. 🤖 AI Architecture Context Packager (`ai`)
+Teach AI coding assistants (Cursor, Claude Code, GitHub Copilot, ChatGPT) your exact project architecture rules so they never write misplaced code again:
+- **Copy to Clipboard**: `larats ai --copy` — Copies clean, compressed architecture instructions (< 500 tokens) ready to paste into ChatGPT or Claude.
+- **Cursor AI Rules**: `larats ai --cursor` — Injects architecture boundaries and directory maps directly into `.cursorrules`.
+- **Claude Code Rules**: `larats ai --claude` — Injects architecture conventions into `CLAUDE.md`.
+*(Safe merge: uses `<!-- larats-rules:start -->` tags so existing user instructions are never overwritten).*
 ---
 
 ## 🔒 Strict Security & Safety Guarantees
@@ -142,6 +152,7 @@ USAGE:
 COMMANDS:
   scan                 Scan repository & generate ARCHITECTURE.md
   view, preview        Open interactive architecture diagram in local browser
+  ai                   Export architecture context prompt for AI (Cursor, Claude, Copilot)
   scaffold, make [name] Scaffold a new module or feature with clean boilerplate
   info                 Show detected project type & architectural flavor
   help                 Display help message
@@ -149,6 +160,9 @@ COMMANDS:
 OPTIONS:
   -o, --output <file>    Output path for scan (default: ARCHITECTURE.md)
   --view                 Open local browser viewer immediately after scanning
+  --copy                 Copy AI architecture context prompt to clipboard
+  --cursor               Inject architecture rules into .cursorrules
+  --claude               Inject architecture rules into CLAUDE.md
   -t, --tree             Print directory tree in terminal
   --html                 Also export standalone ARCHITECTURE.html
   -m, --modular          Enforce modular directory structure

package/dist/index.js

@@ -1091,6 +1091,135 @@ function generateArchitectureHtml(scanResult) {
 </html>`;
 }
 
+// src/generator/ai-context.ts
+var AI_RULES_START_TAG = "<!-- larats-rules:start -->";
+var AI_RULES_END_TAG = "<!-- larats-rules:end -->";
+function generateAiContext(scanResult) {
+  const { projectInfo, components, modules } = scanResult;
+  const lines = [];
+  lines.push("# Codebase Architecture Rules");
+  lines.push(`> Project: ${projectInfo.name} | Stack: ${projectInfo.summary}`);
+  lines.push("");
+  lines.push("## Architectural Boundaries & Principles");
+  lines.push("- Maintain strict separation of concerns across active architectural layers.");
+  lines.push("- Keep Controllers thin: handle HTTP requests, invoke Services, and return responses.");
+  lines.push("- Encapsulate all business rules, calculations, and mutations inside Services/Actions.");
+  lines.push("- Isolate data storage and queries to Repositories or Model entities.");
+  lines.push("- Validate all incoming user inputs with dedicated DTOs or Form Requests before reaching domain logic.");
+  lines.push("");
+  lines.push("## Project Structure & Layer Conventions");
+  if (projectInfo.type === "laravel") {
+    const isModular = Boolean(projectInfo.laravel?.isModular);
+    const modDir = projectInfo.laravel?.modulesDir || "app/Modules";
+    if (isModular) {
+      lines.push(`- **Architecture Style**: Modular Domain Architecture`);
+      lines.push(`- **Module Root**: \`${modDir}/<FeatureName>/\``);
+      lines.push(`- **Controllers**: \`${modDir}/<FeatureName>/Controllers/\` (HTTP handlers)`);
+      lines.push(`- **Services / Actions**: \`${modDir}/<FeatureName>/Services/\` or \`Actions/\` (Business logic)`);
+      lines.push(`- **Models**: \`${modDir}/<FeatureName>/Models/\` (Eloquent entities)`);
+      lines.push(`- **Validation**: \`${modDir}/<FeatureName>/Requests/\` (FormRequest classes)`);
+      lines.push(`- **Routes**: \`${modDir}/<FeatureName>/routes.php\` or root \`routes/\``);
+    } else {
+      lines.push(`- **Architecture Style**: Standard Laravel Layered Architecture`);
+      lines.push(`- **Controllers**: \`app/Http/Controllers/\``);
+      lines.push(`- **Services / Actions**: \`app/Services/\` or \`app/Actions/\``);
+      lines.push(`- **Models**: \`app/Models/\``);
+      lines.push(`- **Validation**: \`app/Http/Requests/\``);
+      lines.push(`- **Routes**: \`routes/web.php\`, \`routes/api.php\``);
+      lines.push(`- **Migrations**: \`database/migrations/\``);
+    }
+    if (projectInfo.laravel?.hasFilament) {
+      lines.push(`- **Admin Panel**: Filament Resources live in \`app/Filament/Resources/\``);
+    }
+  } else if (projectInfo.type === "typescript") {
+    const isModular = Boolean(projectInfo.typescript?.isModular);
+    const srcDir = projectInfo.typescript?.srcDir || "src";
+    const orm = projectInfo.typescript?.hasPrisma ? "Prisma" : projectInfo.typescript?.hasTypeORM ? "TypeORM" : projectInfo.typescript?.hasDrizzle ? "Drizzle" : null;
+    if (isModular) {
+      lines.push(`- **Architecture Style**: Feature Module Architecture`);
+      lines.push(`- **Module Root**: \`${srcDir}/modules/<feature>/\``);
+      lines.push(`- **Controllers**: \`${srcDir}/modules/<feature>/<feature>.controller.ts\``);
+      lines.push(`- **Services**: \`${srcDir}/modules/<feature>/<feature>.service.ts\``);
+      lines.push(`- **Repositories**: \`${srcDir}/modules/<feature>/<feature>.repository.ts\``);
+      lines.push(`- **DTOs / Schemas**: \`${srcDir}/modules/<feature>/<feature>.dto.ts\``);
+      lines.push(`- **Routes**: \`${srcDir}/modules/<feature>/<feature>.routes.ts\``);
+      lines.push(`- **Module Index**: \`${srcDir}/modules/<feature>/index.ts\` (barrel export)`);
+    } else {
+      lines.push(`- **Architecture Style**: Layered Architecture`);
+      lines.push(`- **Controllers**: \`${srcDir}/controllers/\``);
+      lines.push(`- **Services**: \`${srcDir}/services/\``);
+      lines.push(`- **Repositories / Data**: \`${srcDir}/repositories/\``);
+      lines.push(`- **DTOs / Schemas**: \`${srcDir}/dtos/\` or \`${srcDir}/schemas/\``);
+      lines.push(`- **Routes**: \`${srcDir}/routes/\``);
+    }
+    if (orm) {
+      lines.push(`- **Database ORM**: ${orm} is used for data persistence.`);
+    }
+  } else {
+    lines.push(`- **Source Code**: \`src/\``);
+    lines.push(`- **Automated Tests**: \`tests/\``);
+  }
+  if (modules.length > 0) {
+    lines.push("");
+    lines.push(`## Active Feature Modules (${modules.length})`);
+    lines.push(`Existing domains: ${modules.map((m) => `\`${m}\``).join(", ")}`);
+    lines.push("When creating new features, follow this established domain partition.");
+  }
+  lines.push("");
+  lines.push("## AI Coding Guardrails");
+  lines.push("1. NEVER place raw queries or database transactions inside Controller files.");
+  lines.push("2. When implementing a new feature, always create cohesive layers: Route -> Controller -> Service -> Repository/Model.");
+  lines.push("3. Keep naming conventions consistent with existing files in the repository.");
+  lines.push("4. Write automated unit/feature tests for new domain services.");
+  return lines.join("\n");
+}
+function mergeAiRules(existingContent, newRules) {
+  const block = `${AI_RULES_START_TAG}
+${newRules}
+${AI_RULES_END_TAG}`;
+  if (!existingContent || existingContent.trim() === "") {
+    return block + "\n";
+  }
+  const regex = new RegExp(`${AI_RULES_START_TAG}[\\s\\S]*?${AI_RULES_END_TAG}`, "m");
+  if (regex.test(existingContent)) {
+    return existingContent.replace(regex, block);
+  }
+  return existingContent.trimEnd() + "\n\n" + block + "\n";
+}
+
+// src/utils/clipboard.ts
+import { spawn } from "child_process";
+async function copyToClipboard(text2) {
+  const platform = process.platform;
+  let command;
+  let args = [];
+  if (platform === "win32") {
+    command = "clip";
+  } else if (platform === "darwin") {
+    command = "pbcopy";
+  } else {
+    command = process.env.WAYLAND_DISPLAY ? "wl-copy" : "xclip";
+    if (command === "xclip") {
+      args = ["-selection", "clipboard"];
+    }
+  }
+  return new Promise((resolve) => {
+    try {
+      const child = spawn(command, args, { stdio: ["pipe", "ignore", "ignore"] });
+      child.on("error", () => {
+        resolve(false);
+      });
+      child.on("close", (code) => {
+        resolve(code === 0);
+      });
+      child.stdin.write(text2);
+      child.stdin.end();
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
 // src/generator/scaffolder.ts
 import fs2 from "fs";
 import path3 from "path";
@@ -2032,7 +2161,7 @@ async function scaffoldModule(projectInfo, options) {
 }
 
 // src/index.ts
-var VERSION = true ? "1.1.0" : "1.1.0";
+var VERSION = true ? "1.1.1" : "1.1.1";
 function showHelp() {
   console.log(`
 ${pc.bold(pc.cyan("LaraTS CLI"))} ${pc.gray(`v${VERSION}`)}
@@ -2045,6 +2174,7 @@ ${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("ai")}                   Export architecture context prompt for AI (Cursor, Claude, Copilot)
   ${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
@@ -2052,6 +2182,9 @@ ${pc.bold("COMMANDS:")}
 ${pc.bold("OPTIONS:")}
   ${pc.yellow("-o, --output")} <file>    Output path for scan (default: ARCHITECTURE.md)
   ${pc.yellow("--view")}                 Open local browser viewer immediately after scanning
+  ${pc.yellow("--copy")}                 Copy AI architecture context prompt to clipboard
+  ${pc.yellow("--cursor")}               Inject architecture rules into .cursorrules
+  ${pc.yellow("--claude")}               Inject architecture rules into CLAUDE.md
   ${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
@@ -2072,12 +2205,12 @@ function handleCancel() {
   p.cancel(pc.yellow("Operation cancelled. See you next time! \u{1F44B}"));
   process.exit(0);
 }
-function checkAndPromptStar() {
+async function checkAndPromptStar(customStatsPath, forceAnswer) {
   try {
     const configDir = path4.join(os2.homedir(), ".larats");
-    const statsFile = path4.join(configDir, "stats.json");
-    if (!fs3.existsSync(configDir)) {
-      fs3.mkdirSync(configDir, { recursive: true });
+    const statsFile = customStatsPath || path4.join(configDir, "stats.json");
+    if (!fs3.existsSync(path4.dirname(statsFile))) {
+      fs3.mkdirSync(path4.dirname(statsFile), { recursive: true });
     }
     let stats = {};
     if (fs3.existsSync(statsFile)) {
@@ -2085,15 +2218,30 @@ function checkAndPromptStar() {
     }
     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(
-        `
+    if (runs >= 3 && !stats.hasPromptedStar) {
+      stats.hasPromptedStar = true;
+      const repoUrl = "https://github.com/SidiqFatuh187/larats-cli";
+      if (process.stdin.isTTY || typeof forceAnswer === "boolean") {
+        const shouldStar = typeof forceAnswer === "boolean" ? forceAnswer : await p.confirm({
+          message: "\u2B50 Enjoying LaraTS? Would you like to support the project with a star on GitHub?",
+          initialValue: true
+        });
+        if (shouldStar && !p.isCancel(shouldStar)) {
+          openViewer(repoUrl);
+          p.log.success(pc.green("Thank you so much for your support! \u2B50 Opening GitHub repository in your browser..."));
+        } else {
+          p.log.message(pc.gray("No problem, enjoy building with LaraTS! \u{1F44D}"));
+        }
+      } else {
+        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"))}
+   ${pc.bold(pc.cyan("\u{1F449} " + repoUrl))}
 `
-      );
+        );
+      }
     }
+    fs3.writeFileSync(statsFile, JSON.stringify(stats, null, 2), "utf-8");
   } catch {
   }
 }
@@ -2109,6 +2257,61 @@ function openViewer(destination) {
     p.log.warn(`Could not open browser automatically. Please open ${pc.cyan(destination)} manually.`);
   }
 }
+async function runAi(projectInfo, options = {}) {
+  const spinner2 = p.spinner();
+  spinner2.start("Scanning codebase & formulating AI architecture context...");
+  try {
+    const scanResult = await scanProject(projectInfo);
+    spinner2.stop(pc.green(`Architecture context ready (${scanResult.scanDurationMs}ms)`));
+    const aiContext = generateAiContext(scanResult);
+    let handled = false;
+    if (options.cursor) {
+      const cursorPath = path4.resolve(projectInfo.rootPath, ".cursorrules");
+      const existing = fs3.existsSync(cursorPath) ? fs3.readFileSync(cursorPath, "utf-8") : "";
+      const updated = mergeAiRules(existing, aiContext);
+      fs3.writeFileSync(cursorPath, updated, "utf-8");
+      p.log.success(pc.green(`\u2714 Architecture rules injected into ${pc.bold(".cursorrules")}`));
+      handled = true;
+    }
+    if (options.claude) {
+      const claudePath = path4.resolve(projectInfo.rootPath, "CLAUDE.md");
+      const existing = fs3.existsSync(claudePath) ? fs3.readFileSync(claudePath, "utf-8") : "";
+      const updated = mergeAiRules(existing, aiContext);
+      fs3.writeFileSync(claudePath, updated, "utf-8");
+      p.log.success(pc.green(`\u2714 Architecture rules injected into ${pc.bold("CLAUDE.md")}`));
+      handled = true;
+    }
+    if (options.copy) {
+      const copied = await copyToClipboard(aiContext);
+      if (copied) {
+        p.log.success(pc.green("\u2714 Architecture context copied to clipboard! Ready to paste into ChatGPT or Claude."));
+      } else {
+        p.log.warn("Could not access system clipboard. Printing prompt to console instead.");
+        console.log(`
+${aiContext}
+`);
+      }
+      handled = true;
+    }
+    if (!handled) {
+      console.log(`
+${pc.bold(pc.cyan("--- AI Codebase Architecture Prompt ---"))}
+${aiContext}
+${pc.bold(pc.cyan("---------------------------------------"))}
+`);
+      p.note(
+        `Tip: Run with ${pc.yellow("--copy")} to copy directly to clipboard,
+or ${pc.yellow("--cursor")} / ${pc.yellow("--claude")} to inject into rules files automatically!`,
+        pc.green("Prompt Ready for AI \u{1F916}")
+      );
+    }
+    p.outro(pc.cyan("Done!"));
+  } catch (err) {
+    spinner2.stop(pc.red("Failed to generate AI context"));
+    p.log.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+}
 async function runScan(projectInfo, outputPath = "ARCHITECTURE.md", options = {}) {
   const spinner2 = p.spinner();
   spinner2.start("Scanning codebase structure & components (strict ignore list active)...");
@@ -2432,13 +2635,16 @@ async function main() {
         tree: { type: "boolean", short: "t" },
         html: { type: "boolean" },
         version: { type: "boolean", short: "v" },
+        copy: { type: "boolean" },
+        cursor: { type: "boolean" },
+        claude: { type: "boolean" },
         help: { type: "boolean", short: "h" }
       },
       allowPositionals: true,
       strict: true
     });
   } catch (err) {
-    console.error(pc.red(`Error: ${err.message}`));
+    console.error(pc.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
     showHelp();
     process.exitCode = 1;
     return;
@@ -2459,6 +2665,7 @@ async function main() {
     scaffold: true,
     make: true,
     info: true,
+    ai: true,
     help: true
   };
   if (command && !VALID_COMMANDS[command]) {
@@ -2486,7 +2693,7 @@ async function main() {
       tree: isTreeFlag,
       html: isHtmlFlag
     });
-    checkAndPromptStar();
+    await checkAndPromptStar();
     return;
   }
   if (command === "view" || command === "preview") {
@@ -2506,7 +2713,18 @@ Double-click ${pc.cyan("ARCHITECTURE.html")} anytime to view offline!`,
       pc.green("Opened in Browser! \u{1F310}")
     );
     p.outro(pc.cyan("Done!"));
-    checkAndPromptStar();
+    await checkAndPromptStar();
+    return;
+  }
+  if (command === "ai") {
+    p.intro(`${pc.bgCyan(pc.black(" LaraTS "))} ${pc.gray(`v${VERSION}`)} - AI Architecture Context`);
+    p.log.info(`Target: ${pc.green(projectInfo.summary)}`);
+    await runAi(projectInfo, {
+      copy: parsed.values.copy,
+      cursor: parsed.values.cursor,
+      claude: parsed.values.claude
+    });
+    await checkAndPromptStar();
     return;
   }
   if (command === "scaffold" || command === "make") {
@@ -2519,14 +2737,14 @@ Double-click ${pc.cyan("ARCHITECTURE.html")} anytime to view offline!`,
       force: isForceFlag,
       dryRun: isDryRunFlag
     });
-    checkAndPromptStar();
+    await checkAndPromptStar();
     return;
   }
   if (command === "info") {
     p.intro(`${pc.bgCyan(pc.black(" LaraTS "))} ${pc.gray(`v${VERSION}`)}`);
     showProjectInfo(projectInfo);
     p.outro(pc.cyan("Done."));
-    checkAndPromptStar();
+    await checkAndPromptStar();
     return;
   }
   if (!process.stdin.isTTY) {
@@ -2544,6 +2762,11 @@ Double-click ${pc.cyan("ARCHITECTURE.html")} anytime to view offline!`,
         label: "\u{1F50D} Scan Architecture & Generate ARCHITECTURE.md",
         hint: "Creates component stats, directory tree & Mermaid flowchart"
       },
+      {
+        value: "ai",
+        label: "\u{1F916} Export Architecture Context for AI (Cursor, Claude, Copilot)",
+        hint: "Generate architecture rules for AI coding agents"
+      },
       {
         value: "view",
         label: "\u{1F310} Open Interactive Architecture Viewer in Browser",
@@ -2576,6 +2799,24 @@ Double-click ${pc.cyan("ARCHITECTURE.html")} anytime to view offline!`,
       tree: isTreeFlag,
       html: isHtmlFlag
     });
+  } else if (action === "ai") {
+    const aiTarget = await p.select({
+      message: "How would you like to export the AI architecture context?",
+      options: [
+        { value: "copy", label: "\u{1F4CB} Copy directly to Clipboard", hint: "Ready to paste into ChatGPT or Claude web" },
+        { value: "cursor", label: "\u{1F5B1}\uFE0F  Save into .cursorrules", hint: "Inject rules for Cursor AI" },
+        { value: "claude", label: "\u{1F9E0} Save into CLAUDE.md", hint: "Inject rules for Claude Code" },
+        { value: "print", label: "\u{1F5A5}\uFE0F  Display prompt in terminal", hint: "View formatted markdown text" }
+      ]
+    });
+    if (p.isCancel(aiTarget)) {
+      handleCancel();
+    }
+    await runAi(projectInfo, {
+      copy: aiTarget === "copy",
+      cursor: aiTarget === "cursor",
+      claude: aiTarget === "claude"
+    });
   } else if (action === "view") {
     const spinner2 = p.spinner();
     spinner2.start("Scanning repository & generating architecture map...");
@@ -2596,7 +2837,7 @@ Double-click ${pc.cyan("ARCHITECTURE.html")} anytime to view offline!`,
     showProjectInfo(projectInfo);
     p.outro(pc.cyan("Done!"));
   }
-  checkAndPromptStar();
+  await checkAndPromptStar();
 }
 main().catch((err) => {
   p.log.error(pc.red(`Fatal error: ${err.message || String(err)}`));