@tobi2409/fullsty 0.5.0

package/README.md

@@ -0,0 +1,126 @@
+# fullsty
+
+Fullsty is a modular fullstack framework starter built from three core parts:
+
+- `template-engine` for reactive UI rendering
+- `layout` for lightweight CSS layout composition
+- `proc2rest` for generating REST server/client code from TypeScript server functions
+
+This repository provides a project template and scaffolding script so you can create a new project, generate API/client artifacts, and run the generated server quickly.
+
+Minimal Fullsty starter workflow.
+
+**It is recommended to install fullsty globally.**
+
+A sample application can be found at https://github.com/tobi2409/fullsty/tree/main/projects/db-test
+
+## 1) Create a project
+
+From the repository root:
+
+```bash
+npx create-fullsty-project projects/demo1
+```
+
+This creates a new folder (for example [projects/demo1](projects/demo1)).
+
+## 2) Install project dependencies
+
+Go to the created project and install dependencies:
+
+```bash
+cd projects/demo1
+npm install
+```
+
+## 3) Generate server/client output
+
+Still inside the project folder:
+
+```bash
+npm run generate
+```
+
+This runs:
+
+- `generate-server` (creates server output in [projects/demo1/generated/server](projects/demo1/generated/server))
+- `generate-client` (creates client output in [projects/demo1/generated/client](projects/demo1/generated/client))
+
+It also copies [project-frame/server-package.json](project-frame/server-package.json) to `generated/server/package.json` and [project-frame/client-package.json](project-frame/client-package.json) to `generated/client/package.json`.
+
+## 4) Use `fullsty-pkg` for wrapper packages
+
+`fullsty-pkg.js` is a small project helper for wrapper-aware package changes.
+
+Run it from the project root, for example:
+
+```bash
+../../scripts/fullsty-server-pkg.js add pg
+../../scripts/fullsty-server-pkg.js add sql-template-tag
+../../scripts/fullsty-server-pkg.js remove pg
+```
+
+Alternatively, you can also use npx fullsty-server-pkg.
+
+What it does:
+
+- `add <package>`
+	- adds the package to the project's server package file, which is initially created from [project-frame/server-package.json](project-frame/server-package.json)
+	- copies a matching wrapper from [extension-wrappers](extension-wrappers) into [projects/demo1/src/server](projects/demo1/src/server)
+- `remove <package>`
+	- removes the package from the project's server package file
+	- removes the matching wrapper from [projects/demo1/src/server](projects/demo1/src/server)
+
+The script does not manage the project-level [package.json](project-frame/package.json).
+
+After `fullsty-server-pkg.js add <package>` you should run `npm run generate` again so the updated project server package file is copied into `generated/server/package.json`. After that, run `npm install` again inside [projects/demo1/generated/server](projects/demo1/generated/server) so the generated server gets the updated dependencies.
+
+`fullsty-server-pkg.js add sql-template-tag` copies [extension-wrappers/sql-template-tag/sql-template-tag-wrapper.ts](extension-wrappers/sql-template-tag/sql-template-tag-wrapper.ts) into [projects/demo1/src/server](projects/demo1/src/server). This keeps `sql-template-tag` visible as the recommended SQL style without coupling it to a specific DBMS wrapper. For PostgreSQL pooling and env handling you can add `pg` separately.
+
+## 5) Start the generated server
+
+Move to the generated server folder and install/start it:
+
+```bash
+cd generated/server
+npm install
+npm run start
+```
+
+## package.json responsibilities
+
+- Project-level package file: [project-frame/package.json](project-frame/package.json)
+	- Used for generation tasks (`generate-server`, `generate-client`, `generate`).
+- Generated server package file: [project-frame/server-package.json](project-frame/server-package.json)
+	- Becomes `generated/server/package.json`.
+	- Used to run the generated server (`npm run start`).
+
+## 6) Install client dependencies
+
+Move to the generated client folder and install the dependencies:
+
+```bash
+cd generated/client
+npm install
+```
+
+## VS Code Setup
+
+To prevent Live Server from reloading when server logs are written, add this to `.vscode/settings.json`:
+
+```json
+{
+    "liveServer.settings.ignoreFiles": [
+        "**/generated/server/logs/**",
+        "**/*.log"
+    ]
+}
+```
+
+## Quick summary
+
+1. `node create-project.js projects/<project-name>`
+2. `cd projects/<project-name>`
+3. `npm install`
+4. `npm run generate`
+5. `cd generated/server && npm install && npm run start`

