create-gardener 1.0.0

package/template/Readme.md

@@ -0,0 +1,349 @@
+# Gardener 🌱
+
+**Gardener** is a small development toolkit and micro-framework for building websites with **declarative DOM JSON**, server-rendered templates, and a **custom static site generation pipeline**.
+
+It is designed for developers who want:
+
+* full control over HTML structure
+* minimal abstractions
+* a fast local dev experience
+* a deterministic static output for production
+
+Gardener sits somewhere between a tiny framework and a build system.
+
+---
+
+## What Gardener Includes
+
+### Core
+
+* 🌿 **gardener.js** — declarative DOM builder using JSON objects
+* 🔁 **parser** — convert real DOM elements back into gardener-compatible JSON
+* 📄 **EJS** for simple server-rendered views
+* 🎨 **Tailwind CSS** for fast styling
+
+### Dev Server
+
+* Express-based development server
+* Hot reload toggle (Ctrl + H)
+* Endpoints to create pages and components at runtime (dev convenience)
+
+### Images
+
+* Deterministic image optimization endpoint
+* Sharp-powered resize + WebP conversion
+* Filesystem cache reused during static builds
+
+### Static Site Generation (SSG)
+
+* Render EJS views into HTML
+* Convert route-encoded filenames into nested directories
+* Merge frontend assets and image cache
+* Clean temporary build artifacts
+* Produce a deployable static directory
+
+---
+
+## Project Structure
+
+```
+src/
+├── backend/
+│   ├── routes/
+│   ├── controllers/
+│   ├── libs/
+│   ├── cache/              # generated image cache (build artifact)
+│   └── server.ts
+│
+├── frontend/
+│   ├── views/              # EJS templates (source)
+│   ├── assets/             # original images
+│   ├── components/
+│   ├── gardener.js
+│   └── styles/
+│
+├── frontendStatic/          # final static output (generated)
+└── tempfrontend/            # temporary build output (deleted after build)
+```
+
+---
+
+## Requirements
+
+* Node.js v16+ (v18+ recommended)
+* pnpm (recommended) or npm
+* Optional: PostgreSQL
+
+---
+
+## Quickstart (Development)
+
+### 1. Install
+
+```bash
+git clone https://github.com/ritishDas/Gardener.git
+cd Gardener
+pnpm install
+```
+
+### 2. Run dev server
+
+```bash
+pnpm run dev
+```
+
+* Server runs at **[http://localhost:3000](http://localhost:3000)**
+* Tailwind watcher and TypeScript server run together
+
+---
+
+## Image Optimization & Caching
+
+Gardener provides a **deterministic image optimization endpoint**.
+
+### Route
+
+```
+GET /cache/:name
+```
+
+### Filename format
+
+```
+<basename>_<width>x<height>.webp
+```
+
+### Example
+
+```http
+GET /cache/hero_500x300.webp
+```
+
+HTML usage:
+
+```html
+<img src="/cache/hero_500x300.webp" alt="hero" />
+```
+
+---
+
+### How it works
+
+1. Parses filename to extract:
+
+   * base name
+   * width
+   * height
+2. Checks cache:
+
+   ```
+   src/backend/cache/
+   ```
+3. If cached → return immediately
+4. If not cached:
+
+   * Finds source image in:
+
+     ```
+     src/frontend/assets/
+     ```
+   * Resizes and converts to WebP (Sharp)
+   * Stores result in cache
+5. Serves the optimized image
+
+---
+
+### Static Build Integration
+
+During static generation:
+
+* All cached images under:
+
+  ```
+  src/backend/cache/
+  ```
+
+  are copied into:
+
+  ```
+  src/frontendStatic/
+  ```
+
+Static HTML can safely reference:
+
+```html
+<img src="/cache/hero_500x300.webp" />
+```
+
+No runtime image processing is required in production.
+
+---
+
+## Static Site Generation
+
+Gardener includes a custom static build pipeline.
+
+### What it does
+
+1. Renders EJS views into HTML
+2. Writes temporary files using route-encoded filenames
+   (example: `_blog_posts_hello.html`)
+3. Converts them into directory-based routes:
+
+   ```
+   blog/posts/hello/index.html
+   ```
+4. Copies frontend assets
+5. Copies image cache
+6. Deletes temporary build directory
+
+### Output
+
+```
+src/frontendStatic/
+├── index.html
+├── blog/
+│   └── posts/
+│       └── hello/
+│           └── index.html
+├── assets/
+└── cache/
+```
+
+This directory is ready for:
+
+* static hosting
+* CDN deployment
+* Nginx / Caddy / Netlify / Vercel
+
+---
+
+## Frontend API — `gardener.js`
+
+File: `src/frontend/gardener.js`
+
+### `gardener(obj)`
+
+Create DOM elements from JSON.
+
+```js
+const el = gardener({
+  t: 'div',
+  cn: ['card', 'p-4'],
+  children: [
+    { t: 'h2', txt: 'Title' },
+    { t: 'p', txt: 'Content' }
+  ]
+});
+
+document.body.appendChild(el);
+```
+
+---
+
+### `parser(elementOrHtml, isParent = true)`
+
+Convert DOM into gardener JSON.
+
+```js
+const json = parser(document.querySelector('.hero'));
+console.log(json);
+```
+
+---
+
+### `parserWindow(text)`
+
+Dev-only UI:
+
+* Preview parsed JSON
+* Press **Y** to create a component file
+
+---
+
+### Utilities
+
+* `imagePreloader(images)`
+* `fetchElement(selector)`
+* `appendElement(parent, child)`
+* `replaceElement(original, newElem)`
+* `createElement(type, classname)`
+
+---
+
+## Dev-Only Endpoints ⚠️
+
+### `POST /addcomponent`
+
+Creates a frontend component file.
+
+```json
+{
+  "path": "components/MyComp.js",
+  "component": "{ t: 'div', txt: 'Hello' }"
+}
+```
+
+Writes directly to the filesystem.
+
+---
+
+### `POST /addpage`
+
+Creates an EJS page and registers a route.
+
+```json
+{ "page": "/my-page" }
+```
+
+* Generates a new EJS file
+* Appends a route to the backend router
+
+---
+
+## Security Notes
+
+⚠️ **Important**
+
+* `/addcomponent` and `/addpage` mutate files and routes
+* Intended for **local development only**
+* Do NOT expose publicly without authentication and sanitization
+
+---
+
+## Troubleshooting
+
+* **Server not starting**
+
+  * Check `.env`
+  * Ensure PostgreSQL is running (if enabled)
+  * Inspect logs from `pnpm run dev`
+
+* **Images not loading**
+
+  * Ensure source image exists in `src/frontend/assets`
+  * Filename must match `<name>_<width>x<height>.webp`
+
+* **Tailwind not updating**
+
+  * Ensure `pnpm install` completed successfully
+
+---
+
+## Contributing
+
+This is a small personal/dev-focused toolkit.
+
+Contributions are welcome:
+
+* bug fixes
+* documentation improvements
+* build pipeline enhancements
+* security hardening
+
+---
+
+## License
+
+MIT
+

package/template/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "create-gardener",
+  "version": "1.0.0",
+  "description": "A dom gardener converting dom elements into json and vice versa",
+  "main": "index.js",
+  "bin":{
+    "create-gardener":"./starter.js"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "dev": "concurrently \"tsx watch src/backend/server.ts\" \"tailwindcss -w -i src/frontend/tailwind.css -o src/frontend/style.css\""
+  },
+  "keywords": [],
+  "author": "ritishDas",
+  "license": "MIT",
+  "packageManager": "pnpm@10.20.0",
+  "dependencies": {
+    "@types/ejs": "^3.1.5",
+    "dotenv": "^17.2.3",
+    "ejs": "^3.1.10",
+    "express": "^5.2.1",
+    "sharp": "^0.34.5",
+    "tailwindcss": "^4.1.18",
+    "types": "^0.1.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.0.2",
+    "concurrently": "^9.2.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}

package/template/src/backend/controllers/gardener.controller.ts

@@ -0,0 +1,211 @@
+import type { Request, Response } from "express";
+import fs, { readFile, readFileSync } from "fs";
+import path from "path";
+import ejs from "ejs";
+import fsp from "fs/promises";
+import generateWebP from "../libs/generateWebp.js";
+import { fileURLToPath } from "url";
+const availableCache: Record<string, boolean> = {};
+
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+interface AddComponentBody {
+  path: string;
+  component: string;
+}
+
+export function addComponent(req: Request<{}, {}, AddComponentBody>, res: Response) {
+  try {
+    const { path: filePath, component } = req.body;
+    const parsed = JSON.parse(component);
+
+    // pretty format (2 spaces)
+    const formatted = JSON.stringify(parsed, null, 2);
+
+    const filecontent = `
+import { gardener } from '../gardener.js'
+
+export default function () {
+  return gardener(${formatted})
+}
+`;
+
+    fs.writeFileSync(`./src/frontend/${filePath}`, filecontent, "utf8");
+
+    res.json({ success: true });
+  } catch (err) {
+    const error = err as Error;
+    res.json({ success: false, msg: error.message });
+  }
+}
+
+
+export async function imageOptimiser(req: Request, res: Response) {
+  try {
+    const { name } = req.params;
+
+    if (!name) return;
+    // name format: test_500x300.webp
+    const match = name.match(/^(.+?)_(\d+)x(\d+)\.webp$/);
+
+    if (!match) {
+      return res.status(400).json({ error: "Invalid image format" });
+    }
+
+    const [, baseName, widthStr, heightStr] = match;
+
+    if (!widthStr || !heightStr) return;
+    const width = parseInt(widthStr, 10);
+    const height = parseInt(heightStr, 10);
+
+    const cacheDir = path.join(__dirname, "../cache");
+    await fsp.mkdir(cacheDir, { recursive: true });
+
+    const outputPath = path.join(cacheDir, name);
+
+    // 1️⃣ Return cached file if exists
+    try {
+      await fsp.access(outputPath);
+      return res.sendFile(path.basename(outputPath), {
+        root: path.dirname(outputPath),
+      });
+    } catch {
+      // not cached → continue
+    }
+
+    // 2️⃣ Find source image with same base name
+    const assetsDir = path.resolve("./src/frontend/assets");
+    const files = await fsp.readdir(assetsDir);
+
+    const sourceFile = files.find((file) => {
+      const parsed = path.parse(file);
+      return parsed.name === baseName;
+    });
+
+    if (!sourceFile) {
+      return res.status(404).json({ error: "Source image not found" });
+    }
+
+    const inputPath = path.join(assetsDir, sourceFile);
+
+    // 3️⃣ Generate optimized WebP
+    await generateWebP(inputPath, outputPath, width, height);
+
+    // 4️⃣ Return generated file
+    return res.sendFile(path.basename(outputPath), {
+      root: path.dirname(outputPath),
+    });
+  } catch (err) {
+    console.error(err);
+    return res.status(500).json({ error: "Image optimisation failed" });
+  }
+}
+
+export async function addPage(req: Request, res: Response) {
+  try {
+    const pagename: string = req.body.page;
+    const buffer = readFileSync('./src/backend/frontendtemplate.ejs', 'utf8');
+    const name = pagename.replaceAll('/', '_');
+
+    fs.writeFileSync(`./src/frontend/views/${name}.ejs`, buffer, "utf8");
+
+    fs.appendFileSync('./src/backend/routes/gardener.route.ts', ` router.route("${pagename}").get((req, res) => res.render("${name}"))\n `);
+
+    res.json({ success: true });
+  }
+  catch (err) {
+    const error = err as Error;
+    res.json({ success: false, msg: error.message });
+  }
+
+}
+
+
+export async function createStatic(req: Request, res: Response) {
+  try {
+    const viewsDir = path.resolve("src/frontend/views");
+    const outDir = path.resolve("src/tempfrontend");
+    const finalOut = path.resolve("src/frontendStatic");
+
+    const otherAssets = path.resolve("src/frontend");
+    await fsp.mkdir(outDir, { recursive: true });
+
+    const entries2 = await fsp.readdir(otherAssets, { withFileTypes: true });
+    const entries = await fsp.readdir(viewsDir, { withFileTypes: true });
+
+    const rendered: string[] = [];
+
+    for (const entry of entries2) {
+      if (!entry.isFile()) continue;
+      const srcPath = path.join(otherAssets, entry.name);
+      const outputPath = path.join(finalOut, entry.name);
+
+      await fsp.copyFile(srcPath, outputPath);
+
+    }
+
+    for (const entry of entries) {
+      // skip folders (partials, layouts, etc.)
+      if (!entry.isFile()) continue;
+      if (!entry.name.endsWith(".ejs")) continue;
+
+      const inputPath = path.join(viewsDir, entry.name);
+      const outputName = entry.name.replace(/\.ejs$/, ".html");
+      const outputPath = path.join(outDir, outputName);
+
+      const html = await ejs.renderFile(
+        inputPath,
+        {
+        },
+        {
+          // async: true,
+          views: [viewsDir], // needed for includes
+        }
+      );
+
+      await fsp.writeFile(outputPath, html, "utf8");
+      rendered.push(outputName);
+    }
+
+    const entries3 = await fsp.readdir(outDir, { withFileTypes: true });
+    for (const entry of entries3) {
+
+      // "_path1_path2_path3.html" -> ["path1", "path2", "path3"]
+      const parts = entry.name
+        .replace(/^_/, "")
+        .replace(/\.html$/, "")
+        .split("_");
+
+      const targetDir = path.join(finalOut, ...parts);
+      const targetFile = path.join(targetDir, "index.html");
+
+      // ensure directories exist
+      await fsp.mkdir(targetDir, { recursive: true });
+      console.log('done');
+      // copy file
+      await fsp.copyFile(path.join(outDir, entry.name), targetFile);
+
+    }
+    await fsp.rm(outDir, { recursive: true, force: true });
+    await fsp.cp(
+      path.resolve("src/frontend/components"),
+      path.join(finalOut, 'components'),
+      { recursive: true }
+    );
+    await fsp.cp(
+      path.resolve("src/backend/cache"),
+      path.join(finalOut, 'cache'),
+      { recursive: true }
+    );
+    return res.json({
+      success: true,
+      generated: rendered,
+      outDir,
+    });
+  } catch (err) {
+    console.error(err);
+    return res.status(500).json({ error: "Static build failed" });
+  }
+}

package/template/src/backend/frontendtemplate.ejs

@@ -0,0 +1,26 @@
+<!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="/style.css">
+    <title>Gardener</title>
+  </head>
+  <body>
+    <div id='body'>
+      <%- include('partials/loader') %>
+      <div class="hero flex justify-around items-center p-5 h-[90vh]">
+        <p class='p-5'>
+          Gardener is a front-end library for creating and manipulating DOM elements using a declarative JavaScript object syntax. It includes a development server with features like hot-reloading and on-the-fly component creation from existing HTML. The server also provides dynamic image resizing and caching.
+        </p>
+        <img src="/cache/w_500x500.webp" alt="logo" class="w-500">
+      </div>
+
+    </div>
+    <script src='/global.js' type="module"></script>
+    <script type="module">
+
+    </script>
+  </body>
+</html>
+

package/template/src/backend/libs/generateWebp.ts

@@ -0,0 +1,26 @@
+import path from "path";
+import fsp from "fs/promises";
+import sharp from "sharp";
+
+export default async function generateWebP(
+  inputPath: string,
+  outputPath: string,
+  width: number,
+  height: number
+): Promise<void> {
+  const cacheDir = path.dirname(outputPath);
+  await fsp.mkdir(cacheDir, { recursive: true });
+
+  console.log(`Processing image: ${inputPath}`);
+  console.log(`Output path: ${outputPath}`);
+
+  await sharp(inputPath)
+    .resize(width, height, {
+      fit: "inside",
+      withoutEnlargement: true,
+    })
+    .webp({ quality: 100 })
+    .toFile(outputPath);
+
+  console.log("✅ Image successfully generated");
+}

package/template/src/backend/routes/gardener.route.ts

@@ -0,0 +1,19 @@
+import { Router } from "express"
+import { addComponent, addPage, createStatic, imageOptimiser } from "../controllers/gardener.controller.js";
+
+const router: Router = Router();
+export default router;
+
+
+
+
+router.route("/cache/:name").get(imageOptimiser);
+router.route("/createstatic").get(createStatic);
+router.route('/addcomponent').post(addComponent);
+router.route('/addpage').post(addPage);
+
+
+
+
+
+router.route('/').get((req, res) => res.render('_'));

package/template/src/backend/server.ts

@@ -0,0 +1,30 @@
+// server.ts
+import 'dotenv/config';
+import express from 'express';
+import frontendRoute from './routes/gardener.route.js'
+
+const app = express();
+
+
+
+app.set('views', './src/frontend/views');
+app.set("view engine", "ejs");
+app.use(express.static('./src/frontend'));
+app.use(express.json());
+app.use(frontendRoute);
+
+const PORT = 5000;
+//
+// initDB().then(
+//   () => {
+//     app.listen(PORT, () => {
+//       console.log("server listening 🚀🚀🚀 PORT:", PORT);
+//     });
+//   }
+// )
+
+app.listen(PORT, () => {
+  console.log("server listening 🚀🚀🚀 PORT:", PORT);
+});
+
+