create-gardener 1.0.0

package/.envrc

@@ -0,0 +1 @@
+use flake

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 ritishDas
+
+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,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/flake.lock

@@ -0,0 +1,61 @@
+{
+  "nodes": {
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1769018530,
+        "narHash": "sha256-MJ27Cy2NtBEV5tsK+YraYr2g851f3Fl1LpNHDzDX15c=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "88d3861acdd3d2f0e361767018218e51810df8a1",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-utils": "flake-utils",
+        "nixpkgs": "nixpkgs"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

package/flake.nix

@@ -0,0 +1,23 @@
+{
+  description="A flake template";
+  inputs={
+    nixpkgs.url="github:NixOS/nixpkgs/nixos-unstable";
+    flake-utils.url="github:numtide/flake-utils";
+  };
+    outputs={self,nixpkgs,flake-utils}:
+  flake-utils.lib.eachDefaultSystem(system:
+      let
+        pkgs=import nixpkgs{
+          inherit system;
+  };
+      in {
+devShells.default=pkgs.mkShell{
+          name="Flake template";
+          shellHook=''
+export PNPM_HOME="$HOME/.local/share/pnpm"
+export PATH="$PNPM_HOME:$PATH"
+          '';
+        };
+      }
+    );
+}

package/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/starter.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+// --- ESM __dirname fix ---
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// --- CLI args ---
+const projectName = process.argv[2];
+
+if (!projectName) {
+  console.log(`
+🌱 create-gardener
+
+Usage:
+  create-gardener <project-name>
+
+Example:
+  create-gardener my-app
+`);
+  process.exit(1);
+}
+
+// --- Target dir ---
+const targetDir = path.resolve(process.cwd(), projectName);
+
+if (fs.existsSync(targetDir)) {
+  console.error(`❌ Directory "${projectName}" already exists`);
+  process.exit(1);
+}
+
+fs.mkdirSync(targetDir, { recursive: true });
+console.log(`✅ Created ${projectName}`);
+
+// --- Copy template ---
+const templateDir = path.join(__dirname, "template");
+
+if (!fs.existsSync(templateDir)) {
+  console.error("❌ Template folder not found");
+  process.exit(1);
+}
+
+copyDir(templateDir, targetDir);
+
+console.log(`
+🌿 Project ready!
+
+Next steps:
+  cd ${projectName}
+  pnpm install
+  pnpm dev
+`);
+
+
+// ---------- helpers ----------
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+