package/package.json

@@ -0,0 +1,63 @@
+{
+    "name": "@tobi2409/fullsty",
+    "version": "0.5.0",
+    "description": "Fullsty is a modular fullstack framework starter built from three core parts: template-engine, layout and proc2rest. It provides a project frame for building fullstack applications with a clear separation of client and server code.",
+    "license": "ISC",
+    "author": "Tobias Hollstein",
+    "type": "module",
+    "main": "./scripts/create-project.js",
+    "bin": {
+        "create-fullsty-project": "./scripts/create-project.js",
+        "fullsty-server-pkg": "./scripts/fullsty-server-pkg.js"
+    },
+    "files": [
+        "scripts",
+        "README.md"
+    ],
+    "keywords": [
+        "codegen",
+        "typescript",
+        "express",
+        "expressjs",
+        "rest",
+        "rest-api",
+        "api",
+        "api-generator",
+        "client-generator",
+        "javascript-client",
+        "fetch",
+        "msgpack",
+        "messagepack",
+        "ts-morph",
+        "node",
+        "nodejs",
+        "npm-cli",
+        "automation",
+        "scaffolding",
+        "rpc",
+        "backend",
+        "template-engine",
+        "reactive",
+        "mvvm",
+        "frontend",
+        "declarative",
+        "data-binding",
+        "dom",
+        "html",
+        "vanilla-js",
+        "rendering",
+        "javascript",
+        "template"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "homepage": "https://github.com/tobi2409/fullsty#readme",
+    "bugs": {
+        "url": "https://github.com/tobi2409/fullsty/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/tobi2409/fullsty.git"
+    }
+}

package/scripts/create-project.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+import { copyDirectory } from "./shared/file-copy.js";
+import { readJson, writeJson } from "./shared/project-json-utils.js";
+
+// Update package.json name in the copied project frame.
+function updatePackageName(targetProjectDir, projectName) {
+    const packageJson = readJson(targetProjectDir, "package.json");
+    packageJson.name = projectName;
+    writeJson(targetProjectDir, "package.json", packageJson);
+}
+
+function main() {
+    const projectName = process.argv[2];
+
+    if (!projectName) {
+        console.error("Usage: node create-project.js <project-name>");
+        process.exit(1);
+    }
+
+    const scriptDir = path.dirname(new URL(import.meta.url).pathname);
+    const sourceFrameDir = path.join(scriptDir, "project-frame");
+    const targetProjectDir = path.resolve(process.cwd(), projectName);
+
+    if (!fs.existsSync(sourceFrameDir)) {
+        throw new Error(`project-frame not found: ${sourceFrameDir}`);
+    }
+
+    if (fs.existsSync(targetProjectDir)) {
+        throw new Error(`Target directory already exists: ${targetProjectDir}`);
+    }
+
+    copyDirectory(sourceFrameDir, targetProjectDir);
+    updatePackageName(targetProjectDir, projectName);
+
+    console.log(`\n✅ Project created: ${targetProjectDir}`);
+}
+
+try {
+    main();
+} catch (error) {
+    console.error(`\n❌ ${error.message}`);
+    process.exit(1);
+}

package/scripts/extension-wrappers/pg/.env.pg

@@ -0,0 +1,15 @@
+# Connection name: default
+DEFAULT_PGHOST=127.0.0.1
+DEFAULT_PGPORT=5432
+DEFAULT_PGUSER=postgres
+DEFAULT_PGPASSWORD=postgres
+DEFAULT_PGDATABASE=fullsty_demo
+DEFAULT_POOL_MAX=10
+
+# Optional second connection example: analytics
+# ANALYTICS_PGHOST=127.0.0.1
+# ANALYTICS_PGPORT=5432
+# ANALYTICS_PGUSER=postgres
+# ANALYTICS_PGPASSWORD=postgres
+# ANALYTICS_PGDATABASE=fullsty_analytics
+# ANALYTICS_POOL_MAX=10

package/scripts/extension-wrappers/pg/pg-wrapper.ts

@@ -0,0 +1,78 @@
+import dotenv from "dotenv";
+import fs from "fs";
+import { Pool } from "pg";
+
+const pools = new Map<string, Pool>();
+let pgEnv: Record<string, string> = {};
+let pgEnvLoaded = false;
+
+function envKey(connectionName: string, key: string): string {
+    const prefix = connectionName.toUpperCase().replace(/[^A-Z0-9_]/g, "_");
+    return `${prefix}_${key}`;
+}
+
+function loadPgEnv(): void {
+    if (pgEnvLoaded) {
+        return;
+    }
+
+    // Load .env.pg into a local cache instead of writing into process.env.
+    // This keeps the pg wrapper isolated from other wrappers such as auth,
+    // which may load their own .env files later.
+    const envFileContent = fs.existsSync(".env.pg")
+        ? fs.readFileSync(".env.pg", "utf8")
+        : "";
+
+    pgEnv = dotenv.parse(envFileContent);
+    pgEnvLoaded = true;
+}
+
+function getEnv(
+    connectionName: string,
+    key: string,
+    fallback?: string,
+): string {
+    loadPgEnv();
+    return pgEnv[envKey(connectionName, key)] ?? fallback ?? "";
+}
+
+export function getPgPool(connectionName: string = "default"): Pool {
+    const existing = pools.get(connectionName);
+    if (existing) {
+        return existing;
+    }
+
+    const pool = new Pool({
+        host: getEnv(connectionName, "PGHOST", "127.0.0.1"),
+        port: Number(getEnv(connectionName, "PGPORT", "5432")),
+        user: getEnv(connectionName, "PGUSER", "postgres"),
+        password: getEnv(connectionName, "PGPASSWORD", "postgres"),
+        database: getEnv(connectionName, "PGDATABASE", "fullsty_demo"),
+        max: Number(getEnv(connectionName, "POOL_MAX", "10")),
+    });
+
+    pools.set(connectionName, pool);
+    return pool;
+}
+
+export async function closePgPool(
+    connectionName: string = "default",
+): Promise<void> {
+    const pool = pools.get(connectionName);
+
+    if (!pool) {
+        return;
+    }
+
+    await pool.end();
+    pools.delete(connectionName);
+}
+
+export async function closeAllPgPools(): Promise<void> {
+    const all = [...pools.entries()];
+
+    for (const [name, pool] of all) {
+        await pool.end();
+        pools.delete(name);
+    }
+}

package/scripts/extension-wrappers/sql-template-tag/sql-template-tag-wrapper.ts

@@ -0,0 +1 @@
+export { default as sql } from "sql-template-tag";

package/scripts/fullsty-server-pkg.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+import path from "path";
+import { handleAdd, handleRemove } from "./shared/server-package-utils.js";
+
+function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+
+    if (!command) {
+        console.log(
+            "Usage: node fullsty-server-pkg.js <add|remove> <package-name> [more-package-names...]",
+        );
+        
+        process.exit(1);
+    }
+
+    const scriptDir = path.dirname(new URL(import.meta.url).pathname);
+    const projectDir = process.cwd();
+    const serverDir = path.join(projectDir, "src", "server");
+    const packageNames = args.slice(1).filter((arg) => !arg.startsWith("-"));
+
+    if (packageNames.length === 0 || !["add", "remove"].includes(command)) {
+        console.log(
+            "Usage: node fullsty-server-pkg.js <add|remove> <package-name> [more-package-names...]",
+        );
+
+        process.exit(1);
+    }
+
+    if (command === "add") {
+        handleAdd(projectDir, scriptDir, serverDir, packageNames);
+        return;
+    }
+
+    handleRemove(projectDir, scriptDir, serverDir, packageNames);
+}
+
+try {
+    main();
+} catch (error) {
+    console.error(
+        `\n❌ ${error instanceof Error ? error.message : String(error)}`,
+    );
+    process.exit(1);
+}

