boilercraft 1.0.0

package/services/readmeGenerator.js

@@ -0,0 +1,221 @@
+/**
+ * Generates an exhaustive, production-grade customized README.md 
+ * tailored specifically for the chosen backend, database, styling, and auth setup.
+ */
+function generateDynamicStackReadme(config, backend, database, styling, theme, mode) {
+  const title = config.appTitle || config.projectName;
+  const author = config.author || 'ARG RABBI';
+  const desc = config.description || 'Enterprise grade application crafted with BoilerCraft Studio';
+
+  let stackSpecificGuide = '';
+
+  if (backend === 'raw-php') {
+    stackSpecificGuide = `
+## 🐘 Raw PHP (MVC) Architecture & Guide
+
+### 📂 Directory Architecture
+\`\`\`text
+├── app/
+│   ├── Controllers/          # HomeController, AuthController
+│   ├── Models/               # User Model with QueryBuilder & Auto-Schema
+│   └── Views/                # home.php, dashboard.php, auth/login.php, auth/register.php
+├── config/
+│   ├── Database.php          # Universal PDO Connection (MySQL, MSSQL, SQLite, Postgres)
+│   ├── QueryBuilder.php      # Fluent ORM Query Builder (table, select, where, orderBy, get, insert)
+│   ├── Auth.php              # Session Auth & Role Manager (check, user, login, logout, hasRole)
+│   ├── Middleware.php        # Route guards (auth, guest, role)
+│   └── Env.php               # Zero-dependency .env reader
+├── public/                   # Web Root (css, js, index.php)
+└── .env                      # Database & Server configuration
+\`\`\`
+
+### 🔐 Authentication & Roles Usage
+- **Protected Route Example:**
+\`\`\`php
+$router->get('/dashboard', function() {
+    Middleware::auth(); // Redirects to /login if guest
+    require __DIR__ . '/../app/Views/dashboard.php';
+});
+\`\`\`
+- **Admin Role Guard Example:**
+\`\`\`php
+$router->get('/admin', function() {
+    Middleware::role('admin'); // Returns 403 Forbidden if not admin
+    require __DIR__ . '/../app/Views/admin.php';
+});
+\`\`\`
+
+### 🗄️ QueryBuilder Examples
+\`\`\`php
+use App\\Config\\QueryBuilder;
+
+// Select with condition
+$users = QueryBuilder::table('users')->where('role', 'user')->orderBy('id', 'DESC')->get();
+
+// Insert record
+QueryBuilder::table('users')->insert([
+    'name' => 'John Doe',
+    'email' => 'john@example.com'
+]);
+\`\`\`
+
+### 🚀 Running the App
+\`\`\`bash
+# Using PHP Built-in Server:
+php -S localhost:${config.port || 8000} -t public
+\`\`\`
+`;
+  } else if (backend === 'dotnet-core' || backend.includes('dotnet')) {
+    stackSpecificGuide = `
+## 🟣 .NET Core 8 Web API & Guide
+
+### 📂 Directory Architecture
+\`\`\`text
+├── Controllers/              # ProductsController, Api Controllers
+├── Models/                   # C# Data Models & Entities
+├── Data/                     # ApplicationDbContext (EF Core SQL Server / MySQL)
+├── Program.cs                # Dependency Injection, Middleware, Swagger & Static Files
+└── ${config.projectName}.csproj
+\`\`\`
+
+### 🗄️ Entity Framework Core Database Setup
+\`\`\`bash
+# 1. Add EF Core Migration:
+dotnet ef migrations add InitialCreate
+
+# 2. Apply Migration to Database (${database.toUpperCase()}):
+dotnet ef database update
+\`\`\`
+
+### 🚀 Running the App
+\`\`\`bash
+dotnet restore
+dotnet build
+dotnet run
+\`\`\`
+- **Interactive Swagger OpenAPI:** Navigate to \`http://localhost:${config.port || 5000}/swagger\`
+`;
+  } else if (backend === 'nextjs' || backend.includes('nextjs')) {
+    stackSpecificGuide = `
+## 🚀 Next.js App Router Architecture & Guide
+
+### 📂 Directory Architecture
+\`\`\`text
+├── src/
+│   ├── app/
+│   │   ├── api/health/route.js # Route Handler API
+│   │   ├── layout.jsx          # Root Layout & Theme Injection
+│   │   └── page.jsx            # Landing Page with Components
+│   ├── lib/
+│   │   └── db.js               # Database Connection Pool (${database.toUpperCase()})
+│   └── styles/
+│       └── theme.css           # Curated CSS Variable Design Tokens
+\`\`\`
+
+### 🚀 Development & Build
+\`\`\`bash
+# Install dependencies
+npm install
+
+# Start Dev Server with Hot-Reload:
+npm run dev
+
+# Build for Production:
+npm run build
+npm start
+\`\`\`
+`;
+  } else if (backend === 'laravel' || backend.includes('laravel')) {
+    stackSpecificGuide = `
+## 🔴 Laravel 11 + Vue 3 Guide
+
+### 📂 Directory Architecture
+\`\`\`text
+├── app/Http/Controllers/     # HomeController with Inertia responses
+├── resources/
+│   ├── js/
+│   │   ├── Pages/            # Vue 3 Composition API Pages (Home.vue)
+│   │   └── Components/       # Vue UI Components & Modals
+│   └── css/                  # Styling & Theme Variables
+├── routes/web.php            # Web Routes
+└── composer.json
+\`\`\`
+
+### 🚀 Quick Start
+\`\`\`bash
+composer install
+npm install
+npm run dev
+php artisan serve
+\`\`\`
+`;
+  } else {
+    // Node Express
+    stackSpecificGuide = `
+## ⚡ Node.js + Express Clean Architecture Guide
+
+### 📂 Directory Architecture
+\`\`\`text
+├── src/
+│   ├── controllers/          # Business logic handlers
+│   ├── models/               # Database Schemas (${database.toUpperCase()})
+│   ├── routes/               # Modular Express Routers
+│   ├── middlewares/          # Error handling & Auth guards
+│   ├── db.js                 # Database connection connector
+│   └── server.js             # Express entry point
+├── public/                   # Static theme & demo UI
+└── .env
+\`\`\`
+
+### 🚀 Running the Server
+\`\`\`bash
+npm install
+npm run dev   # Auto-reload via node --watch
+\`\`\`
+`;
+  }
+
+  return `# ${title}
+
+> ${desc}
+
+---
+
+## 📋 Technology Configuration
+- **Backend Architecture:** \`${backend}\`
+- **Database Engine:** \`${database.toUpperCase()}\`
+- **Styling System:** \`${styling.toUpperCase()}\`
+- **Theme Palette:** \`${theme}\` (${mode} mode)
+- **Developer & Maintainer:** **${author}**
+- **Created with:** [BoilerCraft Studio](https://github.com/itrabbi24/BoilerCraft)
+
+---
+
+${stackSpecificGuide}
+
+---
+
+## 🎨 Theme & Appearance
+- Active Theme: \`${theme}\`
+- Mode: \`${mode}\`
+- Custom CSS variables can be modified directly in the generated \`theme.css\` file.
+- Client-side theme switching is powered by the included \`ThemeManager\` helper.
+
+---
+
+## 🛡️ Maintenance & Best Practices
+1. **Environment Variables:** Never commit sensitive credentials or real passwords to version control. Always copy \`.env.example\` to \`.env\`.
+2. **Database Migrations:** Ensure your local database server (${database.toUpperCase()}) is active and the database name matches \`.env\`.
+3. **Updating Packages:** This boilerplate was generated with the latest stable versions from online package registries. Regularly execute security audits (\`npm audit\` or \`composer audit\`).
+
+---
+
+## 🤝 Support & Author
+Developed by **[${author}](https://github.com/itrabbi24)**.  
+Feedback and questions: [BoilerCraft Issues](https://github.com/itrabbi24/BoilerCraft/issues)
+`;
+}
+
+module.exports = {
+  generateDynamicStackReadme
+};

