satto 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Satto
+
+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/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "satto",
+  "version": "1.0.0",
+  "description": "A minimal server-rendered web framework for Node.js",
+  "main": "src/lib/index.js",
+  "bin": {
+    "satto": "./src/bin/satto.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Satto-js/satto.git"
+  },
+  "keywords": [
+    "satto",
+    "web-framework",
+    "ssr",
+    "nodejs"
+  ],
+  "author": "joaopedroleonel",
+  "license": "MIT",
+  "type": "commonjs",
+  "bugs": {
+    "url": "https://github.com/Satto-js/satto/issues"
+  },
+  "homepage": "https://github.com/Satto-js/satto#readme",
+  "dependencies": {
+    "ejs": "^3.1.10",
+    "esbuild": "^0.27.1",
+    "express": "^5.2.1"
+  }
+}

package/readme.md

@@ -0,0 +1,197 @@
+# Satto
+
+**Satto** is a lightweight web framework for building server-rendered applications with a **file-based structure**, **simple routing**, and **fast builds** powered by **Node.js**, **Express**, and **esbuild**.
+
+It is designed to be **minimal**, **opinionated**, and **easy to reason about**, focusing on productivity without unnecessary abstraction.
+
+## Key Features
+
+* File-based page structure
+* Simple and explicit routing
+* Server-Side Rendering (SSR)
+* Page-scoped CSS and JavaScript
+* Fast production builds with esbuild
+* Development mode with file watching
+* Minimal templating syntax for SSR
+* Zero configuration by default
+
+## Installation
+
+Install globally to use the CLI:
+
+```bash
+npm install -g satto
+```
+
+Or install locally in a project:
+
+```bash
+npm install satto
+```
+
+## Creating a New Project
+
+```bash
+satto init my-app
+```
+
+This command creates a new project with the following structure:
+
+```txt
+my-app/
+├── src/
+│   ├── app/
+│   │   └── home/
+│   │       ├── home.html
+│   │       ├── home.css
+│   │       └── home.js
+│   ├── static/
+│   │   └── styles.css
+│   ├── index.html
+│   └── server.js
+└── package.json
+```
+
+## Development Server
+
+Start the development server with file watching enabled:
+
+```bash
+npm run dev
+```
+
+or
+
+```bash
+satto run dev
+```
+
+The application will be available at:
+
+```
+http://localhost:3000
+```
+
+## Production Build
+
+Create an optimized production build:
+
+```bash
+npm run build
+```
+
+or
+
+```bash
+satto run build
+```
+
+This generates the following output:
+
+```txt
+dist/
+├── app/
+├── static/
+├── index.html
+└── server.js
+```
+
+All assets are minified and ready for deployment.
+
+## Creating Routes
+
+Generate a new route using the CLI:
+
+```bash
+satto route blog
+```
+
+This creates:
+
+```txt
+src/app/blog/
+├── blog.html
+├── blog.css
+└── blog.js
+```
+
+And automatically updates `src/server.js`:
+
+```js
+const routes = [
+  { path: "/", page: "home" },
+  { path: "/blog", page: "blog" },
+];
+```
+
+## Page Structure
+
+Each route corresponds to a folder inside `src/app/` and may contain:
+
+* `page.html` – Page markup
+* `page.css` – Page-specific styles
+* `page.js` – Page-specific scripts
+
+The page content is automatically injected into `<routes></routes>` inside `index.html`.
+
+## Server-Side Rendering (SSR)
+
+Satto provides a minimal SSR syntax for rendering data on the server.
+
+### Example
+
+```html
+<ssr url="https://jsonplaceholder.typicode.com/posts" response="posts">
+    <section>
+        <for condition="let post in posts">
+            <div>
+                <h1>{{ post.title }}</h1>
+            </div>
+        </for>
+    </section>
+</ssr>
+```
+
+### Supported Directives
+
+* `{{ variable }}`
+* `<for condition="let item in array">`
+* `<if condition="expression">`
+* Attribute binding: `[src]="image.url"`
+
+## Cache Busting
+
+Satto automatically appends a version query string to assets:
+
+```txt
+styles.css?v=timestamp
+page.js?v=timestamp
+```
+
+This ensures browsers always load the latest version.
+
+## API Reference
+
+### `createServer`
+
+```js
+const createServer = require("satto");
+
+const routes = [
+  { path: "/", page: "home" },
+  { path: "/blog", page: "blog" },
+];
+
+createServer(__dirname, routes, 3000);
+```
+
+**Parameters:**
+
+* `root` – Project root directory
+* `routes` – Array of route definitions
+* `port` – Server port (default: 3000)
+
+## Requirements
+
+* Node.js 18 or later
+* npm