package/scripts/project-frame/client-package.json

@@ -0,0 +1,9 @@
+{
+    "name": "generated-client",
+    "private": true,
+    "type": "module",
+    "dependencies": {
+        "@tobi2409/template-engine": "^0.9.1",
+        "@tobi2409/layout": "^0.5.0"
+    }
+}

package/scripts/project-frame/package.json

@@ -0,0 +1,17 @@
+{
+    "name": "project-frame",
+    "version": "1.0.0",
+    "description": "",
+    "license": "ISC",
+    "author": "",
+    "type": "module",
+    "scripts": {
+        "generate-server": "npx proc2rest-server && node -e \"require('fs').copyFileSync('server-package.json','generated/server/package.json'); require('fs').copyFileSync('server-tsconfig.json','generated/server/tsconfig.json')\"",
+        "generate-client": "npx proc2rest-client && node -e \"require('fs').copyFileSync('client-package.json','generated/client/package.json');\"",
+        "generate": "npm run generate-server && npm run generate-client",
+        "test": "echo \"Error: no test specified\" && exit 1"
+    },
+    "devDependencies": {
+        "@tobi2409/proc2rest": "^0.4.1"
+    }
+}

package/scripts/project-frame/proc2rest.config.json

@@ -0,0 +1,28 @@
+{
+    "jsClients": ["src/client/index.js"],
+    "servers": [
+        {
+            "src": "src/server/server.ts",
+            "namespace": "Server"
+        }
+    ],
+    "apiUrl": "http://localhost:3000",
+    "cors": {
+        "origin": "*"
+    },
+    "method-rules": {
+        "GET": "^(get|list|find)",
+        "POST": "^(create|add|insert)",
+        "PATCH": "^(update|set|patch)",
+        "DELETE": "^(delete|remove)"
+    },
+    "binaryTypes": [
+        "ArrayBuffer",
+        "Uint8Array",
+        "Uint8Array<ArrayBufferLike>",
+        "Buffer",
+        "Blob",
+        "ImageData",
+        "File"
+    ]
+}

