free-framework 4.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dev Omar Tolba
+
+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,198 @@
+# Free Framework
+
+> The blazing-fast, full-stack web framework with its own `.free` language syntax.  
+> Build modern production apps in a fraction of the time — with **zero boilerplate**.
+
+[![NPM Version](https://img.shields.io/npm/v/free-framework.svg)](https://www.npmjs.com/package/free-framework)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org)
+
+---
+
+## ⚡ Why Free Framework?
+
+| Feature | Free | Next.js | Laravel |
+|---|---|---|---|
+| Custom DSL Syntax | ✅ `.free` | ❌ JSX | ❌ Blade |
+| Performance Engine | ✅ uWebSockets | ⚠️ Node HTTP | ⚠️ PHP-FPM |
+| Built-in ORM | ✅ Yes | ❌ No | ✅ Eloquent |
+| Server Actions | ✅ `action {}` | ✅ Yes | ❌ No |
+| Real-Time Sockets | ✅ Built-in | ❌ Manual | ❌ Manual |
+| Edge Runtime | ✅ Yes | ✅ Yes | ❌ No |
+| Islands Architecture | ✅ Native | ⚠️ Extra | ❌ No |
+| CLI DevTools | ✅ `free devtools` | ❌ No | ⚠️ Artisan |
+
+---
+
+## 🚀 Quick Start
+
+```bash
+npx free-framework new my-app
+cd my-app
+free serve
+```
+
+---
+
+## 🧩 The `.free` Syntax
+
+**Routing:**
+```
+route GET "/" {
+    view "Home"
+}
+
+route GET "/dashboard" {
+    middleware auth
+    view "Dashboard"
+}
+```
+
+**Components with Reactive State:**
+```
+component Counter {
+    state count = 0
+
+    button {
+        text "Clicked {count} times!"
+        on-click { count++ }
+    }
+}
+```
+
+**Server Actions (no API routes needed):**
+```
+action createPost {
+    const post = await Post.create({ title: body.title, content: body.content });
+    return post;
+}
+```
+
+**Database Models:**
+```
+model Post {
+    title  string
+    content string
+    likes  number
+}
+```
+
+**Authentication:**
+```
+auth {
+    login    "/login"
+    register "/register"
+}
+```
+
+**File Uploads:**
+```
+upload avatar {
+    path    "public/uploads"
+    maxSize "10mb"
+}
+```
+
+**Error Pages:**
+```
+error 404 {
+    view "NotFound"
+}
+```
+
+---
+
+## 🛠️ CLI Commands
+
+| Command | Description |
+|---|---|
+| `free new <name>` | Create a new Free project |
+| `free serve` | Start the development server |
+| `free build` | Build for production (minified) |
+| `free devtools` | Launch the DevTools Dashboard |
+| `free test` | Run the test suite with Vitest |
+| `free install <pkg>` | Install ecosystem plugins |
+| `free make:model <name>` | Scaffold a new model |
+
+---
+
+## 🏗️ Architecture
+
+```
+my-app/
+├── app/
+│   ├── routes.free      # Route definitions
+│   ├── config.free      # Auth, Uploads, Error pages
+│   ├── models.free      # ORM Models
+│   ├── actions.free     # Server Actions
+│   └── *.free           # Pages & Components
+├── public/              # Static assets
+├── views/               # EJS fallback views
+├── .env                 # Environment config
+└── .free/               # Compiled output
+    └── app.js
+```
+
+---
+
+## ⚡ Performance
+
+Powered by **HyperExpress (uWebSockets.js)** — the fastest HTTP/WebSocket server for Node.js:
+
+- **Multi-core clustering** via built-in `ClusterManager`
+- **LRU page cache** for instant SSR delivery
+- **Zero-copy streaming** for file uploads
+- **Native pub/sub** WebSocket rooms
+- **Minified HTML/CSS/JS** output at build time
+
+---
+
+## 🔌 Built-in Plugins
+
+```js
+const { AuthPlugin, UploadPlugin, ChatPlugin } = require('free-framework');
+
+server.use(AuthPlugin({ login: '/login', register: '/register' }));
+server.use(UploadPlugin('avatar', { path: 'uploads', maxSize: '10mb' }));
+server.use(ChatPlugin());
+```
+
+---
+
+## 🔒 Security Built-in
+
+- Zero-config **security headers** (CSP, X-Frame-Options, HSTS)
+- **DDoS & Rate limiting** (1000 req/min per IP by default)
+- **CSRF token injection** on every page
+- **bcrypt** password hashing in `AuthPlugin`
+- **XSS-safe** template interpolation (auto-escaped)
+
+---
+
+## 🌐 Edge Runtime
+
+Deploy anywhere — Cloudflare Workers, Bun, or standard Node.js:
+
+```js
+const { EdgeRuntime } = require('free-framework');
+const edge = new EdgeRuntime(myFreeApp);
+
+// Cloudflare Workers / Bun compatible
+export default { fetch: edge.fetch.bind(edge) };
+```
+
+---
+
+## 📦 Ecosystem
+
+```bash
+free install free-auth
+free install free-mail
+free install free-payments
+```
+
+---
+
+## License
+
+MIT © [Dev Omar Tolba](https://github.com/dev-omartolba)

package/bin/free.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+
+/**
+ * bin/free.js
+ * CLI entry point for the Free framework.
+ */
+
+const { program } = require("commander");
+const path = require("path");
+
+// Load Environment variables globally
+require('dotenv').config();
+
+program
+    .version("1.0.0")
+    .description("Free Framework CLI");
+
+program
+    .command("new <name>")
+    .description("Create a new Free project")
+    .action((name) => {
+        require("../cli/commands/new")(name);
+    });
+
+program
+    .command("serve")
+    .description("Start the development server")
+    .option("-p, --port <port>", "Port to run on", "3000")
+    .option("--cluster", "Run in Enterprise Cluster Mode")
+    .action((options) => {
+        require("../cli/commands/serve")(options);
+    });
+
+program
+    .command("build")
+    .description("Build the project for production")
+    .action(() => {
+        require("../cli/commands/build")();
+    });
+
+program
+    .command("make:model <name>")
+    .description("Scaffold a new model")
+    .action((name) => { require("../cli/commands/make").model(name); });
+
+program
+    .command("make:controller <name>")
+    .description("Scaffold route file for a controller")
+    .action((name) => { require("../cli/commands/make").controller(name); });
+
+program
+    .command("make:page <name>")
+    .description("Scaffold a new .free page")
+    .action((name) => { require("../cli/commands/make").page(name); });
+
+program
+    .command("make:component <name>")
+    .description("Scaffold a new .free component")
+    .action((name) => { require("../cli/commands/make").component(name); });
+
+program
+    .command("make:middleware <name>")
+    .description("Scaffold a new middleware file")
+    .action((name) => { require("../cli/commands/make").middleware(name); });
+
+program
+    .command("make:plugin <name>")
+    .description("Scaffold a new plugin file")
+    .action((name) => { require("../cli/commands/make").plugin(name); });
+
+program
+    .command("make:migration <name>")
+    .description("Scaffold a new database migration")
+    .action((name) => { require("../cli/commands/make").migration(name); });
+
+program
+    .command("migrate")
+    .description("Run pending database migrations")
+    .action(() => {
+        require("../cli/commands/migrate")();
+    });
+
+program
+    .command("devtools")
+    .description("Open Free DevTools Dashboard")
+    .action(() => {
+        require("../cli/commands/devtools")();
+    });
+
+program
+    .command("test")
+    .description("Run Vitest Testing Suite")
+    .action(() => {
+        require("../cli/commands/test")();
+    });
+
+program
+    .command("install [packages...]")
+    .description("Install ecosystem NPM plugins")
+    .action((packages) => {
+        require("../cli/commands/install")(packages);
+    });
+
+program
+    .command("deploy")
+    .description("Generate Docker + PM2 deployment files")
+    .action(() => {
+        require("../cli/commands/deploy")();
+    });
+
+program
+    .command("doctor")
+    .description("Run project health diagnostics")
+    .action(() => {
+        require("../cli/commands/doctor")();
+    });
+
+program.parse(process.argv);

package/cli/commands/build.js

@@ -0,0 +1,124 @@
+/**
+ * cli/commands/build.js
+ * Implementation of 'free build' command.
+ */
+
+const fs = require("fs-extra");
+const path = require("path");
+const { tokenize } = require("../../compiler/lexer");
+const { parse } = require("../../compiler/parser");
+const { generate } = require("../../compiler/generator");
+const { analyze, printAnalysis } = require("../../compiler/analyzer");
+
+module.exports = function () {
+    const baseDir = process.cwd();
+    const outputDir = path.join(baseDir, ".free");
+
+    if (!fs.existsSync(path.join(baseDir, "app"))) {
+        console.error("Error: 'app' directory not found. Are you in a Free Enterprise project?");
+        process.exit(1);
+    }
+
+    if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir);
+    }
+
+    console.log("🔨 Building Enterprise Project...");
+
+    const freeFiles = [];
+    function scanDir(dir) {
+        if (!fs.existsSync(dir)) return;
+        const files = fs.readdirSync(dir);
+        files.forEach(file => {
+            const filePath = path.join(dir, file);
+            if (fs.statSync(filePath).isDirectory()) {
+                scanDir(filePath);
+            } else if (file.endsWith(".free")) {
+                freeFiles.push(filePath);
+            }
+        });
+    }
+
+    // Scan all enterprise directories for .free files
+    scanDir(path.join(baseDir, "app"));
+    scanDir(path.join(baseDir, "routes"));
+    scanDir(path.join(baseDir, "resources", "views"));
+    let combinedAST = [];
+
+    console.log(`🔍 Found ${freeFiles.length} files to process.`);
+    freeFiles.forEach(filePath => {
+        const file = path.basename(filePath);
+        console.log(`   📄 Processing ${file}...`);
+        const code = fs.readFileSync(filePath, "utf-8");
+
+        try {
+            const tokens = tokenize(code, file);
+            const ast = parse(tokens, file, code);
+            console.log(`      ✅ Parsed ${ast.length} nodes from ${file}`);
+            combinedAST = combinedAST.concat(ast);
+        } catch (err) {
+            if (err.name === 'FreeSyntaxError') {
+                console.error(err.toString());
+            } else {
+                console.error(`Error in ${filePath}: ${err.message}`);
+            }
+            process.exit(1);
+        }
+    });
+
+    // ── Static Analysis ──────────────────────────────────────────────────────
+    console.log("🔍 Running static analysis...");
+    const analysis = analyze(combinedAST, 'app/');
+    printAnalysis(analysis, 'app/');
+    if (!analysis.clean) {
+        console.error("❌ Build aborted due to errors.");
+        process.exit(1);
+    }
+
+    const jsCode = generate(combinedAST);
+    const outputPath = path.join(outputDir, "app.js");
+
+    fs.writeFileSync(outputPath, jsCode);
+
+    // Bundle client runtime
+    console.log("📦 Bundling client assets...");
+    const { buildSync } = require("esbuild");
+
+    try {
+        const publicDir = path.join(process.cwd(), "public");
+        fs.ensureDirSync(publicDir);
+
+        buildSync({
+            entryPoints: [path.join(__dirname, "../../runtime/client.js")],
+            bundle: true,
+            minify: true,
+            outfile: path.join(publicDir, "free-runtime.js"),
+        });
+        console.log("✅ Client runtime bundled to public/free-runtime.js");
+    } catch (err) {
+        console.error("Bundling failed:", err.message || err);
+    }
+
+    // ── CSS Build (Tailwind) ──────────────────────────────────────────────────
+    console.log("🎨 Compiling Tailwind CSS...");
+    const { execSync } = require("child_process");
+    try {
+        const publicCssDir = path.join(process.cwd(), "public/css");
+        fs.ensureDirSync(publicCssDir);
+
+        let tailwindInput = "./resources/css/app.css";
+        // Fallback for older projects
+        if (!fs.existsSync(path.join(process.cwd(), "resources/css/app.css"))) {
+            if (fs.existsSync(path.join(process.cwd(), "app/styles.css"))) {
+                tailwindInput = "./app/styles.css";
+            }
+        }
+
+        execSync(`npx tailwindcss -i ${tailwindInput} -o ./public/css/app.css --minify`, { stdio: "inherit" });
+        console.log("✅ Tailwind CSS compiled to public/css/app.css");
+    } catch (err) {
+        console.error("Tailwind compilation failed:", err);
+    }
+
+    console.log(`✅ Build complete! Compiled to ${outputPath}`);
+};

package/cli/commands/deploy.js

@@ -0,0 +1,143 @@
+/**
+ * cli/commands/deploy.js
+ * Free Framework Deployment Generator.
+ * Generates: Dockerfile, docker-compose.yml, .dockerignore, deploy.sh
+ */
+
+const fs = require("fs-extra");
+const path = require("path");
+
+module.exports = function deploy(options = {}) {
+    const cwd = process.cwd();
+    const appName = require(path.join(cwd, "package.json")).name || "free-app";
+    const port = process.env.PORT || 3000;
+
+    console.log(`\n🚀 Generating deployment files for "${appName}"...\n`);
+
+    // ── Dockerfile ────────────────────────────────────────────────────────────
+    fs.writeFileSync(path.join(cwd, "Dockerfile"), `# Free Framework — Production Dockerfile
+FROM node:20-alpine AS base
+WORKDIR /app
+
+# Install dependencies
+COPY package*.json ./
+RUN npm ci --only=production
+
+# Copy source
+COPY . .
+
+# Build
+RUN node bin/free.js build 2>/dev/null || true
+
+EXPOSE ${port}
+
+# Use clustered production start
+CMD ["node", ".free/app.js"]
+`);
+
+    // ── docker-compose.yml ────────────────────────────────────────────────────
+    fs.writeFileSync(path.join(cwd, "docker-compose.yml"), `version: "3.9"
+
+services:
+  app:
+    build: .
+    container_name: ${appName}
+    restart: unless-stopped
+    ports:
+      - "${port}:${port}"
+    environment:
+      NODE_ENV: production
+      PORT: ${port}
+      # Add your .env values here or use --env-file .env
+    volumes:
+      - ./storage:/app/storage    # persist file uploads
+      - ./database.sqlite:/app/database.sqlite  # persist SQLite DB
+
+  # Uncomment for Redis cache support
+  # redis:
+  #   image: redis:7-alpine
+  #   restart: unless-stopped
+  #   ports:
+  #     - "6379:6379"
+
+  # Uncomment for PostgreSQL support
+  # postgres:
+  #   image: postgres:16-alpine
+  #   restart: unless-stopped
+  #   environment:
+  #     POSTGRES_DB: free_db
+  #     POSTGRES_USER: postgres
+  #     POSTGRES_PASSWORD: changeme
+  #   ports:
+  #     - "5432:5432"
+  #   volumes:
+  #     - pgdata:/var/lib/postgresql/data
+
+# volumes:
+#   pgdata:
+`);
+
+    // ── .dockerignore ─────────────────────────────────────────────────────────
+    fs.writeFileSync(path.join(cwd, ".dockerignore"), `node_modules
+.free
+*.log
+.env
+.git
+coverage
+demo-app
+free-social-app
+`);
+
+    // ── deploy.sh (VPS quick deploy) ──────────────────────────────────────────
+    fs.writeFileSync(path.join(cwd, "deploy.sh"), `#!/bin/bash
+# Quick VPS deployment script for ${appName}
+set -e
+
+echo "📦 Pulling latest changes..."
+git pull origin main
+
+echo "📥 Installing dependencies..."
+npm ci --only=production
+
+echo "🔨 Building..."
+node bin/free.js build
+
+echo "🚀 Restarting with PM2..."
+pm2 restart ${appName} || pm2 start .free/app.js --name ${appName} --instances max
+
+echo "✅ Deployed successfully!"
+`);
+    fs.chmodSync(path.join(cwd, "deploy.sh"), "755");
+
+    // ── PM2 ecosystem config ──────────────────────────────────────────────────
+    fs.writeFileSync(path.join(cwd, "ecosystem.config.js"), `// PM2 Ecosystem Config for ${appName}
+module.exports = {
+    apps: [{
+        name: "${appName}",
+        script: ".free/app.js",
+        instances: "max",       // Use all CPU cores
+        exec_mode: "cluster",
+        env_production: {
+            NODE_ENV: "production",
+            PORT: ${port},
+        },
+        max_memory_restart: "500M",
+        error_file: "logs/err.log",
+        out_file:   "logs/out.log",
+    }],
+};
+`);
+
+    console.log("✅ Deployment files generated:");
+    console.log("   📄 Dockerfile");
+    console.log("   📄 docker-compose.yml");
+    console.log("   📄 .dockerignore");
+    console.log("   📄 deploy.sh");
+    console.log("   📄 ecosystem.config.js (PM2)\n");
+    console.log("🐳 Docker:");
+    console.log("   docker build -t " + appName + " .");
+    console.log("   docker-compose up -d\n");
+    console.log("🖥️  VPS (with PM2):");
+    console.log("   npm install -g pm2");
+    console.log("   bash deploy.sh\n");
+};