leedstack 3.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Colby Leed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,364 @@
+# leedstack
+
+> One-command scaffolder for full-stack web applications with pluggable stacks and modern defaults.
+
+Generate production-ready full-stack applications in seconds with your choice of frontend, backend, database, and optional modules. The recommended default is React + Go (Echo) with Postgres.
+
+## Features
+
+- **60+ Stack Combinations**: Mix and match your preferred technologies
+- **âš¡ Lightning Fast**: From zero to coding in <30 seconds with `make setup`
+- **🚀 Production-Ready**: Docker, CI/CD, testing, monitoring - all included
+- **🧪 Automated Testing**: Vitest with example tests, coverage, and test UI
+- **🔄 CI/CD Pipeline**: GitHub Actions workflow for automated testing and deployment
+- **🐳 Docker Support**: Multi-stage builds for optimized production images
+- **📊 Monitoring**: Health checks, memory tracking, K8s-compatible endpoints
+- **Optimized Performance**: HMR <50ms, builds 20-40x faster with esbuild
+- **Zero Memory Leaks**: Proper cleanup in all components and graceful shutdown
+- **Most Popular Stacks**: React, Vue, Next.js, Python/FastAPI, Node/Express, and more
+- **Auto-Configured Connectivity**: Frontend and backend pre-wired with correct ports and CORS
+- **Modern Defaults**: SSR, code-splitting, tree-shaking, strict types
+- **AI Chatbot Module**: Works out-of-box, upgrades with OpenAI/Anthropic API key
+- **Auth0 Integration**: OIDC/PKCE flow with JWT validation
+- **Stripe Payments**: Checkout + webhook handling
+- **Code Quality Tools**: ESLint, Prettier, Error Boundaries pre-configured
+- **Type-Safe**: TypeScript for frontends and Node backend
+
+## Free vs Pro (Planned)
+
+The npm package will always include the core scaffolding and base stacks.
+Pro will unlock premium modules and templates (Auth, Payments, Admin, Chatbot, deployment presets).
+
+**Pricing (planned)**: one-time purchase for Pro (no subscription).
+**Licensing (planned)**: Pro access will use a simple license key file (e.g. `~/.leedstackrc`) with no heavy DRM.
+
+FAQ: Will there be a subscription later? Possibly for updates and new templates, but the initial plan is a one-time purchase.
+
+### Pro Module Compatibility (Current)
+
+Frontends:
+
+| Module | React | Vue | Next.js | Svelte | Angular |
+| --- | --- | --- | --- | --- | --- |
+| Auth | — | — | — | ✓ | — |
+| Payments | — | — | — | ✓ | — |
+| Admin | — | — | — | ✓ | — |
+| Contact | — | — | — | ✓ | — |
+| Chatbot | ✓ | — | — | — | — |
+
+Backends:
+
+| Module | node-express | python-fastapi | java-spring | go-echo |
+| --- | --- | --- | --- | --- |
+| Auth | ✓ | — | ✓ | — |
+| Payments | ✓ | — | ✓ | — |
+| Admin | — | — | ✓ | — |
+| Contact | — | — | ✓ | — |
+| Chatbot | ✓ | ✓ | — | — |
+
+If your selected stack isn't listed above, that module will be unavailable until we add support.
+
+### Pro Templates (ZIP Install)
+
+If you purchase the Pro templates ZIP, install it like this:
+
+```bash
+# Create the local templates folder
+mkdir -p ~/.leedstack/templates
+
+# Unzip the download into that folder (replace the zip path)
+unzip /path/to/leedstack-pro-templates.zip -d ~/.leedstack/templates
+```
+
+TODO: Add `leedstack login` and automated template downloads from a private registry.
+
+## Quick Start
+
+```bash
+npx leedstack my-app \
+  --frontend react \
+  --backend go-echo \
+  --db postgres
+```
+
+Then follow the printed instructions to start your app!
+
+## âš¡ Fastest Setup
+
+```bash
+npx leedstack my-app --frontend react --backend go-echo --db postgres
+
+cd my-app
+make setup  # Installs everything + starts database (parallel)
+make dev    # Start development servers
+```
+
+**Total time: ~30 seconds to fully operational!** 🚀
+
+See [PERFORMANCE.md](./PERFORMANCE.md) for optimization details.
+
+## 💰 Deployment Options
+
+**Monorepo (Simple):**
+- Deploy everything together: ~$5-15/month
+- Best for: MVPs, small teams, rapid development
+
+**Separate Repos (Cost Optimized):**
+- Deploy frontend and backend separately: **$0/month** possible!
+- Frontend: Vercel/Netlify/Cloudflare (FREE)
+- Backend: Fly.io/Railway (FREE tiers)
+- Database: Supabase/PlanetScale (FREE)
+- Best for: Maximizing free tiers, independent scaling
+
+**Split your monorepo:**
+```bash
+./scripts/split-repos.sh
+```
+
+See [DEPLOYMENT_STRATEGIES.md](./DEPLOYMENT_STRATEGIES.md) for complete guide.
+
+## Supported Stacks
+
+### Frontends (5 options)
+- **react** - Vite + React 19 (most popular!)
+- **vue** - Vue 3.5 with Vite (lightweight and fast)
+- **nextjs** - Next.js 15 (React with SSR/SSG)
+- **svelte** - SvelteKit 5.x (innovative and performant)
+- **angular** - Angular ≥19.0.0 (enterprise-ready)
+
+### Backends (4 options)
+- **go-echo** - Go 1.22+ with Echo framework (high performance, recommended)
+- **node-express** - TypeScript + Express 5.x, Node 20+ (JavaScript ecosystem)
+- **python-fastapi** - Python 3.11+ with FastAPI (great for AI/ML integration)
+- **java-spring** - Spring Boot 3.3.x, Maven, Java 21 LTS (enterprise standard)
+
+### Databases
+- **postgres** - PostgreSQL 16+
+- **mysql** - MySQL 8+
+- **mongodb** - MongoDB 7+
+
+### Optional Modules
+- **--auth auth0** - Auth0 OIDC authentication
+- **--payments stripe** - Stripe Checkout integration
+- **contact** - Contact form with DB persistence
+- **admin** - Protected admin dashboard with stats
+- **chatbot** - AI chatbot (works out-of-box, upgrades with OpenAI/Anthropic API key)
+
+## Usage
+
+```bash
+npx leedstack <appName> \
+  --frontend <react|vue|nextjs|svelte|angular> \
+  --backend <node-express|python-fastapi|java-spring|go-echo> \
+  --db <postgres|mysql|mongodb> \
+  [--auth auth0|none] \
+  [--payments stripe|none] \
+  [contact] [admin]
+```
+
+### Options
+
+- `-f, --frontend <type>` (required) - Frontend framework
+- `-b, --backend <type>` (required) - Backend stack
+- `--db <type>` (required) - Database
+- `--auth <type>` - Authentication (default: none)
+- `--payments <type>` - Payments (default: none)
+- Trailing arguments: Additional modules (`contact`, `admin`, `chatbot`)
+
+## Examples
+
+### Modern Python + React Stack with AI Chatbot
+```bash
+npx leedstack my-saas \
+  --frontend react \
+  --backend python-fastapi \
+  --db postgres \
+  --auth auth0 \
+  --payments stripe \
+  contact admin chatbot
+```
+
+### Recommended Default: React + Go + Postgres
+```bash
+npx leedstack my-app \
+  --frontend react \
+  --backend go-echo \
+  --db postgres
+```
+
+### Vue + Node.js Blog
+```bash
+npx leedstack blog \
+  --frontend vue \
+  --backend node-express \
+  --db mongodb \
+  chatbot
+```
+
+### Next.js E-commerce
+```bash
+npx leedstack shop \
+  --frontend nextjs \
+  --backend node-express \
+  --db postgres \
+  --payments stripe
+
+```
+
+### Enterprise Java Stack
+```bash
+npx leedstack enterprise \
+  --frontend angular \
+  --backend java-spring \
+  --db postgres \
+  --auth auth0 \
+  admin
+```
+
+## Generated Project Structure
+
+```
+my-app/
+├── docker-compose.yml          # Database container
+├── README.md                   # Project-specific docs
+├── .env.example                # Environment template
+├── frontend/                   # Frontend app
+│   ├── src/
+│   ├── package.json
+│   └── .env.example
+└── backend/                    # Backend API
+    ├── src/
+    └── .env.example
+```
+
+## What's Included
+
+### Base Features
+- Docker Compose for database
+- Health endpoints (`/actuator/health` or `/health`)
+- CORS configuration for development
+- Environment variable management
+- Production-ready defaults
+
+### With Auth0 (`--auth auth0`)
+- Frontend: Login/logout flow, token management
+- Backend: JWT validation via JWKS, protected routes
+- Admin scope enforcement for `/api/admin/**` endpoints
+
+### With Stripe (`--payments stripe`)
+- Create Checkout sessions
+- Webhook signature verification
+- Payment success handling
+
+### With Contact Module
+- Contact form (name, email, message)
+- Database persistence
+- `/api/contact` endpoint
+
+### With Admin Module
+- Protected dashboard (requires `admin` scope)
+- User and contact stats
+- `/api/admin/stats` endpoint
+
+## Technology Choices
+
+### Version Policy
+- Pin majors, float minors/patches using `^` (npm) or latest minor (Maven/Go)
+- Enforce minimum runtimes via `engines` field
+
+### Security
+- JWT validation via JWKS (no custom crypto)
+- CORS configurable per environment
+- Secrets via environment variables only
+- Admin routes protected by scope/permission
+
+### Efficiency
+- **Frontend**: SSR, code-splitting, lazy-loaded admin, minimal deps
+- **Backend**: JSON-only APIs, no view engines
+- **Docker**: Multi-stage builds, distroless/alpine images
+
+## Requirements
+
+- **Node.js** ≥20.0.0
+- **Java** 21 LTS (for java-spring backend)
+- **Go** ≥1.22 (for go-echo backend)
+- **Docker** (for running databases)
+- **Maven** (for java-spring backend)
+
+## Development
+
+### Running Generated Projects
+
+1. **Start database**:
+   ```bash
+   docker compose up -d
+   ```
+
+2. **Backend**:
+   ```bash
+   cd backend
+   # Java Spring
+   mvn spring-boot:run
+
+   # Node Express
+   npm install && npm run dev
+
+   # Go Echo
+   go run ./cmd/server
+   ```
+
+3. **Frontend**:
+   ```bash
+   cd frontend
+   cp .env.example .env
+   npm install
+   npm run dev
+   ```
+
+### Environment Setup
+
+See the generated `README.md` in your project for specific Auth0 and Stripe configuration instructions.
+
+## Publishing to npm
+
+If you want to publish this package:
+
+1. Update `package.json`:
+   - Change `name` if needed (must be unique on npm)
+   - Set your `author` name and email
+   - Update `repository`, `bugs`, `homepage` URLs
+
+2. Create npm account: https://www.npmjs.com/signup
+
+3. Login and publish:
+   ```bash
+   npm login
+   npm publish
+   ```
+
+4. Users can then run:
+   ```bash
+   npx leedstack my-app --frontend react --backend node-express --db postgres
+   ```
+
+## License
+
+MIT (c) Colby Leed
+
+## Contributing
+
+Issues and PRs welcome! Please ensure generated projects compile and run before submitting.
+
+## Support
+
+- Report issues: https://github.com/CTLeed/leedstack/issues
+- Documentation: https://github.com/CTLeed/leedstack
+
+
+
+
+
+
+
+
+