package/scripts/project-frame/server-package.json

@@ -0,0 +1,22 @@
+{
+    "name": "generated-server",
+    "private": true,
+    "type": "module",
+    "scripts": {
+        "start": "tsx routes.generated.ts"
+    },
+    "dependencies": {
+        "@msgpack/msgpack": "^3.0.0",
+        "cors": "^2.8.5",
+        "dotenv": "^16.4.7",
+        "express": "^5.2.1",
+        "express-rate-limit": "^7.5.1"
+    },
+    "devDependencies": {
+        "@types/cors": "^2.8.17",
+        "@types/express": "^5.0.5",
+        "@types/node": "^24.10.1",
+        "tsx": "^4.20.6",
+        "typescript": "^5.9.3"
+    }
+}

package/scripts/project-frame/server-tsconfig.json

@@ -0,0 +1,11 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "NodeNext",
+        "moduleResolution": "NodeNext",
+        "esModuleInterop": true,
+        "strict": true,
+        "skipLibCheck": true
+    },
+    "include": ["*.ts"]
+}

package/scripts/project-frame/src/client/index.html

@@ -0,0 +1,36 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Document</title>
+
+    <script type="importmap">
+    {
+        "imports": {
+            "template-engine/": "./node_modules/@tobi2409/template-engine/src/"
+        }
+    }
+    </script>
+
+    <link rel="stylesheet" href="node_modules/@tobi2409/layout/src/layout.css">
+    <link rel="stylesheet" href="index.css">
+</head>
+<body>
+    
+    <div id="app">
+    </div>
+
+    <template id="app-template">
+        <h1>👋 Hello, <get>name</get></h1>
+
+        <p><get>serverMessage</get></p>
+    </template>
+
+    <template-use id="app-template-use" template-id="app-template" mount-id="app">
+    </template-use>
+
+    <script type="module" src="index.js"></script>
+
+</body>
+</html>

package/scripts/project-frame/src/client/index.js

@@ -0,0 +1,10 @@
+// @server-import server.ts
+
+import TemplateEngine from 'template-engine/template-engine.js'
+
+const data = TemplateEngine.reactive({
+    name: 'my friend',
+    serverMessage: 'Server not responded yet'
+}, document.getElementById('app-template-use'))
+
+data.serverMessage = await Server.helloFromServer('my friend')