package/services/themeGenerator.js

@@ -0,0 +1,150 @@
+/**
+ * Color palettes and Theme configurations
+ */
+const THEMES = {
+  midnight: {
+    id: 'midnight',
+    name: 'Slate Midnight',
+    primary: '#3b82f6',
+    secondary: '#64748b',
+    background: '#090d16',
+    surface: '#111827',
+    surfaceHover: '#1f2937',
+    border: '#1f293d',
+    text: '#f8fafc',
+    textMuted: '#94a3b8'
+  },
+  emerald: {
+    id: 'emerald',
+    name: 'Cyber Emerald',
+    primary: '#10b981',
+    secondary: '#065f46',
+    background: '#04100c',
+    surface: '#081c15',
+    surfaceHover: '#0f2f24',
+    border: '#133a2d',
+    text: '#ecfdf5',
+    textMuted: '#6ee7b7'
+  },
+  royal: {
+    id: 'royal',
+    name: 'Royal Indigo',
+    primary: '#6366f1',
+    secondary: '#818cf8',
+    background: '#0a091a',
+    surface: '#12102e',
+    surfaceHover: '#1b1945',
+    border: '#2a265f',
+    text: '#f5f3ff',
+    textMuted: '#a5b4fc'
+  },
+  crimson: {
+    id: 'crimson',
+    name: 'Crimson Amber',
+    primary: '#f43f5e',
+    secondary: '#fb923c',
+    background: '#120508',
+    surface: '#1f0b11',
+    surfaceHover: '#2e111a',
+    border: '#451624',
+    text: '#fff1f2',
+    textMuted: '#fda4af'
+  }
+};
+
+/**
+ * Returns CSS stylesheet content based on selected theme and mode
+ */
+function generateThemeCSS(themeKey = 'midnight', colorMode = 'dark') {
+  const theme = THEMES[themeKey] || THEMES.midnight;
+
+  return `
+/* ==========================================================
+   Ultimate Boilerplate Studio Generated Theme
+   Theme: ${theme.name} | Default Mode: ${colorMode}
+   ========================================================== */
+:root {
+  --color-primary: ${theme.primary};
+  --color-secondary: ${theme.secondary};
+  --color-bg: ${colorMode === 'light' ? '#ffffff' : theme.background};
+  --color-surface: ${colorMode === 'light' ? '#f8fafc' : theme.surface};
+  --color-surface-hover: ${colorMode === 'light' ? '#f1f5f9' : theme.surfaceHover};
+  --color-border: ${colorMode === 'light' ? '#e2e8f0' : theme.border};
+  --color-text: ${colorMode === 'light' ? '#0f172a' : theme.text};
+  --color-text-muted: ${colorMode === 'light' ? '#64748b' : theme.textMuted};
+  --color-accent: ${theme.primary};
+  --radius-base: 0.75rem;
+  --transition-fast: 150ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+[data-theme="dark"] {
+  --color-bg: ${theme.background};
+  --color-surface: ${theme.surface};
+  --color-surface-hover: ${theme.surfaceHover};
+  --color-border: ${theme.border};
+  --color-text: ${theme.text};
+  --color-text-muted: ${theme.textMuted};
+}
+
+[data-theme="light"] {
+  --color-bg: #ffffff;
+  --color-surface: #f8fafc;
+  --color-surface-hover: #f1f5f9;
+  --color-border: #e2e8f0;
+  --color-text: #0f172a;
+  --color-text-muted: #64748b;
+}
+
+body {
+  background-color: var(--color-bg);
+  color: var(--color-text);
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
+  margin: 0;
+  padding: 0;
+  transition: background-color var(--transition-fast), color var(--transition-fast);
+}
+`;
+}
+
+/**
+ * Client Theme switcher runtime helper script
+ */
+function getThemeSwitcherJS() {
+  return `
+(function() {
+  const STORAGE_KEY = 'ubs-theme-mode';
+  const getPreferredMode = () => {
+    const saved = localStorage.getItem(STORAGE_KEY);
+    if (saved) return saved;
+    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+  };
+
+  const applyMode = (mode) => {
+    if (mode === 'device' || mode === 'all') {
+      const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+      document.documentElement.setAttribute('data-theme', isDark ? 'dark' : 'light');
+    } else {
+      document.documentElement.setAttribute('data-theme', mode);
+    }
+    localStorage.setItem(STORAGE_KEY, mode);
+  };
+
+  window.ThemeManager = {
+    setMode: applyMode,
+    getMode: () => localStorage.getItem(STORAGE_KEY) || 'device',
+    toggle: () => {
+      const current = document.documentElement.getAttribute('data-theme') || 'dark';
+      applyMode(current === 'dark' ? 'light' : 'dark');
+    }
+  };
+
+  applyMode(getPreferredMode());
+})();
+`;
+}
+
+module.exports = {
+  THEMES,
+  generateThemeCSS,
+  getThemeSwitcherJS
+};