package/src/bin/satto.js

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+const esbuild = require("esbuild");
+
+const args = process.argv.slice(2);
+
+const banner = [
+  "  ____        _   _        ",
+  " / ___|  __ _| |_| |_ ___  ",
+  " \\___ \\ / _` | __| __/ _ \\ ",
+  "  ___) | (_| | |_| || (_) |",
+  " |____/ \\__,_|\\__|\\__\\___/ ",
+  "                           "
+].join("\n");
+
+console.log(banner + "\n");
+
+function write(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+}
+
+if (args[0] === "init") {
+  const appName = args[1];
+
+  if (!appName) {
+    console.error("Error: You must provide an app name.");
+    process.exit(1);
+  }
+
+  console.log(`Creating project '${appName}'...`);
+
+  const root = path.join(process.cwd(), appName);
+
+  const template = {
+    [`${root}/src/app/home/home.html`]: `<h1>Home</h1>`,
+    [`${root}/src/app/home/home.css`]: `h1 {color: green}`,
+    [`${root}/src/app/home/home.js`]: `console.log("home loaded");`,
+    [`${root}/src/static/styles.css`]: ``,
+    [`${root}/src/index.html`]: `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <link rel="stylesheet" href="/styles.css">
+  <title>${appName}</title>
+</head>
+<body>
+  <routes></routes>
+</body>
+</html>`,
+    [`${root}/src/server.js`]: `const createServer = require("satto");
+
+const routes = [
+  { path: "/", page: "home" },
+];
+
+createServer(__dirname, routes);
+`,
+    [`${root}/package.json`]: `{
+  "name": "${appName}",
+  "version": "1.0.0",
+  "type": "commonjs",
+  "scripts": {
+    "dev": "satto run dev",
+    "build": "satto run build"
+  }
+}`
+  };
+
+  for (const file in template) {
+    write(file, template[file]);
+  }
+
+  execSync(
+    `npm i satto`,
+    {
+      stdio: "inherit",
+      cwd: root
+    }
+  );
+
+  console.log("Project created successfully!");
+  process.exit(0);
+}
+
+if (args[0] === "route") {
+  const routeName = args[1];
+
+  if (!routeName) {
+    console.error("Error: You must provide a route name.");
+    process.exit(1);
+  }
+
+  const root = process.cwd();
+
+  console.log(`Creating route '${routeName}'...`);
+
+  write(`${root}/src/app/${routeName}/${routeName}.html`, `<h1>${routeName}</h1>`);
+  write(`${root}/src/app/${routeName}/${routeName}.css`, ``);
+  write(`${root}/src/app/${routeName}/${routeName}.js`, ``);
+
+  const serverPath = `${root}/src/server.js`;
+
+  if (!fs.existsSync(serverPath)) {
+    console.error("Error: server.js not found. Run this command inside a project created using 'satto init'.");
+    process.exit(1);
+  }
+
+  let serverContent = fs.readFileSync(serverPath, "utf8");
+
+  const routeEntry = `  { path: "/${routeName}", page: "${routeName}" },`;
+
+  serverContent = serverContent.replace(
+    /const routes\s*=\s*\[/,
+    `const routes = [\n${routeEntry}`
+  );
+
+  fs.writeFileSync(serverPath, serverContent);
+
+  console.log(`Route '${routeName}' created.`);
+  process.exit(0);
+}
+
+if (args[0] === "run" && args[1] === "dev") {
+  console.log("Development server is starting...");
+  console.clear();
+
+  execSync(
+    "node --watch --watch-path=./src ./src/server.js",
+    {
+      stdio: "inherit",
+      cwd: process.cwd()
+    }
+  );
+
+  process.exit(0);
+}
+
+function copyRecursive(src, dest) {
+  if (!fs.existsSync(src)) return;
+
+  const stats = fs.lstatSync(src);
+
+  if (stats.isFile()) {
+    if(src.includes("css") || src.includes("js")) {
+      esbuild.buildSync({
+        entryPoints: [src],
+        outfile: dest,  
+        minify: true,                 
+        bundle: false
+      });
+    } else {
+      fs.copyFileSync(src, dest);
+    }
+  } else if (stats.isDirectory()) {
+    if (!fs.existsSync(dest)) {
+      fs.mkdirSync(dest);
+    }
+
+    const entries = fs.readdirSync(src);
+
+    for (const entry of entries) {
+      const srcPath = path.join(src, entry);
+      const destPath = path.join(dest, entry);
+      copyRecursive(srcPath, destPath);
+    }
+  }
+}
+
+if (args[0] === "run" && args[1] === "build") {
+  console.log("Build is starting...");
+
+  const root = process.cwd();
+  if (fs.existsSync(`${root}/dist`)) fs.rmSync(`${root}/dist`, { recursive: true, force: true });
+
+  esbuild.buildSync({
+    entryPoints: ["src/server.js"],
+    bundle: true,
+    platform: "node",
+    outfile: "dist/server.js",
+    format: "cjs",
+    minify: true,
+  });
+
+  copyRecursive(`${root}/src/index.html`, `${root}/dist/index.html`);
+  copyRecursive(`${root}/src/app`, `${root}/dist/app`);
+  copyRecursive(`${root}/src/static`, `${root}/dist/static`);
+
+  console.log("Build completed successfully!");
+  process.exit(0);
+}
+
+console.log("Unknown command.");
+console.log("Usage:");
+console.log("  satto init <app_name>       # Initialize a new Satto application");
+console.log("  satto route <route_name>    # Create a new route in the application");
+console.log("  satto run dev               # Run the application in development mode");
+console.log("  satto run build             # Build the application for production");
+process.exit(1);

package/src/lib/index.js

@@ -0,0 +1,119 @@
+const express = require("express");
+const path = require("path");
+const fs = require("fs");
+const ejs = require("ejs");
+
+function hasContent(filePath) {
+  try {
+    return fs.statSync(filePath).size > 0;
+  } catch {
+    return false;
+  }
+}
+
+function applyParams(template, params) {
+  return template.replace(/{{\s*params\.(\w+)\s*}}/g, (_, key) => {
+    return params[key] ?? "";
+  });
+}
+
+async function renderPage(html, params) {
+  const match = html.match(/<ssr\s+url="([^"]+)"\s+.*response="([^"]+)"[^>]*>/);
+
+  if(match) {
+    const url = applyParams(match?.[1], params);
+    const resVar = match?.[2];
+    let data = {};
+
+    if (url) {
+      const res = await fetch(url);
+      data = await res.json();
+    }
+
+    html = html.replace(/<ssr[^>]*>([\s\S]*?)<\/ssr>/g, (_, content) => {
+      return content.replace(
+        /<ssr[^>]*>|<\/ssr>|\{\{\s*([\w.]+)\s*\}\}|<for\s+condition="let\s+(\w+)\s+in\s+([\w.]+)"\s*>|<\/for>|<if\s+condition="(.+?)"\s*>|<\/if>|\[(\w+)\]="([^"]+)"/g,
+        (match, expr, item, arr, cond, attr, val) => {
+          if (match.startsWith("<ssr")) return "";
+          if (match === "</ssr>") return "";
+          if (expr) return `<%= ${expr} %>`;
+          if (item && arr) return `<% ${arr}.forEach(${item} => { %>`;
+          if (match === "</for>") return "<% }) %>";
+          if (cond) return `<% if (${cond}) { %>`;
+          if (match === "</if>") return "<% } %>";
+          if (attr && val) return `${attr}="<%= ${val} %>"`;
+          return match;
+        }
+      );
+    });
+
+    return ejs.render(html, {params, [resVar]: data});
+  } else {
+    return html;
+  }
+}
+
+function createServer(__dirname, routes = [], port = 3000) {
+  const versionApp = Date.now();
+  const app = express();
+
+  app.set("views", path.join(__dirname, "app"));
+  app.engine("html", ejs.renderFile);
+  app.set("view engine", "html");
+
+  app.use(express.static(path.join(__dirname, "app")));
+  app.use(express.static(path.join(__dirname, "static")));
+
+  routes.forEach((route) => {
+    app.get(route.path, (req, res) => {
+      const page = route.page;
+      const htmlPath = path.join(__dirname, "app", page, page + ".html");
+      app.use(express.static(path.join(__dirname, "app", page)));
+
+      fs.readFile(htmlPath, "utf8", async (err, html) => {
+        if (err) {
+          return res.status(404).send();
+        }
+
+        const params = { ...req.params };
+        const index = fs.readFileSync(__dirname + "/index.html", "utf8");
+
+        const CssPath = path.join(__dirname, "app", page, page + ".css");
+        const JsPath = path.join(__dirname, "app", page, page + ".js");
+
+        if(hasContent(JsPath)) {
+          html += `\n<script src="./${page}.js?v=${versionApp}"></script>`;
+        }
+
+        html = index.replace("<routes></routes>", html);
+        html = html.replace(`<link rel="stylesheet" href="/styles.css">`, `<link rel="stylesheet" href="/styles.css?v=${versionApp}">`);
+
+        if(hasContent(CssPath)) {
+          html = html.replace(
+            "</head>", 
+            `<link rel="stylesheet" href="./${page}.css?v=${versionApp}">
+            </head>`
+          );
+        }
+
+        res.send(await renderPage(html, params));
+      });
+    });
+  });
+
+  app.listen(port, () => {
+    const banner = [
+      "  ____        _   _        ",
+      " / ___|  __ _| |_| |_ ___  ",
+      " \\___ \\ / _` | __| __/ _ \\ ",
+      "  ___) | (_| | |_| || (_) |",
+      " |____/ \\__,_|\\__|\\__\\___/ ",
+      "                           "
+    ].join("\n");
+
+    console.log(banner + "\n");
+    console.log(`Server running on http://localhost:${port}`);
+  });
+}
+
+module.exports = createServer;