package/scripts/project-frame/src/server/server.ts

@@ -0,0 +1,4 @@
+// @rest
+export function helloFromServer(name: string): string {
+    return `Hello, ${name}! This is the server speaking.`
+}

package/scripts/shared/file-copy.js

@@ -0,0 +1,19 @@
+import fs from "fs";
+import path from "path";
+
+// Recursively copy a directory and all nested files/folders.
+export function copyDirectory(sourceDir, targetDir) {
+    fs.mkdirSync(targetDir, { recursive: true });
+    const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+        const sourcePath = path.join(sourceDir, entry.name);
+        const targetPath = path.join(targetDir, entry.name);
+
+        if (entry.isDirectory()) {
+            copyDirectory(sourcePath, targetPath);
+        } else {
+            fs.copyFileSync(sourcePath, targetPath);
+        }
+    }
+}

package/scripts/shared/project-json-utils.js

@@ -0,0 +1,17 @@
+import fs from "fs";
+import path from "path";
+
+export function readJson(projectDir, fileName) {
+    const filePath = path.join(projectDir, fileName);
+
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`${fileName} not found: ${filePath}`);
+    }
+
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+export function writeJson(projectDir, fileName, json) {
+    const filePath = path.join(projectDir, fileName);
+    fs.writeFileSync(filePath, `${JSON.stringify(json, null, 2)}\n`, "utf8");
+}

package/scripts/shared/server-package-utils.js

@@ -0,0 +1,79 @@
+import fs, { write } from "fs";
+import path from "path";
+import { copyDirectory } from "./file-copy.js";
+import { readJson, writeJson } from "./project-json-utils.js";
+
+function wrapperDirFromPackage(scriptDir, packageName) {
+    return path.join(scriptDir, "extension-wrappers", packageName);
+}
+
+function removeWrapperFiles(sourceWrapperDir, targetServerDir) {
+    const entries = fs.readdirSync(sourceWrapperDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+        const sourcePath = path.join(sourceWrapperDir, entry.name);
+        const targetPath = path.join(targetServerDir, entry.name);
+
+        if (entry.isDirectory()) {
+            if (fs.existsSync(targetPath)) {
+                removeWrapperFiles(sourcePath, targetPath);
+            }
+
+            continue;
+        }
+
+        if (fs.existsSync(targetPath)) {
+            fs.rmSync(targetPath, { force: true });
+        }
+    }
+}
+
+export function handleAdd(projectDir, scriptDir, serverDir, packageNames) {
+    const json = readJson(projectDir, "server-package.json");
+
+    if (!json.dependencies || typeof json.dependencies !== "object") {
+        json.dependencies = {};
+    }
+
+    for (const packageName of packageNames) {
+        const wrapperDir = wrapperDirFromPackage(scriptDir, packageName);
+
+        json.dependencies[packageName] = "latest";
+
+        if (fs.existsSync(wrapperDir)) {
+            copyDirectory(wrapperDir, serverDir);
+            console.log(`\n✅ Copied wrapper for ${packageName} to src/server`);
+        }
+    }
+
+    writeJson(projectDir, "server-package.json", json);
+}
+
+export function handleRemove(projectDir, scriptDir, serverDir, packageNames) {
+    const json = readJson(projectDir, "server-package.json");
+
+    if (!json.dependencies || typeof json.dependencies !== "object") {
+        json.dependencies = {};
+    }
+
+    if (!json.devDependencies || typeof json.devDependencies !== "object") {
+        json.devDependencies = {};
+    }
+
+    for (const packageName of packageNames) {
+        const wrapperDir = wrapperDirFromPackage(scriptDir, packageName);
+
+        delete json.dependencies[packageName];
+        delete json.devDependencies[packageName];
+
+        if (fs.existsSync(wrapperDir)) {
+            removeWrapperFiles(wrapperDir, serverDir);
+            
+            console.log(
+                `\n✅ Removed wrapper for ${packageName} from src/server`,
+            );
+        }
+    }
+
+    writeJson(projectDir, "server-package.json", json);
+}