package/services/versionResolver.js

@@ -0,0 +1,176 @@
+const axios = require('axios');
+
+// Known-good major version for each package this generator scaffolds against.
+// Bumping these is a deliberate, tested decision (update the templates too),
+// NOT something that should happen automatically just because upstream
+// published a new major release.
+const TESTED_MAJOR = {
+  npm: {
+    'next': 14,
+    'react': 18,
+    'react-dom': 18,
+    'express': 4,
+    'mongoose': 8,
+    'mysql2': 3,
+    'mssql': 11,
+    'tailwindcss': 3,
+    'bootstrap': 5,
+    'dotenv': 16,
+    'cors': 2,
+    'vue': 3
+  },
+  packagist: {
+    'laravel/framework': 11,
+    'vlucas/phpdotenv': 5
+  }
+};
+
+// Fallback stable versions if the registry is unreachable (offline usage).
+const FALLBACK_VERSIONS = {
+  npm: {
+    'next': '^14.2.5',
+    'react': '^18.3.1',
+    'react-dom': '^18.3.1',
+    'express': '^4.19.2',
+    'mongoose': '^8.5.2',
+    'mysql2': '^3.11.0',
+    'mssql': '^11.0.1',
+    'tailwindcss': '^3.4.7',
+    'bootstrap': '^5.3.3',
+    'dotenv': '^16.4.5',
+    'cors': '^2.8.5',
+    'vue': '^3.4.34'
+  },
+  packagist: {
+    'laravel/framework': '^11.0',
+    'vlucas/phpdotenv': '^5.6'
+  }
+};
+
+const cache = new Map();
+
+function majorOf(versionString) {
+  const match = /^v?(\d+)\./.exec(versionString);
+  return match ? parseInt(match[1], 10) : null;
+}
+
+/**
+ * Resolves the latest version within this generator's tested major line from
+ * the NPM Registry. Falls back to the pinned/fallback version if the
+ * registry's current "latest" has moved to a newer, untested major (so a
+ * scaffolded project never silently picks up a breaking upstream release),
+ * or if the registry can't be reached.
+ */
+async function getLatestNpmVersion(pkgName) {
+  if (cache.has(`npm:${pkgName}`)) {
+    return cache.get(`npm:${pkgName}`);
+  }
+
+  const testedMajor = TESTED_MAJOR.npm[pkgName];
+
+  try {
+    const res = await axios.get(`https://registry.npmjs.org/${encodeURIComponent(pkgName)}`, {
+      timeout: 3500
+    });
+    const distTags = res.data && res.data['dist-tags'];
+    const latest = distTags && distTags.latest;
+
+    if (latest) {
+      let resolvedVersion = latest;
+
+      // If we have a tested major pin and the registry's "latest" has moved
+      // past it, look for the newest published version still on that major
+      // instead of jumping to an unverified major release.
+      if (testedMajor !== undefined && majorOf(latest) !== testedMajor) {
+        const versions = Object.keys(res.data.versions || {});
+        const onTestedMajor = versions
+          .filter(v => majorOf(v) === testedMajor && !/-/.test(v)) // exclude pre-releases (canary/alpha/beta/rc)
+          .sort((a, b) => compareVersions(b, a));
+        resolvedVersion = onTestedMajor[0] || latest;
+      }
+
+      const ver = `^${resolvedVersion}`;
+      cache.set(`npm:${pkgName}`, ver);
+      return ver;
+    }
+  } catch (err) {
+    console.warn(`[VersionResolver] Failed to fetch version info for npm package '${pkgName}'. Using fallback.`);
+  }
+  return FALLBACK_VERSIONS.npm[pkgName] || 'latest';
+}
+
+/**
+ * Resolves the latest version within this generator's tested major line from
+ * Packagist (PHP / Laravel). Same tested-major guard as the NPM resolver.
+ */
+async function getLatestPackagistVersion(packageName) {
+  if (cache.has(`php:${packageName}`)) {
+    return cache.get(`php:${packageName}`);
+  }
+
+  const testedMajor = TESTED_MAJOR.packagist[packageName];
+
+  try {
+    const res = await axios.get(`https://repo.packagist.org/p2/${packageName}.json`, {
+      timeout: 3500
+    });
+    if (res.data && res.data.packages && res.data.packages[packageName]) {
+      const releases = res.data.packages[packageName];
+      const stableReleases = releases.filter(
+        r => !r.version.includes('dev') && !r.version.includes('alpha') && !r.version.includes('beta') && !r.version.includes('RC')
+      );
+
+      let candidates = stableReleases;
+      if (testedMajor !== undefined) {
+        const onTestedMajor = stableReleases.filter(r => majorOf(r.version.replace(/^v/, '')) === testedMajor);
+        if (onTestedMajor.length) candidates = onTestedMajor;
+      }
+
+      const stable = candidates[0]; // packagist returns releases newest-first
+      if (stable) {
+        const ver = `^${stable.version.replace(/^v/, '')}`;
+        cache.set(`php:${packageName}`, ver);
+        return ver;
+      }
+    }
+  } catch (err) {
+    console.warn(`[VersionResolver] Failed to fetch packagist package '${packageName}'. Using fallback.`);
+  }
+  return FALLBACK_VERSIONS.packagist[packageName] || '*';
+}
+
+// Minimal semver-ish comparator, sufficient for sorting registry version strings.
+function compareVersions(a, b) {
+  const pa = a.split('.').map(n => parseInt(n, 10) || 0);
+  const pb = b.split('.').map(n => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const diff = (pa[i] || 0) - (pb[i] || 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+/**
+ * Batch resolve versions for requested package list
+ */
+async function resolveDependencies(pkgList, type = 'npm') {
+  const result = {};
+  await Promise.all(
+    pkgList.map(async (pkg) => {
+      if (type === 'npm') {
+        result[pkg] = await getLatestNpmVersion(pkg);
+      } else if (type === 'packagist') {
+        result[pkg] = await getLatestPackagistVersion(pkg);
+      }
+    })
+  );
+  return result;
+}
+
+module.exports = {
+  getLatestNpmVersion,
+  getLatestPackagistVersion,
+  resolveDependencies,
+  FALLBACK_VERSIONS,
+  TESTED_MAJOR
+};

package/stacks/dotnet-core/overlays/api/Controllers/ProductsController.cs

@@ -0,0 +1,33 @@
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.EntityFrameworkCore;
+using {{NAMESPACE}}.Data;
+using {{NAMESPACE}}.Models;
+
+namespace {{NAMESPACE}}.Controllers
+{
+    [ApiController]
+    [Route("api/[controller]")]
+    public class ProductsController : ControllerBase
+    {
+        private readonly ApplicationDbContext _context;
+
+        public ProductsController(ApplicationDbContext context)
+        {
+            _context = context;
+        }
+
+        [HttpGet]
+        public async Task<ActionResult<IEnumerable<Product>>> GetProducts()
+        {
+            return await _context.Products.ToListAsync();
+        }
+
+        [HttpPost]
+        public async Task<ActionResult<Product>> PostProduct(Product product)
+        {
+            _context.Products.Add(product);
+            await _context.SaveChangesAsync();
+            return CreatedAtAction(nameof(GetProducts), new { id = product.Id }, product);
+        }
+    }
+}

package/stacks/dotnet-core/overlays/api/Program.cs

@@ -0,0 +1,33 @@
+using Microsoft.EntityFrameworkCore;
+using {{NAMESPACE}}.Data;
+{{AUTH_USINGS}}
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddControllers();
+builder.Services.AddEndpointsApiExplorer();
+builder.Services.AddSwaggerGen();
+
+// Database: {{DATABASE}} (Entity Framework Core)
+var connectionString = builder.Configuration.GetConnectionString("DefaultConnection")
+    ?? throw new InvalidOperationException("ConnectionStrings:DefaultConnection is not configured");
+builder.Services.AddDbContext<ApplicationDbContext>(options => {{DB_USE}});
+
+{{AUTH_SERVICES}}
+
+var app = builder.Build();
+
+if (app.Environment.IsDevelopment())
+{
+    app.UseSwagger();
+    app.UseSwaggerUI();
+}
+
+app.UseHttpsRedirection();
+app.UseDefaultFiles(); // serves wwwroot/index.html at "/"
+app.UseStaticFiles();
+{{AUTH_MIDDLEWARE}}
+app.UseAuthorization();
+app.MapControllers();
+
+app.Run();

package/stacks/dotnet-core/overlays/api/wwwroot/index.html

@@ -0,0 +1,38 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="{{COLOR_MODE}}">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{APP_TITLE}}</title>
+    <link rel="stylesheet" href="/theme.css">
+    {{STYLESHEET_LINK}}
+</head>
+<body class="p-8">
+    <div style="max-width: 900px; margin: 0 auto; text-align: center;">
+        {{LOGO_HTML}}
+        <h1 style="font-size: 2.5rem; font-weight: 800;">{{APP_TITLE}}</h1>
+        <p style="color: var(--color-text-muted);">{{APP_DESC}}</p>
+        <p style="font-size: 0.85rem; color: var(--color-primary); font-weight: bold;">Developer: {{AUTHOR}}</p>
+
+        <div style="margin: 1.5rem 0;">
+            <a href="/swagger" style="padding: 10px 20px; background: var(--color-primary); color: white; border-radius: 8px; text-decoration: none; font-weight: bold; display: inline-block;">
+                Explore Swagger API ↗
+            </a>
+        </div>
+
+        <div style="text-align: left; padding: 2rem; background: var(--color-surface); border: 1px solid var(--color-border); border-radius: var(--radius-base); margin-top: 2rem;">
+            <h3 style="margin-top: 0;">Active Architecture:</h3>
+            <ul>
+                <li><strong>Backend:</strong> ASP.NET Core Web API (.NET {{VERSION}})</li>
+                <li><strong>Database:</strong> {{DATABASE}} (EF Core)</li>
+                <li><strong>Styling:</strong> {{STYLING}}</li>
+                <li><strong>Theme:</strong> {{THEME}}</li>
+            </ul>
+            <hr style="border: none; border-top: 1px solid var(--color-border); margin: 1.5rem 0;" />
+            <h4>Components:</h4>
+            {{UI_COMPONENTS}}
+        </div>
+    </div>
+    <script src="/theme.js"></script>
+</body>
+</html>