package/bin/create-stack.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import ejs from 'ejs';
+// Simple case converters
+function paramCase(str) {
+  return str.replace(/([a-z])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase();
+}
+
+function pascalCase(str) {
+  return str.replace(/[-_\s]+(.)?/g, (_, c) => c ? c.toUpperCase() : '')
+    .replace(/^(.)/, (_, c) => c.toUpperCase());
+}
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const program = new Command();
+
+program
+  .name('leedstack')
+  .version('3.1.0')
+  .description('Generate a full-stack web application with your choice of tech stack')
+  .argument('<appName>', 'Name of the application')
+  .requiredOption('-f, --frontend <type>', 'Frontend stack (react|vue|nextjs|svelte|angular)')
+  .requiredOption('-b, --backend <type>', 'Backend stack (node-express|python-fastapi|java-spring|go-echo)')
+  .requiredOption('--db <type>', 'Database (postgres|mysql|mongodb)')
+  .option('--auth <type>', 'Authentication (auth0|none)', 'none')
+  .option('--payments <type>', 'Payments (stripe|none)', 'none')
+  .addHelpText('after', `
+Examples:
+  $ npx leedstack my-app --frontend react --backend python-fastapi --db postgres --auth auth0 --payments stripe contact admin
+  $ npx leedstack blog --frontend vue --backend node-express --db mongodb
+  $ npx leedstack shop --frontend nextjs --backend java-spring --db mysql --payments stripe
+
+Supported Stacks:
+  Frontends:  react (Vite + React 19), vue (Vue 3.5), nextjs (Next.js 15), svelte (SvelteKit 5.x), angular (Angular 19+)
+  Backends:   node-express (Node 20+ + TypeScript), python-fastapi (Python 3.11+ FastAPI), java-spring (Java 21 + Maven), go-echo (Go 1.22+)
+  Databases:  postgres (16+), mysql (8+), mongodb (7+)
+
+Optional Modules:
+  --auth auth0       Auth0 OIDC authentication with JWT validation
+  --payments stripe  Stripe Checkout + webhook integration
+  contact            Contact form with database persistence
+  admin              Protected admin dashboard (requires auth with 'admin' scope)
+  chatbot            AI chatbot (works out-of-box, upgrades with OpenAI/Anthropic API key)
+
+For more info: https://github.com/CTLeed/leedstack
+`)
+  .action(async (appName, options, command) => {
+    const additionalModules = command.args.slice(1);
+
+    const validFrontends = ['react', 'vue', 'nextjs', 'svelte', 'angular'];
+    const validBackends = ['node-express', 'python-fastapi', 'java-spring', 'go-echo'];
+    const validDatabases = ['postgres', 'mysql', 'mongodb'];
+    const validAuth = ['auth0', 'none'];
+    const validPayments = ['stripe', 'none'];
+    const validModules = ['contact', 'admin', 'chatbot'];
+
+    // Validation
+    if (!validFrontends.includes(options.frontend)) {
+      console.error(`❌ Invalid frontend: ${options.frontend}. Must be one of: ${validFrontends.join(', ')}`);
+      process.exit(1);
+    }
+    if (!validBackends.includes(options.backend)) {
+      console.error(`❌ Invalid backend: ${options.backend}. Must be one of: ${validBackends.join(', ')}`);
+      process.exit(1);
+    }
+    if (!validDatabases.includes(options.db)) {
+      console.error(`❌ Invalid database: ${options.db}. Must be one of: ${validDatabases.join(', ')}`);
+      process.exit(1);
+    }
+    if (!validAuth.includes(options.auth)) {
+      console.error(`❌ Invalid auth: ${options.auth}. Must be one of: ${validAuth.join(', ')}`);
+      process.exit(1);
+    }
+    if (!validPayments.includes(options.payments)) {
+      console.error(`❌ Invalid payments: ${options.payments}. Must be one of: ${validPayments.join(', ')}`);
+      process.exit(1);
+    }
+    for (const mod of additionalModules) {
+      if (!validModules.includes(mod)) {
+        console.error(`❌ Invalid module: ${mod}. Must be one of: ${validModules.join(', ')}`);
+        process.exit(1);
+      }
+    }
+
+    const targetDir = path.resolve(process.cwd(), appName);
+
+    // Fail if target directory exists
+    if (await fs.pathExists(targetDir)) {
+      console.error(`❌ Directory ${appName} already exists. Please choose a different name or remove the existing directory.`);
+      process.exit(1);
+    }
+
+    const appSlug = paramCase(appName);
+    const AppName = pascalCase(appName);
+
+    const modules = {
+      auth: options.auth !== 'none',
+      payments: options.payments !== 'none',
+      contact: additionalModules.includes('contact'),
+      admin: additionalModules.includes('admin'),
+      chatbot: additionalModules.includes('chatbot')
+    };
+
+    const frontendPorts = {
+      react: 5173,
+      vue: 5173,
+      svelte: 5173,
+      nextjs: 3000,
+      angular: 4200
+    };
+    const frontendPort = frontendPorts[options.frontend] || 5173;
+
+    const context = {
+      appName,
+      appSlug,
+      AppName,
+      frontend: options.frontend,
+      backend: options.backend,
+      db: options.db,
+      auth: options.auth,
+      payments: options.payments,
+      modules,
+      frontendPort
+    };
+
+    console.log(`\n🚀 Creating ${appName}...`);
+    console.log(`   Frontend: ${options.frontend}`);
+    console.log(`   Backend: ${options.backend}`);
+    console.log(`   Database: ${options.db}`);
+    if (modules.auth) console.log(`   Auth: ${options.auth}`);
+    if (modules.payments) console.log(`   Payments: ${options.payments}`);
+    if (modules.contact) console.log(`   ✓ contact module`);
+    if (modules.admin) console.log(`   ✓ admin module`);
+    if (modules.chatbot) console.log(`   ✓ chatbot module`);
+    console.log('');
+
+    const warnings = [];
+    const templatesDir = path.resolve(__dirname, '..', 'tools', 'templates');
+
+    // Template resolution order
+    const templateLayers = [
+      { type: 'base', path: path.join(templatesDir, 'base') },
+      { type: 'frontend', path: path.join(templatesDir, 'frontend', options.frontend) },
+      { type: 'backend', path: path.join(templatesDir, 'backend', options.backend) },
+      { type: 'db', path: path.join(templatesDir, 'db', options.db, 'backend', options.backend) }
+    ];
+
+    // Add module layers
+    const moduleNames = [];
+    if (modules.auth) moduleNames.push('auth');
+    if (modules.payments) moduleNames.push('payments');
+    if (modules.contact) moduleNames.push('contact');
+    if (modules.admin) moduleNames.push('admin');
+    if (modules.chatbot) moduleNames.push('chatbot');
+
+    for (const modName of moduleNames) {
+      templateLayers.push({
+        type: `module-${modName}-frontend`,
+        path: path.join(templatesDir, 'modules', modName, 'frontend', options.frontend)
+      });
+      templateLayers.push({
+        type: `module-${modName}-backend`,
+        path: path.join(templatesDir, 'modules', modName, 'backend', options.backend)
+      });
+    }
+
+    // Process each layer
+    for (const layer of templateLayers) {
+      if (await fs.pathExists(layer.path)) {
+        await copyAndRenderTemplates(layer.path, targetDir, context);
+      } else {
+        const skipDbWarning = layer.type === 'db' && ['go-echo', 'python-fastapi'].includes(options.backend);
+        if (!skipDbWarning) {
+          warnings.push(`⚠ ${layer.type}: MISSING (path: ${layer.path})`);
+
+          // Generate stub
+          const stubPath = path.join(targetDir, `MISSING_${layer.type}.txt`);
+          await fs.writeFile(stubPath, `TODO: Missing template\nPath: ${layer.type}\nContract: Implement the documented endpoint/component signature.\n`);
+        }
+      }
+    }
+
+    console.log(`✅ Project ${appName} created successfully!\n`);
+
+    if (warnings.length > 0) {
+      console.log('⚠️  Warnings:');
+      warnings.forEach(w => console.log(`   ${w}`));
+      console.log('');
+    }
+
+    // Print next steps
+    console.log('📋 Next steps:\n');
+    console.log('1. Start the database:');
+    console.log(`   cd ${appName}`);
+    console.log('   docker compose up -d\n');
+
+    console.log('2. Set up environment variables:');
+    console.log('   cp .env.example .env');
+    console.log('   # Edit .env with your configuration\n');
+
+    console.log('3. Start the backend:');
+    console.log('   cd backend');
+    if (options.backend === 'java-spring') {
+      console.log('   mvn spring-boot:run');
+    } else if (options.backend === 'node-express') {
+      console.log('   npm install');
+      console.log('   npm run dev');
+    } else if (options.backend === 'go-echo') {
+      console.log('   go run ./cmd/server');
+    }
+    console.log('');
+
+    console.log('4. Start the frontend (in a new terminal):');
+    console.log('   cd frontend');
+    console.log('   cp .env.example .env');
+    console.log('   npm install');
+    console.log('   npm run dev');
+    console.log('');
+
+    if (modules.auth) {
+      console.log('5. Configure Auth0:');
+      console.log('   - Create a SPA app in Auth0');
+      console.log('   - Set Allowed Callback URLs: http://localhost:5173/callback');
+      console.log('   - Set Allowed Logout URLs: http://localhost:5173');
+      console.log('   - Set Allowed Web Origins: http://localhost:5173');
+      console.log(`   - Create an API with Identifier: https://api.${appSlug}`);
+      console.log('   - Update .env files with Auth0 credentials\n');
+    }
+
+    if (modules.payments) {
+      console.log(`${modules.auth ? '6' : '5'}. Configure Stripe:`);
+      console.log('   - Set STRIPE_SECRET_KEY in backend .env');
+      console.log('   - Run: stripe listen --forward-to localhost:8080/stripe/webhook');
+      console.log('   - Set STRIPE_WEBHOOK_SECRET from the output\n');
+    }
+  });
+
+async function copyAndRenderTemplates(srcDir, destDir, context) {
+  const items = await fs.readdir(srcDir, { withFileTypes: true });
+
+  for (const item of items) {
+    const srcPath = path.join(srcDir, item.name);
+    let destName = item.name;
+
+    // Remove .ejs extension if present
+    if (destName.endsWith('.ejs')) {
+      destName = destName.slice(0, -4);
+    }
+
+    const destPath = path.join(destDir, destName);
+
+    if (item.isDirectory()) {
+      await fs.ensureDir(destPath);
+      await copyAndRenderTemplates(srcPath, destPath, context);
+    } else {
+      // Check if it's an EJS template
+      if (item.name.endsWith('.ejs')) {
+        const template = await fs.readFile(srcPath, 'utf-8');
+        const rendered = ejs.render(template, context);
+        await fs.writeFile(destPath, rendered);
+      } else {
+        // Copy as-is
+        await fs.copy(srcPath, destPath);
+      }
+    }
+  }
+}
+
+program.parse();